class RelationshipProperty(StrategizedProperty):
Describes an object property that holds a single item or list of items that correspond to a related database table.
Public constructor is the _orm.relationship
function.
See Also
Class | Comparator |
Produce boolean, comparison, and other operators for .RelationshipProperty attributes. |
Static Method | _check_sync_backref |
Undocumented |
Method | __init__ |
Provide a relationship between two mapped classes. |
Method | __str__ |
Undocumented |
Method | _add_reverse_property |
Undocumented |
Method | _check_cascade_settings |
Undocumented |
Method | _check_conflicts |
Test that this relationship is legal, warn about inheritance conflicts. |
Method | _columns_are_mapped |
Return True if all columns in the given collection are mapped by the tables referenced by this .Relationship . |
Method | _create_joins |
Undocumented |
Method | _generate_backref |
Interpret the 'backref' instruction to create a _orm.relationship complementary to this one. |
Method | _get_attr_w_warn_on_none |
Create the callable that is used in a many-to-one expression. |
Method | _lazy_none_clause |
Undocumented |
Method | _optimized_compare |
Undocumented |
Method | _persists_for |
Return True if this property will persist values on behalf of the given mapper. |
Method | _post_init |
Undocumented |
Method | _process_dependent_arguments |
Convert incoming configuration arguments to their proper form. |
Method | _set_cascade |
Undocumented |
Method | _setup_join_conditions |
Undocumented |
Method | _setup_registry_dependencies |
Undocumented |
Method | _value_as_iterable |
Return a list of tuples (state, obj) for the given key. |
Method | _warn_for_persistence_only_flags |
Undocumented |
Method | _with_parent |
Undocumented |
Method | cascade.setter |
Undocumented |
Method | cascade_iterator |
Iterate through instances related to the given instance for a particular 'cascade', starting with this MapperProperty. |
Method | do_init |
Perform subclass-specific initialization post-mapper-creation steps. |
Method | instrument_class |
Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty. |
Method | merge |
Merge the attribute represented by this MapperProperty from source to destination object. |
Class Variable | _links_to_entity |
True if this MapperProperty refers to a mapped entity. |
Class Variable | _persistence_only |
Undocumented |
Class Variable | inherit_cache |
Indicate if this .HasCacheKey instance should make use of the cache key generation scheme used by its immediate superclass. |
Class Variable | strategy_wildcard_key |
Undocumented |
Instance Variable | _calculated_foreign_keys |
Undocumented |
Instance Variable | _cascade |
Undocumented |
Instance Variable | _dependency_processor |
Undocumented |
Instance Variable | _join_condition |
Undocumented |
Instance Variable | _lazy_strategy |
Undocumented |
Instance Variable | _legacy_inactive_history_style |
Undocumented |
Instance Variable | _overlaps |
Undocumented |
Instance Variable | _reverse_property |
Undocumented |
Instance Variable | _user_defined_foreign_keys |
Undocumented |
Instance Variable | active_history |
Undocumented |
Instance Variable | argument |
Undocumented |
Instance Variable | back_populates |
Undocumented |
Instance Variable | backref |
Undocumented |
Instance Variable | bake_queries |
Undocumented |
Instance Variable | cascade_backrefs |
Undocumented |
Instance Variable | collection_class |
Undocumented |
Instance Variable | comparator |
Undocumented |
Instance Variable | comparator_factory |
Undocumented |
Instance Variable | direction |
Undocumented |
Instance Variable | distinct_target_key |
Undocumented |
Instance Variable | doc |
Undocumented |
Instance Variable | enable_typechecks |
Undocumented |
Instance Variable | info |
Undocumented |
Instance Variable | innerjoin |
Undocumented |
Instance Variable | join_depth |
Undocumented |
Instance Variable | lazy |
Undocumented |
Instance Variable | load_on_pending |
Undocumented |
Instance Variable | local_columns |
Undocumented |
Instance Variable | local_remote_pairs |
Undocumented |
Instance Variable | omit_join |
Undocumented |
Instance Variable | order_by |
Undocumented |
Instance Variable | passive_deletes |
Undocumented |
Instance Variable | passive_updates |
Undocumented |
Instance Variable | post_update |
Undocumented |
Instance Variable | primaryjoin |
Undocumented |
Instance Variable | query_class |
Undocumented |
Instance Variable | remote_side |
Undocumented |
Instance Variable | secondary |
Undocumented |
Instance Variable | secondary_synchronize_pairs |
Undocumented |
Instance Variable | secondaryjoin |
Undocumented |
Instance Variable | single_parent |
Undocumented |
Instance Variable | strategy_key |
Undocumented |
Instance Variable | sync_backref |
Undocumented |
Instance Variable | synchronize_pairs |
Undocumented |
Instance Variable | target |
Undocumented |
Instance Variable | uselist |
Undocumented |
Instance Variable | viewonly |
Undocumented |
Property | _clsregistry_resolve_arg |
Undocumented |
Property | _clsregistry_resolve_name |
Undocumented |
Property | _clsregistry_resolvers |
Undocumented |
Property | _effective_sync_backref |
Undocumented |
Property | _is_self_referential |
Undocumented |
Property | _use_get |
memoize the 'use_get' attribute of this RelationshipLoader's lazyloader. |
Property | cascade |
Return the current cascade setting for this .RelationshipProperty . |
Property | entity |
Return the target mapped entity, which is an inspect() of the class or aliased class that is referred towards. |
Property | mapper |
Return the targeted _orm.Mapper for this .RelationshipProperty . |
Inherited from StrategizedProperty
:
Class Method | strategy_for |
Undocumented |
Class Method | _strategy_lookup |
Undocumented |
Method | _get_context_loader |
Undocumented |
Method | _get_strategy |
Undocumented |
Method | _memoized_attr__default_path_loader_key |
Undocumented |
Method | _memoized_attr__wildcard_token |
Undocumented |
Method | create_row_processor |
Produce row processing functions and append to the given set of populators lists. |
Method | post_instrument_class |
Perform instrumentation adjustments that need to occur after init() has completed. |
Method | setup |
Called by Query for the purposes of constructing a SQL statement. |
Class Variable | __slots__ |
Undocumented |
Class Variable | _all_strategies |
Undocumented |
Instance Variable | _strategies |
Undocumented |
Instance Variable | strategy |
Undocumented |
Inherited from MapperProperty
(via StrategizedProperty
):
Method | __repr__ |
Undocumented |
Method | _memoized_attr_info |
Info dictionary associated with the object, allowing user-defined data to be associated with this .InspectionAttr . |
Method | init |
Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps. |
Method | set_parent |
Set the parent mapper that references this MapperProperty. |
Class Variable | _cache_key_traversal |
Undocumented |
Class Variable | is_property |
Part of the InspectionAttr interface; states this object is a mapper property. |
Instance Variable | _configure_finished |
Undocumented |
Instance Variable | _configure_started |
Undocumented |
Instance Variable | parent |
Undocumented |
Property | class_attribute |
Return the class-bound descriptor corresponding to this .MapperProperty . |
Inherited from HasCacheKey
(via StrategizedProperty
, MapperProperty
):
Class Method | _generate_cache_attrs |
generate cache key dispatcher for a new class. |
Class Method | _generate_cache_key_for_object |
Undocumented |
Method | _gen_cache_key |
return an optional cache key. |
Method | _generate_cache_key |
return a cache key. |
Class Variable | _hierarchy_supports_caching |
private attribute which may be set to False to prevent the inherit_cache warning from being emitted for a hierarchy of subclasses. |
Class Variable | _is_has_cache_key |
Undocumented |
Inherited from InspectionAttr
(via StrategizedProperty
, MapperProperty
):
Class Variable | _is_internal_proxy |
True if this object is an internal proxy object. |
Class Variable | is_aliased_class |
True if this object is an instance of .AliasedClass . |
Class Variable | is_attribute |
True if this object is a Python :term:`descriptor`. |
Class Variable | is_bundle |
True if this object is an instance of .Bundle . |
Class Variable | is_clause_element |
True if this object is an instance of _expression.ClauseElement . |
Class Variable | is_instance |
True if this object is an instance of .InstanceState . |
Class Variable | is_mapper |
True if this object is an instance of _orm.Mapper . |
Class Variable | is_selectable |
Return True if this object is an instance of _expression.Selectable . |
Inherited from MemoizedSlots
(via StrategizedProperty
, MapperProperty
):
Method | __getattr__ |
Undocumented |
Method | _fallback_getattr |
Undocumented |
Provide a relationship between two mapped classes.
This corresponds to a parent-child or associative table relationship.
The constructed class is an instance of
.RelationshipProperty
.
A typical _orm.relationship
, used in a classical mapping:
mapper(Parent, properties={ 'children': relationship(Child) })
Some arguments accepted by _orm.relationship
optionally accept a
callable function, which when called produces the desired value.
The callable is invoked by the parent _orm.Mapper
at "mapper
initialization" time, which happens only when mappers are first used,
and is assumed to be after all mappings have been constructed. This
can be used to resolve order-of-declaration and other dependency
issues, such as if Child is declared below Parent in the same
file:
mapper(Parent, properties={ "children":relationship(lambda: Child, order_by=lambda: Child.id) })
When using the :ref:`declarative_toplevel` extension, the Declarative
initializer allows string arguments to be passed to
_orm.relationship
. These string arguments are converted into
callables that evaluate the string as Python code, using the
Declarative class-registry as a namespace. This allows the lookup of
related classes to be automatic via their string name, and removes the
need for related classes to be imported into the local module space
before the dependent classes have been declared. It is still required
that the modules in which these related classes appear are imported
anywhere in the application at some point before the related mappings
are actually used, else a lookup error will be raised when the
_orm.relationship
attempts to resolve the string reference to the
related class. An example of a string- resolved class is as
follows:
from sqlalchemy.ext.declarative import declarative_base Base = declarative_base() class Parent(Base): __tablename__ = 'parent' id = Column(Integer, primary_key=True) children = relationship("Child", order_by="Child.id")
See Also
:ref:`relationship_config_toplevel` - Full introductory and
reference documentation for _orm.relationship
.
:ref:`orm_tutorial_relationship` - ORM tutorial introduction.
Parameters | |
argument | A mapped class, or actual :paramref:`_orm.relationship.argument` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a string name when using Declarative. Warning Prior to SQLAlchemy 1.3.16, this value is interpreted
using Python's eval() function.
DO NOT PASS UNTRUSTED INPUT TO THIS STRING.
See :ref:`declarative_relationship_eval` for details on
declarative evaluation of See Also :ref:`declarative_configuring_relationships` - further detail on relationship configuration when using Declarative. |
secondary | For a many-to-many relationship, specifies the intermediary
table, and is typically an instance of :paramref:`_orm.relationship.secondary` may
also be passed as a callable function which is evaluated at
mapper initialization time. When using Declarative, it may also
be a string argument noting the name of a Warning When passed as a Python-evaluable string, the
argument is interpreted using Python's eval() function.
DO NOT PASS UNTRUSTED INPUT TO THIS STRING.
See :ref:`declarative_relationship_eval` for details on
declarative evaluation of The :paramref:`_orm.relationship.secondary` keyword argument is
typically applied in the case where the intermediary
See Also :ref:`relationships_many_to_many` - Reference example of "many to many". :ref:`orm_tutorial_many_to_many` - ORM tutorial introduction to many-to-many relationships. :ref:`self_referential_many_to_many` - Specifics on using many-to-many in a self-referential case. :ref:`declarative_many_to_many` - Additional options when using Declarative. :ref:`association_pattern` - an alternative to :paramref:`_orm.relationship.secondary` when composing association table relationships, allowing additional attributes to be specified on the association table. :ref:`composite_secondary_join` - a lesser-used pattern which
in some cases can enable complex
New in version 0.9.2: :paramref:`_orm.relationship.secondary`
works
more effectively when referring to a
_expression.Join
instance. |
primaryjoin | A SQL expression that will be used as the primary join of the child object against the parent object, or in a many-to-many relationship the join of the parent object to the association table. By default, this value is computed based on the foreign key relationships of the parent and child tables (or association table). :paramref:`_orm.relationship.primaryjoin` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. Warning When passed as a Python-evaluable string, the
argument is interpreted using Python's eval() function.
DO NOT PASS UNTRUSTED INPUT TO THIS STRING.
See :ref:`declarative_relationship_eval` for details on
declarative evaluation of See Also |
secondaryjoin | A SQL expression that will be used as the join of an association table to the child object. By default, this value is computed based on the foreign key relationships of the association and child tables. :paramref:`_orm.relationship.secondaryjoin` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. Warning When passed as a Python-evaluable string, the
argument is interpreted using Python's eval() function.
DO NOT PASS UNTRUSTED INPUT TO THIS STRING.
See :ref:`declarative_relationship_eval` for details on
declarative evaluation of See Also |
foreign_keys | A list of columns which are to be used as "foreign key"
columns, or columns which refer to the value in a remote
column, within the context of this In normal cases, the :paramref:`_orm.relationship.foreign_keys`
parameter is not required.
The :paramref:`_orm.relationship.foreign_keys` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. Warning When passed as a Python-evaluable string, the
argument is interpreted using Python's eval() function.
DO NOT PASS UNTRUSTED INPUT TO THIS STRING.
See :ref:`declarative_relationship_eval` for details on
declarative evaluation of See Also :ref:`relationship_foreign_keys` :ref:`relationship_custom_foreign`
|
uselist | A boolean that indicates if this property should be loaded as a
list or a scalar. In most cases, this value is determined
automatically by The :paramref:`_orm.relationship.uselist`
flag is also available on an
existing >>> User.addresses.property.uselist True See Also :ref:`relationships_one_to_one` - Introduction to the "one to one" relationship pattern, which is typically when the :paramref:`_orm.relationship.uselist` flag is needed. |
order_by | Indicates the ordering that should be applied when loading these
items. :paramref:`_orm.relationship.order_by`
is expected to refer to
one of the :paramref:`_orm.relationship.order_by` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. Warning When passed as a Python-evaluable string, the
argument is interpreted using Python's eval() function.
DO NOT PASS UNTRUSTED INPUT TO THIS STRING.
See :ref:`declarative_relationship_eval` for details on
declarative evaluation of |
backref | Indicates the string name of a property to be placed on the related
mapper's class that will handle this relationship in the other
direction. The other property will be created automatically
when the mappers are configured. Can also be passed as a
See Also :ref:`relationships_backref` - Introductory documentation and examples. :paramref:`_orm.relationship.back_populates` - alternative form of backref specification.
|
back_populates | Takes a string name and has the same meaning as :paramref:`_orm.relationship.backref`, except the complementing property is not created automatically, and instead must be configured explicitly on the other mapper. The complementing property should also indicate :paramref:`_orm.relationship.back_populates` to this relationship to ensure proper functioning. See Also :ref:`relationships_backref` - Introductory documentation and examples. :paramref:`_orm.relationship.backref` - alternative form of backref specification. |
overlaps | A string name or comma-delimited set of names of other relationships on either this mapper, a descendant mapper, or a target mapper with which this relationship may write to the same foreign keys upon persistence. The only effect this has is to eliminate the warning that this relationship will conflict with another upon persistence. This is used for such relationships that are truly capable of conflicting with each other on write, but the application will ensure that no such conflicts occur.
New in version 1.4.
See Also :ref:`error_qzyx` - usage example |
post_update | This indicates that the relationship should be handled by a second UPDATE statement after an INSERT or before a DELETE. Currently, it also will issue an UPDATE after the instance was UPDATEd as well, although this technically should be improved. This flag is used to handle saving bi-directional dependencies between two individual rows (i.e. each row references the other), where it would otherwise be impossible to INSERT or DELETE both rows fully since one row exists before the other. Use this flag when a particular mapping arrangement will incur two rows that are dependent on each other, such as a table that has a one-to-many relationship to a set of child rows, and also has a column that references a single child row within that list (i.e. both tables contain a foreign key to each other). If a flush operation returns an error that a "cyclical dependency" was detected, this is a cue that you might want to use :paramref:`_orm.relationship.post_update` to "break" the cycle. See Also :ref:`post_update` - Introductory documentation and examples. |
cascade | A comma-separated list of cascade rules which determines how Session operations should be "cascaded" from parent to child. This defaults to False, which means the default cascade should be used - this default cascade is "save-update, merge". The available cascades are save-update, merge, expunge, delete, delete-orphan, and refresh-expire. An additional option, all indicates shorthand for "save-update, merge, refresh-expire, expunge, delete", and is often used as in "all, delete-orphan" to indicate that related objects should follow along with the parent object in all cases, and be deleted when de-associated. See Also :ref:`unitofwork_cascades` - Full detail on each of the available cascade options. :ref:`tutorial_delete_cascade` - Tutorial example describing a delete cascade. |
viewonly | Undocumented |
lazy | Undocumented |
collection_class | A class or callable that returns a new list-holding object. will be used in place of a plain list for storing elements. See Also :ref:`custom_collections` - Introductory documentation and examples. |
passive_deletes | Undocumented |
passive_updates | Undocumented |
remote_side | Used for self-referential relationships, indicates the column or list of columns that form the "remote side" of the relationship. :paramref:`_orm.relationship.remote_side` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. Warning When passed as a Python-evaluable string, the
argument is interpreted using Python's eval() function.
DO NOT PASS UNTRUSTED INPUT TO THIS STRING.
See :ref:`declarative_relationship_eval` for details on
declarative evaluation of See Also :ref:`self_referential` - in-depth explanation of how :paramref:`_orm.relationship.remote_side` is used to configure self-referential relationships.
|
enable_typechecks | Undocumented |
join_depth | When non-None, an integer value indicating how many levels deep "eager" loaders should join on a self-referring or cyclical relationship. The number counts how many times the same Mapper shall be present in the loading condition along a particular join branch. When left at its default of None, eager loaders will stop chaining when they encounter a the same target mapper which is already higher up in the chain. This option applies both to joined- and subquery- eager loaders. See Also :ref:`self_referential_eager_loading` - Introductory documentation and examples. |
comparator_factory | A class which extends See Also
:ref:`custom_comparators` - Brief intro to this feature. |
single_parent | When True, installs a validator which will prevent objects
from being associated with more than one parent at a time.
This is used for many-to-one or many-to-many relationships that
should be treated either as one-to-one or one-to-many. Its usage
is optional, except for See Also :ref:`unitofwork_cascades` - includes detail on when the :paramref:`_orm.relationship.single_parent` flag may be appropriate. |
innerjoin | Undocumented |
distinct_target_key | Undocumented |
doc | Docstring which will be applied to the resulting descriptor. |
active_history | Undocumented |
cascade_backrefs | Undocumented |
load_on_pending | Undocumented |
bake_queries | Undocumented |
_local_remote_pairs | Undocumented |
query_class | A See Also :ref:`dynamic_relationship` - Introduction to "dynamic" relationship loaders. |
info | Optional data dictionary which will be populated into the
.MapperProperty.info attribute of this object. |
omit_join | Allows manual control over the "selectin" automatic join optimization. Set to False to disable the "omit join" feature added in SQLAlchemy 1.3; or leave as None to leave automatic optimization in place. Note This flag may only be set to False. It is not necessary to set it to True as the "omit_join" optimization is automatically detected; if it is not detected, then the optimization is not supported.
Changed in version 1.3.11: setting omit_join to True will now
emit a warning as this was not the intended use of this flag.
New in version 1.3.
|
sync_backref | A boolean that enables the events used to synchronize the in-Python attributes when this relationship is target of either :paramref:`_orm.relationship.backref` or :paramref:`_orm.relationship.back_populates`. Defaults to None, which indicates that an automatic value should be selected based on the value of the :paramref:`_orm.relationship.viewonly` flag. When left at its default, changes in state will be back-populated only if neither sides of a relationship is viewonly.
New in version 1.3.17.
Changed in version 1.4: - A relationship that specifies
:paramref:`_orm.relationship.viewonly` automatically implies
that :paramref:`_orm.relationship.sync_backref` is False.
|
_legacy_inactive_history_style | Undocumented |
active_history=False | When True, indicates that the "previous" value for a
many-to-one reference should be loaded when replaced, if
not already loaded. Normally, history tracking logic for
simple many-to-ones only needs to be aware of the "new"
value in order to perform a flush. This flag is available
for applications that make use of
.attributes.get_history which also need to know
the "previous" value of the attribute. |
bake_queries=True | Enable :ref:`lambda caching <engine_lambda_caching>` for loader strategies, if applicable, which adds a performance gain to the construction of SQL constructs used by loader strategies, in addition to the usual SQL statement caching used throughout SQLAlchemy. This parameter currently applies only to the "lazy" and "selectin" loader strategies. There is generally no reason to set this parameter to False.
Changed in version 1.4: Relationship loaders no longer use the
previous "baked query" system of query caching. The "lazy"
and "selectin" loaders make use of the "lambda cache" system
for the construction of SQL constructs,
as well as the usual SQL caching system that is throughout
SQLAlchemy as of the 1.4 series.
|
cascade_backrefs=True | A boolean value indicating if the save-update cascade should operate along an assignment event intercepted by a backref. When set to False, the attribute managed by this relationship will not cascade an incoming transient object into the session of a persistent parent, if the event is received via backref.
Deprecated since version 1.4: The
:paramref:`_orm.relationship.cascade_backrefs`
flag will default to False in all cases in SQLAlchemy 2.0.
See Also :ref:`backref_cascade` - Full discussion and examples on how the :paramref:`_orm.relationship.cascade_backrefs` option is used. |
distinct_target_key=None | Indicate if a "subquery" eager load should apply the DISTINCT keyword to the innermost SELECT statement. When left as None, the DISTINCT keyword will be applied in those cases when the target columns do not comprise the full primary key of the target table. When set to True, the DISTINCT keyword is applied to the innermost SELECT unconditionally. It may be desirable to set this flag to False when the DISTINCT is reducing performance of the innermost subquery beyond that of what duplicate innermost rows may be causing.
Changed in version 0.9.0: -
:paramref:`_orm.relationship.distinct_target_key` now defaults to
None, so that the feature enables itself automatically for
those cases where the innermost query targets a non-unique
key.
See Also :ref:`loading_toplevel` - includes an introduction to subquery eager loading. |
innerjoin=False | When True, joined eager loads will use an inner join to join against related tables instead of an outer join. The purpose of this option is generally one of performance, as inner joins generally perform better than outer joins. This flag can be set to True when the relationship references an object via many-to-one using local foreign keys that are not nullable, or when the reference is one-to-one or a collection that is guaranteed to have one or at least one entry. The option supports the same "nested" and "unnested" options as that of :paramref:`_orm.joinedload.innerjoin`. See that flag for details on nested / unnested behaviors. See Also :paramref:`_orm.joinedload.innerjoin` - the option as specified by loader option, including detail on nesting behavior. :ref:`what_kind_of_loading` - Discussion of some details of various loader options. |
lazy='select' | specifies How the related items should be loaded. Default value is select. Values include:
See Also :doc:`/orm/loading_relationships` - Full documentation on relationship loader configuration. :ref:`dynamic_relationship` - detail on the dynamic option. :ref:`collections_noload_raiseload` - notes on "noload" and "raise" |
load_on_pending=False | Indicates loading behavior for transient or pending parent objects. When set to True, causes the lazy-loader to
issue a query for a parent object that is not persistent, meaning it
has never been flushed. This may take effect for a pending object
when autoflush is disabled, or for a transient object that has been
"attached" to a The :paramref:`_orm.relationship.load_on_pending` flag does not improve behavior when the ORM is used normally - object references should be constructed at the object level, not at the foreign key level, so that they are present in an ordinary way before a flush proceeds. This flag is not not intended for general use. See Also
|
passive_deletes=False | Indicates loading behavior during delete operations. A value of True indicates that unloaded child items should not be loaded during a delete operation on the parent. Normally, when a parent item is deleted, all child items are loaded so that they can either be marked as deleted, or have their foreign key to the parent set to NULL. Marking this flag as True usually implies an ON DELETE <CASCADE|SET NULL> rule is in place which will handle updating/deleting child rows on the database side. Additionally, setting the flag to the string value 'all' will disable the "nulling out" of the child foreign keys, when the parent object is deleted and there is no delete or delete-orphan cascade enabled. This is typically used when a triggering or error raise scenario is in place on the database side. Note that the foreign key attributes on in-session child objects will not be changed after a flush occurs so this is a very special use-case setting. Additionally, the "nulling out" will still occur if the child object is de-associated with the parent. See Also :ref:`passive_deletes` - Introductory documentation and examples. |
passive_updates=True | Indicates the persistence behavior to take when a referenced primary key value changes in place, indicating that the referencing foreign key columns will also need their value changed. When True, it is assumed that ON UPDATE CASCADE is configured on
the foreign key in the database, and that the database will
handle propagation of an UPDATE from a source column to
dependent rows. When False, the SQLAlchemy
It is highly advised that an application which is employing mutable primary keys keeps passive_updates set to True, and instead uses the referential integrity features of the database itself in order to handle the change efficiently and fully. See Also :ref:`passive_updates` - Introductory documentation and examples. :paramref:`.mapper.passive_updates` - a similar flag which takes effect for joined-table inheritance mappings. |
viewonly=False | When set to True, the relationship is used only for loading
objects, and not for any persistence operation. A
When using the :paramref:`_orm.relationship.viewonly` flag in conjunction with backrefs, the originating relationship for a particular state change will not produce state changes within the viewonly relationship. This is the behavior implied by :paramref:`_orm.relationship.sync_backref` being set to False.
Changed in version 1.3.17: - the
:paramref:`_orm.relationship.sync_backref` flag is set to False
when using viewonly in conjunction with backrefs.
|
.Relationship
.Undocumented
_orm.relationship
complementary to this one.Create the callable that is used in a many-to-one expression.
E.g.:
u1 = s.query(User).get(5) expr = Address.user == u1
Above, the SQL should be "address.user_id = 5". The callable returned by this method produces the value "5" based on the identity of u1.
Undocumented
Convert incoming configuration arguments to their proper form.
Callables are resolved, ORM annotations removed.
Return a list of tuples (state, obj) for the given key.
returns an empty list if the value is None/empty/PASSIVE_NO_RESULT
Iterate through instances related to the given instance for a particular 'cascade', starting with this MapperProperty.
Return an iterator3-tuples (instance, mapper, state).
Note that the 'cascade' collection on this MapperProperty is checked first for the given type before cascade_iterator is called.
This method typically only applies to RelationshipProperty.
Perform subclass-specific initialization post-mapper-creation steps.
This is a template method called by the MapperProperty object's init() method.
Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty.
The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute.
This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process.
The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the "impl") which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc).
bool
=
True if this MapperProperty refers to a mapped entity.
Should only be True for RelationshipProperty, False for all others.
bool
=
Indicate if this .HasCacheKey
instance should make use of the
cache key generation scheme used by its immediate superclass.
The attribute defaults to None, which indicates that a construct has not yet taken into account whether or not its appropriate for it to participate in caching; this is functionally equivalent to setting the value to False, except that a warning is also emitted.
This flag can be set to True on a particular class, if the SQL that corresponds to the object does not change based on attributes which are local to this class, and not its superclass.
See Also
:ref:`compilerext_caching` - General guideslines for setting the
.HasCacheKey.inherit_cache
attribute for third-party or user
defined SQL constructs.