传统查询 API

关于传统查询 API

本页包含 Query 结构的 Python 生成的文档，多年来，它一直是使用 SQLAlchemy ORM 时唯一的 SQL 接口。从 2.0 版本开始，一种全新的工作方式现在成为了标准方法，其中与 Core 工作相同的 select() 结构同样适用于 ORM，为构建查询提供了统一的接口。

对于任何在 2.0 API 之前基于 SQLAlchemy ORM 构建的应用程序，Query API 通常代表应用程序中绝大多数的数据库访问代码，因此 Query API 的大多数内容**不会从 SQLAlchemy 中删除**。在幕后，Query 对象现在会将自身转换为 2.0 风格的 select() 对象，当 Query 对象执行时，因此它现在只是一个非常薄的适配器 API。

有关基于 Query 的应用程序迁移到 2.0 风格的指南，请参见 2.0 迁移 - ORM 使用。

有关以 2.0 风格为 ORM 对象编写 SQL 的介绍，请从 SQLAlchemy 统一教程 开始。有关 2.0 风格查询的其他参考，请参见 ORM 查询指南。

查询对象

Query 是根据给定的 Session 生成的，使用 Session.query() 方法

q = session.query(SomeMappedClass)

以下是 Query 对象的完整接口。

对象名称 描述

查询

ORM 级别的 SQL 构造对象。
class sqlalchemy.orm.Query

ORM 级别的 SQL 构造对象。

传统特性

ORM Query 对象从 SQLAlchemy 2.0 开始是一种传统结构。有关概述，包括迁移文档的链接，请参见 传统查询 API 顶部的说明。

Query 对象通常最初使用 Session.query() 方法生成 Session，在不太常见的情况下，通过直接实例化 Query 并使用 Query.with_session() 方法将其与 Session 关联。

成员

__init__()，add_column()，add_columns()，add_entity()，all()，apply_labels()，as_scalar()，autoflush()，column_descriptions，correlate()，count()，cte()，delete()，distinct()，enable_assertions()，enable_eagerloads()，except_()，except_all()，execution_options()，exists()，filter()，filter_by()，first()，from_statement()，get()，get_children()，get_execution_options()，get_label_style，group_by()，having()，instances()，intersect()，intersect_all()，is_single_entity，join()，label()，lazy_loaded_from，limit()，merge_result()，offset()，one()，one_or_none()，only_return_tuples()，options()，order_by()，outerjoin()，params()，populate_existing()，prefix_with()，reset_joinpoint()，scalar()，scalar_subquery()，select_from()，selectable，set_label_style()，slice()，statement，subquery()，suffix_with()，tuples()，union()，union_all()，update()，value()，values()，where()，whereclause，with_entities()，with_for_update()，with_hint()，with_labels()，with_parent()，with_session()，with_statement_hint()，with_transformation()，yield_per()

类签名

class sqlalchemy.orm.Query (sqlalchemy.sql.expression._SelectFromElements, sqlalchemy.sql.annotation.SupportsCloneAnnotations, sqlalchemy.sql.expression.HasPrefixes, sqlalchemy.sql.expression.HasSuffixes, sqlalchemy.sql.expression.HasHints, sqlalchemy.event.registry.EventTarget, sqlalchemy.log.Identified, sqlalchemy.sql.expression.Generative, sqlalchemy.sql.expression.Executable, typing.Generic)

method sqlalchemy.orm.Query.__init__(entities: _ColumnsClauseArgument[Any] | Sequence[_ColumnsClauseArgument[Any]], session: Session | None = None)

直接构造一个 Query。

例如

q = Query([User, Address], session=some_session)

以上等价于

q = some_session.query(User, Address)
参数:

另见

Session.query()

Query.with_session()

method sqlalchemy.orm.Query.add_column(column: _ColumnExpressionArgument[Any]) → Query[Any]

将列表达式添加到要返回的结果列列表中。

已弃用，自版本 1.4 起： Query.add_column() 已弃用，将在未来的版本中移除。请使用 Query.add_columns()

方法 sqlalchemy.orm.Query.add_columns(*column: _ColumnExpressionArgument[Any]) → Query[Any]

将一个或多个列表达式添加到要返回的结果列列表中。

另见

Select.add_columns() - v2 兼容方法。

方法 sqlalchemy.orm.Query.add_entity(entity: _EntityType[Any], alias: Alias | Subquery | None = None) → Query[Any]

将一个映射实体添加到要返回的结果列列表中。

另见

Select.add_columns() - v2 兼容方法。

方法 sqlalchemy.orm.Query.all() → List[_T]

将此 Query 表示的结果作为列表返回。

这会导致底层 SQL 语句的执行。

警告

当 Query 对象被要求返回由完整 ORM 映射实体组成的序列或迭代器时，将根据主键进行 **去重**。有关更多详细信息，请参阅常见问题解答。

另见

Result.all() - v2 兼容方法。

Result.scalars() - v2 兼容方法。

方法 sqlalchemy.orm.Query.apply_labels() → Self

已弃用，自版本 2.0 起： 从 SQLAlchemy 1.x 系列开始，Query.with_labels() 和 Query.apply_labels() 方法被视为遗留方法，在 2.0 中变为遗留构造。请改用 set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)。（有关 SQLAlchemy 2.0 的背景信息，请参阅：SQLAlchemy 2.0 - 主要迁移指南)

方法 sqlalchemy.orm.Query.as_scalar() → ScalarSelect[Any]

将此 Query 表示的完整 SELECT 语句转换为标量子查询。

已弃用，自版本 1.4 起： Query.as_scalar() 方法已弃用，将在未来的版本中移除。请参考 Query.scalar_subquery().

方法 sqlalchemy.orm.Query.autoflush(setting: bool) → Self

返回一个具有特定 'autoflush' 设置的 Query。

从 SQLAlchemy 1.4 开始，Query.autoflush() 方法等同于在 ORM 级别使用 autoflush 执行选项。有关此选项的更多背景信息，请参阅 自动刷新 部分。

属性 sqlalchemy.orm.Query.column_descriptions

返回关于此 Query 所返回的列的元数据。

格式是一个字典列表

user_alias = aliased(User, name='user2')
q = sess.query(User, User.id, user_alias)

# this expression:
q.column_descriptions

# would return:
[
    {
        'name':'User',
        'type':User,
        'aliased':False,
        'expr':User,
        'entity': User
    },
    {
        'name':'id',
        'type':Integer(),
        'aliased':False,
        'expr':User.id,
        'entity': User
    },
    {
        'name':'user2',
        'type':User,
        'aliased':True,
        'expr':user_alias,
        'entity': user_alias
    }
]

另见

此 API 可用于 2.0 样式 查询，文档如下：

方法 sqlalchemy.orm.Query.correlate(*fromclauses: Literal[None, False] | FromClauseRole | Type[Any] | Inspectable[_HasClauseElement[Any]] | _HasClauseElement[Any]) → Self

返回一个 Query 构造，它会将给定的 FROM 子句与包含的 Query 或 select() 的 FROM 子句关联。

这里的方法接受映射类、aliased() 构造和 Mapper 构造作为参数，这些参数将解析为表达式构造，以及适当的表达式构造。

相关参数最终在转换为表达式构造后传递给 Select.correlate()。

相关参数在以下情况下生效：当使用 Query.from_self() 时，或者当由 Query.subquery() 返回的子查询嵌入在另一个 select() 构造中时。

另见

Select.correlate() - v2 等效方法。

method sqlalchemy.orm.Query.count() → int

返回此 Query 生成的 SQL 语句将返回的行数。

该方法按以下方式生成此 Query 的 SQL 语句

SELECT count(1) AS count_1 FROM (
    SELECT <rest of query follows...>
) AS anon_1

上述 SQL 语句返回一行，该行是计数函数的聚合值；然后，Query.count() 方法返回该单个整数值。

警告

重要的是要注意，count() 返回的值 **与此 Query 从 .all() 等方法返回的 ORM 对象数量不同**。当要求 Query 对象返回完整的实体时，它将 **根据主键对条目进行去重**，这意味着如果同一个主键值在结果中出现多次，则结果中只会有一个该主键的对象。 这不适用于针对单个列的查询。

另见

我的查询返回的对象数量与 query.count() 所说的不同 - 为什么？

要对要计数的特定列进行细粒度的控制，跳过子查询的使用或以其他方式控制 FROM 子句，或者使用其他聚合函数，请将 expression.func 表达式与 Session.query() 结合使用，例如

from sqlalchemy import func

# count User records, without
# using a subquery.
session.query(func.count(User.id))

# return count of user "id" grouped
# by "name"
session.query(func.count(User.id)).\
        group_by(User.name)

from sqlalchemy import distinct

# count distinct "name" values
session.query(func.count(distinct(User.name)))

另见

2.0 迁移 - ORM 使用

method sqlalchemy.orm.Query.cte(name: str | None = None, recursive: bool = False, nesting: bool = False) → CTE

返回此 Query 代表的完整 SELECT 语句，表示为通用表表达式 (CTE)。

参数和用法与 SelectBase.cte() 方法的参数和用法相同；有关更多详细信息，请参阅该方法。

这是 PostgreSQL WITH RECURSIVE 示例。注意，在此示例中，included_parts cte 和它的 incl_alias 别名是 Core 可选的，这意味着列是通过 .c. 属性访问的。 parts_alias 对象是 Part 实体的 aliased() 实例，因此列映射属性可以直接使用

from sqlalchemy.orm import aliased

class Part(Base):
    __tablename__ = 'part'
    part = Column(String, primary_key=True)
    sub_part = Column(String, primary_key=True)
    quantity = Column(Integer)

included_parts = session.query(
                Part.sub_part,
                Part.part,
                Part.quantity).\
                    filter(Part.part=="our part").\
                    cte(name="included_parts", recursive=True)

incl_alias = aliased(included_parts, name="pr")
parts_alias = aliased(Part, name="p")
included_parts = included_parts.union_all(
    session.query(
        parts_alias.sub_part,
        parts_alias.part,
        parts_alias.quantity).\
            filter(parts_alias.part==incl_alias.c.sub_part)
    )

q = session.query(
        included_parts.c.sub_part,
        func.sum(included_parts.c.quantity).
            label('total_quantity')
    ).\
    group_by(included_parts.c.sub_part)

另见

Select.cte() - v2 等效方法。

method sqlalchemy.orm.Query.delete(synchronize_session: SynchronizeSessionArgument = 'auto') → int

使用任意 WHERE 子句执行 DELETE 操作。

从数据库中删除此查询匹配的行。

例如

sess.query(User).filter(User.age == 25).\
    delete(synchronize_session=False)

sess.query(User).filter(User.age == 25).\
    delete(synchronize_session='evaluate')

警告

有关重要注意事项和警告，包括在使用具有映射器继承配置的批量 UPDATE 和 DELETE 操作时的限制，请参阅 支持 ORM 的 INSERT、UPDATE 和 DELETE 语句 部分。

参数:

synchronize_session – 选择更新会话中对象属性的策略。有关这些策略的讨论，请参阅 支持 ORM 的 INSERT、UPDATE 和 DELETE 语句 部分。

返回值：:

由数据库的“行计数”功能返回的匹配行数。

另见

ORM 支持的 INSERT、UPDATE 和 DELETE 语句

method sqlalchemy.orm.Query.distinct(*expr: _ColumnExpressionArgument[Any]) → Self

对查询应用 DISTINCT 并返回新的结果 Query。

注意

ORM 级别的 distinct() 调用包括逻辑，该逻辑会自动将查询的 ORDER BY 中的列添加到 SELECT 语句的列子句中，以满足数据库后端通常需要 ORDER BY 列作为 SELECT 列表的一部分才能使用 DISTINCT 的需求。但是，这些列 **不会** 添加到 Query 实际获取的列列表中，因此不会影响结果。但是，在使用 Query.statement 访问器时，这些列会通过传递。

已在版本 2.0 中弃用： 此逻辑已弃用，将在 SQLAlchemy 2.0 中删除。有关 2.0 中此用例的描述，请参阅 使用 DISTINCT 附加列，但只选择实体。

另见

Select.distinct() - v2 等效方法。

参数:

*expr –

可选的列表达式。当存在时，PostgreSQL 方言将呈现一个 DISTINCT ON (<expressions>) 结构。

已在版本 1.4 中弃用： 在其他方言中使用 *expr 已弃用，将在未来的版本中引发 CompileError。

method sqlalchemy.orm.Query.enable_assertions(value: bool) → Self

控制是否生成断言。

当设置为 False 时，返回的 Query 不会在某些操作之前断言其状态，包括在调用 filter() 时 LIMIT/OFFSET 未应用，在调用 get() 时不存在条件，以及在调用 filter()/order_by()/group_by() 等时不存在“from_statement()”。这种更宽松的模式被自定义 Query 子类用于在通常的用法模式之外指定条件或其他修饰符。

应谨慎确保使用模式是可能的。例如，由 from_statement() 应用的语句将覆盖由 filter() 或 order_by() 设置的任何条件。

方法 sqlalchemy.orm.Query.enable_eagerloads(value: bool) → Self

控制是否渲染急切联接和子查询。

当设置为 False 时，返回的 Query 将不会渲染急切联接，无论 joinedload()、subqueryload() 选项或映射器级别的 lazy='joined'/lazy='subquery' 配置。

这主要用于将 Query 的语句嵌套到子查询或其他可选择对象中，或者使用 Query.yield_per()。

方法 sqlalchemy.orm.Query.except_(*q: Query) → Self

对一个或多个查询生成此 Query 的 EXCEPT。

工作方式与 Query.union() 相同。有关使用示例，请参见该方法。

另见

Select.except_() - v2 等效方法。

方法 sqlalchemy.orm.Query.except_all(*q: Query) → Self

对一个或多个查询生成此 Query 的 EXCEPT ALL。

工作方式与 Query.union() 相同。有关使用示例，请参见该方法。

另见

Select.except_all() - v2 等效方法。

方法 sqlalchemy.orm.Query.execution_options(**kwargs: Any) → Self

设置执行期间生效的非 SQL 选项。

此处允许的选项包括 Connection.execution_options() 接受的所有选项，以及一系列 ORM 特定选项

populate_existing=True - 等同于使用 Query.populate_existing()

autoflush=True|False - 等同于使用 Query.autoflush()

yield_per=<value> - 等同于使用 Query.yield_per()

注意，如果使用 Query.yield_per() 方法或执行选项，则会自动启用 stream_results 执行选项。

版本 1.4 中的新内容： - 将 ORM 选项添加到 Query.execution_options()

使用 2.0 样式 查询通过 Session.execution_options 参数也可以在每次执行的基础上指定执行选项。

警告

Connection.execution_options.stream_results 参数不应该在单个 ORM 语句执行的级别使用，因为 Session 不会在一个会话中跟踪来自不同模式转换映射的对象。对于单个 Session 范围内的多个模式转换映射，请参见 水平分片。

另见

使用服务器端游标（又名流结果）

Query.get_execution_options()

Select.execution_options() - v2 等效方法。

方法 sqlalchemy.orm.Query.exists() → Exists

一个将查询转换为 EXISTS 子查询的便利方法，形式为 EXISTS (SELECT 1 FROM … WHERE …)。

例如：

q = session.query(User).filter(User.name == 'fred')
session.query(q.exists())

生成类似于以下 SQL 的 SQL

SELECT EXISTS (
    SELECT 1 FROM users WHERE users.name = :name_1
) AS anon_1

EXISTS 结构通常用于 WHERE 子句中

session.query(User.id).filter(q.exists()).scalar()

注意，某些数据库（如 SQL Server）不允许 EXISTS 表达式出现在 SELECT 的列子句中。要根据 WHERE 中的 exists 选择一个简单的布尔值，请使用 literal()

from sqlalchemy import literal

session.query(literal(True)).filter(q.exists()).scalar()

另见

Select.exists() - v2 相似方法。

方法 sqlalchemy.orm.Query.filter(*criterion: _ColumnExpressionArgument[bool]) → Self

使用 SQL 表达式将给定的过滤条件应用于此 Query 的副本。

例如：

session.query(MyClass).filter(MyClass.name == 'some name')

可以使用逗号分隔符指定多个条件；效果是它们将使用 and_() 函数连接在一起

session.query(MyClass).\
    filter(MyClass.name == 'some name', MyClass.id > 5)

条件是适用于 SELECT 的 WHERE 子句的任何 SQL 表达式对象。字符串表达式通过 text() 结构强制转换为 SQL 表达式结构。

另见

Query.filter_by() - 对关键字表达式进行过滤。

Select.where() - v2 等效方法。

方法 sqlalchemy.orm.Query.filter_by(**kwargs: Any) → Self

使用关键字表达式将给定的过滤条件应用于此 Query 的副本。

例如：

session.query(MyClass).filter_by(name = 'some name')

可以使用逗号分隔符指定多个条件；效果是它们将使用 and_() 函数连接在一起

session.query(MyClass).\
    filter_by(name = 'some name', id = 5)

关键字表达式是从查询的主体或最后一个作为 Query.join() 调用目标的实体中提取的。

另见

Query.filter() - 对 SQL 表达式进行过滤。

Select.filter_by() - v2 可比方法。

method sqlalchemy.orm.Query.first() → _T | None

返回此 Query 的第一个结果，如果结果不包含任何行，则返回 None。

first() 在生成的 SQL 中应用一个限制，因此服务器端只生成一个主实体行（注意，如果存在联接加载的集合，这可能包含多个结果行）。

调用 Query.first() 将导致底层查询的执行。

另见

Query.one()

Query.one_or_none()

Result.first() - v2 可比方法。

Result.scalars() - v2 兼容方法。

method sqlalchemy.orm.Query.from_statement(statement: ExecutableReturnsRows) → Self

执行给定的 SELECT 语句并返回结果。

此方法绕过所有内部语句编译，并且语句在不修改的情况下执行。

该语句通常是 text() 或 select() 结构，并且应返回与此 Query 所表示的实体类相对应的列集。

另见

Select.from_statement() - v2 可比方法。

method sqlalchemy.orm.Query.get(ident: _PKIdentityArgument) → Any | None

根据给定的主键标识符返回一个实例，如果未找到，则返回 None。

从版本 2.0 开始弃用: 从 SQLAlchemy 的 1.x 系列开始，Query.get() 方法被认为是遗留方法，并且在 2.0 中成为遗留构造。现在该方法作为 Session.get() 可用（有关 SQLAlchemy 2.0 的背景信息，请参见：SQLAlchemy 2.0 - 主要迁移指南）

例如

my_user = session.query(User).get(5)

some_object = session.query(VersionedFoo).get((5, 10))

some_object = session.query(VersionedFoo).get(
    {"id": 5, "version_id": 10})

Query.get() 的特殊之处在于它提供了对拥有 Session 的身份映射的直接访问。如果给定的主键标识符存在于本地身份映射中，则直接从该集合中返回该对象，并且不会发出 SQL，除非该对象已被标记为完全过期。如果不存在，则执行 SELECT 以定位该对象。

Query.get() 还会检查该对象是否存在于身份映射中并标记为过期 - 将发出 SELECT 来刷新该对象，以及确保该行仍然存在。如果不存在，则会引发 ObjectDeletedError。

Query.get() 仅用于返回单个映射的实例，而不是多个实例或单个列构造，并且严格地只用于单个主键值。原始 Query 必须以此方式构建，即针对单个映射的实体，没有任何其他过滤条件。但是，可以通过 Query.options() 应用加载选项，并且如果该对象尚未在本地存在，则将使用这些选项。

参数:

ident –

表示主键的标量、元组或字典。对于复合（例如多列）主键，应传递元组或字典。

对于单列主键，标量调用形式通常是最有效的方式。如果行的主键是值“5”，则调用看起来像

my_object = query.get(5)

元组形式通常包含主键值，它们的顺序与映射的 Table 对象的主键列的顺序相对应，或者如果使用了 Mapper.primary_key 配置参数，则按该参数的顺序排列。例如，如果行的主键由整数数字“5, 10”表示，则调用看起来像

my_object = query.get((5, 10))

字典形式应将与主键的每个元素相对应的映射属性名称作为键。如果映射的类具有属性 id、version_id 作为存储对象主键值的属性，则调用看起来像

my_object = query.get({"id": 5, "version_id": 10})

版本 1.3 中新增: Query.get() 方法现在可以选择接受属性名称到值的字典，以指示主键标识符。

返回值：:

对象实例或 None。

method sqlalchemy.orm.Query.get_children(*, omit_attrs: Tuple[str, ...] = (), **kw: Any) → Iterable[HasTraverseInternals]

继承自 HasTraverseInternals.get_children() 方法的 HasTraverseInternals

返回此 HasTraverseInternals 的直接子 HasTraverseInternals 元素。

这用于访问遍历。

**kw 可能包含更改返回集合的标志，例如返回子集以减少较大遍历，或从不同上下文返回子元素（例如模式级别集合而不是子句级别）。

method sqlalchemy.orm.Query.get_execution_options() → _ImmutableExecuteOptions

获取执行期间将生效的非 SQL 选项。

版本 1.3 中新增。

另见

Query.execution_options()

Select.get_execution_options() - v2 可比方法。

attribute sqlalchemy.orm.Query.get_label_style

检索当前标签样式。

版本 1.4 中新增。

另见

Select.get_label_style() - v2 等效方法。

method sqlalchemy.orm.Query.group_by(_Query__first: Literal[None, False, _NoArg.NO_ARG] | _ColumnExpressionOrStrLabelArgument[Any] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any]) → Self

对查询应用一个或多个 GROUP BY 准则，并返回新生成的 Query。

通过传递 None 可以抑制所有现有的 GROUP BY 设置 - 这也会抑制映射器上配置的任何 GROUP BY。

另见

这些部分从 2.0 样式 调用方面描述 GROUP BY，但也适用于 Query。

使用 GROUP BY / HAVING 的聚合函数 - 在 SQLAlchemy 统一教程 中

按标签排序或分组 - 在 SQLAlchemy 统一教程 中

Select.group_by() - v2 等效方法。

method sqlalchemy.orm.Query.having(*having: _ColumnExpressionArgument[bool]) → Self

对查询应用 HAVING 准则，并返回新生成的 Query。

Query.having() 与 Query.group_by() 结合使用。

HAVING 准则使得对聚合函数（如 COUNT、SUM、AVG、MAX 和 MIN）使用过滤器成为可能，例如。

q = session.query(User.id).\
            join(User.addresses).\
            group_by(User.id).\
            having(func.count(Address.id) > 2)

另见

Select.having() - v2 等效方法。

method sqlalchemy.orm.Query.instances(result_proxy: CursorResult[Any], context: QueryContext | None = None) → Any

返回给定 CursorResult 和 QueryContext 的 ORM 结果。

从版本 2.0 开始弃用: The Query.instances() method is deprecated and will be removed in a future release. Use the Select.from_statement() method or aliased() construct in conjunction with Session.execute() instead.

method sqlalchemy.orm.Query.intersect(*q: Query) → Self

生成此 Query 与一个或多个查询的 INTERSECT。

工作方式与 Query.union() 相同。有关使用示例，请参见该方法。

另见

Select.intersect() - v2 等效方法。

method sqlalchemy.orm.Query.intersect_all(*q: Query) → Self

生成此 Query 与一个或多个查询的 INTERSECT ALL。

工作方式与 Query.union() 相同。有关使用示例，请参见该方法。

另见

Select.intersect_all() - v2 等效方法。

attribute sqlalchemy.orm.Query.is_single_entity

指示此 Query 返回元组还是单个实体。

如果此查询为其结果列表中的每个实例返回单个实体，则返回 True，如果此查询为每个结果返回实体元组，则返回 False。

版本 1.3.11 中的新增功能。

另见

Query.only_return_tuples()

method sqlalchemy.orm.Query.join(target: _JoinTargetArgument, onclause: _OnClauseArgument | None = None, *, isouter: bool = False, full: bool = False) → Self

针对此 Query 对象的准则创建 SQL JOIN 并以生成方式应用，返回新生成的 Query。

简单关系联接

考虑两个类 User 和 Address 之间的映射，关系 User.addresses 代表与每个 User 关联的 Address 对象的集合。 Query.join() 的最常见用法是沿着这种关系创建 JOIN，使用 User.addresses 属性作为如何执行此操作的指示器

q = session.query(User).join(User.addresses)

在上面，沿着 User.addresses 对 Query.join() 的调用将生成与以下 SQL 大致等效的 SQL：

SELECT user.id, user.name
FROM user JOIN address ON user.id = address.user_id

在上面的示例中，我们将传递给 Query.join() 的 User.addresses 称为“ON 子句”，也就是说，它指示如何构建 JOIN 的“ON”部分。

要构建连接链，可以使用多个 Query.join() 调用。与关系绑定的属性同时暗示了连接的左右两侧。

q = session.query(User).\
        join(User.orders).\
        join(Order.items).\
        join(Item.keywords)

注意

如上面示例所示，**每次调用 join() 方法的顺序非常重要**。例如，如果我们先指定 User，然后是 Item，最后是 Order，那么 Query 将无法知道如何正确连接；在这种情况下，根据传递的参数，它可能会引发一个错误，表明它不知道如何连接，或者它可能会生成无效的 SQL，在这种情况下数据库会引发错误。在正确的实践中，Query.join() 方法的调用方式应该与我们希望 JOIN 子句在 SQL 中呈现的方式一致，并且每次调用都应该代表一个从其之前部分的明确链接。

连接到目标实体或可选择项

Query.join() 的第二种形式允许任何映射实体或核心可选择构造作为目标。在这种用法中，Query.join() 将尝试沿着两个实体之间的自然外键关系创建 JOIN。

q = session.query(User).join(Address)

在上面的调用形式中，Query.join() 被调用来为我们自动创建“ON 子句”。如果两个实体之间没有外键，或者目标实体与左侧已存在的实体之间存在多个外键链接，使得创建连接需要更多信息，则这种调用形式最终会引发错误。请注意，在指示连接到没有 ON 子句的目标时，不会考虑 ORM 配置的关系。

连接到具有 ON 子句的目标

第三种调用形式允许显式传递目标实体以及 ON 子句。一个包含 SQL 表达式作为 ON 子句的示例如下

q = session.query(User).join(Address, User.id==Address.user_id)

上面的形式也可以使用与关系绑定的属性作为 ON 子句。

q = session.query(User).join(Address, User.addresses)

上面的语法对于希望连接到特定目标实体的别名的情况很有用。如果我们想连接到 Address 两次，可以使用 aliased() 函数设置的两个别名来实现。

a1 = aliased(Address)
a2 = aliased(Address)

q = session.query(User).\
        join(a1, User.addresses).\
        join(a2, User.addresses).\
        filter(a1.email_address=='[email protected]').\
        filter(a2.email_address=='[email protected]')

与关系绑定的调用形式也可以使用 PropComparator.of_type() 方法指定目标实体；与上面相同的查询等效于

a1 = aliased(Address)
a2 = aliased(Address)

q = session.query(User).\
        join(User.addresses.of_type(a1)).\
        join(User.addresses.of_type(a2)).\
        filter(a1.email_address == '[email protected]').\
        filter(a2.email_address == '[email protected]')

增强内置 ON 子句

作为为现有关系提供完整自定义 ON 条件的替代方法，可以使用 PropComparator.and_() 函数将其他条件应用到关系属性，以增强 ON 子句；这些其他条件将使用 AND 与默认条件组合。

q = session.query(User).join(
    User.addresses.and_(Address.email_address != '[email protected]')
)

版本 1.4 中新增。

连接到表和子查询

连接的目标也可以是任何表或 SELECT 语句，它们可能与目标实体相关联，也可能不相关联。使用适当的 .subquery() 方法来从查询中创建一个子查询。

subq = session.query(Address).\
    filter(Address.email_address == '[email protected]').\
    subquery()


q = session.query(User).join(
    subq, User.id == subq.c.user_id
)

在特定关系和/或目标实体方面连接到子查询可以通过使用 aliased() 将子查询链接到实体来实现。

subq = session.query(Address).\
    filter(Address.email_address == '[email protected]').\
    subquery()

address_subq = aliased(Address, subq)

q = session.query(User).join(
    User.addresses.of_type(address_subq)
)

控制连接源

在 Query 的当前状态左侧与我们想要连接的源不一致的情况下，可以使用 Query.select_from() 方法。

q = session.query(Address).select_from(User).\
                join(User.addresses).\
                filter(User.name == 'ed')

这将生成类似于以下内容的 SQL

SELECT address.* FROM user
    JOIN address ON user.id=address.user_id
    WHERE user.name = :name_1

另见

Select.join() - v2 等效方法。

参数:

  • *props – Query.join() 的传入参数，在现代用法中，props 集合应被认为是一或二参数形式，可以是单个“目标”实体或 ORM 属性绑定的关系，也可以是目标实体加上一个“ON 子句”，该子句可以是 SQL 表达式或 ORM 属性绑定的关系。

  • isouter=False – 如果为 True，则使用的连接将是左外连接，就像调用了 Query.outerjoin() 方法一样。

  • full=False – 呈现 FULL OUTER JOIN；暗示 isouter。

method sqlalchemy.orm.Query.label(name: str | None) → Label[Any]

返回由此 Query 表示的完整 SELECT 语句，转换为具有给定名称的标签的标量子查询。

另见

Select.label() - v2 可比方法。

attribute sqlalchemy.orm.Query.lazy_loaded_from

一个 InstanceState，它正在使用此 Query 进行延迟加载操作。

自版本 1.4 起弃用: 此属性应通过 ORMExecuteState.lazy_loaded_from 属性，在 SessionEvents.do_orm_execute() 事件的上下文中查看。

另见

ORMExecuteState.lazy_loaded_from

method sqlalchemy.orm.Query.limit(limit: _LimitOffsetType) → Self

将 LIMIT 应用于查询并返回新生成的 Query。

另见

Select.limit() - v2 等效方法。

method sqlalchemy.orm.Query.merge_result(iterator: FrozenResult[Any] | Iterable[Sequence[Any]] | Iterable[object], load: bool = True) → FrozenResult[Any] | Iterable[Any]

将结果合并到此 Query 对象的 Session 中。

从版本 2.0 开始弃用: The Query.merge_result() 方法在 SQLAlchemy 的 1.x 版本中被视为遗留方法，并在 2.0 版本中成为遗留结构。该方法被 merge_frozen_result() 函数取代。（关于 SQLAlchemy 2.0 的背景信息，请参见：SQLAlchemy 2.0 - Major Migration Guide)

给定由与当前 Query 结构相同的 Query 返回的迭代器，返回一个具有相同结果结构的相同迭代器，其中所有映射的实例都使用 Session.merge() 合并到会话中。这是一种优化的方法，它将合并所有映射的实例，并保留结果行的结构和非映射的列，方法开销小于为每个值显式调用 Session.merge()。

结果的结构根据此 Query 的列列表确定 - 如果它们不一致，将会发生未检查的错误。

“load”参数与 Session.merge() 中的参数相同。

有关如何使用 Query.merge_result() 的示例，请参见示例 Dogpile Caching 的源代码，其中 Query.merge_result() 用于将状态从缓存有效地恢复到目标 Session。

method sqlalchemy.orm.Query.offset(offset: _LimitOffsetType) → Self

将 OFFSET 应用于查询，并返回新生成的 Query。

另见

Select.offset() - v2 等效方法。

method sqlalchemy.orm.Query.one() → _T

返回恰好一个结果，否则抛出异常。

如果查询未选择任何行，则引发 sqlalchemy.orm.exc.NoResultFound。如果返回多个对象标识，或者如果针对仅返回标量值而不是完整标识映射实体的查询返回多行，则引发 sqlalchemy.orm.exc.MultipleResultsFound。

调用 one() 将导致执行底层查询。

另见

Query.first()

Query.one_or_none()

Result.one() - v2 可比较方法。

Result.scalar_one() - v2 可比较方法。

method sqlalchemy.orm.Query.one_or_none() → _T | None

返回最多一个结果，否则抛出异常。

如果查询未选择任何行，则返回 None。如果返回多个对象标识，或者如果针对仅返回标量值而不是完整标识映射实体的查询返回多行，则引发 sqlalchemy.orm.exc.MultipleResultsFound。

调用 Query.one_or_none() 将导致执行底层查询。

另见

Query.first()

Query.one()

Result.one_or_none() - v2 可比较方法。

Result.scalar_one_or_none() - v2 可比较方法。

method sqlalchemy.orm.Query.only_return_tuples(value: bool) → Query

当设置为 True 时，查询结果将始终是 Row 对象。

这可以将通常返回单个实体作为标量的查询更改为在所有情况下都返回 Row 结果。

另见

Query.tuples() - 返回元组，但在类型级别上也将结果类型化为 Tuple。

Query.is_single_entity()

Result.tuples() - v2 可比较方法。

method sqlalchemy.orm.Query.options(*args: ExecutableOption) → Self

返回一个新的 Query 对象，应用给定的映射器选项列表。

大多数提供的选项都与更改列和关系映射属性的加载方式有关。

另见

列加载选项

使用加载程序选项进行关系加载

method sqlalchemy.orm.Query.order_by(_Query__first: Literal[None, False, _NoArg.NO_ARG] | _ColumnExpressionOrStrLabelArgument[Any] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any]) → Self

将一个或多个 ORDER BY 条件应用于查询，并返回新生成的 Query。

例如：

q = session.query(Entity).order_by(Entity.id, Entity.name)

多次调用此方法等同于使用所有连接的子句调用它一次。通过单独传递 None 可以取消所有现有的 ORDER BY 条件。然后可以通过再次调用 Query.order_by() 添加新的 ORDER BY 条件，例如：

# will erase all ORDER BY and ORDER BY new_col alone
q = q.order_by(None).order_by(new_col)

另见

这些部分从 2.0 样式 调用方面描述了 ORDER BY，但适用于 Query。

ORDER BY - 在 SQLAlchemy 统一教程 中。

按标签排序或分组 - 在 SQLAlchemy 统一教程 中

Select.order_by() - v2 等效方法。

method sqlalchemy.orm.Query.outerjoin(target: _JoinTargetArgument, onclause: _OnClauseArgument | None = None, *, full: bool = False) → Self

对这个 Query 对象的标准创建左外连接，并以生成方式应用，返回新生成的 Query。

使用方法与 join() 方法相同。

另见

Select.outerjoin() - v2 等效方法。

method sqlalchemy.orm.Query.params(_Query__params: Dict[str, Any] | None = None, **kw: Any) → Self

添加可能在 filter() 中指定的绑定参数的值。

可以使用 **kwargs 指定参数，或者可以选择使用单个字典作为第一个位置参数。 两者兼顾的原因是 **kwargs 很方便，但是一些参数字典包含 unicode 键，在这种情况下无法使用 **kwargs。

method sqlalchemy.orm.Query.populate_existing() → Self

返回一个 Query，它将在加载时或从当前 Session 中重用时，使所有实例失效并刷新。

从 SQLAlchemy 1.4 开始，Query.populate_existing() 方法等效于在 ORM 级别使用 populate_existing 执行选项。 有关此选项的更多背景信息，请参阅部分 填充现有。

method sqlalchemy.orm.Query.prefix_with(*prefixes: _TextCoercedExpressionArgument[Any], dialect: str = '*') → Self

继承自 HasPrefixes.prefix_with() 方法的 HasPrefixes

在语句关键字（例如 SELECT、INSERT、UPDATE 或 DELETE）之后添加一个或多个表达式。 生成式。

这用于支持后端特定的前缀关键字，例如 MySQL 提供的关键字。

例如

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

# MySQL 5.7 optimizer hints
stmt = select(table).prefix_with(
    "/*+ BKA(t1) */", dialect="mysql")

可以通过多次调用 HasPrefixes.prefix_with() 指定多个前缀。

参数:

  • *prefixes – 文本或 ClauseElement 构造，它将在 INSERT、UPDATE 或 DELETE 关键字之后呈现。

  • dialect – 可选的字符串方言名称，它将限制此前缀的呈现，仅限于该方言。

method sqlalchemy.orm.Query.reset_joinpoint() → Self

返回一个新的 Query，其中“连接点”已重置回查询的基 FROM 实体。

此方法通常与 Query.join() 方法的 aliased=True 功能结合使用。 请参阅 Query.join() 中的示例，了解如何使用它。

method sqlalchemy.orm.Query.scalar() → Any

返回第一个结果的第一个元素，如果没有行则返回 None。 如果返回多行，则引发 MultipleResultsFound。

>>> session.query(Item).scalar()
<Item>
>>> session.query(Item.id).scalar()
1
>>> session.query(Item.id).filter(Item.id < 0).scalar()
None
>>> session.query(Item.id, Item.name).scalar()
1
>>> session.query(func.count(Parent.id)).scalar()
20

这将导致执行底层查询。

另见

Result.scalar() - v2 可比较方法。

method sqlalchemy.orm.Query.scalar_subquery() → ScalarSelect[Any]

将此 Query 表示的完整 SELECT 语句转换为标量子查询。

类似于 SelectBase.scalar_subquery()。

在版本 1.4 中更改: The Query.scalar_subquery() 方法取代了 Query.as_scalar() 方法。

另见

Select.scalar_subquery() - v2 可比较方法。

method sqlalchemy.orm.Query.select_from(*from_obj: FromClauseRole | Type[Any] | Inspectable[_HasClauseElement[Any]] | _HasClauseElement[Any]) → Self

显式设置此 Query 的 FROM 子句。

Query.select_from() 通常与 Query.join() 结合使用，以控制在联接的“左侧”选择哪个实体。

这里的实体或可选择对象有效地替换了对 Query.join() 的任何调用时的“左边缘”，当没有建立联接点时 - 通常，默认的“联接点”是 Query 对象中要选择的实体列表的最左侧实体。

一个典型的例子

q = session.query(Address).select_from(User).\
    join(User.addresses).\
    filter(User.name == 'ed')

产生等效于 SQL 的代码

SELECT address.* FROM user
JOIN address ON user.id=address.user_id
WHERE user.name = :name_1
参数:

*from_obj – 要应用于 FROM 子句的一个或多个实体的集合。实体可以是映射类、AliasedClass 对象、Mapper 对象以及核心 FromClause 元素（如子查询）。

另见

Query.join()

Query.select_entity_from()

Select.select_from() - v2 等效方法。

attribute sqlalchemy.orm.Query.selectable

返回此 Query 发出的 Select 对象。

用于 inspect() 兼容性，这等效于

query.enable_eagerloads(False).with_labels().statement
method sqlalchemy.orm.Query.set_label_style(style: SelectLabelStyle) → Self

将列标签应用于 Query.statement 的返回值。

指示此 Query 的 statement 访问器应返回一个 SELECT 语句，该语句将标签应用于所有列，形式为 <tablename>_<columnname>；这通常用于消除来自具有相同名称的多个表的列的歧义。

当 Query 实际发出 SQL 来加载行时，它始终使用列标记。

注意

Query.set_label_style() 方法 *仅* 应用 Query.statement 的输出，而 *不* 应用于 Query 本身的任何结果行调用系统，例如 Query.first()、Query.all() 等。要使用 Query.set_label_style() 执行查询，请使用 Session.execute() 调用 Query.statement。

result = session.execute(
    query
    .set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
    .statement
)

版本 1.4 中新增。

另见

Select.set_label_style() - v2 等效方法。

method sqlalchemy.orm.Query.slice(start: int, stop: int) → Self

计算由给定索引表示的 Query 的“切片”，并返回生成的 Query。

起始和结束索引的行为类似于 Python 的内置 range() 函数的参数。此方法提供了一种替代使用 LIMIT/OFFSET 来获取查询切片的方法。

例如，

session.query(User).order_by(User.id).slice(1, 3)

渲染为

SELECT users.id AS users_id,
       users.name AS users_name
FROM users ORDER BY users.id
LIMIT ? OFFSET ?
(2, 1)

另见

Query.limit()

Query.offset()

Select.slice() - v2 等效方法。

attribute sqlalchemy.orm.Query.statement

此 Query 表示的完整 SELECT 语句。

默认情况下，该语句不会在构造中应用区分标签，除非首先调用 with_labels(True)。

method sqlalchemy.orm.Query.subquery(name: str | None = None, with_labels: bool = False, reduce_columns: bool = False) → Subquery

返回此 Query 表示的完整 SELECT 语句，嵌入到 Alias 中。

禁用查询中的急切 JOIN 生成。

另见

Select.subquery() - v2 可比较的方法。

参数:

  • name – 要分配为别名的字符串名称；这将传递给 FromClause.alias()。如果为 None，则会在编译时确定性地生成一个名称。

  • with_labels – 如果为 True，则会先在 Query 上调用 with_labels()，以将表限定标签应用于所有列。

  • reduce_columns – 如果为 True，则会对生成的 select() 构造调用 Select.reduce_columns()，以删除同名列，其中一个列也通过外键或 WHERE 子句等效性引用另一个列。

method sqlalchemy.orm.Query.suffix_with(*suffixes: _TextCoercedExpressionArgument[Any], dialect: str = '*') → Self

继承自 HasSuffixes.suffix_with() 方法 HasSuffixes

在语句末尾添加一个或多个表达式。

这用于支持某些结构上的后端特定后缀关键字。

例如

stmt = select(col1, col2).cte().suffix_with(
    "cycle empno set y_cycle to 1 default 0", dialect="oracle")

可以通过对 HasSuffixes.suffix_with() 的多次调用来指定多个后缀。

参数:

  • *suffixes – 文本或 ClauseElement 结构，将在目标子句之后呈现。

  • dialect – 可选的字符串方言名称，它将限制此后缀的呈现，使其仅适用于该方言。

method sqlalchemy.orm.Query.tuples() → Query

返回此 Query 的元组类型形式。

此方法使用值为 True 的值调用 Query.only_return_tuples() 方法，这本身确保此 Query 将始终返回 Row 对象，即使查询针对单个实体也是如此。然后，它还将在类型级别返回一个“类型化”查询（如果可能），该查询将结果行类型化为具有类型化元素的 Tuple 对象。

此方法可以与 Result.tuples() 方法进行比较，该方法返回“self”，但从类型角度来看，返回一个将为结果生成类型化 Tuple 对象的对象。类型化仅在该 Query 对象本身已经是类型化查询对象时才生效。

版本 2.0 中的新增功能。

另见

Result.tuples() - v2 等效方法。

method sqlalchemy.orm.Query.union(*q: Query) → Self

对该查询与一个或多个查询进行 UNION 操作。

例如：

q1 = sess.query(SomeClass).filter(SomeClass.foo=='bar')
q2 = sess.query(SomeClass).filter(SomeClass.bar=='foo')

q3 = q1.union(q2)

该方法接受多个 Query 对象，以便控制嵌套级别。一系列 union() 调用，例如

x.union(y).union(z).all()

将在每个 union() 上嵌套，并生成

SELECT * FROM (SELECT * FROM (SELECT * FROM X UNION
                SELECT * FROM y) UNION SELECT * FROM Z)

而

x.union(y, z).all()

生成

SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y UNION
                SELECT * FROM Z)

注意，许多数据库后端不允许在 UNION、EXCEPT 等中调用的查询上呈现 ORDER BY。要禁用包括映射器配置的 ORDER BY 子句在内的所有 ORDER BY 子句，请发出 query.order_by(None) - 生成的 Query 对象将不会在其 SELECT 语句中呈现 ORDER BY。

另见

Select.union() - v2 等效方法。

method sqlalchemy.orm.Query.union_all(*q: Query) → Self

对该查询与一个或多个查询进行 UNION ALL 操作。

工作方式与 Query.union() 相同。有关使用示例，请参见该方法。

另见

Select.union_all() - v2 等效方法。

method sqlalchemy.orm.Query.update(values: Dict[_DMLColumnArgument, Any], synchronize_session: SynchronizeSessionArgument = 'auto', update_args: Dict[Any, Any] | None = None) → int

使用任意 WHERE 子句执行 UPDATE。

更新数据库中此查询匹配的行。

例如

sess.query(User).filter(User.age == 25).\
    update({User.age: User.age - 10}, synchronize_session=False)

sess.query(User).filter(User.age == 25).\
    update({"age": User.age - 10}, synchronize_session='evaluate')

警告

有关重要注意事项和警告，包括使用任意 UPDATE 和 DELETE 时在映射器继承配置方面的限制，请参阅 启用 ORM 的 INSERT、UPDATE 和 DELETE 语句 部分。

参数:
返回值：:

由数据库的“行计数”功能返回的匹配行数。

另见

ORM 支持的 INSERT、UPDATE 和 DELETE 语句

method sqlalchemy.orm.Query.value(column: _ColumnExpressionArgument[Any]) → Any

返回与给定列表达式相对应的标量结果。

已弃用，版本 1.4: Query.value() 已弃用，将在未来版本中移除。请使用 Query.with_entities() 并结合 Query.scalar()

method sqlalchemy.orm.Query.values(*columns: _ColumnsClauseArgument[Any]) → Iterable[Any]

返回一个迭代器，生成与给定列列表相对应的结果元组。

已弃用，版本 1.4: Query.values() 已弃用，将在未来版本中移除。请使用 Query.with_entities()

method sqlalchemy.orm.Query.where(*criterion: _ColumnExpressionArgument[bool]) → Self

Query.filter() 的同义词。

版本 1.4 中新增。

另见

Select.where() - v2 等效方法。

attribute sqlalchemy.orm.Query.whereclause

一个只读属性，返回此 Query 的当前 WHERE 条件。

此返回值是一个 SQL 表达式构造，如果未建立任何条件，则为 None。

另见

Select.whereclause - v2 等效属性。

method sqlalchemy.orm.Query.with_entities(*entities: _ColumnsClauseArgument[Any], **_Query__kw: Any) → Query[Any]

返回一个新的 Query，用给定的实体替换 SELECT 列表。

例如：

# Users, filtered on some arbitrary criterion
# and then ordered by related email address
q = session.query(User).\
            join(User.address).\
            filter(User.name.like('%ed%')).\
            order_by(Address.email)

# given *only* User.id==5, Address.email, and 'q', what
# would the *next* User in the result be ?
subq = q.with_entities(Address.email).\
            order_by(None).\
            filter(User.id==5).\
            subquery()
q = q.join((subq, subq.c.email < Address.email)).\
            limit(1)

另见

Select.with_only_columns() - v2 可比较方法。

method sqlalchemy.orm.Query.with_for_update(*, nowait: bool = False, read: bool = False, of: _ForUpdateOfArgument | None = None, skip_locked: bool = False, key_share: bool = False) → Self

返回一个新的 Query，其中包含 FOR UPDATE 子句的指定选项。

此方法的行为与 GenerativeSelect.with_for_update() 的行为相同。当不带任何参数调用时，生成的 SELECT 语句将附加一个 FOR UPDATE 子句。当指定了其他参数时，特定于后端的选项（如 FOR UPDATE NOWAIT 或 LOCK IN SHARE MODE）可以生效。

例如

q = sess.query(User).populate_existing().with_for_update(nowait=True, of=User)

在 PostgreSQL 后端上的上述查询将呈现为

SELECT users.id AS users_id FROM users FOR UPDATE OF users NOWAIT

警告

在涉及急切加载关系的上下文中使用 with_for_update，不受 SQLAlchemy 官方支持，也不推荐使用，并且可能无法在各种数据库后端上的某些查询中使用。当 with_for_update 成功地与涉及 joinedload() 的查询一起使用时，SQLAlchemy 将尝试发出锁定所有相关表的 SQL。

注意

通常，在使用 Query.with_for_update() 方法时，将 Query.populate_existing() 方法组合起来是一个好主意。 Query.populate_existing() 的目的是强制将从 SELECT 读取的所有数据填充到返回的 ORM 对象中，即使这些对象已在 身份映射 中。

另见

GenerativeSelect.with_for_update() - 核心级方法，具有完整的参数和行为描述。

Query.populate_existing() - 覆盖已加载到身份映射中的对象的属性。

method sqlalchemy.orm.Query.with_hint(selectable: _FromClauseArgument, text: str, dialect_name: str = '*') → Self

继承自 HasHints.with_hint() 方法的 HasHints

为给定的可选择对象添加索引或其他执行上下文提示，用于此 Select 或其他可选择对象。

提示

Select.with_hint() 方法添加仅针对单个表的提示，在特定于方言的位置。要将通用优化器提示添加到语句的开头，在 SELECT 关键字之前，例如对于 MySQL 或 Oracle，请使用 Select.prefix_with() 方法。要将优化器提示添加到语句的结尾，例如对于 PostgreSQL，请使用 Select.with_statement_hint() 方法。

提示文本将在正在使用的数据库后端中，相对于给定的 Table 或 Alias（作为 selectable 参数传递）的位置呈现。方言实现通常使用 Python 字符串替换语法，带有令牌 %(name)s 来呈现表或别名的名称。例如，在使用 Oracle 时，以下

select(mytable).\
    with_hint(mytable, "index(%(name)s ix_mytable)")

将呈现以下 SQL：

select /*+ index(mytable ix_mytable) */ ... from mytable

dialect_name 选项将限制特定提示在特定后端的呈现。例如，要同时添加 Oracle 和 Sybase 的提示

select(mytable).\
    with_hint(mytable, "index(%(name)s ix_mytable)", 'oracle').\
    with_hint(mytable, "WITH INDEX ix_mytable", 'mssql')

另见

Select.with_statement_hint()

Select.prefix_with() - 通用 SELECT 前缀，它也适合某些数据库特定的 HINT 语法，例如 MySQL 或 Oracle 优化器提示

method sqlalchemy.orm.Query.with_labels() → Self

已弃用，自版本 2.0 起： 从 SQLAlchemy 1.x 系列开始，Query.with_labels() 和 Query.apply_labels() 方法被视为遗留方法，在 2.0 中变为遗留构造。请改用 set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)。（有关 SQLAlchemy 2.0 的背景信息，请参阅：SQLAlchemy 2.0 - 主要迁移指南)

method sqlalchemy.orm.Query.with_parent(instance: object, property: attributes.QueryableAttribute[Any] | None = None, from_entity: _ExternalEntityType[Any] | None = None) → Self

使用给定实例的属性状态以及已建立的 relationship() 配置，添加将给定实例关联到子对象或集合的过滤条件。

自版本 2.0 起已弃用: Query.with_parent() 方法在 SQLAlchemy 的 1.x 系列中被视为遗留方法，并在 2.0 中成为遗留结构。使用 with_parent() 自立结构。（有关 SQLAlchemy 2.0 的背景信息，请访问：SQLAlchemy 2.0 - 主要迁移指南)

该方法使用 with_parent() 函数生成子句，其结果传递给 Query.filter()。

参数与 with_parent() 相同，只是给定的属性可以是 None，在这种情况下，将针对此 Query 对象的目标映射器执行搜索。

参数:

  • instance – 具有 relationship() 的实例。

  • property – 类绑定属性，指示应使用实例中的什么关系来协调父子关系。

  • from_entity – 视为左侧的实体。这默认为 Query 本身的“零”实体。

method sqlalchemy.orm.Query.with_session(session: Session) → Self

返回一个将使用给定 Session 的 Query。

虽然 Query 对象通常使用 Session.query() 方法实例化，但可以直接构建 Query，而不一定使用 Session。这样的 Query 对象，或任何已与其他 Session 关联的 Query，可以使用此方法生成与目标会话关联的新 Query 对象

from sqlalchemy.orm import Query

query = Query([MyClass]).filter(MyClass.id == 5)

result = query.with_session(my_session).one()
method sqlalchemy.orm.Query.with_statement_hint(text: str, dialect_name: str = '*') → Self

继承自 HasHints.with_statement_hint() 方法的 HasHints

为此 Select 或其他可选择对象添加语句提示。

提示

Select.with_statement_hint() 通常会在 SELECT 语句的末尾添加提示。若要将特定于方言的提示（如优化器提示）放置在 SELECT 关键字之前的 SELECT 语句开头，请使用 Select.prefix_with() 方法创建开放式空间，或者使用 Select.with_hint() 方法在特定于方言的位置放置针对表的提示。

此方法与 Select.with_hint() 相似，区别在于它不需要单独的表，而是应用于整个语句。

此处的提示特定于后端数据库，可能包括隔离级别指令、文件指令、提取指令等。

另见

Select.with_hint()

Select.prefix_with() - 通用 SELECT 前缀，它也适合某些数据库特定的 HINT 语法，例如 MySQL 或 Oracle 优化器提示

method sqlalchemy.orm.Query.with_transformation(fn: Callable[[Query], Query]) → Query

返回一个新的 Query 对象，该对象已由给定函数转换。

例如

def filter_something(criterion):
    def transform(q):
        return q.filter(criterion)
    return transform

q = q.with_transformation(filter_something(x==5))

这允许为 Query 对象创建临时配方。

method sqlalchemy.orm.Query.yield_per(count: int) → Self

一次仅生成 count 行。

此方法的目的是在获取非常大的结果集（> 10K 行）时，将结果批处理到子集合中并部分地生成它们，以便 Python 解释器不需要声明非常大的内存区域，这既耗时又会导致过度使用内存。即使使用缓冲行的 DBAPI（大多数 DBAPI 都是如此），从数十万行中获取数据的性能也通常可以提高一倍，只要使用合适的 yield-per 设置（例如，大约 1000）。

从 SQLAlchemy 1.4 开始，Query.yield_per() 方法等效于在 ORM 级别使用 yield_per 执行选项。有关此选项的更多背景信息，请参阅 使用 Yield Per 获取大型结果集 部分。

另见

使用 Yield Per 获取大型结果集

特定于 ORM 的查询构造

本节内容已移至 其他 ORM API 构造。