传统查询 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 对象

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

q = session.query(SomeMappedClass)

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

对象名称 描述

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]

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

Deprecated since version 1.4: Query.add_column() 已弃用，将在未来版本中删除。请使用 Query.add_columns()

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

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

另请参阅

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

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

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

另请参阅

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

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

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

这将导致执行底层 SQL 语句。

警告

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

另请参阅

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

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

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

Deprecated since version 2.0: Query.with_labels() 和 Query.apply_labels() 方法从 SQLAlchemy 1.x 系列开始被认为是旧版，并在 2.0 中成为旧版构造。请改用 set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)。（有关 SQLAlchemy 2.0 的背景信息，请访问：SQLAlchemy 2.0 - 主要迁移指南）

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

返回由此 Query 表示的完整 SELECT 语句，并将其转换为标量子查询。

Deprecated since version 1.4: Query.as_scalar() 方法已弃用，将在未来版本中删除。请参阅 Query.scalar_subquery()。

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

返回具有特定“自动刷新”设置的 Query。

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

attribute 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 风格 的查询，文档位于

method 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', delete_args: Dict[Any, Any] | None = None) → 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"
)

警告

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

参数:

  • synchronize_session – 选择更新会话中对象属性的策略。请参阅 启用 ORM 的 INSERT、UPDATE 和 DELETE 语句 部分，了解这些策略的讨论。

  • delete_args –

    可选字典，如果存在，将作为 **kw 传递给底层 delete() 构造。可用于传递特定于方言的参数，例如 mysql_limit。

    2.0.37 版本新增。

返回:

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

另请参阅

启用 ORM 的 INSERT、UPDATE 和 DELETE 语句

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

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

注意

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

Deprecated since version 2.0: 此逻辑已弃用，将在 SQLAlchemy 2.0 中删除。请参阅 使用 DISTINCT 和附加列，但仅选择实体，了解 2.0 中此用例的描述。

另请参阅

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

参数:

*expr –

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

Deprecated since version 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() 设置的任何条件。

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

控制是否呈现迫切连接和子查询。

设置为 False 时，无论 joinedload()、subqueryload() 选项或映射器级别的 lazy='joined'/lazy='subquery' 配置如何，返回的 Query 都不会呈现迫切连接。

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

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

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

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

另请参阅

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

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

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

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

另请参阅

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

method 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 执行选项。

New in version 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 等效方法。

method sqlalchemy.orm.Query.exists() → Exists

一种便捷方法，可将查询转换为 EXISTS 子查询，形式为 EXISTS (SELECT 1 FROM … WHERE …)。

例如：

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

生成类似于以下的 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 的列子句中。要基于 exists 选择一个简单的布尔值作为 WHERE，请使用 literal()

from sqlalchemy import literal

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

另请参阅

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

method 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 等效方法。

method 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 中应用限制为 1，以便仅在服务器端生成一个主实体行（请注意，如果存在连接加载的集合，则这可能包含多个结果行）。

调用 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。

Deprecated since version 2.0: Query.get() 方法从 SQLAlchemy 1.x 系列开始被认为是遗留方法，并在 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})

New in version 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 选项。

New in version 1.3.

另请参阅

Query.execution_options()

Select.get_execution_options() - v2 对等方法。

attribute sqlalchemy.orm.Query.get_label_style

检索当前标签样式。

New in version 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 结果。

Deprecated since version 2.0: Query.instances() 方法已弃用，并将在未来的版本中删除。 请使用 Select.from_statement() 方法或 aliased() 构造与 Session.execute() 结合使用。

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。

New in version 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。

简单的关系 JOIN

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

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

在上面，调用 Query.join() 沿着 User.addresses 将导致 SQL 大致等效于

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

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

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

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

注意

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

JOIN 到目标实体或可选对象

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

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

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

使用 ON 子句 JOIN 到目标

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

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

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

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

对于我们希望两次 JOIN 到 Address 的情况，上面的语法可能很有用，可以使用使用 aliased() 函数设置的两个别名来实现

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

q = (
    session.query(User)
    .join(a1, User.addresses)
    .join(a2, User.addresses)
    .filter(a1.email_address == "ed@foo.com")
    .filter(a2.email_address == "ed@bar.com")
)

关系绑定的调用形式还可以使用 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 == "ed@foo.com")
    .filter(a2.email_address == "ed@bar.com")
)

增强内置 ON 子句

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

q = session.query(User).join(
    User.addresses.and_(Address.email_address != "foo@bar.com")
)

New in version 1.4.

JOIN 到表和子查询

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

subq = (
    session.query(Address)
    .filter(Address.email_address == "ed@foo.com")
    .subquery()
)


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

可以通过使用 aliased() 将子查询链接到实体，来实现根据特定关系和/或目标实体 JOIN 到子查询

subq = (
    session.query(Address)
    .filter(Address.email_address == "ed@foo.com")
    .subquery()
)

address_subq = aliased(Address, subq)

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

控制从何处 JOIN

在 Query 的当前状态的左侧与我们想要从中 JOIN 的内容不一致的情况下，可以使用 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 集合应被视为单参数或双参数形式，要么是单个“target”实体或 ORM 属性绑定关系，要么是目标实体加上 “on 子句”，它可以是 SQL 表达式或 ORM 属性绑定关系。

  • isouter=False – 如果为 True，则使用的 JOIN 将是左外连接，就像调用了 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

使用此 Query 进行延迟加载操作的 InstanceState。

Deprecated since version 1.4: 自版本 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 中。

Deprecated since version 2.0: 自版本 2.0 起已弃用：Query.merge_result() 方法在 SQLAlchemy 1.x 系列中被认为是遗留方法，并在 2.0 中成为遗留构造。此方法已被 merge_frozen_result() 函数取代。（关于 SQLAlchemy 2.0 的背景信息：SQLAlchemy 2.0 - 主要迁移指南）

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

结果的结构是根据此 Query 的列列表确定的 - 如果这些不对应，则会发生未检查的错误。

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

有关如何使用 Query.merge_result() 的示例，请参阅示例 Dogpile 缓存 的源代码，其中 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。

调用 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 – 将在 INSERT、UPDATE 或 DELETE 关键字之后呈现的文本或 ClauseElement 构造。

  • 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()。

Changed in version 1.4: 在版本 1.4 中更改：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
)

New in version 1.4.

另请参阅

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

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

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

start 和 stop 索引的行为类似于 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 的元组类型形式。

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

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

2.0 版本中的新功能。

另请参阅

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

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

生成此 Query 与一个或多个查询的 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 子句，包括在映射器上配置的那些，请发出 query.order_by(None) - 生成的 Query 对象将不会在其 SELECT 语句中呈现 ORDER BY。

另请参阅

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

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

生成此 Query 与一个或多个查询的 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-Enabled INSERT、UPDATE 和 DELETE 语句 部分。

参数:
返回:

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

另请参阅

启用 ORM 的 INSERT、UPDATE 和 DELETE 语句

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

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

Deprecated since version 1.4: Query.value() 已弃用，将在未来的版本中删除。请使用 Query.with_entities() 与 Query.scalar() 结合使用

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

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

Deprecated since version 1.4: Query.values() 已弃用，将在未来的版本中删除。请使用 Query.with_entities()

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

与 Query.filter() 的同义词。

New in version 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 可比较方法。

方法 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 对象中，即使这些对象已在 identity map 中也是如此。

另请参阅

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

Query.populate_existing() - 覆盖已加载到 identity map 中的对象的属性。

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

继承自 HasHints.with_hint() 方法，属于 HasHints

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

提示

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

提示的文本在使用的数据库后端的适当位置呈现，相对于作为 selectable 参数传递的 Table 或 Alias。方言实现通常使用带有标记 %(name)s 的 Python 字符串替换语法来呈现表或别名的名称。例如，当使用 Oracle Database 时，以下内容：

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

将 SQL 呈现为：

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

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

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 Database 优化器提示

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

Deprecated since version 2.0: Query.with_labels() 和 Query.apply_labels() 方法从 SQLAlchemy 1.x 系列开始被认为是旧版，并在 2.0 中成为旧版构造。请改用 set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)。（有关 SQLAlchemy 2.0 的背景信息，请访问：SQLAlchemy 2.0 - 主要迁移指南）

方法 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() 相同，但给定的 property 可以为 None，在这种情况下，将针对此 Query 对象的 target mapper 执行搜索。

参数:

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

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

  • from_entity – 在其中考虑作为左侧的实体。默认为 Query 本身的“零”实体。

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

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

虽然 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()
方法 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 Database 优化器提示

方法 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 对象创建临时的自定义方法。

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

每次仅 yield count 行。

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

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

另请参阅

使用 Yield Per 获取大型结果集

ORM 特定的查询构造

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