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.