Customizing — Flask-SQLAlchemy Documentation ()
When first accessed, the association proxy performs introspection operations on .. can be used to construct the scalar relationship on-demand in this situation. statements on a particular set of backends with more stringent requirements. A second directive, known as relationship(), tells the ORM that the Address. The loading of relationships falls into three categories; lazy loading, eager loading, and The special ordering requirements of subqueryload described at The.
By default, this collection is a list: This because objects are always loaded from the database as lists, and a key-generation strategy must be available to populate the dictionary correctly. It produces a dictionary class that will apply a particular attribute of the mapped class as a key.
Below we map an Item class containing a dictionary of Note items keyed to the Note. Such as, when assigning to Item. Note 'a', 'atext''b': Using a regular Python property allows virtually any detail or combination of details about the object to be used as the key, as below when we establish it as a tuple of Note. Assigning to this reverse relationship, the Note is added to the Item. The key value must be immutable for the lifetime of the object. You can not, for example, map on foreign key values if those key values will change during the session, i.
Returns a MappedCollection factory with a keying function generated from keyfunc, a callable that takes an entity and returns a key value.
In other cases, special decorators are needed to tell SQLAlchemy more detail about how the collection operates. Do I need a custom collection implementation? In most cases not at all! For the first use case, the orm. See Simple Validators for an example of this. This approach leaves the underlying mapped collection unaffected and avoids the need to carefully tailor collection behavior on a method-by-method basis.
They can of course be combined with the above two approaches. Collections in SQLAlchemy are transparently instrumented.
Instrumentation means that normal operations on the collection are tracked and result in changes being written to the database at flush time. Additionally, collection operations can fire events which indicate some secondary operation must take place.
The collections package understands the basic interface of lists, sets and dicts and will automatically apply instrumentation to those built-in types and their subclasses. Object-derived types that implement a basic collection interface are detected and instrumented via duck-typing: The ORM needs to know which methods to use to append, remove and iterate over members of the collection. When using a type like list or set, the appropriate methods are well-known and used automatically when present.
This set-like class does not provide the expected add method, so we must supply an explicit mapping for the ORM via a decorator. SQLAlchemy will add instances via the append method.
Default methods can be changed as well: There is no requirement to be list- or set-like at all. Append and remove methods will be called with a mapped entity as the single argument, and iterator methods are called with no arguments and must return an iterator.
Joined eager loading is detailed at Joined Eager Loading. Subquery eager loading is detailed at Subquery Eager Loading. An introduction to raise loading is at Preventing unwanted lazy loads using raiseload. This is configured using the relationship. For example, to configure a relationship to use joined eager loading when the parent object is queried: See Joined Eager Loading for background on this style of loading.
The default value of the relationship. See Lazy Loading for further background. Very detailed control over relationship loading is available using loader options; the most common are joinedloadsubqueryloadselectinload and lazyload. The option accepts either the string name of an attribute against a parent, or for greater specificity can accommodate a class-bound attribute directly: This means that when a collection or association is lazily loaded upon access, the specified option will then take effect: When the children collection on a particular Parent object is first accessed, it will lazy load the related objects, but additionally apply eager loading to the subelements collection on each member of children.
Using method chaining, the loader style of each link in the path is explicitly stated. For example, given the previous example: This stays the case even if the above Parent object is accessed from a subsequent query that specifies a different set of options. To change the options on an existing object without expunging it and re-loading, they must be set explicitly in conjunction with the Query. A future SQLAlchemy release may add more alternatives to manipulating the loader options on already-loaded objects.
The scalar or collection attribute associated with a relationship contains a trigger which fires the first time the attribute is accessed. This trigger typically issues a SQL call at the point of access in order to load the related object or objects: For this reason, while lazy loading can be expensive for related collections, in the case that one is loading lots of objects with simple many-to-ones against a relatively small set of possible target objects, lazy loading may be able to refer to these objects locally without emitting as many SELECT statements as there are parent objects.
Lazy loading can be enabled for a given attribute that is normally configured in some other way using the lazyload loader option: However, eager loading requires that the attributes which are to be loaded be specified with the Query up front.
- SQLAlchemy 1.3 Documentation
The problem of code that may access other attributes that were not eagerly loaded, where lazy loading is not desired, may be addressed using the raiseload strategy; this loader strategy replaces the behavior of lazy loading with an informative error being raised: For example, to set up only one attribute as eager loading, and all the rest as raise: To set up raiseload for only the Order objects, specify a full path with orm.
At the mapping level, this looks like: This is achieved using the joinedload loader option: For an attribute that is guaranteed to have an element, such as a many-to-one reference to a related object where the referencing foreign key is NOT NULL, the query can be made more efficient by using an inner join; this is available at the mapping level via the relationship.
Older versions of SQLAlchemy would convert right-nested joins into subuqeries in all cases. Such as above, if the User object we loaded referred to three Address objects, the result of the SQL statement would have had three rows; yet the Query returns only one User object.
As additional rows are received for a User object just loaded in a previous row, the additional columns that refer to new Address objects are directed into additional results within the User.
Key Features of SQLAlchemy
Joined eager loading used for scalar references is however compatible with Query. It is critical to understand the distinction that while Query.
A particular query might start out using all lazy loads. After using it in context, it might be revealed that particular attributes or collections are always accessed, and that it would be more efficient to change the loader strategy for these. The strategy can be changed with no other modifications to the query, the results will remain identical, but fewer SQL statements would be emitted.
In theory and pretty much in practicenothing you can do to the Query would make it load a different set of primary or related objects based on a change in loader strategy.
Features - SQLAlchemy
The correct way to load the User records and order by email address is to use Query. We can add joinedload back in, so that there are two joins - one is that which we are ordering on, the other is used anonymously to load the contents of the User. In this case, the two joins most probably appear redundant - which they are. But to see why joinedload does what it does, consider if we were filtering on a particular Address: One will match exactly one row, that of the join of User and Address where Address.
By changing the usage of joinedload to another style of loading, we can change how the collection is loaded completely independently of SQL used to retrieve the actual User rows we want. Below we change joinedload into subqueryload: The operation of subquery eager loading is to emit a second SELECT statement for each relationship to be loaded, across all result objects at once.SQLAlchemy: Object Relational Modelling (ORM) for Python, quick-start
This SELECT statement refers to the original SELECT statement, wrapped inside of a subquery, so that we retrieve the same list of primary keys for the primary object being returned, then link that to the sum of all the collection members to load them at once: