在映射时配置加载程序策略¶

特定关系的加载器策略可以在映射时配置为在加载映射类型的对象的所有情况下发生，而不需要修改它的任何查询级别选项。这是使用 relationship.lazy 参数到 relationship() ；此参数的常用值包括 select ， joined ， subquery 和 selectin .

例如，要将关系配置为在查询父对象时使用Joined Earge Loading，请执行以下操作：

class Parent(Base):
    __tablename__ = 'parent'

    id = Column(Integer, primary_key=True)
    children = relationship("Child", lazy='joined')

上面，每当 Parent 加载对象，每个 Parent 也会有它的 children 集合已填充，使用通过向查询中添加联接获取的行 Parent 物体。见 加入的热切装载 对于这种加载方式的背景。

的默认值 relationship.lazy 论证是 "select" ，表示延迟加载。见 延迟加载 了解更多背景。

与加载程序选项的关系加载¶

另一种配置加载策略的更常见方法是使用 Query.options() 方法。使用加载程序选项可以非常详细地控制关系加载；最常见的是 joinedload() ， subqueryload() ， selectinload() 和 lazyload() . 该选项接受属性相对于父级的字符串名称，或者为了更高的特异性，可以直接容纳类绑定属性：

# set children to load lazily
session.query(Parent).options(lazyload(Parent.children)).all()

# set children to load eagerly with a join
session.query(Parent).options(joinedload(Parent.children)).all()

加载程序选项也可以使用 方法链 若要指定在更深的层次上加载的方式，请执行以下操作：

session.query(Parent).options(
    joinedload(Parent.children).
    subqueryload(Child.subelements)).all()

可以对“惰性”加载的集合应用链接加载程序选项。这意味着，当访问时延迟加载集合或关联时，指定的选项将生效：：

session.query(Parent).options(
    lazyload(Parent.children).
    subqueryload(Child.subelements)).all()

在上面，查询将返回 Parent 没有的对象 children 集合已加载。当 children 一个特定的集合 Parent 对象首先被访问，它将延迟加载相关的对象，但还将预先加载应用于 subelements 每个成员的集合 children .

上面的例子，使用 Query ，现在称为 1.x style 查询。选项系统也可用于 2.0 style 使用 Select.options() 方法：

stmt = select(Parent).options(
      lazyload(Parent.children).
      subqueryload(Child.subelements))

result = session.execute(stmt)

在引擎盖下， Query 最终使用的是上述方法 select 基于机制。

session.query(A).options(lazyload(A.bs.and_(B.id > 5)))

session.query(A).options(lazyload(A.bs.and_(B.id > 5))).populate_existing()

session.query(A).options(
    defaultload(A.atob).
    joinedload(B.btoc)).all()

session.query(A).options(
    defaultload(A.atob).options(
      joinedload(B.btoc),
      joinedload(B.btod)
    )).all()

session.query(Parent).options(
    lazyload(Parent.children).
    subqueryload(Child.subelements)).all()

# change the options on Parent objects that were already loaded
session.query(Parent).populate_existing().options(
    lazyload(Parent.children).
    lazyload(Child.subelements)).all()

延迟加载¶

默认情况下，所有对象间关系都是 延迟加载 . 与 relationship() 包含第一次访问属性时激发的触发器。此触发器通常在访问点发出SQL调用，以便加载相关对象：

>>> jack.addresses
SELECT
    addresses.id AS addresses_id,
    addresses.email_address AS addresses_email_address,
    addresses.user_id AS addresses_user_id
FROM addresses
WHERE ? = addresses.user_id
[5]
[<Address(u'jack@google.com')>, <Address(u'j25@yahoo.com')>]

不发出SQL的一种情况是对于简单的多对一关系，当相关对象可以通过其主键单独标识，并且该对象已存在于当前 Session . 因此，尽管延迟加载对于相关的集合来说可能很昂贵，但是如果一个人正在加载许多对象，其中简单的多对一对象对应一组相对较小的可能目标对象，则延迟加载可能能够在本地引用这些对象，而不会发出与父对象相同的SELECT语句。

“属性访问时加载”的默认行为称为“lazy”或“select”加载-名称为“select”，因为“select”语句通常在首次访问属性时发出。

可以为通常以其他方式配置的给定属性启用延迟加载，方法是使用 lazyload() 加载器选项：

from sqlalchemy.orm import lazyload

# force lazy loading for an attribute that is set to
# load some other way normally
session.query(User).options(lazyload(User.addresses))

from sqlalchemy.orm import raiseload
session.query(User).options(raiseload(User.addresses))

session.query(Order).options(
    joinedload(Order.items), raiseload('*'))

from sqlalchemy.orm import Load

session.query(Order).options(
    joinedload(Order.items), Load(Order).raiseload('*'))

session.query(Order).options(
    joinedload(Order.items).raiseload('*'))

加入的热切装载¶

联合预加载是ORM中最基本的预加载方式。它的工作方式是将一个联接（默认情况下是左外部联接）连接到由 Query 并从与父级相同的结果集填充目标标量/集合。

在映射级别，如下所示：

class Address(Base):
    # ...

    user = relationship(User, lazy="joined")

联合的预加载通常作为查询的选项应用，而不是作为映射上的默认加载选项应用，特别是用于集合而不是多对一引用时。这是通过使用 joinedload() 加载器选项：

>>> jack = session.query(User).\
... options(joinedload(User.addresses)).\
... filter_by(name='jack').all()
SELECT
    addresses_1.id AS addresses_1_id,
    addresses_1.email_address AS addresses_1_email_address,
    addresses_1.user_id AS addresses_1_user_id,
    users.id AS users_id, users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
LEFT OUTER JOIN addresses AS addresses_1
    ON users.id = addresses_1.user_id
WHERE users.name = ?
['jack']

默认情况下发出的联接是左外部联接，以允许不引用相关行的前导对象。对于保证具有元素的属性，例如引用外键不为空的相关对象的多对一引用，可以通过使用内部联接提高查询效率；这在映射级别通过 relationship.innerjoin 旗帜：

class Address(Base):
    # ...

    user_id = Column(ForeignKey('users.id'), nullable=False)
    user = relationship(User, lazy="joined", innerjoin=True)

在查询选项级别，通过 joinedload.innerjoin 旗帜：

session.query(Address).options(
    joinedload(Address.user, innerjoin=True))

当应用于包含外部联接的链时，联接将正确嵌套自身：

>>> session.query(User).options(
...     joinedload(User.addresses).
...     joinedload(Address.widgets, innerjoin=True)).all()
SELECT
    widgets_1.id AS widgets_1_id,
    widgets_1.name AS widgets_1_name,
    addresses_1.id AS addresses_1_id,
    addresses_1.email_address AS addresses_1_email_address,
    addresses_1.user_id AS addresses_1_user_id,
    users.id AS users_id, users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
LEFT OUTER JOIN (
    addresses AS addresses_1 JOIN widgets AS widgets_1 ON
    addresses_1.widget_id = widgets_1.id
) ON users.id = addresses_1.user_id

在旧版本的sqlite上，可以将上面嵌套的右联接重新呈现为嵌套的子查询。旧版本的SQLAlchemy在任何情况下都会将正确的嵌套联接转换为子查询。

>>> jack = session.query(User).\
... options(joinedload(User.addresses)).\
... filter(User.name=='jack').\
... order_by(Address.email_address).all()
SELECT
    addresses_1.id AS addresses_1_id,
    addresses_1.email_address AS addresses_1_email_address,
    addresses_1.user_id AS addresses_1_user_id,
    users.id AS users_id,
    users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
LEFT OUTER JOIN addresses AS addresses_1
    ON users.id = addresses_1.user_id
WHERE users.name = ?
ORDER BY addresses.email_address   <-- this part is wrong !
['jack']

>>> jack = session.query(User).\
... join(User.addresses).\
... filter(User.name=='jack').\
... order_by(Address.email_address).all()
SELECT
    users.id AS users_id,
    users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
JOIN addresses ON users.id = addresses.user_id
WHERE users.name = ?
ORDER BY addresses.email_address
['jack']

>>> jack = session.query(User).\
... join(User.addresses).\
... options(joinedload(User.addresses)).\
... filter(User.name=='jack').\
... order_by(Address.email_address).all()
SELECT
    addresses_1.id AS addresses_1_id,
    addresses_1.email_address AS addresses_1_email_address,
    addresses_1.user_id AS addresses_1_user_id,
    users.id AS users_id, users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users JOIN addresses
    ON users.id = addresses.user_id
LEFT OUTER JOIN addresses AS addresses_1
    ON users.id = addresses_1.user_id
WHERE users.name = ?
ORDER BY addresses.email_address
['jack']

>>> jack = session.query(User).\
... join(User.addresses).\
... options(joinedload(User.addresses)).\
... filter(User.name=='jack').\
... filter(Address.email_address=='someaddress@foo.com').\
... all()
SELECT
    addresses_1.id AS addresses_1_id,
    addresses_1.email_address AS addresses_1_email_address,
    addresses_1.user_id AS addresses_1_user_id,
    users.id AS users_id, users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users JOIN addresses
    ON users.id = addresses.user_id
LEFT OUTER JOIN addresses AS addresses_1
    ON users.id = addresses_1.user_id
WHERE users.name = ? AND addresses.email_address = ?
['jack', 'someaddress@foo.com']

>>> jack = session.query(User).\
... join(User.addresses).\
... options(subqueryload(User.addresses)).\
... filter(User.name=='jack').\
... filter(Address.email_address=='someaddress@foo.com').\
... all()
SELECT
    users.id AS users_id,
    users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
JOIN addresses ON users.id = addresses.user_id
WHERE
    users.name = ?
    AND addresses.email_address = ?
['jack', 'someaddress@foo.com']

# ... subqueryload() emits a SELECT in order
# to load all address records ...

子查询预加载¶

子查询加载预加载的配置方式与联接的预加载相同；用于 relationship.lazy 参数，我们将指定 "subquery" 而不是 "joined" 对于选项，我们使用 subqueryload() 选项而不是 joinedload() 选择权。

子查询预加载的操作是为要加载的每个关系发出第二条SELECT语句，一次跨所有结果对象。此select语句引用包装在子查询中的原始select语句，以便我们检索所返回的主对象的相同主键列表，然后将其链接到所有集合成员的总和，以便一次加载它们：

>>> jack = session.query(User).\
... options(subqueryload(User.addresses)).\
... filter_by(name='jack').all()
SELECT
    users.id AS users_id,
    users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
WHERE users.name = ?
('jack',)
SELECT
    addresses.id AS addresses_id,
    addresses.email_address AS addresses_email_address,
    addresses.user_id AS addresses_user_id,
    anon_1.users_id AS anon_1_users_id
FROM (
    SELECT users.id AS users_id
    FROM users
    WHERE users.name = ?) AS anon_1
JOIN addresses ON anon_1.users_id = addresses.user_id
ORDER BY anon_1.users_id, addresses.id
('jack',)

在加载集合方面，子查询加载策略与联合的预加载相比具有许多优势。首先，它允许原始查询在不进行任何更改的情况下继续进行，特别是不引入可能降低效率的左外部联接。其次，它允许在不生成具有多个联接的单个查询的情况下急切地加载多个集合，这样效率甚至更低；每个关系都加载在完全独立的查询中。最后，由于附加查询只需要加载集合项而不需要Lead对象，因此它可以在所有情况下使用内部联接以提高查询效率。

子查询负载的缺点包括原始查询的复杂性被转移到关系查询中，当与子查询结合使用时，在某些情况下（尤其是mysql）的某些后端会产生非常慢的查询。此外，子查询加载策略只能一次加载所有集合的全部内容，因此与由提供的“批处理”加载不兼容。 Query.yield_per() 对于集合和标量关系。

由提供的较新加载样式 selectinload() 解决了 subqueryload() .

# incorrect, no ORDER BY
session.query(User).options(
    subqueryload(User.addresses)).first()

# incorrect if User.name is not unique
session.query(User).options(
    subqueryload(User.addresses)
).order_by(User.name).first()

# correct
session.query(User).options(
    subqueryload(User.addresses)
).order_by(User.name, User.id).first()

加载时选择¶

Select-IN-loading在操作上与subquery-eager-loading类似，但是发出的Select语句的结构要比subquery eager-loading简单得多。在大多数情况下，selectin加载是快速加载对象集合的最简单、最有效的方法。selectin预先加载不可行的唯一情况是模型使用复合主键，而后端数据库不支持in的元组（当前包括sqlserver）。

“select in”（在中选择）通过 "selectin" 参数 relationship.lazy 或通过使用 selectinload() 装载机选项。这种加载方式在in子句中发出一个SELECT，它引用父对象的主键值，或者在与子对象的主键值存在多对一关系的情况下，发出一个SELECT，以便加载相关的关联：

>>> jack = session.query(User).\
... options(selectinload(User.addresses)).\
... filter(or_(User.name == 'jack', User.name == 'ed')).all()
SELECT
    users.id AS users_id,
    users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
WHERE users.name = ? OR users.name = ?
('jack', 'ed')
SELECT
    addresses.id AS addresses_id,
    addresses.email_address AS addresses_email_address,
    addresses.user_id AS addresses_user_id
FROM addresses
WHERE addresses.user_id IN (?, ?)
(5, 7)

上面第二个选择是指 addresses.user_id IN (5, 7) ，其中“5”和“7”是前两个的主键值 User 对象已加载；在一批对象完全加载后，它们的主键值被注入到 IN 用于第二次选择的子句。因为两者之间的关系 User 和 Address 有一个简单的 1 主联接条件，并提供 User 可以派生自 Address.user_id 语句完全没有联接或子查询。

为了简单 1 多对一加载时，也不需要联接，因为使用父对象的外键值：

>>> session.query(Address).\
... options(selectinload(Address.user)).all()
SELECT
    addresses.id AS addresses_id,
    addresses.email_address AS addresses_email_address,
    addresses.user_id AS addresses_user_id
    FROM addresses
SELECT
    users.id AS users_id,
    users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
WHERE users.id IN (?, ?)
(1, 2)

1(1,2)

“简单”是指 relationship.primaryjoin condition表示“one”端的主键与“many”端的直接外键之间的相等比较，无需任何附加条件。

Select-IN-loading还支持多对多关系，目前它将连接所有三个表，以匹配从一端到另一端的行。

关于这种装载需要了解的事项包括：

• 与“子查询”不同，“selectin”加载程序策略发出的select语句不需要子查询，也不继承原始查询的任何性能限制；查找是简单的主键查找，应具有较高的性能。

• 子查询负载的特殊排序要求 订购的重要性 也不适用于selectin加载；selectin总是直接链接到父主键，不能真正返回错误的结果。

• 与joined或subquery eager loading不同，“selectin”加载总是根据刚加载的直接父对象而不是链顶部的原始对象类型发出SELECT。因此，如果急切地加载许多级别，那么对于简单的一对多或多对一关系，“selectin”加载仍然不需要任何连接。相比之下，joined和subquery eager loading总是指向原始父级的多个联接。

• 当主键在SQL语句中呈现为一个大的IN表达式时，该策略一次最多发出500个父主键值的SELECT。像Oracle这样的一些数据库对IN表达式的大小有一个硬限制，总体上SQL字符串的大小不应该任意大。

• 由于“selectin”加载依赖于in，对于具有复合主键的映射，它必须使用in的“tuple”形式，这看起来像 WHERE (table.column_a, table.column_b) IN ((?, ?), (?, ?), (?, ?)) . SQL Server当前不支持此语法，并且SQLite至少需要3.15版。SQLAlchemy中没有特殊的逻辑来提前检查哪些平台支持此语法；如果在不支持的平台上运行，数据库将立即返回错误。SQLAlchemy的一个优点是，如果一个特定的数据库开始支持这种语法，它将工作而不会对SQLAlchemy进行任何更改（就像SQLite一样）。

一般来说，“select in”加载在大多数情况下可能优于“subquery”的预加载，除了使用复合主键的语法要求，还可能为较大的结果集发出许多select语句。和往常一样，开发人员应该花时间查看他们的应用程序在开发中生成的语句和结果，以检查事物是否有效工作。

使用哪种装载？¶

通常，使用哪种类型的加载来优化SQL执行次数、发出的SQL的复杂性和获取的数据量之间的权衡。我们举两个例子，A relationship() 它引用了一个集合，并且 relationship() 它引用一个标量多对一的引用。

• 一对多收藏

• 当使用默认的延迟加载时，如果加载100个对象，然后在每个对象上访问一个集合，则总共会发出101个SQL语句，尽管每个语句通常是一个简单的select，没有任何联接。

• 使用联合加载时，100个对象及其集合的加载将只发出一条SQL语句。但是，获取的行总数将等于所有集合的大小加上每个父对象有一个空集合的额外行的总和。每一行还将包含由父级表示的完整列集，对每个集合项重复这些列-sqlAlchemy不会重新获取这些列，而不是主键的列，但是大多数dbapis（除了某些例外）在任何情况下都会通过连接将每个父级的完整数据传输到客户端连接。因此，只有当集合的大小相对较小时，联合的热切加载才有意义。与内部联接相比，左侧外部联接也可能是性能密集型联接。

• 使用子查询加载时，100个对象的加载将发出两条SQL语句。第二条语句将获取等于所有集合大小之和的总行数。使用内部联接，并且至少请求父列，仅请求主键。因此，当集合较大时，子查询负载是有意义的。

• 当在联接或子查询加载中使用多个深度级别时，在-collections中加载集合将乘以以笛卡尔方式获取的行总数。joined和subquery都是从原始父类进行的join；如果加载一个四层深度的集合，那么将有四个join输出到父类。另一方面，selectin加载始终只有一个到直接父表的联接。

• 使用selectin加载，100个对象的加载还将发出两个SQL语句，其中第二个语句引用所加载对象的100个主键。但是，selectin加载将在单个select语句中呈现最多500个主键值；因此，对于大于500的潜在客户集合，将为每批选定的500个对象发出一个select语句。

• 在selectin加载中使用多个深度级别不会引起联接和子查询的“笛卡尔”问题；selectin加载的查询具有最佳的性能特征和最少的行数。唯一需要注意的是，根据潜在客户结果的大小，可能会发出多个选择。

• 与联接（使用集合时）和子查询预加载（各种关系）不同，selectin加载可能与由提供的结果集批处理兼容。 Query.yield_per() 假设有一个适当的数据库驱动程序，那么就可以允许对大型结果集进行批处理。

• 多对一参考

• 当使用默认的延迟加载时，如果集合发出多达101个SQL语句，则需要加载100个对象。但是-有一个明显的例外，即如果多对一引用是对目标主键的简单外键引用，则将首先在当前标识映射中使用 Query.get() . 因此，在这里，如果对象集合引用了一组相对较小的目标对象，或者完整的可能目标对象集已经加载到会话中并被强引用，则使用默认的 lazy='select' 是目前为止最有效的方法。

• 使用联合加载时，100个对象的加载将只发出一条SQL语句。联接将是一个左外部联接，在所有情况下，行总数将等于100。如果您知道每个父级肯定有一个子级（即外键引用不是空的），那么可以使用 relationship.innerjoin 设置为 True ，通常在 relationship() . 对于可能存在许多尚未加载的目标引用的对象负载，使用内部联接进行联接加载非常有效。

• 子查询加载将为所有子对象发出第二次加载，因此对于100个对象的加载，将发出两个SQL语句。然而，与联接加载相比，这里可能没有什么优势，除非子查询加载在所有情况下都可以使用内部联接，而联接加载要求外键不为空。

• selectin加载还将为所有子对象发出第二个加载（如前所述，对于较大的结果，它将每500行发出一个select），因此对于100个对象的加载，将发出两个SQL语句。查询本身仍然必须联接到父表，因此对于多对一的selectin加载与联接的热切加载相比，选择in加载没有太大的优势，除了在所有情况下使用内部联接之外。

多态性预加载¶

支持基于每个预加载的多态选项规范。见剖面图 特异性或多态性亚型的热切加载 例如 PropComparator.of_type() 方法与 with_polymorphic() 功能。

通配符加载策略¶

每一个 joinedload() ， subqueryload() ， lazyload() ， selectinload() ， noload() 和 raiseload() 可用于设置默认样式 relationship() 为特定查询加载，影响所有 relationship() -未在中另外指定映射的属性 Query . 通过传递字符串可以使用此功能 '*' 作为这些选项的参数：

session.query(MyClass).options(lazyload('*'))

上面， lazyload('*') 选项将取代 lazy 全设置 relationship() 用于该查询的构造，但使用 'dynamic' 装载方式。如果某些关系指定 lazy='joined' 或 lazy='subquery' ，例如，使用 lazyload('*') 将单方面导致所有这些关系的使用 'select' 加载，例如在访问每个属性时发出一条SELECT语句。

该选项不会取代查询中指定的加载程序选项，例如 eagerload() ， subqueryload() 等等。下面的查询仍将使用 widget 关系：

session.query(MyClass).options(
    lazyload('*'),
    joinedload(MyClass.widget)
)

中频倍数 '*' 选项被传递，最后一个选项将覆盖以前传递的选项。

session.query(User, Address).options(
    Load(Address).lazyload('*'))

将显式联接/语句路由到热切加载的集合中¶

行为 joinedload() 这样，就可以使用匿名别名作为目标自动创建联接，其结果将路由到已加载对象上的集合和标量引用中。通常情况下，查询已经包含了表示特定集合或标量引用的必要联接，并且由joinedload功能添加的联接是多余的，但是您仍然希望填充集合/引用。

对于这个sqlacalchemy提供 contains_eager() 选择权。此选项的使用方式与 joinedload() 选项，除非假设 Query 将显式指定适当的联接。下面，我们指定 User 和 Address 此外，还将其作为 User.addresses ：：

class User(Base):
    __tablename__ = 'user'
    id = Column(Integer, primary_key=True)
    addresses = relationship("Address")

class Address(Base):
    __tablename__ = 'address'

    # ...

q = session.query(User).join(User.addresses).\
            options(contains_eager(User.addresses))

如果语句的“急切”部分是“别名”的，则应该使用 PropComparator.of_type() ，这允许特定的 aliased() 要传递的构造：

# use an alias of the Address entity
adalias = aliased(Address)

# construct a Query object which expects the "addresses" results
query = session.query(User).\
    outerjoin(User.addresses.of_type(adalias)).\
    options(contains_eager(User.addresses.of_type(adalias)))

# get results normally
r = query.all()
SELECT
    users.user_id AS users_user_id,
    users.user_name AS users_user_name,
    adalias.address_id AS adalias_address_id,
    adalias.user_id AS adalias_user_id,
    adalias.email_address AS adalias_email_address,
    (...other columns...)
FROM users
LEFT OUTER JOIN email_addresses AS email_addresses_1
ON users.user_id = email_addresses_1.user_id

作为参数给出的路径 contains_eager() 需要是起始实体的完整路径。例如，如果我们正在加载 Users->orders->Order->items->Item ，则该选项将用作：：

query(User).options(
    contains_eager(User.orders).
    contains_eager(Order.items))

q = session.query(User).\
        join(User.addresses).\
        filter(Address.email_address.like('%@aol.com')).\
        options(contains_eager(User.addresses)).\
        populate_existing()

创建自定义加载规则¶

ORM有各种边缘情况，其中属性的值在本地可用，但是ORM本身没有意识到这一点。在某些情况下，需要用户定义的加载属性系统。为了支持用户定义的加载系统的用例，一个关键功能 set_committed_value() 提供。这个函数基本上等同于python自己的 setattr() 函数，除了应用于目标对象时，将绕过用于确定刷新时间更改的SQLAlchemy的“属性历史记录”系统；该属性的分配方式与ORM从数据库以这种方式加载该属性的方式相同。

使用 set_committed_value() 可以与另一个称为 InstanceEvents.load() 要在加载对象时产生属性填充行为，请执行以下操作。一个这样的例子是双向的“一对一”情况，在这种情况下，加载一对一的“多对一”端也应该暗示“一对多”端的值。SQLAlChemy ORM在加载相关对象时不考虑后向引用，它将“一对一”视为另一种“一对多”，只是恰好是一行而已。

给定以下映射：

from sqlalchemy import Integer, ForeignKey, Column
from sqlalchemy.orm import relationship, backref
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()


class A(Base):
    __tablename__ = 'a'
    id = Column(Integer, primary_key=True)
    b_id = Column(ForeignKey('b.id'))
    b = relationship(
        "B",
        backref=backref("a", uselist=False),
        lazy='joined')


class B(Base):
    __tablename__ = 'b'
    id = Column(Integer, primary_key=True)

如果我们查询 A 排成一排，然后要求 a.b.a ，我们将得到一个额外的选择：

>>> a1.b.a
SELECT a.id AS a_id, a.b_id AS a_b_id
FROM a
WHERE ? = a.b_id

此选择是多余的，因为 b.a 与相同的值 a1 . 我们可以创建一个加载规则来为我们填充：

from sqlalchemy import event
from sqlalchemy.orm import attributes

@event.listens_for(A, "load")
def load_b(target, context):
    if 'b' in target.__dict__:
        attributes.set_committed_value(target.b, 'a', target)

现在当我们查询 A 我们会得到 A.b 从加入的热切负荷，和 A.b.a 从我们的事件：

a1 = s.query(A).first()
SELECT
    a.id AS a_id,
    a.b_id AS a_b_id,
    b_1.id AS b_1_id
FROM a
LEFT OUTER JOIN b AS b_1 ON b_1.id = a.b_id
 LIMIT ? OFFSET ?
(1, 0)
assert a1.b.a is a1

关系加载器API¶

function sqlalchemy.orm.contains_eager(*keys, **kw)¶

指示应该从查询中手动声明的列中热切地加载给定的属性。

此函数是 Load 接口和支持方法链接和独立操作。

该选项与加载所需行的显式联接一起使用，即：

sess.query(Order).\
        join(Order.user).\
        options(contains_eager(Order.user))

上面的查询将从 Order 与其相关的实体 User 实体和返回的 Order 对象将具有 Order.user 属性预填充。

它还可以用于自定义急切加载的集合中的条目；查询通常希望使用 Query.populate_existing() 假设父对象的主要集合可能已加载的方法：：

sess.query(User).\
    join(User.addresses).\
    filter(Address.email_address.like('%@aol.com')).\
    options(contains_eager(User.addresses)).\
    populate_existing()

请参阅部分 将显式联接/语句路由到热切加载的集合中 了解完整的用法详细信息。

参见

关系加载技术

将显式联接/语句路由到热切加载的集合中

function sqlalchemy.orm.defaultload(*keys)¶

指示应使用默认加载程序样式加载属性。

此方法用于将其他加载程序选项进一步链接到属性链中，而不改变链中链接的加载程序样式。例如，要为元素的某个元素设置连接的热切加载，请执行以下操作：

session.query(MyClass).options(
    defaultload(MyClass.someattribute).
    joinedload(MyOtherClass.someotherattribute)
)

defaultload() 也可用于在相关类上设置列级选项，即 defer() 和 undefer() ：：

session.query(MyClass).options(
    defaultload(MyClass.someattribute).
    defer("some_column").
    undefer("some_other_column")
)

参见

Load.options() -允许复杂的层次加载程序选项结构，其详细程度低于单个加载程序的详细程度。 defaultload() 指令。

与加载程序选项的关系加载

跨多个实体延迟加载

function sqlalchemy.orm.eagerload(*args, **kwargs)¶

同义词 joinedload() .

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

function sqlalchemy.orm.immediateload(*keys)¶

指示应使用带有per attribute select语句的即时加载来加载给定的属性。

加载是使用“lazyloader”策略实现的，并且不会触发任何额外的急切加载程序。

这个 immediateload() 期权通常被 selectinload() 选项，它通过为所有加载的对象发出一个选择来更有效地执行相同的任务。

此函数是 Load 接口和支持方法链接和独立操作。

参见

关系加载技术

加载时选择

function sqlalchemy.orm.joinedload(*keys, **kw)¶

指示应使用joined eager loading加载给定的属性。

此函数是 Load 接口和支持方法链接和独立操作。

实例：

# joined-load the "orders" collection on "User"
query(User).options(joinedload(User.orders))

# joined-load Order.items and then Item.keywords
query(Order).options(
    joinedload(Order.items).joinedload(Item.keywords))

# lazily load Order.items, but when Items are loaded,
# joined-load the keywords collection
query(Order).options(
    lazyload(Order.items).joinedload(Item.keywords))

参数

innerjoin¶ -- 如果 True ，指示联接的热切加载应使用内部联接而不是默认的左外部联接：：query（order）.options（joined load（order.user，inner join=true）），以便将多个热切联接链接在一起，其中一些联接可能是外部联接，另一些联接可能是内部联接，右嵌套联接用于将它们链接：：query（a）.options（joined load（a.bs，innerjoin=假）。joinedLoad（b.cs，inner join=true））上述查询通过“outer”join链接a.bs，通过“inner”join链接b.cs，将使join呈现为“a left outer join（b join c）”。当使用旧版本的sqlite（<3.7.16）时，这种形式的join被转换为使用完整的子查询，因为这种语法不直接受支持。这个 innerjoin 标志也可以用术语来表示 "unnested" . 这表示应使用内部联接， 除非 该联接链接到左侧的左侧外部联接，在这种情况下，它将呈现为左侧外部联接。例如，假设 A.bs 是outerjoin:：query（a）.options（joinedload（a.bs）。joinedLoad（b.cs，innerjoin=“unnested”））上述联接将呈现为“左外部联接B左外部联接C”，而不是“左外部联接（b联接C）”。…注意：“unested”标志 not 影响从多对多关联表呈现的联接，例如配置为 relationship.secondary 对于目标表；为了结果的正确性，这些联接始终是内部的，因此如果链接到外部联接，则是正确嵌套的。…版本已更改：：1.0.0 innerjoin=True 现在暗示 innerjoin="nested" ，而在0.9中，它意味着 innerjoin="unnested" . 为了实现pre-1.0“untested”内部连接行为，请使用值 innerjoin="unnested" . 见 右内部联接嵌套现在是joinedLoad的默认值，inner join=true .

注解

产生的连接 joinedload() 是 匿名别名 . 不能修改联接进行的条件，也不能 Query 以任何方式引用这些联接，包括排序。见 加入渴望装载的禅宗 更多细节。

要生成显式可用的特定SQL联接，请使用 Query.join() . 若要将显式联接与集合的急切加载结合起来，请使用 contains_eager() 见 将显式联接/语句路由到热切加载的集合中 .

参见

关系加载技术

加入的热切装载

function sqlalchemy.orm.lazyload(*keys)¶

指示应使用“lazy”加载来加载给定的属性。

此函数是 Load 接口和支持方法链接和独立操作。

参见

关系加载技术

延迟加载

class sqlalchemy.orm.Load(entity)¶

表示修改 Query 以影响各种映射属性的加载方式。

这个 Load 在大多数情况下，当使用类似 joinedload() ， defer() 或类似。然而， Load 对象也可以直接使用，在某些情况下是有用的。

使用 Load 直接用目标映射类作为参数实例化它。这种用法在处理 Query 有多个实体：

myopt = Load(MyClass).joinedload("widgets")

以上 myopt 现在可用于 Query.options() ，仅对 MyClass 单位：

session.query(MyClass, MyOtherClass).options(myopt)

其中一例 Load 当指定仅对特定类生效的“通配符”选项时，公共API非常有用：

session.query(Order).options(Load(Order).lazyload('*'))

上面，所有关系 Order 将被延迟加载，但这些子对象上的其他属性将使用它们的常规加载策略进行加载。

参见

延迟的列加载程序查询选项

跨多个实体延迟加载

与加载程序选项的关系加载

类签名

class sqlalchemy.orm.Load (sqlalchemy.sql.expression.Generative, sqlalchemy.orm.LoaderOption)

method sqlalchemy.orm.Load.baked_lazyload(attr)¶

产生新的 Load 对象与 baked_lazyload() 选项应用。

见 baked_lazyload() 用于示例。

method sqlalchemy.orm.Load.contains_eager(attr, alias=None)¶

产生新的 Load 对象与 contains_eager() 选项应用。

见 contains_eager() 用于示例。

method sqlalchemy.orm.Load.defaultload(attr)¶

产生新的 Load 对象与 defaultload() 选项应用。

见 defaultload() 用于示例。

method sqlalchemy.orm.Load.defer(key, raiseload=False)¶

产生新的 Load 对象与 defer() 选项应用。

见 defer() 用于示例。

method sqlalchemy.orm.Load.immediateload(attr)¶

产生新的 Load 对象与 immediateload() 选项应用。

见 immediateload() 用于示例。

method sqlalchemy.orm.Load.joinedload(attr, innerjoin=None)¶

产生新的 Load 对象与 joinedload() 选项应用。

见 joinedload() 用于示例。

method sqlalchemy.orm.Load.lazyload(attr)¶

产生新的 Load 对象与 lazyload() 选项应用。

见 lazyload() 用于示例。

method sqlalchemy.orm.Load.load_only(*attrs)¶

产生新的 Load 对象与 load_only() 选项应用。

见 load_only() 用于示例。

method sqlalchemy.orm.Load.noload(attr)¶

产生新的 Load 对象与 noload() 选项应用。

见 noload() 用于示例。

method sqlalchemy.orm.Load.options(*opts)¶

将一系列选项作为子选项应用于此 Load 对象。

例如。：：

query = session.query(Author)
query = query.options(
            joinedload(Author.book).options(
                load_only(Book.summary, Book.excerpt),
                joinedload(Book.citations).options(
                    joinedload(Citation.author)
                )
            )
        )

参数

*opts¶ -- 一系列加载程序选项对象（最终 Load 对象），应应用于 Load 对象。

1.3.6 新版功能.

参见

defaultload()

与加载程序选项的关系加载

跨多个实体延迟加载

method sqlalchemy.orm.Load.process_compile_state(compile_state)¶

对给定的 CompileState .

method sqlalchemy.orm.Load.process_compile_state_replaced_entities(compile_state, mapper_entities)¶

将修改应用于给定的 CompileState ，给定被替换为WITH_ONLY_COLUMNS()或WITH_ENTITIES()的实体。

1.4.19 新版功能.

method sqlalchemy.orm.Load.raiseload(attr, sql_only=False)¶

产生新的 Load 对象与 raiseload() 选项应用。

见 raiseload() 用于示例。

method sqlalchemy.orm.Load.selectin_polymorphic(classes)¶

产生新的 Load 对象与 selectin_polymorphic() 选项应用。

见 selectin_polymorphic() 用于示例。

method sqlalchemy.orm.Load.selectinload(attr)¶

产生新的 Load 对象与 selectinload() 选项应用。

见 selectinload() 用于示例。

method sqlalchemy.orm.Load.subqueryload(attr)¶

产生新的 Load 对象与 subqueryload() 选项应用。

见 subqueryload() 用于示例。

method sqlalchemy.orm.Load.undefer(key)¶

产生新的 Load 对象与 undefer() 选项应用。

见 undefer() 用于示例。

method sqlalchemy.orm.Load.undefer_group(name)¶

产生新的 Load 对象与 undefer_group() 选项应用。

见 undefer_group() 用于示例。

method sqlalchemy.orm.Load.with_expression(key, expression)¶

产生新的 Load 对象与 with_expression() 选项应用。

见 with_expression() 用于示例。

function sqlalchemy.orm.noload(*keys)¶

指示给定的关系属性应保持卸载状态。

关系属性将返回 None 当在不产生任何加载效果的情况下被访问时。

此函数是 Load 接口和支持方法链接和独立操作。

noload() 适用于 relationship() 属性；有关基于列的属性，请参见 defer() .

注解

属性将此加载策略设置为关系的默认策略。 relationship.lazy 参数可能会导致刷新问题，例如如果删除操作需要加载相关对象，而不是 None 被退回了。

参见

关系加载技术

function sqlalchemy.orm.raiseload(*keys, **kw)¶

指示给定属性在访问时应引发错误。

使用配置的关系属性 raiseload() 将提高 InvalidRequestError 访问时。当应用程序试图确保在特定上下文中访问的所有关系属性都已通过预先加载加载时，这种方法非常有用。不必通过读取SQL日志来确保不发生延迟加载，此策略将导致它们立即提升。

raiseload() 适用于 relationship() 仅属性。若要将raise on SQL行为应用于基于列的属性，请使用 defer.raiseload 上的参数 defer() 装入程序选项。

参数

sql_only¶ -- 如果为True，则仅当延迟加载将发出SQL时才会引发，但如果只是检查标识映射，或者由于缺少键而确定相关值应为None，则不应引发。当错误时，该策略将针对所有类型的关系加载进行提升。

此函数是 Load 接口和支持方法链接和独立操作。

1.1 新版功能.

参见

关系加载技术

使用raiseload防止不需要的懒惰负载

延迟列的Raiseload

function sqlalchemy.orm.selectinload(*keys)¶

指示应使用select在预加载中加载给定的属性。

此函数是 Load 接口和支持方法链接和独立操作。

实例：

# selectin-load the "orders" collection on "User"
query(User).options(selectinload(User.orders))

# selectin-load Order.items and then Item.keywords
query(Order).options(
    selectinload(Order.items).selectinload(Item.keywords))

# lazily load Order.items, but when Items are loaded,
# selectin-load the keywords collection
query(Order).options(
    lazyload(Order.items).selectinload(Item.keywords))

1.2 新版功能.

参见

关系加载技术

加载时选择

function sqlalchemy.orm.subqueryload(*keys)¶

指示应使用子查询预加载来加载给定的属性。

此函数是 Load 接口和支持方法链接和独立操作。

实例：

# subquery-load the "orders" collection on "User"
query(User).options(subqueryload(User.orders))

# subquery-load Order.items and then Item.keywords
query(Order).options(
    subqueryload(Order.items).subqueryload(Item.keywords))

# lazily load Order.items, but when Items are loaded,
# subquery-load the keywords collection
query(Order).options(
    lazyload(Order.items).subqueryload(Item.keywords))

参见

关系加载技术

子查询预加载