ORM配置的函数构造。
有关如何使用此模块的概述,请参阅SQLAlchemy对象关系教程和映射器配置文档。
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='select', 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, _local_remote_pairs=None, query_class=None, info=None, omit_join=None)¶提供两个映射类之间的关系。
这对应于父子关系或关联表关系。构造的类是 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")
argument¶ -- 映射类或实际类 Mapper
实例,表示关系的目标。 argument
也可以作为可调用函数传递,该函数在映射器初始化时进行计算,并且在使用声明性时可以作为python可计算字符串传递。…参阅: 配置关系 -在使用声明性时有关关系配置的进一步详细信息。
secondary¶ -- 对于多对多关系,指定中间表,通常是 Table
Alias
Join
构造。 secondary
Table
存在于 MetaData
与映射的父级关联的集合 Table
. 这个 secondary
Table
关联对象 )应该考虑应用 viewonly
标记以便 relationship()
多对多 -“多对多”的参考示例。 建立多对多关系 -ORM教程介绍多对多关系。 自指多对多关系 配置多对多关系 关联对象 -替代 secondary
当组成关联表关系时,允许在关联表上指定其他属性。 复合“二次”连接 -在某些情况下可以使复杂 relationship()
要使用的SQL条件。…添加的版本:0.9.2 secondary
当提到 Join
实例。
active_history=False¶ -- 什么时候? True
,表示如果尚未加载,则在替换时应加载多对一引用的“上一个”值。通常,简单的多对一的历史跟踪逻辑只需要知道“新”值就可以执行刷新。此标志可用于使用 attributes.get_history()
它还需要知道属性的“上一个”值。
backref¶ -- 指示要放置在相关映射器类上的属性的字符串名称,该类将在其他方向处理此关系。配置映射器时,将自动创建其他属性。也可以作为 backref()
对象来控制新关系的配置。…参阅: 链接与backref的关系 -介绍性文件和示例。 back_populates
-backref规范的替代形式。 backref()
-允许控制 relationship()
使用时的配置 backref
.
back_populates¶ -- 采用字符串名称,其含义与 backref
,除了补充属性是 not 自动创建,而必须在另一个映射器上显式配置。补充属性还应指明 back_populates
以确保正常运转。…参阅: 链接与backref的关系 -介绍性文件和示例。 backref
-backref规范的替代形式。
bake_queries=True¶ -- 使用 BakedQuery
缓存以缓存惰性加载中使用的SQL构造。默认为true。如果关系的联接条件具有可能对语句缓存响应不好的异常特性,则设置为false。…versionChanged::1.2“baked”加载是“select”的默认实现,即关系的“lazy”加载策略。…版本已添加::1.0.0..参阅: 烘焙查询
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接收到事件,则此关系管理的属性不会将传入的临时对象级联到持久父级的会话中。…参阅: 在backrefs上控制级联 -充分讨论并举例说明 cascade_backrefs
使用选项。
collection_class¶ -- 返回新的包含对象的列表的类或可调用的。将用于代替普通列表来存储元素。…参阅: 自定义集合访问 -介绍性文件和示例。
comparator_factory¶ -- 扩展的类 RelationshipProperty.Comparator
它为比较操作提供自定义SQL子句生成。…参阅: PropComparator
-关于在这个级别重新定义比较器的一些细节。 操作符自定义 -简要介绍此功能。
distinct_target_key=None¶ -- 指示“subquery”抢先加载是否应将distinct关键字应用于最内层的select语句。什么时候离开 None
当目标列不包含目标表的完整主键时,将应用distinct关键字。当设置为 True
,distinct关键字将无条件应用于最内部的select。如果distinct降低了最内层子查询的性能,使其超过了最内层重复行可能导致的性能,则可能需要将此标志设置为false。…版本更改::0.9.0- distinct_target_key
现在默认为 None
,以便在最里面的查询针对非唯一键的情况下,该特性自动启用自己。…参阅: 关系加载技术 -包括子查询预加载的介绍。
doc¶ -- 将应用于结果描述符的docstring。
extension¶ -- 一个 AttributeExtension
实例或扩展名列表,它将在类上所放置的结果描述符的属性侦听器列表的前面。…已弃用::0.7 AttributeExtension
已弃用,取而代之的是 AttributeEvents
侦听器接口。这个 relationship.extension
参数将在将来的版本中删除。
foreign_keys¶ -- 在此上下文中用作“外键”列或引用远程列中值的列的列表。 relationship()
对象的 primaryjoin
条件。也就是说,如果 primaryjoin
条件 relationship()
是 a.id == b.a_id
和中的值 b.a_id
必须存在于 a.id
,然后是这个的“外键”列 relationship()
是 b.a_id
. 在正常情况下, foreign_keys
参数是 不需要。 relationship()
将自动确定 primaryjoin
条件将被视为基于这些条件的“外键”列 Column
指定的对象 ForeignKey
或以其他方式列为引用列 ForeignKeyConstraint
构造。 foreign_keys
仅在以下情况下需要:1。有多种方法可以从本地表构造到远程表的联接,因为存在多个外键引用。设置 foreign_keys
将限制 relationship()
只考虑这里指定为“外国”的列。2。这个 Table
被映射实际上没有 ForeignKey
或 ForeignKeyConstraint
存在构造,通常是因为表是从不支持外键反射(mysql myisam)的数据库反射的。三。这个 primaryjoin
参数用于构造非标准联接条件,该条件使用通常不引用其“父”列的列或表达式,例如通过使用SQL函数的复杂比较表示的联接条件。这个 relationship()
构造将引发信息性错误消息,建议使用 foreign_keys
参数出现不明确的条件时。在典型情况下,如果 relationship()
不会引发任何异常, foreign_keys
通常不需要参数。 foreign_keys
也可以作为可调用函数传递,该函数在映射器初始化时进行计算,并且在使用声明性时可以作为python可计算字符串传递。…参阅: 处理多个连接路径 创造习惯性的国外条件 foreign()
-允许直接批注 primaryjoin
条件。
info¶ -- 可选数据字典,将填充到 MapperProperty.info
此对象的属性。
innerjoin=False¶ -- 什么时候? True
,联接的热切加载将使用内部联接来针对相关表而不是外部联接进行联接。此选项的目的通常是性能之一,因为内部联接通常比外部联接性能更好。此标志可以设置为 True
当关系使用不可为空的本地外键通过多对一引用对象时,或者当引用是一对一或保证有一个或至少一个条目的集合时。该选项支持与以下选项相同的“嵌套”和“未列出”选项 joinedload.innerjoin
. 有关嵌套/未嵌套行为的详细信息,请参见该标志。…参阅: joinedload.innerjoin
-由加载程序选项指定的选项,包括嵌套行为的详细信息。 使用哪种装载? -讨论各种加载程序选项的一些细节。
join_depth¶ -- 当非``无``时,一个整数值,指示在自引用或循环关系中,深度为“热切”的加载程序应加入多少层。这个数字计算同一个映射器在加载条件下沿特定连接分支出现的次数。当其违约时 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 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
但不是其挂起集合的一部分。这个 load_on_pending
标志不能改善通常使用ORM时的行为-对象引用应该在对象级别而不是在外键级别构造,以便在刷新进行之前以普通方式存在。此标志不用于一般用途。…参阅: Session.enable_relationship_loading()
-此方法为整个对象建立“挂起时加载”行为,并允许加载保持瞬时或分离的对象。
order_by¶ -- 指示加载这些项时应应用的顺序。 order_by
应引用 Column
目标类映射到的对象,或属性本身绑定到引用该列的目标类。 order_by
也可以作为可调用函数传递,该函数在映射器初始化时进行计算,并且在使用声明性时可以作为python可计算字符串传递。
passive_deletes=False¶ -- 指示删除操作期间的加载行为。值为true表示在对父级执行删除操作期间不应加载已卸载的子项。通常,删除父项时,会加载所有子项,以便可以将其标记为已删除,或者将其对父项的外键设置为空。将此标志标记为“真”通常意味着存在“on delete<cascade_set null>规则”,该规则将处理数据库端的更新/删除子行。此外,如果父对象被删除,并且没有启用删除或删除孤立级联,则将标志设置为字符串值“all”将禁用子外键的“注销”。这通常在数据库端有触发或错误引发方案时使用。注意,在发生刷新之后,会话内子对象的外键属性将不会被更改,因此这是一个非常特殊的用例设置。此外,如果子对象与父对象取消关联,则仍然会发生“注销”。…参阅: 使用被动删除 -介绍性文件和示例。
passive_updates=True¶ -- 指示当引用的主键值就地更改时要采取的持久性行为,指示引用的外键列也需要更改其值。如果为真,则假定 ON UPDATE CASCADE
在数据库中的外键上配置,数据库将处理从源列到依赖行的更新传播。如果为false,则为sqlAlchemy relationship()
构造将尝试发出自己的更新语句来修改相关目标。但是请注意,sqlAlchemy 不能 为多个层叠级别发出更新。此外,如果数据库实际上正在强制引用完整性,那么将此标志设置为false是不兼容的,除非这些约束在目标后端支持时显式地“延迟”。强烈建议使用可变主键的应用程序保留 passive_updates
设置为true,而是使用数据库本身的引用完整性功能,以便高效、全面地处理更改。…参阅: 可变主键/更新级联 -介绍性文件和示例。 mapper.passive_updates
-对联接表继承映射生效的类似标志。
post_update¶ -- 这表示关系应该由插入后或删除前的第二条更新语句处理。目前,它还将在更新实例之后发布更新,尽管这在技术上应该得到改进。此标志用于处理保存两个单独行(即每行引用另一行)之间的双向依赖关系,否则将无法完全插入或删除两行,因为一行在另一行之前。当一个特定的映射安排将产生相互依赖的两行时,例如一个表与一组子行具有一对多关系,并且有一个列引用该列表中的单个子行(即两个表都包含彼此的外键),请使用此标志。如果刷新操作返回检测到“循环依赖”的错误,则这是您可能希望使用的提示 post_update
打破这个循环。…参阅: 指向自身/相互依赖的行的行 -介绍性文件和示例。
primaryjoin¶ -- 将用作此子对象相对于父对象的主联接的SQL表达式,或在多对多关系中用作主对象与关联表的联接。默认情况下,此值是根据父表和子表(或关联表)的外键关系计算的。 primaryjoin
也可以作为可调用函数传递,该函数在映射器初始化时进行计算,并且在使用声明性时可以作为python可计算字符串传递。…参阅: 指定备用联接条件
remote_side¶ -- 用于自引用关系,指示构成关系“远程端”的列或列列表。 relationship.remote_side
也可以作为可调用函数传递,该函数在映射器初始化时进行计算,并且在使用声明性时可以作为python可计算字符串传递。…参阅: 相邻列表关系 -深入讲解如何 remote_side
用于配置自引用关系。 remote()
-一种注释函数,其作用与 remote_side
,通常在自定义 primaryjoin
使用条件。
query_class¶ -- 一 Query
将用作"动态"关系(即指定 lazy="dynamic"
或者是用 orm.dynamic_loader()
功能。…参阅: 动态关系加载器 -"动态"关系加载器简介。
secondaryjoin¶ -- 将用作关联表与子对象的联接的SQL表达式。默认情况下,该值是根据关联表和子表的外键关系计算的。 secondaryjoin
也可以作为可调用函数传递,该函数在映射器初始化时进行计算,并且在使用声明性时可以作为python可计算字符串传递。…参阅: 指定备用联接条件
single_parent¶ -- 如果为true,则安装一个验证程序,该验证程序将防止对象一次与多个父级关联。这用于多对一或多对多关系,应将其视为一对一或一对多关系。它的用法是可选的,除了 relationship()
构造多对一或多对多,还指定 delete-orphan
层叠选项。这个 relationship()
构造本身将在需要此选项时引发错误指示。…参阅: 级联 -包括有关何时 single_parent
标志可能是适当的。
uselist¶ -- 一个布尔值,指示是否应将此属性作为列表或标量加载。在大多数情况下,该值由 relationship()
在映射器配置时,根据关系的类型和方向-一对多形成一个列表,多对一形成一个标量,多对多形成一个列表。如果需要一个标量,通常会出现一个列表,例如双向一对一关系,则设置 uselist
错了。这个 uselist
标志也可用于现有的 relationship()
构造为只读属性,该属性可用于确定 relationship()
处理集合或标量属性::>>>user.addresses.property.useList true..参阅: 一对一 -介绍“一对一”关系模式,这通常是 uselist
需要标志。
viewonly=False¶ -- 当设置为true时,关系仅用于加载对象,而不用于任何持久性操作。一 relationship()
其中指定 viewonly
可以在 primaryjoin
条件,包括使用各种比较运算符以及SQL函数(如 cast()
. 这个 viewonly
在定义任何类型的 relationship()
它不代表完整的相关对象集,以防止对集合的修改导致持久化操作。
omit_join¶ -- 允许手动控制“selectin”自动连接优化。设置为 False
禁用SQLAlchemy 1.3中添加的“省略连接”功能。…添加的版本:1.3
sqlalchemy.orm.
backref
(name, **kwargs)¶使用显式关键字参数创建反向引用,这些参数与可以发送到的参数相同 relationship()
.
与之一起使用 backref
关键字参数 relationship()
代替字符串参数,例如:
'items':relationship(
SomeItem, backref=backref('parent', lazy='subquery'))
sqlalchemy.orm.
relation
(*arg, **kw)¶同义词 relationship()
.
sqlalchemy.orm.
dynamic_loader
(argument, **kw)¶构造动态加载映射器属性。
这与使用 lazy='dynamic'
争论与 relationship()
::
dynamic_loader(SomeClass)
# is the same as
relationship(SomeClass, lazy="dynamic")
见剖面图 动态关系加载器 有关动态加载的详细信息。
sqlalchemy.orm.
foreign
(expr)¶用“foreign”批注对primaryjoin表达式的一部分进行批注。
见剖面图 创造习惯性的国外条件 用于描述用途。
sqlalchemy.orm.
remote
(expr)¶用“远程”批注对PrimaryJoin表达式的一部分进行批注。
见剖面图 创造习惯性的国外条件 用于描述用途。