关系 API

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

这对应于父子关系或关联表关系。构造的类是 RelationshipProperty .

典型 relationship() ，用于经典映射：：

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

一些被接受的论点 relationship() 可选地接受一个可调用函数，当调用该函数时，它将生成所需的值。可调用由父级调用 Mapper 在“映射器初始化”时，这仅在首次使用映射器时发生，并且假定是在构造完所有映射之后发生。这可用于解决声明顺序和其他依赖关系问题，例如 Child 在下面声明 Parent 在同一个文件中：

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

当使用 声明性扩展 扩展，声明性初始值设定项允许将字符串参数传递给 relationship() . 这些字符串参数被转换为可调用文件，这些可调用文件将字符串作为python代码进行计算，并使用声明性类注册表作为命名空间。这允许通过相关类的字符串名称自动查找相关类，并消除了在声明依赖类之前将相关类导入本地模块空间的需要。仍然需要在实际使用相关映射之前将这些相关类出现在其中的模块导入应用程序中的任何位置，否则当 relationship() 尝试解析对相关类的字符串引用。字符串解析类的示例如下：

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() .

建立关系 -ORM教程介绍。

参数

• argument¶ -- 映射类，或实际类 Mapper 实例，表示关系的目标。 relationship.argument 也可以作为可调用函数传递，该函数在映射器初始化时求值，也可以在使用声明性。。警告：：在SQLAlchemy 1.3.16之前，此值使用Python的 eval() 功能。 不要将不受信任的输入传递到此字符串 . 见 关系论据的评估 有关声明性评估的详细信息 relationship() 参数。。versionchanged 1.3.16：：主“argument”的字符串计算不再接受开放式Python表达式，而只接受字符串类名或虚线包限定名。。另请参见： 配置关系 -在使用声明性时有关关系配置的进一步详细信息。

• secondary¶ -- 对于多对多关系，指定中间表，并且通常是 Table . 在不太常见的情况下，该论点也可以指定为 Alias 构造，甚至是 Join 构造。 relationship.secondary 也可以作为可调用函数传递，该函数在映射器初始化时计算。当使用声明性时，它也可以是一个字符串参数，用于记录 Table 存在于 MetaData 与映射的父级关联的集合 Table . .. 警告：：当作为Python可求值字符串传递时，将使用Python的 eval() 功能。 不要将不受信任的输入传递到此字符串 . 见 关系论据的评估 有关声明性评估的详细信息 relationship() 论据。这个 relationship.secondary 关键字参数通常应用于中介 Table 不以其他方式在任何直接类映射中表示。如果“secondary”表也显式映射到其他地方（例如 关联对象 ）应该考虑应用 relationship.viewonly 标记以便 relationship() 不用于可能与关联对象模式冲突的持久性操作。。另请参见： 多对多 -“多对多”的参考示例。 建立多对多关系 -ORM教程介绍多对多关系。 自指多对多关系 -在自我参照案例中使用多对多的细节。 配置多对多关系 -使用声明性时的其他选项。 关联对象 -替代 relationship.secondary 当组成关联表关系时，允许在关联表上指定其他属性。 复合“二次”连接 -在某些情况下可以使复杂 relationship() 要使用的SQL条件。…添加的版本：0.9.2 relationship.secondary 当提到 Join 实例。

• active_history=False¶ -- 什么时候？ True ，表示如果尚未加载，则在替换时应加载多对一引用的“上一个”值。通常，简单的多对一的历史跟踪逻辑只需要知道“新”值就可以执行刷新。此标志可用于使用 get_history() 它还需要知道属性的“上一个”值。

• backref¶ -- 指示要放置在相关映射器类上的属性的字符串名称，该类将在另一个方向上处理此关系。另一个属性将在配置映射器时自动创建。也可以作为 backref() 对象来控制新关系的配置。…参阅： 链接与backref的关系 -介绍性文件和示例。 relationship.back_populates -backref规范的替代形式。 backref() -允许控制 relationship() 使用时的配置 relationship.backref .

• back_populates¶ -- 采用字符串名称，其含义与 relationship.backref ，除了补充属性是 not 自动创建，而必须在另一个映射器上显式配置。补充属性还应指明 relationship.back_populates 以确保正常运转。…参阅： 链接与backref的关系 -介绍性文件和示例。 relationship.backref -backref规范的替代形式。

• overlaps¶ -- 此映射器、子代映射器或目标映射器上的其他关系的字符串名称或逗号分隔的名称集，此关系可在持久化时使用这些名称写入相同的外键。这样做的唯一效果是消除了这样的警告，即此关系将在持久化时与另一个关系冲突。这用于这样的关系，这些关系在写入时确实能够相互冲突，但应用程序将确保不会发生这样的冲突。。。版本已添加：：1.4..另请参阅：： 关系X会将列Q复制到列P，这与关系冲突：‘Y’ -使用示例

• bake_queries=True¶ -- 启用 lambda caching 对于加载器策略，如果适用，除了在整个SQLAlChemy中使用的常用SQL语句缓存之外，这还可以为加载器策略使用的SQL结构的构造增加性能。此参数当前仅适用于“惰性”和“选择”加载器策略。通常没有理由将此参数设置为False。。。VersionChanged：：1.4关系加载器不再使用以前的“烘焙查询”查询缓存系统。“懒惰”和“选择”加载器使用“lambda cache”系统来构造SQL构造，以及从1.4系列开始贯穿整个SQLAlChemy的常用SQL缓存系统。“lazy”和“selectin”加载器使用“lambda cache”系统来构造SQL构造，以及从1.4系列开始贯穿整个SQLAlChemy的常用SQL缓存系统。

• cascade¶ -- 以逗号分隔的级联规则列表，用于确定会话操作应如何从父级“级联”到子级。默认为 False ，这意味着应该使用默认层叠-此默认层叠是 "save-update, merge" . 可用的层叠是 save-update ， merge ， expunge ， delete ， delete-orphan 和 refresh-expire . 一个附加选项， all 表示缩写 "save-update, merge, refresh-expire, expunge, delete" ，通常用于 "all, delete-orphan" 指示相关对象在所有情况下都应跟随父对象，并在取消关联时删除。…参阅： 级联 -所有可用级联选项的详细信息。 配置删除/删除孤立级联 -描述删除层叠的教程示例。

• cascade_backrefs=True¶ -- 一个布尔值，指示 save-update cascade应该沿着backref截获的分配事件进行操作。当设置为 False ，如果事件是通过backref接收的，则此关系管理的属性不会将传入的瞬态对象级联到持久父对象的会话中。。已弃用：：1.4 relationship.cascade_backrefs 在SQLAlchemy 2.0中的所有情况下，标志都将默认为False。。另请参见： 在backrefs上控制级联 -充分讨论并举例说明 relationship.cascade_backrefs 使用选项。

• collection_class¶ -- 返回一个新的列表保存对象的类或可调用的类。将被用来代替普通列表来存储元素。。另请参见： 自定义集合访问 -介绍性文件和示例。

• comparator_factory¶ -- 扩展的类 Comparator 它为比较操作提供自定义SQL子句生成。…参阅： PropComparator -关于在这个级别重新定义比较器的一些细节。 操作员自定义 -简要介绍此功能。

• distinct_target_key=None¶ -- 指示“subquery”抢先加载是否应将distinct关键字应用于最内层的select语句。什么时候离开 None 当目标列不包含目标表的完整主键时，将应用distinct关键字。当设置为 True ，distinct关键字将无条件应用于最内部的select。如果distinct降低了最内层子查询的性能，使其超过了最内层重复行可能导致的性能，则可能需要将此标志设置为false。…版本更改：：0.9.0- relationship.distinct_target_key 现在默认为 None ，以便在最里面的查询针对非唯一键的情况下，该特性自动启用自己。…参阅： 关系加载技术 -包括子查询预加载的介绍。

• doc¶ -- 将应用于结果描述符的Docstring。

• foreign_keys¶ --

  “列”是指列的外部或列的值 relationship() 对象的 relationship.primaryjoin 条件。也就是说，如果 relationship.primaryjoin 条件 relationship() 是 a.id == b.a_id 和中的值 b.a_id 必须存在于 a.id ，然后是这个的“外键”列 relationship() 是 b.a_id .

  在正常情况下， relationship.foreign_keys 参数是 不需要。 relationship() 将自动确定 relationship.primaryjoin 条件将被视为基于这些条件的“外键”列 Column 指定的对象 ForeignKey 或以其他方式列为引用列 ForeignKeyConstraint 构造。 relationship.foreign_keys 仅在以下情况下需要：

  1. 有多种方法可以从本地表构造到远程表的联接，因为存在多个外键引用。设置 foreign_keys 将限制 relationship() 只考虑这里指定为“外国”的列。

  2. 这个 Table 被映射实际上没有 ForeignKey 或 ForeignKeyConstraint 存在构造，通常是因为表是从不支持外键反射（mysql myisam）的数据库反射的。

  3. 这个 relationship.primaryjoin 参数用于构造非标准联接条件，该条件使用通常不引用其“父”列的列或表达式，例如通过使用SQL函数的复杂比较表示的联接条件。

  这个 relationship() 构造将引发信息性错误消息，建议使用 relationship.foreign_keys 参数出现不明确的条件时。在典型情况下，如果 relationship() 不会引发任何异常， relationship.foreign_keys 通常不需要参数。

  relationship.foreign_keys 也可以作为可调用函数传递，该函数在映射器初始化时进行计算，并且在使用声明性时可以作为python可计算字符串传递。

  警告

  当作为Python可求值字符串传递时，将使用Python的 eval() 功能。 不要将不受信任的输入传递到此字符串 . 见 关系论据的评估 有关声明性评估的详细信息 relationship() 争论。

  参见

  处理多个连接路径

  创造习惯性的国外条件

  foreign() -允许直接批注 relationship.primaryjoin 条件。

• info¶ -- 可选数据字典，将填充到 MapperProperty.info 此对象的属性。

• innerjoin=False¶ -- 什么时候？ True ，联接的热切加载将使用内部联接来针对相关表而不是外部联接进行联接。此选项的目的通常是性能之一，因为内部联接通常比外部联接性能更好。此标志可以设置为 True 当关系使用不可为空的本地外键通过多对一引用对象时，或者当引用是一对一或保证有一个或至少一个条目的集合时。该选项支持与以下选项相同的“嵌套”和“未列出”选项 joinedload.innerjoin . 有关嵌套/未嵌套行为的详细信息，请参见该标志。…参阅： joinedload.innerjoin -由加载程序选项指定的选项，包括嵌套行为的详细信息。 使用哪种装载？ -讨论各种加载程序选项的一些细节。

• join_depth¶ -- 非“None”时，一个整数值，指示在一个自引用或循环关系中，深度为“eager”的加载程序应加入多少层。该数字计算在加载条件下同一映射器在特定连接分支上出现的次数。当保留默认值时 None 当他们遇到一个已经在链中更高的目标映射器时，热切的加载程序将停止链接。此选项同时适用于连接的和子查询的预加载程序。…参阅： 配置自引用预加载 -介绍性文件和示例。

• 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 -应在加载父项时加载项，使用单独的select语句，或为简单的多对一引用获取标识映射。 * joined - items should be loaded "eagerly" in the same query as that of the parent, using a JOIN or LEFT OUTER JOIN. Whether the join is "outer" or not is determined by the relationship.innerjoin parameter. * subquery -当父级被加载时，应该使用一条附加的SQL语句“急切地”加载项，该语句为每个请求的集合发出到原始语句的子查询的联接。 * selectin - items should be loaded "eagerly" as the parents are loaded, using one or more additional SQL statements, which issues a JOIN to the immediate parent object, specifying primary key identifiers using an IN clause. .. versionadded:: 1.2 * noload -任何时候都不应加载。这是为了支持“只写”属性，或者以特定于应用程序的某种方式填充的属性。 * raise - lazy loading is disallowed; accessing the attribute, if its value were not already loaded via eager loading, will raise an InvalidRequestError. This strategy can be used when objects are to be detached from their attached Session after they are loaded. .. versionadded:: 1.1 * raise_on_sql -不允许延迟加载发出SQL；如果属性的值尚未通过预先加载加载加载，则访问该属性将引发 InvalidRequestError ， 如果惰性负载需要发出SQL . 如果延迟加载可以从标识映射中提取相关值，或者确定该值应为“无”，则会加载该值。当对象将与附加的 Session 但是，应阻止其他select语句。…添加的版本：1.1 * dynamic - the attribute will return a pre-configured Query object for all read operations, onto which further filtering operations can be applied before iterating the results. See the section 动态关系加载器 for more details. * true-是“select”的同义词 * False - a synonym for 'joined' * 无-是“noload”的同义词。参阅： 关系加载技术 -有关关系加载器配置的完整文档。 动态关系加载器 -详述 dynamic 选择权。 设置无负载，raiseload -关于“无负荷”和“提高”的注释

• load_on_pending=False¶ -- 指示临时或挂起父对象的加载行为。当设置为 True ，使懒惰加载程序为非持久性的父对象发出查询，这意味着它从未被刷新。当禁用自动刷新时，这可能对挂起的对象生效，或者对已“附加”到 Session 但不是其挂起集合的一部分。这个 relationship.load_on_pending 标志不能改善通常使用ORM时的行为-对象引用应该在对象级别而不是在外键级别构造，以便在刷新进行之前以普通方式存在。此标志不用于一般用途。…参阅： Session.enable_relationship_loading() -此方法为整个对象建立“挂起时加载”行为，并允许加载保持瞬时或分离的对象。

• order_by¶ -- 指示加载这些项时应应用的顺序。 relationship.order_by 应引用 Column 目标类映射到的对象，或属性本身绑定到引用该列的目标类。 relationship.order_by 也可以作为可调用函数传递，该函数在映射器初始化时计算，也可以在使用声明性时作为Python可计算字符串传递。。警告：：当作为Python可求值字符串传递时，将使用Python的 eval() 功能。 不要将不受信任的输入传递到此字符串 . 见 关系论据的评估 有关声明性评估的详细信息 relationship() 争论。

• passive_deletes=False¶ -- 指示删除操作期间的加载行为。值为true表示在对父级执行删除操作期间不应加载已卸载的子项。通常，删除父项时，会加载所有子项，以便可以将其标记为已删除，或者将其对父项的外键设置为空。将此标志标记为“真”通常意味着存在“on delete<cascade_set null>规则”，该规则将处理数据库端的更新/删除子行。此外，如果父对象被删除，并且没有启用删除或删除孤立级联，则将标志设置为字符串值“all”将禁用子外键的“注销”。这通常在数据库端有触发或错误引发方案时使用。注意，在发生刷新之后，会话内子对象的外键属性将不会被更改，因此这是一个非常特殊的用例设置。此外，如果子对象与父对象取消关联，则仍然会发生“注销”。…参阅： 在具有ORM关系的DELETE cascade中使用外键 -介绍性文件和示例。

• passive_updates=True¶ -- 指示当引用的主键值就地更改时要采取的持久性行为，指示引用的外键列也需要更改其值。如果为真，则假定 ON UPDATE CASCADE 在数据库中的外键上配置，数据库将处理从源列到依赖行的更新传播。如果为false，则为sqlAlchemy relationship() 构造将尝试发出自己的更新语句来修改相关目标。但是请注意，sqlAlchemy 不能 为多个层叠级别发出更新。此外，如果数据库实际上正在强制引用完整性，那么将此标志设置为false是不兼容的，除非这些约束在目标后端支持时显式地“延迟”。强烈建议使用可变主键的应用程序保留 passive_updates 设置为true，而是使用数据库本身的引用完整性功能，以便高效、全面地处理更改。…参阅： 可变主键/更新级联 -介绍性文件和示例。 mapper.passive_updates -对联接表继承映射生效的类似标志。

• post_update¶ -- 这表示在INSERT之后或DELETE之前应该由第二个UPDATE语句处理关系。目前，它也会在实例更新后发布更新，尽管这在技术上还需要改进。此标志用于处理保存两行之间的双向依赖关系（即每行引用另一行），否则无法完全插入或删除两行，因为一行在另一行之前存在。当特定的映射安排将产生两个相互依赖的行时，使用此标志，例如与一组子行有一对多关系的表，并且有一列引用该列表中的一个子行（即两个表都包含彼此的外键）。如果flush操作返回检测到“循环依赖”的错误，则这是一个您可能需要使用的提示 relationship.post_update 打破这个循环。…参阅： 指向自身/相互依赖的行的行 -介绍性文件和示例。

• primaryjoin¶ -- 一个SQL表达式，将用作子对象对父对象的主联接，或在多对多关系中，将父对象与关联表的联接。默认情况下，此值是根据父表和子表（或关联表）的外键关系计算的。 relationship.primaryjoin 也可以作为可调用函数传递，该函数在映射器初始化时计算，也可以在使用声明性时作为Python可计算字符串传递。。警告：：当作为Python可求值字符串传递时，将使用Python的 eval() 功能。 不要将不受信任的输入传递到此字符串 . 见 关系论据的评估 有关声明性评估的详细信息 relationship() 参数。。另请参见： 指定备用联接条件

• remote_side¶ -- 用于自引用关系，指示构成关系“远程端”的列或列列表。 relationship.remote_side 也可以作为可调用函数传递，该函数在映射器初始化时计算，也可以在使用声明性时作为Python可计算字符串传递。。警告：：当作为Python可求值字符串传递时，将使用Python的 eval() 功能。 不要将不受信任的输入传递到此字符串 . 见 关系论据的评估 有关声明性评估的详细信息 relationship() 参数。。另请参见： 相邻列表关系 -深入讲解如何 relationship.remote_side 用于配置自引用关系。 remote() -一种注释函数，其作用与 relationship.remote_side ，通常在 relationship.primaryjoin 使用条件。

• query_class¶ -- A Query 将在内部使用的子类 AppenderQuery 由“动态”关系返回，即指定 lazy="dynamic" 或以其他方式使用 dynamic_loader() 功能。。。另请参阅：： 动态关系加载器 -介绍“动态”关系加载器。

• secondaryjoin¶ -- 将用作关联表与子对象的联接的SQL表达式。默认情况下，此值是根据关联表和子表的外键关系计算的。 relationship.secondaryjoin 也可以作为可调用函数传递，该函数在映射器初始化时计算，也可以在使用声明性时作为Python可计算字符串传递。。警告：：当作为Python可求值字符串传递时，将使用Python的 eval() 功能。 不要将不受信任的输入传递到此字符串 . 见 关系论据的评估 有关声明性评估的详细信息 relationship() 参数。。另请参见： 指定备用联接条件

• single_parent¶ -- 如果为True，则安装一个验证器，该验证器将防止对象一次与多个父对象关联。这用于多对一或多对多的关系，这些关系应被视为一对一或一对多。它的用法是可选的，除了 relationship() 构造多对一或多对多，还指定 delete-orphan 层叠选项。这个 relationship() 构造本身将在需要此选项时引发错误指示。…参阅： 级联 -包括有关何时 relationship.single_parent 标志可能是适当的。

• uselist¶ -- 一个布尔值，指示此属性应作为列表还是标量加载。在大多数情况下，该值由 relationship() 在映射器配置时，根据关系的类型和方向-一对多形成一个列表，多对一形成一个标量，多对多形成一个列表。如果需要一个标量，通常会出现一个列表，例如双向一对一关系，则设置 relationship.uselist 错了。这个 relationship.uselist 标志也可用于现有的 relationship() 构造为只读属性，该属性可用于确定 relationship() 处理集合或标量属性：：>>>user.addresses.property.useList true..参阅： 一对一 -介绍“一对一”关系模式，这通常是 relationship.uselist 需要旗帜。

• viewonly=False¶ -- 当设置为 True 不用于任何对象的持久性操作。A relationship() 其中指定 relationship.viewonly 可以在 relationship.primaryjoin 条件，包括使用各种比较运算符以及SQL函数（如 cast() . 这个 relationship.viewonly 在定义任何类型的 relationship() 它不代表完整的相关对象集，以防止对集合的修改导致持久性操作。当使用 relationship.viewonly 标志与backrefs结合使用时，特定状态更改的原始关系将不会在viewonly关系中产生状态更改。这是由 relationship.sync_backref 设置为False。。版本更改：：1.3.17- relationship.sync_backref 当将viewonly与backrefs结合使用时，标志设置为False。。另请参见： relationship.sync_backref

• sync_backref¶ -- 一个布尔值，当此关系为目标时，启用用于同步Python中属性的事件 relationship.backref 或 relationship.back_populates . 默认为 None ，表示应根据的值选择自动值 relationship.viewonly 旗子。当保留为默认值时，只有当关系的任何一方都不可见时，状态更改才会重新填充。。版本添加：：1.3.17。。versionchanged:：1.4-指定 relationship.viewonly 自动暗示 relationship.sync_backref 是 False . …参阅： relationship.viewonly

• omit_join¶ -- 允许手动控制“selectin”自动连接优化。设置为 False 禁用SQLAlchemy 1.3中添加的“忽略联接”功能；或保留为 None 让自动优化留在原地。。注意：此标志只能设置为 False . 没有必要将其设置为 True 因为自动检测到“省略连接”优化；如果未检测到，则不支持优化。。versionchanged:：1.3.11设置 omit_join 如果设置为True，则会发出警告，因为这不是此标志的预期用途。。版本添加：：1.3

使用显式关键字参数创建反向引用，这些参数与可以发送到的参数相同 relationship() .

与之一起使用 backref 关键字参数 relationship() 代替字符串参数，例如：

'items':relationship(
    SomeItem, backref=backref('parent', lazy='subquery'))

参见

链接与backref的关系

同义词 relationship() .

1.4 版后已移除: 关系构造被认为是SQLAlchemy 1.x系列的遗留部分，将在2.0中删除。请使用 relationship() . （SQLAlchemy 2.0的背景： 迁移到Alchemy ）

构造动态加载映射器属性。

这与使用 lazy='dynamic' 争论与 relationship() ：：

dynamic_loader(SomeClass)

# is the same as

relationship(SomeClass, lazy="dynamic")

见剖面图 动态关系加载器 有关动态加载的详细信息。

用“foreign”批注对primaryjoin表达式的一部分进行批注。

见剖面图 创造习惯性的国外条件 用于描述用途。

参见

创造习惯性的国外条件

remote()

用“远程”批注对PrimaryJoin表达式的一部分进行批注。

见剖面图 创造习惯性的国外条件 用于描述用途。

参见

创造习惯性的国外条件

foreign()