关系 API

对象名称	描述
backref(name, **kwargs)	当使用 relationship.backref 参数时，提供用于生成新的 relationship() 的特定参数。
dynamic_loader([argument], **kw)	构造一个动态加载的映射器属性。
foreign(expr)	用“外键”注解标记 primaryjoin 表达式的一部分。
relationship([argument, secondary], *, [uselist, collection_class, primaryjoin, secondaryjoin, back_populates, order_by, backref, overlaps, post_update, cascade, viewonly, init, repr, default, default_factory, compare, kw_only, hash, lazy, passive_deletes, passive_updates, active_history, enable_typechecks, foreign_keys, remote_side, join_depth, comparator_factory, single_parent, innerjoin, distinct_target_key, load_on_pending, query_class, info, omit_join, sync_backref], **kw)	在两个映射类之间建立关系。
remote(expr)	用“远程”注解标记 primaryjoin 表达式的一部分。

function sqlalchemy.orm.relationship(argument: _RelationshipArgumentType[Any] | None = None, secondary: _RelationshipSecondaryArgument | None = None, *, uselist: bool | None = None, collection_class: Type[Collection[Any]] | Callable[[], Collection[Any]] | None = None, primaryjoin: _RelationshipJoinConditionArgument | None = None, secondaryjoin: _RelationshipJoinConditionArgument | None = None, back_populates: str | None = None, order_by: _ORMOrderByArgument = False, backref: ORMBackrefArgument | None = None, overlaps: str | None = None, post_update: bool = False, cascade: str = 'save-update, merge', viewonly: bool = False, init: _NoArg | bool = _NoArg.NO_ARG, repr: _NoArg | bool = _NoArg.NO_ARG, default: _NoArg | _T = _NoArg.NO_ARG, default_factory: _NoArg | Callable[[], _T] = _NoArg.NO_ARG, compare: _NoArg | bool = _NoArg.NO_ARG, kw_only: _NoArg | bool = _NoArg.NO_ARG, hash: _NoArg | bool | None = _NoArg.NO_ARG, lazy: _LazyLoadArgumentType = 'select', passive_deletes: Literal['all'] | bool = False, passive_updates: bool = True, active_history: bool = False, enable_typechecks: bool = True, foreign_keys: _ORMColCollectionArgument | None = None, remote_side: _ORMColCollectionArgument | None = None, join_depth: int | None = None, comparator_factory: Type[RelationshipProperty.Comparator[Any]] | None = None, single_parent: bool = False, innerjoin: bool = False, distinct_target_key: bool | None = None, load_on_pending: bool = False, query_class: Type[Query[Any]] | None = None, info: _InfoType | None = None, omit_join: Literal[None, False] = None, sync_backref: bool | None = None, **kw: Any) → _RelationshipDeclared[Any]

在两个映射类之间建立关系。

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

另请参见

使用 ORM 关联对象 - SQLAlchemy 统一教程 中对 relationship() 的教程介绍

关系配置 - 叙述性文档

参数:

• argument –

  此参数引用要关联的类。它接受多种形式，包括对目标类的直接引用，目标类的 Mapper 实例，一个当被调用时会返回类或 Mapper 引用的 Python 可调用对象/lambda 表达式，以及最后是类的字符串名称，该名称将从正在使用的 registry 中解析以定位该类，例如

  class SomeClass(Base):
      # ...
  
      related = relationship("RelatedClass")

  relationship.argument 也可能完全从 relationship() 构造中省略，而是放在左侧的 Mapped 注解中，该注解应包含一个 Python 集合类型，如果该关系预期是一个集合，例如

  class SomeClass(Base):
      # ...
  
      related_items: Mapped[List["RelatedItem"]] = relationship()

  或对于多对一或一对一关系

  class SomeClass(Base):
      # ...
  
      related_item: Mapped["RelatedItem"] = relationship()

  另请参见

  使用 Declarative 定义映射属性 - 使用 Declarative 配置关系的更多细节。

• secondary –

  对于多对多关系，指定中间表，通常是 Table 的实例。在不太常见的情况下，该参数也可以指定为 Alias 构造，甚至可以指定为 Join 构造。

  relationship.secondary 也可以作为在映射器初始化时评估的可调用函数传递。当使用 Declarative 时，它也可以是一个字符串参数，表示与父级映射的 Table 关联的 MetaData 集合中存在的 Table 的名称。

  警告

  当作为可执行的 Python 字符串传递时，该参数将使用 Python 的 eval() 函数解释。不要将不可信的输入传递给此字符串。有关 Declarative 评估 relationship() 参数的详细信息，请参见 关系参数的评估。

  relationship.secondary 关键字参数通常应用于中间 Table 在其他任何直接类映射中都没有表达的情况下。如果“secondary”表在其他地方也显式映射（例如，如 关联对象 中那样），应该考虑应用 relationship.viewonly 标志，以便此 relationship() 不用于可能与关联对象模式冲突的持久化操作。

  另请参见

  多对多 - “多对多”的参考示例。

  自引用多对多关系 - 关于在自引用情况下使用多对多的具体细节。

  配置多对多关系 - 使用 Declarative 时的附加选项。

  关联对象 - 当组合关联表关系时，relationship.secondary 的一种替代方法，允许在关联表上指定其他属性。

  复合“secondary”联接 - 一种不太常用的模式，它可以在某些情况下使复杂的 relationship() SQL 条件能够使用。

• active_history=False – 当为 True 时，表示在替换多对一引用时，如果尚未加载，则应加载该引用的“前一个”值。通常，简单多对一的历史跟踪逻辑只需要了解“新”值才能执行刷新。此标志适用于使用 get_history() 并且还需要了解属性的“前一个”值的应用程序。

• backref –

  这是一个指向字符串关系名的引用，或者一个 backref() 构造，它将用于自动在相关类上生成一个新的 relationship()，然后使用双向 relationship.back_populates 配置引用此类。

  在现代 Python 中，应该优先使用 relationship() 与 relationship.back_populates 的显式使用，因为它在映射器配置方面更健壮，概念上也更直观。它还与 SQLAlchemy 2.0 中引入的新的 PEP 484 类型功能集成，而动态生成的属性无法做到这一点。

  另请参见

  使用遗留的“backref”关系参数 - 关于使用 relationship.backref 的说明

  使用 ORM 相关对象 - 在 SQLAlchemy 统一教程 中，介绍了使用 relationship.back_populates 的双向关系配置和行为概述。

  backref() - 允许在使用 relationship.backref 时控制 relationship() 配置。

• back_populates –

  指示相关类上 relationship() 的名称，该关系将与当前关系同步。通常期望相关类上的 relationship() 也引用此关系。这允许每个 relationship() 两侧的对象同步 Python 状态更改，并为 工作单元 刷新过程提供指令，说明如何持久化这些关系的更改。

  另请参见

  使用 ORM 相关对象 - 在 SQLAlchemy 统一教程 中，介绍了双向关系配置和行为概述。

  基本关系模式 - 包含许多 relationship.back_populates 的示例。

  relationship.backref - 遗留形式，允许更简洁的配置，但不支持显式类型化

• overlaps –

  一个字符串名称或逗号分隔的名称集，代表此映射器、后代映射器或目标映射器上的其他关系，这些关系在持久化时可能写入相同的外部键。这唯一的作用是消除关于此关系在持久化时将与另一个关系发生冲突的警告。这用于那些确实有可能在写入时彼此发生冲突的关系，但应用程序将确保不会发生此类冲突。

  新功能：版本 1.4。

  另请参见

  关系 X 将将列 Q 复制到列 P，这与关系“Y”发生冲突 - 用例示例

• cascade –

  一个逗号分隔的级联规则列表，用于确定如何将 Session 操作从父级级联到子级。默认值为 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=False –

  遗留；此标志始终为 False。

  更改于版本 2.0: “cascade_backrefs” 功能已移除。

• collection_class –

  一个类或可调用对象，用于返回一个新的列表持有对象。将用于代替普通列表来存储元素。

  另请参见

  自定义集合访问 - 简介和示例。

• comparator_factory –

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

  另请参见

  PropComparator - 关于在此级别重新定义比较器的部分详细信息。

  运算符自定义 - 此功能的简要介绍。

• distinct_target_key=None –

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

  当 DISTINCT 降低最里面子查询的性能，超过重复最里面行的性能下降时，可能需要将此标志设置为 False。

  另请参见

  关系加载技术 - 包含对子查询急切加载的介绍。

• doc – 将应用于生成的描述符的文档字符串。

• foreign_keys –

  用于作为“外键”列的列列表，或在当前 relationship() 对象的 relationship.primaryjoin 条件下引用远程列中值的列。也就是说，如果当前 relationship() 的 relationship.primaryjoin 条件是 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() 函数解释。不要将不可信的输入传递给此字符串。有关 Declarative 评估 relationship() 参数的详细信息，请参见 关系参数的评估。

  另请参见

  处理多个联接路径

  创建自定义外键条件

  foreign() - 允许在 relationship.primaryjoin 条件中直接注释“外键”列。

• info – 可选的数据字典，它将被填充到该对象的 MapperProperty.info 属性中。

• innerjoin=False –

  当为 True 时，联接式预加载将使用内联接来联接相关表，而不是外联接。此选项的目的通常是性能，因为内联接通常比外联接性能更好。

  当关系通过使用不可为空的本地外键的多数对一方式引用对象，或当引用是一对一或保证至少包含一个条目的集合时，此标志可以设置为 True。

  该选项支持与 joinedload.innerjoin 相同的“嵌套”和“非嵌套”选项。有关嵌套/非嵌套行为的详细信息，请参阅该标志。

  另请参见

  joinedload.innerjoin - 由加载器选项指定的选项，包括有关嵌套行为的详细信息。

  应该使用哪种加载方式？ - 关于各种加载器选项的一些详细信息的讨论。

• join_depth –

  当不为 None 时，表示“预加载”加载器应在自引用或循环关系上联接多少层的整数。该数字计算了相同映射器在特定联接分支上的加载条件中出现的次数。当保留为默认值 None 时，预加载器将在遇到已在链条中更高位置存在的相同目标映射器时停止链接。此选项适用于联接式和子查询式预加载器。

  另请参见

  配置自引用式预加载 - 介绍性文档和示例。

• lazy='select' –

  指定如何加载相关项目。默认值为 select。值包括：

  • select - 项目应在首次访问属性时延迟加载，使用单独的 SELECT 语句，或使用标识映射获取简单多数对一引用。

  • immediate - 项目应在加载父对象时加载，使用单独的 SELECT 语句，或使用标识映射获取简单多数对一引用。

  • joined - 项目应与父对象在同一个查询中“预加载”，使用 JOIN 或 LEFT OUTER JOIN。联接是“外联接”还是“内联接”由 relationship.innerjoin 参数决定。

  • subquery - 项目应在加载父对象时“预加载”，使用一个额外的 SQL 语句，该语句为每个请求的集合发出对原始语句的子查询的 JOIN。

  • selectin - 项目应在加载父对象时“预加载”，使用一个或多个额外的 SQL 语句，该语句发出对直接父对象的 JOIN，使用 IN 子句指定主键标识符。

  • noload - 任何时候都不应加载。相关集合将保持为空。不推荐将 noload 策略用于一般用途。有关一般用途的“从不加载”方法，请参阅 只写关系

  • raise - 禁止延迟加载；访问属性（如果其值尚未通过急切加载加载）将引发 InvalidRequestError。此策略可用于在对象加载后将其从关联的 Session 中分离。

  • raise_on_sql - 禁止发出 SQL 的延迟加载；访问属性（如果其值尚未通过急切加载加载）将引发 InvalidRequestError，如果延迟加载需要发出 SQL。如果延迟加载可以从标识映射中获取相关值或确定它应该是 None，则加载该值。此策略可用于当对象将保持与关联的 Session 关联时，但应阻止额外的 SELECT 语句。

  • write_only - 该属性将使用特殊的“虚拟集合”进行配置，该集合可以接收 WriteOnlyCollection.add() 和 WriteOnlyCollection.remove() 命令来添加或删除单个对象，但在任何情况下都不会直接从数据库加载或迭代完整的对象集。相反，提供了诸如 WriteOnlyCollection.select()、WriteOnlyCollection.insert()、WriteOnlyCollection.update() 和 WriteOnlyCollection.delete() 的方法，这些方法生成可用于批量加载和修改行的 SQL 结构。用于从不适合一次加载到内存中的大型集合。

    当在声明性映射中的左侧提供 WriteOnlyMapped 注释时，将自动配置 write_only 加载器样式。有关示例，请参见 写只关系 部分。

    版本 2.0 中的新增功能。

    另请参见

    写只关系 - 在 ORM 查询指南 中

  • dynamic - 该属性将为所有读取操作返回一个预先配置的 Query 对象，可以在迭代结果之前对该对象应用进一步的过滤操作。

    当在声明性映射中的左侧提供 DynamicMapped 注释时，将自动配置 dynamic 加载器样式。有关示例，请参见 动态关系加载器 部分。

    遗留功能

    “动态”延迟加载策略是现在 写只关系 部分中描述的“写只”策略的遗留形式。

    另请参见

    动态关系加载器 - 在 ORM 查询指南 中

    写只关系 - 对于不应该完全加载到内存中的大型集合，更普遍实用的方法

  • True - “select” 的同义词

  • False - “joined” 的同义词

  • None - “noload” 的同义词

  另请参见

  关系加载技术 - ORM 查询指南 中关系加载器配置的完整文档。

• 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() 函数解释。不要将不可信的输入传递给此字符串。有关 Declarative 评估 relationship() 参数的详细信息，请参见 关系参数的评估。

• passive_deletes=False –

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

  值为 True 表示在对父项进行删除操作时，不应该加载未加载的子项。通常，当父项被删除时，所有子项都会被加载，以便它们可以被标记为已删除，或者它们的父项外键被设置为 NULL。将此标志标记为 True 通常意味着 ON DELETE <CASCADE|SET NULL> 规则已就位，它将在数据库端处理更新/删除子行。如果此标志设置为字符串值“all”，则在父对象被删除并且没有启用删除或删除孤儿级联时，将禁用对子外键的“设置为空”。这通常用于在数据库端存在触发或错误引发场景时使用。请注意，在刷新发生后，会话中子对象上的外键属性不会更改，因此这是一个非常特殊的用例设置。此外，如果子对象与父对象分离，则“设置为空”仍然会发生。

  此外，将标志设置为字符串值“all”将禁用对子外键的“设置为空”，当父对象被删除并且没有启用删除或删除孤儿级联时。这通常用于在数据库端存在触发或错误引发场景时使用。请注意，在刷新发生后，会话中子对象上的外键属性不会更改，因此这是一个非常特殊的用例设置。此外，如果子对象与父对象分离，则“设置为空”仍然会发生。

  另请参见

  在 ORM 关系中使用外键 ON DELETE 级联 - 入门文档和示例。

• passive_updates=True –

  指示当引用主鍵值就地更改时要采取的持久性行为，这表明引用外键列也需要更改其值。

  当为 True 时，假设在数据库中的外键上配置了 ON UPDATE CASCADE，并且数据库将处理从源列到依赖行的 UPDATE 的传播。当为 False 时，SQLAlchemy relationship() 结构将尝试发出自己的 UPDATE 语句来修改相关目标。但是请注意，SQLAlchemy 不能为超过一个级别的级联发出 UPDATE。此外，如果数据库实际上正在强制执行引用完整性，则将此标志设置为 False 与之不兼容，除非显式地“延迟”这些约束（如果目标后端支持）。

  强烈建议采用可变主鍵的应用程序将 passive_updates 设置为 True，而是使用数据库本身的引用完整性功能来有效且完全地处理更改。

  另请参见

  可变主鍵 / 更新级联 - 入门文档和示例。

  mapper.passive_updates - 对联接表继承映射起作用的类似标志。

• post_update –

  这表示该关系应在 INSERT 之后或 DELETE 之前由第二个 UPDATE 语句处理。此标志用于处理两行之间双向依赖关系的保存（即，每行都引用另一行），否则由于一行在另一行之前存在，因此无法完全 INSERT 或 DELETE 两行。当特定映射安排将导致两行相互依赖时使用此标志，例如一个表与一组子行具有多对一的关系，并且还具有一个列引用该列表中的单个子行（即，两个表都包含彼此的外部键）。如果刷新操作返回一个错误，指示检测到“循环依赖”，则这是一个提示，您可能想要使用 relationship.post_update 来“打破”循环。

  另请参见

  指向自身的行/相互依赖的行 - 简介和示例。

• primaryjoin –

  一个 SQL 表达式，将用作子对象与父对象的 primary join，或者在多对多关系中，用作父对象与关联表的 join。默认情况下，此值根据父表和子表（或关联表）的外键关系计算得出。

  relationship.primaryjoin 也可以作为在映射器初始化时评估的可调用函数传递，并且在使用 Declarative 时可以作为可由 Python 评估的字符串传递。

  警告

  当作为可执行的 Python 字符串传递时，该参数将使用 Python 的 eval() 函数解释。不要将不可信的输入传递给此字符串。有关 Declarative 评估 relationship() 参数的详细信息，请参见 关系参数的评估。

  另请参见

  指定备用连接条件

• remote_side –

  用于自引用关系，指示构成关系“远程端”的列或列列表。

  relationship.remote_side 也可以作为在映射器初始化时评估的可调用函数传递，并且在使用 Declarative 时可以作为可由 Python 评估的字符串传递。

  警告

  当作为可执行的 Python 字符串传递时，该参数将使用 Python 的 eval() 函数解释。不要将不可信的输入传递给此字符串。有关 Declarative 评估 relationship() 参数的详细信息，请参见 关系参数的评估。

  另请参见

  邻接列表关系 - 详细说明 relationship.remote_side 如何用于配置自引用关系。

  remote() - 一个注释函数，它实现了与 relationship.remote_side 相同的目的，通常是在使用自定义 relationship.primaryjoin 条件时。

• query_class –

  一个 Query 子类，它将由“动态”关系返回的 AppenderQuery 在内部使用，即一个指定 lazy="dynamic" 或者使用 dynamic_loader() 函数构建的关系。

  另请参见

  动态关系加载器 - “动态”关系加载器的介绍。

• secondaryjoin –

  一个 SQL 表达式，将用作关联表与子对象的 join。默认情况下，此值根据关联表和子表的外键关系计算得出。

  relationship.secondaryjoin 也可以作为在映射器初始化时评估的可调用函数传递，并且在使用 Declarative 时可以作为可由 Python 评估的字符串传递。

  警告

  当作为可执行的 Python 字符串传递时，该参数将使用 Python 的 eval() 函数解释。不要将不可信的输入传递给此字符串。有关 Declarative 评估 relationship() 参数的详细信息，请参见 关系参数的评估。

  另请参见

  指定备用连接条件

• single_parent –

  当为 True 时，会安装一个验证器，该验证器会阻止对象同时与多个父对象关联。这用于多对一或多对多关系，这些关系应被视为一对一或一对多。它的使用是可选的，除了 relationship() 构造，这些构造是多对一或多对多，并且还指定了 delete-orphan 级联选项。该 relationship() 构造本身将引发一个错误，指示何时需要此选项。

  另请参见

  级联 - 包含有关何时 relationship.single_parent 标志可能适用时的详细信息。

• uselist –

  一个布尔值，指示此属性是否应作为列表或标量加载。在大多数情况下，此值由 relationship() 在映射器配置时自动确定。当使用显式 Mapped 注释时，relationship.uselist 可以从 Mapped 中的注释是否包含集合类推断得出。否则，relationship.uselist 可以从关系的类型和方向推断得出 - 一对多形成列表，多对一形成标量，多对多是列表。如果需要标量而通常存在列表，例如双向一对一关系，请使用适当的 Mapped 注释或将 relationship.uselist 设置为 False。

  该 relationship.uselist 标志也作为只读属性在现有 relationship() 构造中可用，可用于确定此 relationship() 是处理集合还是标量属性。

  >>> User.addresses.property.uselist
  True

  另请参见

  一对一 - “一对一”关系模式的介绍，这通常是涉及 relationship.uselist 的备用设置时。

• viewonly=False –

  当设置为 True 时，该关系仅用于加载对象，而不用于任何持久化操作。一个指定了 relationship.viewonly 的 relationship() 可以与 relationship.primaryjoin 条件内的更广泛的 SQL 操作一起使用，包括使用各种比较运算符以及 SQL 函数（如 cast()）的操作。该 relationship.viewonly 标志在定义任何类型的 relationship() 时也很常用，这些 relationship() 不表示相关对象的完整集合，以防止对集合的修改导致持久化操作。

  另请参见

  使用 viewonly 关系参数的注意事项 - 使用 relationship.viewonly 的最佳实践的更多详细信息。

• sync_backref –

  一个布尔值，它启用用于在该关系是 relationship.backref 或 relationship.back_populates 的目标时同步 Python 中属性的事件。

  默认值为 None，表示应根据 relationship.viewonly 标志的值选择一个自动值。当保留其默认值时，状态更改仅在关系的两侧都不仅为只读时才会被反向填充。

  1.3.17 版本新增。

  1.4 版本变更： - 指定了 relationship.viewonly 的关系会自动意味着 relationship.sync_backref 为 False。

  另请参见

  relationship.viewonly

• omit_join –

  允许手动控制“selectin”自动联接优化。设置为 False 以禁用 SQLAlchemy 1.3 中添加的“省略联接”功能；或者保留为 None 以保留自动优化。

  注意

  此标志只能设置为 False。没有必要将其设置为 True，因为“omit_join”优化会自动检测到；如果未检测到，则不支持优化。

  1.3.11 版本变更： 将 omit_join 设置为 True 现在会发出警告，因为这不是此标志的预期用途。

  1.3 版本新增。

• init – 特别针对 声明式数据类映射，指定映射属性是否应作为数据类过程生成的一部分包含在 __init__() 方法中。

• repr – 特别针对 声明式数据类映射，指定映射属性是否应作为数据类过程生成的一部分包含在 __repr__() 方法中。

• default_factory – 特别针对 声明式数据类映射，指定一个默认值生成函数，该函数将在作为数据类过程生成的一部分包含在 __init__() 方法中。

• compare –

  特别针对 声明式数据类映射，指示在为映射类生成 __eq__() 和 __ne__() 方法时是否应包含此字段在比较操作中。

  2.0.0b4 版本新增。

• kw_only – 特别针对 声明式数据类映射，指示在生成 __init__() 时是否应将此字段标记为关键字专用。

• hash –

  特别针对 声明式数据类映射，控制在为映射类生成 __hash__() 方法时是否包含此字段。

  2.0.36 版本新增。

function sqlalchemy.orm.backref(name: str, **kwargs: Any) → ORMBackrefArgument

当使用 relationship.backref 参数时，提供用于生成新的 relationship() 的特定参数。

例如

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

relationship.backref 参数通常被认为是旧式的；对于现代应用程序，应优先使用使用 relationship.back_populates 参数相互链接的显式 relationship() 结构。

另请参见

使用旧式的“backref”关系参数 - 关于反向引用的背景

function sqlalchemy.orm.dynamic_loader(argument: _RelationshipArgumentType[Any] | None = None, **kw: Any) → RelationshipProperty[Any]

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

这与对 relationship() 使用 lazy='dynamic' 参数基本相同。

dynamic_loader(SomeClass)

# is the same as

relationship(SomeClass, lazy="dynamic")

有关动态加载的更多详细信息，请参阅部分 动态关系加载器。

function sqlalchemy.orm.foreign(expr: _CEA) → _CEA

用“外键”注解标记 primaryjoin 表达式的一部分。

有关用法的说明，请参阅部分 创建自定义外键条件。

另请参见

创建自定义外键条件

remote()

function sqlalchemy.orm.remote(expr: _CEA) → _CEA

用“远程”注解标记 primaryjoin 表达式的一部分。

有关用法的说明，请参阅部分 创建自定义外键条件。

另请参见

创建自定义外键条件

foreign()