Collections (to-many relationships)

When you need to define one-to-many or many-to-many relationship, you should use a Set attribute which represents a collection:

class User(db.Entity):
    name = Required(unicode)
    photos = Set('Photo')

class Photo(db.Entity):
    content = Required(buffer)
    user = Required(User)
    tags = Set('Tag')

class Tag(db.Entity):
    name = PrimaryKey(unicode)
    photos = Set(Photo)

In the example above we’ve defined one-to-many relationship between User and Photo and many-to-many relationship between Photo and Tag entities. Below you can see the description of additional parameters which can be passed during the declaration of relationship attributes.

Collection attributes parameters

class Set

Represents the to-many relationship.

lazy

When we access a specific collection item (check if an element belongs to a collection, add or delete items), Pony loads the whole collection to the db_session cache. Usually it increases the performance reducing the database round trips. But if you have large collections you may prefer not to load them into the cache. Setting lazy=True tells Pony that it shouldn’t load the collection to the cache, but always send queries to the database. Default is lazy=False.

reverse

Specifies the name of the attribute of related entity which is used for the relationship. This parameter should be used when there are more than one relationship between two entities.

table

This parameter is used for many-to-many relationships only and allows to specify the name of the intermediate table used for representing this relationship in the database.

column

columns

reverse_column

reverse_columns

These parameters are used for many-to-many relationships and allows to specify the name of the intermediate columns. The columns and reverse_columns parameters receive a list and used when the entity has a composite key. Typically you use the column or columns parameters in both relationship attributes if you don’t like the default column name.

cascade_delete

Boolean value which controls the cascade deletion of the related objects. Default value depends on the another side of the relationship. If it is Optional - the default value is False and if it is Required then True.

nplus1_threshold

This parameter is used for fine tuning of the N+1 problem solution.

Collection instance methods

class Set

add(item)

add(iter)

Adding instances to a collection establishes a two-way relationship between entity instances:

photo = Photo[123]
photo.tags.add(Tag['Outdoors'])

Now the instance of the Photo entity with the primary key 123 has a relationship with the Tag['Outdoors'] instance. The attribute photos of the Tag['Outdoors'] instance contains the reference to the Photo[123] as well.

We can also establish several relationships at once passing the list of tags to the add() method:

photo.tags.add([Tag['Party'], Tag['New Year']])

remove(item)

remove(iter)

Remove an item or items from the collection and thus break the relationship between entity instances.

clear()

Remove all items from the collection which means breaking relationships between entity instances.

is_empty()

Returns False if there is at lease one relationship and True if this attribute has no relationships.

copy()

Returns a Python set object which contains the same items as the given collection.

count()

Returns the amount of objects in the collection.

create(**kwargs)

Create an return an instance of the related entity and establish a relationship with it:

new_tag = Photo[123].tags.create(name='New tag')

is an equivalent of the following:

new_tag = Tag(name='New tag')
Photo[123].tags.add(new_tag)

Collection class methods

class Set

drop_table(with_all_data=False)

Drops the intermediate table which is created for establishing many-to-many relationship. If the table is not empty and with_all_data=False, the method raises the TableIsNotEmpty exception and doesn’t delete anything. Setting the with_all_data=True allows to delete the table even if it is not empty.

Attribute lifting

Multisets

Pickling collections