版本:1.1.0b2 |发布日期:2016年7月1日

SQLAlchemy 1.1文档

ORM配置的功能结构。

请参阅SQLAlchemy对象关系教程和映射器配置文档,以获取有关如何使用此模块的概述。

关系API

sqlalchemy.orm.relationship(argument, secondary=None, primaryjoin=None, secondaryjoin=None, foreign_keys=None, uselist=None, order_by=False, backref=None, back_populates=None, post_update=False, cascade=False, extension=None, viewonly=False, lazy=True, collection_class=None, passive_deletes=False, passive_updates=True, remote_side=None, enable_typechecks=True, join_depth=None, comparator_factory=None, single_parent=False, innerjoin=False, distinct_target_key=None, doc=None, active_history=False, cascade_backrefs=True, load_on_pending=False, bake_queries=True, strategy_class=None, _local_remote_pairs=None, query_class=None, info=None)

提供两个映射类之间的关系。

这对应于父子关系或关联表关系。构造的类是RelationshipProperty的一个实例。

一个典型的relationship(),在经典的映射中使用:

mapper(Parent, properties={
  'children': relationship(Child)
})

一些被relationship()接受的参数可选地接受一个可调用的函数,当被调用的时候产生所需的值。The callable is invoked by the parent Mapper at “mapper initialization” time, which happens only when mappers are first used, and is assumed to be after all mappings have been constructed. 这可以用来解决声明顺序和其他依赖性问题,例如,如果ChildParent中声明在同一个文件中:

mapper(Parent, properties={
    "children":relationship(lambda: Child,
                        order_by=lambda: Child.id)
})

当使用Declarative扩展名时,Declarative初始化程序允许将字符串参数传递给relationship()这些字符串参数被转换成可以将字符串评估为Python代码的可调用函数,使用Declarative类注册表作为名称空间。这允许相关类的查找通过它们的字符串名称自动进行,并且不需要将相关的类根本导入到本地模块空间中:

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")

也可以看看

Relationship Configuration - relationship()的完整介绍性和参考文档。

Building a Relationship - ORM教程介绍

参数:
  • 参数 -

    映射类或实际的Mapper实例,表示关系的目标。

    argument 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.

    也可以看看

    Configuring Relationships - 使用Declarative时关系配置的更多细节。

  • 辅助 -

    对于多对多关系,指定中间表,并且通常是Table的实例。在不常见的情况下,参数也可以被指定为Alias结构,甚至是Join结构。

    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 Table that is present in the MetaData collection associated with the parent-mapped Table.

    The secondary keyword argument is typically applied in the case where the intermediary Table is not otherwise expressed in any direct class mapping. 如果“辅助”表也被明确地映射到其他地方(例如在Association Object中),应考虑应用viewonly标志,以便relationship()

    也可以看看

    Many To Many - “多对多”的参考例子。

    Building a Many To Many Relationship - ORM教程介绍多对多关系。

    Self-Referential Many-to-Many Relationship - Specifics on using many-to-many in a self-referential case.

    Configuring Many-to-Many Relationships - 使用声明式时的其他选项。

    Association Object - an alternative to secondary when composing association table relationships, allowing additional attributes to be specified on the association table.

    Composite “Secondary” Joins - 一种较少使用的模式,在某些情况下可以使用复杂的relationship() SQL条件。

    版本0.9.2中的新功能: secondary在引用Join实例时更有效。

  • 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. 通常情况下,简单多对一的历史跟踪逻辑只需要知道“新”值就可以执行刷新。该标志可用于使用attributes.get_history()的应用程序,该应用程序也需要知道属性的“上一个”值。
  • 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.其他属性将在配置映射器时自动创建。也可以作为backref()对象传递来控制新关系的配置。

    也可以看看

    Linking Relationships with Backref - Introductory documentation and examples.

    back_populates - alternative form of backref specification.

    backref() - allows control over relationship() configuration when using backref.

  • back_populates -

    一个字符串名称,作用与backref相同,除了补充属性不是自动创建,而是必须在其他映射器上显式配置。补充属性还应该指示back_populates到此关系,以确保正常运行。

    也可以看看

    Linking Relationships with Backref - Introductory documentation and examples.

    backref - alternative form of backref specification.

  • bake_queries = True -

    当首先调用bake_lazy_loaders()函数时,使用BakedQuery缓存来缓存惰性加载中使用的SQL的构造。默认为True,用于在烘焙查询缓存系统正在使用时为每个关系提供“退出”标志。

    警告

    当调用应用程序范围的bake_lazy_loaders()函数时,标志只有有效。它默认为True,所以是“退出”标志。

    如果烘焙查询在其他情况下正在使用,则将此标志设置为False可能会减少此relationship()的ORM内存使用,或者解决在烘焙查询缓存系统中观察到的未解决的稳定性问题。

    版本1.0.0中的新功能

    也可以看看

    Baked Queries

  • 级联 -

    一个由逗号分隔的级联规则列表,它决定了会话操作应该如何从父级到子级“级联”。这默认为False,这意味着应该使用默认级联 - 这个默认级联是“save-update, 合并” / T2>。

    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.

    也可以看看

    Cascades - 每个可用级联选项的详细信息。

    Configuring delete/delete-orphan Cascade - 描述删除级联的教程示例。

  • cascade_backrefs = True -

    一个布尔值,用于指示save-update级联是否应该沿着backref拦截的赋值事件进行操作。当设置为False时,如果通过backref接收事件,则由此关系管理的属性将不会将传入的瞬态对象级联到永久父级的会话中。

    也可以看看

    Controlling Cascade on Backrefs - 有关如何使用cascade_backrefs选项的完整讨论和示例。

  • collection_class -

    一个类或可调用返回一个新的列表持有对象。将被用来代替存储元素的简单列表。

    也可以看看

    Customizing Collection Access - 介绍性文档和示例。

  • comparator_factory -

    一个扩展了RelationshipProperty.Comparator的类,它为比较操作提供了自定义的SQL子句生成。

    也可以看看

    PropComparator - some detail on redefining comparators at this level.

    Operator Customization - 简要介绍此功能。

  • distinct_target_key = None -

    指示“子查询”预加载是否应将DISTINCT关键字应用于最里面的SELECT语句。如果保留为None,则在目标列不包含目标表的完整主键的情况下,将应用DISTINCT关键字。当设置为True时,DISTINCT关键字无条件地应用于最内层的SELECT。

    当DISTINCT将最内层子查询的性能降低到超出最内层重复行可能导致的性能时,可能需要将此标志设置为False。

    New in version 0.8.3: - distinct_target_key allows the subquery eager loader to apply a DISTINCT modifier to the innermost SELECT.

    在0.9.0版本中更改: - distinct_target_key现在默认为None,因此该功能会自动为其中最内层查询目标一个非唯一的密钥。

    也可以看看

    Relationship Loading Techniques - 包括对子查询渴望加载的介绍。

  • doc – docstring which will be applied to the resulting descriptor.
  • 扩展名 -

    一个AttributeExtension实例或扩展名列表,它们将被放置在放置在该类上的结果描述符的属性侦听器列表中。

    从版本0.7开始弃用:请参阅AttributeEvents

  • foreign_keys -

    relationship()对象的primaryjoinThat is, if the primaryjoin condition of this relationship() is a.id == b.a_id, and the values in b.a_id are required to be present in a.id, then the “foreign key” column of this relationship() is b.a_id.

    In normal cases, the foreign_keys parameter is not required. relationship() will automatically determine which columns in the primaryjoin conditition are to be considered “foreign key” columns based on those Column objects that specify ForeignKey, or are otherwise listed as referencing columns in a ForeignKeyConstraint construct. foreign_keys is only needed when:

    1. 由于存在多个外键引用,因此从本地表到远程表构建联接的方式不止一种。设置foreign_keys会限制relationship()来考虑这里指定为“foreign”的列。

      在版本0.8中改变:通过单独设置foreign_keys参数可以解决多外键加入歧义,而不需要明确设置primaryjoin以及。

    2. 被映射的Table实际上并没有存在ForeignKeyForeignKeyConstraint结构,这通常是因为表是从不支持外键的数据库反射(MySQL MyISAM)。
    3. primaryjoin参数用于构造非标准连接条件,该条件使用通常不引用其“父”列的列或表达式,如由复杂比较表示的连接条件使用SQL函数。

    relationship()结构会引发信息性错误消息,提示在使用模糊条件时使用foreign_keys参数。在典型情况下,如果relationship()不引发任何异常,通常不需要foreign_keys参数。

    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.

    也可以看看

    Handling Multiple Join Paths

    Creating Custom Foreign Conditions

    foreign() - allows direct annotation of the “foreign” columns within a primaryjoin condition.

    New in version 0.8: The foreign() annotation can also be applied directly to the primaryjoin expression, which is an alternate, more specific system of describing which columns in a particular primaryjoin should be considered “foreign”.

  • info -

    可选数据字典将被填充到此对象的MapperProperty.info属性中。

    0.8版本中的新功能

  • innerjoin = False -

    True时,加入的紧急加载将使用内部联接来加入相关的表而不是外部联接。这个选项的目的通常是性能之一,因为内部连接通常比外部连接执行得更好。

    当关系通过多对一的方式使用不可为空的局部外键引用对象时,或者当引用是一对一的集合或者是一对一的集合时,可以将此标志设置为True保证有一个或至少一个条目。

    该选项支持与joinedload.innerjoin相同的“嵌套”和“非引入”选项。查看该标志以获取有关嵌套/未引入行为的详细信息。

    也可以看看

    joinedload.innerjoin - 由loader选项指定的选项,包括嵌套行为的详细信息。

    What Kind of Loading to Use ? - 讨论各种装载机选项的一些细节。

  • join_depth -

    当non None时,一个整数值表示深度“渴望”加载者应该加入自我引用或循环关系的级别。该数字表示同一个映射器在特定连接分支的加载条件下应出现多少次。当缺省值为None时,急切的加载器在遇到链中已经更高的相同目标映射器时将停止链接。这个选项适用于加入和子查询的加载器。

    也可以看看

    Configuring Self-Referential Eager Loading - 介绍性文档和示例。

  • lazy ='select' -

    指定如何加载相关项目。默认值是select价值观包括:

    • select - items should be loaded lazily when the property is first accessed, using a separate SELECT statement, or identity map fetch for simple many-to-one references.
    • immediate - items should be loaded as the parents are loaded, using a separate SELECT statement, or identity map fetch for simple many-to-one references.
    • joined - 应该使用JOIN或LEFT OUTER JOIN“加入”与父项相同的查询。连接是否为“外部”由innerjoin参数确定。
    • subquery - items should be loaded “eagerly” as the parents are loaded, using one additional SQL statement, which issues a JOIN to a subquery of the original statement, for each collection requested.
    • noload - 任何时候都不应该发生负载。这是为了支持“只写”属性或以某种特定于应用程序的方式填充的属性。
    • raise - lazy loading is disallowed; accessing the attribute, if its value were not already loaded via eager loading, will raise an InvalidRequestError.

      版本1.1中的新功能

    • dynamic - 该属性将为所有读取操作返回预配置的Query对象,在迭代结果之前,可以对其应用进一步的过滤操作。有关更多详细信息,请参阅Dynamic Relationship Loaders部分。
    • 真 - “选择”的同义词
    • 假 - “加入”的同义词
    • 无 - “noload”的同义词

    也可以看看

    Relationship Loading Techniques - 完整的关系加载器配置文档。

    Dynamic Relationship Loaders - 有关dynamic选项的详细信息。

    Setting Noload, RaiseLoad - 关于“noload”和“raise”

  • load_on_pending = False -

    指示临时或挂起的父对象的加载行为。

    设置为True时,会导致lazy-loader为父对象发出一个不持久的查询,这意味着它从来没有被刷新过。当autoflush被禁用时,或者已经被“附加”到Session但不是未决集合的一部分的临时对象,这可能对未决对象有效。

    当正常使用ORM时,load_on_pending标志不会改善行为 - 对象引用应该在对象级构建,而不是在外键级上构建,以便它们以普通方式存在收益。这个标志不是一般用途的。

    也可以看看

    Session.enable_relationship_loading() - this method establishes “load on pending” behavior for the whole object, and also allows loading on objects that remain transient or detached.

  • order_by -

    指示加载这些项目时应该应用的顺序。order_by is expected to refer to one of the Column objects to which the target class is mapped, or the attribute itself bound to the target class which refers to the column.

    order_by也可以作为可调用函数传递,在映射器初始化时计算,并且在使用Declarative时可以作为Python可评估字符串传递。

  • passive_deletes = False -

    指示删除操作期间的加载行为。

    True值表示在对父级进行删除操作的过程中不应加载卸载的子项。通常情况下,删除父项时,将加载所有子项,以便可以将其标记为已删除,或将其父项的外键设置为NULL。Marking this flag as True usually implies an ON DELETE rule is in place which will handle updating/deleting child rows on the database side.

    此外,如果没有启用删除或删除孤立级联,则将该标志设置为字符串值“all”将禁用子级外键的“空出”。当数据库端出现触发或错误引发场景时,通常使用这种方法。请注意,会话子对象上的外键属性在刷新发生后将不会更改,因此这是非常特殊的用例设置。

    也可以看看

    Using Passive Deletes - 介绍性文档和示例。

  • passive_updates = True -

    指示引用主键值更改时要执行的持久性行为,指示引用外键列也将需要更改其值。

    如果为True,则假定在数据库的外键上配置了ON UPDATE CASCADE数据库将处理从源列到相关行的UPDATE传播。当False时,SQLAlchemy relationship()结构将尝试发出自己的UPDATE语句来修改相关的目标。但是请注意,SQLAlchemy 不能为多个级联发出UPDATE。而且,在数据库实际上实施参照完整性的情况下,将该标志设置为False是不兼容的,除非这些限制被明确地“推迟”,如果目标后端支持。

    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.

    也可以看看

    Mutable Primary Keys / Update Cascades - Introductory documentation and examples.

    mapper.passive_updates - 一个对连接表继承映射有效的类似标志。

  • post_update -

    这表示应该在INSERT之后或DELETE之前通过第二个UPDATE语句来处理关系。目前,它也会在实例更新后发布UPDATE,尽管这在技术上应该得到改进。这个标志用来处理保存两个单独行之间的双向依赖关系(即每个行引用另一个行),否则不可能完全插入或删除两行,因为一行在另一行之前存在。当一个特定的映射安排会产生两个相互依赖的行时,使用这个标志,比如一个与一组子行有一对多关系的表,还有一个引用一个子行的列在该列表中(即两个表都包含彼此的外键)。如果刷新操作返回一个错误,指出“循环依赖”被检测到,这是一个提示,你可能想用post_update来“打断”这个循环。

    也可以看看

    Rows that point to themselves / Mutually Dependent Rows - 介绍性文档和示例。

  • primaryjoin -

    一个将用作此子对象与父对象的主连接的SQL表达式,或者以主对象与关联表的连接的多对多关系。默认情况下,根据父表和子表(或关联表)的外键关系计算此值。

    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.

  • remote_side -

    用于自我指涉关系,表示构成关系的“远程端”的列或列的列表。

    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.

    Changed in version 0.8: The remote() annotation can also be applied directly to the primaryjoin expression, which is an alternate, more specific system of describing which columns in a particular primaryjoin should be considered “remote”.

    也可以看看

    Adjacency List Relationships - in-depth explanation of how remote_side is used to configure self-referential relationships.

    remote() - an annotation function that accomplishes the same purpose as remote_side, typically when a custom primaryjoin condition is used.

  • query_class -

    将被用作由“动态”关系返回的“appender查询”的基础的Query子类,即指定lazy="dynamic"或者使用orm.dynamic_loader()函数进行构建。

    也可以看看

    Dynamic Relationship Loaders - Introduction to “dynamic” relationship loaders.

  • secondaryjoin -

    将用作关联表与子对象的连接的SQL表达式。默认情况下,根据关联表和子表的外键关系计算此值。

    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.

  • single_parent -

    如果为True,则安装一个验证器,该验证器将一次禁止对象与多个父项关联。这是用于多对一或多对多的关系,应该被视为一对一或一对多的关系。它的用法是可选的,除relationship()结构是多对一或多对多的,还指定了delete-orphan级联选项。relationship()构造本身会引发错误,指示何时需要此选项。

    也可以看看

    Cascades - 包含single_parent标志何时适用的详细信息。

  • uselist -

    指示该属性是否应该作为列表或标量加载的布尔值。在大多数情况下,这个值是由映射器配置时的relationship()根据关系的类型和方向自动确定的 - 一对多形成一个列表,多对一形成一个标量,许多到很多是一个列表。如果希望标量在通常的列表中存在,例如双向一对一关系,则将uselist设置为False。

    uselist标志在现有的relationship()结构中也可用作只读属性,可用于确定relationship()

    >>> User.addresses.property.uselist
    True

    也可以看看

    One To One - Introduction to the “one to one” relationship pattern, which is typically when the uselist flag is needed.

  • viewonly=False – when set to True, the relationship is used only for loading objects, and not for any persistence operation. 指定viewonlyrelationship()可以用于primaryjoin条件中的更广范围的SQL操作,包括使用各种比较运算符以及SQL函数(如cast())。viewonly标志在定义任何类型的relationship()时也是通用的,它不代表完整的相关对象集合,以防止对集合进行修改在持久性操作中。
sqlalchemy.orm.backref(name, **kwargs)

使用显式关键字参数创建一个后向引用,这些参数是可以发送到relationship()的相同参数。

relationship()backref关键字参数一起使用以代替字符串参数,例如:

'items':relationship(
    SomeItem, backref=backref('parent', lazy='subquery'))
sqlalchemy.orm.relation(*arg, **kw)

relationship()的同义词。

sqlalchemy.orm.dynamic_loader(argument, **kw)

构建一个动态加载的映射器属性。

这与在relationship()中使用lazy='dynamic'参数基本相同:

dynamic_loader(SomeClass)

# is the same as

relationship(SomeClass, lazy="dynamic")

有关动态加载的更多细节,请参见Dynamic Relationship Loaders部分。

sqlalchemy.orm。 T0> 外国 T1> ( T2> EXPR T3> ) T4> ¶ T5 >

使用“外部”注释标注一个primaryjoin表达式的一部分。

有关使用说明,请参阅Creating Custom Foreign Conditions部分。

0.8版本中的新功能

sqlalchemy.orm。 T0> 远程 T1> ( T2> EXPR T3> ) T4> ¶ T5 >

使用“远程”注释标注一个primaryjoin表达式的一部分。

有关使用说明,请参阅Creating Custom Foreign Conditions部分。

0.8版本中的新功能