遗留查询 API¶

关于旧版查询 API

此页面包含 Python 生成的 Query 结构，多年来一直是唯一的 SQL 接口。从 2.0 版本开始，所有新的工作方式现在是标准方法，其中相同的 select（） 结构也适用于 ORM，为构建查询提供了一致的接口。

对于在 2.0 API 之前的 SQLAlchemy ORM 上构建的任何应用程序，查询 API 通常代表应用程序中的绝大多数数据库访问代码，因此查询 API 的大部分是 未从 SQLAlchemy 中删除。幕后的 Query 对象现在将自身转换为 2.0 样式的 select（） 对象，因此它现在只是一个非常精简的适配器 API。

有关基于 Query 迁移应用程序的指南到 2.0 样式，请参阅 2.0 迁移 - ORM 用法。

有关以 2.0 样式为 ORM 对象编写 SQL 的介绍，请从 SQLAlchemy Unified Tutorial 开始。有关 2.0 样式查询的其他参考，请参阅 ORM 查询指南。

Query 对象¶

Query 是使用 Session.query（） 方法根据给定的 Session 生成的：

q = session.query(SomeMappedClass)

以下是 Query 对象的完整界面。

对象名称	描述
查询	ORM 级别的 SQL 构造对象。

类 sqlalchemy.orm 中。查询¶

ORM 级别的 SQL 构造对象。

旧版功能

ORM Query 对象是一个遗留结构从 SQLAlchemy 2.0 开始。请参阅顶部的注释旧版查询 API 以获取概述，包括指向迁移文档的链接。

查询对象最初通常是使用 Session.query（） 方法，在不太常见的情况下，通过直接实例化 Query 并使用 Query.with_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_subquery（）、select_from（）、可选、set_label_style（）、切片（）、语句、子查询（）、suffix_with（）、元组（）、联合（）、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（）

类签名

类 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.通用）

方法 sqlalchemy.orm.Query 中。__init__（entities：_ColumnsClauseArgument[Any]Sequence[_ColumnsClauseArgument[Any]]， session：SessionNone=None）¶

直接构造 Query。

例如：

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

以上相当于：

q = some_session.query(User, Address)

参数

entities¶—— 一系列实体和/或 SQL 表达式。
session¶—— 一个 Session，其中 查询 将被关联。自选;查询 可以关联与 Session 生成 Query.with_session（） 方法。

另请参阅

Session.query（）

Query.with_session（）

方法 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：AliasSubqueryNone=None）→ Query[Any]¶: 将映射实体添加到要返回的结果列列表中。

另请参阅

Select.add_columns（） - v2 可比较的方法。

方法 sqlalchemy.orm.Query 中。all（）→ 列表[_T]¶

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

这将导致执行基础 SQL 语句。

警告

当要求返回由完整的 ORM 映射实体组成的序列或迭代器时，Query 对象将根据主键删除重复的条目。有关更多详细信息，请参阅 FAQ。

另请参阅

我的 Query 返回的对象数量与 query.count（）告诉我的对象数量不同 - 为什么？

另请参阅

Result.all（） - v2 类似方法。

Result.scalars（） - v2 类似方法。

方法 sqlalchemy.orm.Query 中。apply_labels（）→ 自身¶: 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 中。as_scalar（）→ ScalarSelect[任意]¶: 返回由此表示的完整 SELECT 语句 Query，转换为标量子查询。

1.4 版后已移除： Query.as_scalar（） 方法已弃用，并将在未来发行版中删除。请参阅 Query.scalar_subquery（）。

方法 sqlalchemy.orm.Query 中。autoflush（设置： bool）→ 自身¶

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

从 SQLAlchemy 1.4 开始，Query.autoflush（） 方法等效于在 ORM 级别使用 autoflush 执行选项。请参阅 Autoflush 部分以了解有关此选项的更多背景信息。

属性 sqlalchemy.orm.Query。column_descriptions¶

返回有关此 Query 将返回的列的元数据。

format 是字典列表：

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]FromClauseRoleType[Any]Inspectable[_HasClauseElement[Any]]_HasClauseElement[Any]）→ Self¶

返回一个 Query 结构，该结构将给定的 FROM 子句与封闭 Query 的子句相关联，或者 select（） 的

此处的方法接受映射的类、aliased（） 构造和 Mapper 构造作为参数，除了适当的表达式构造外，这些构造还被解析为表达式构造。

correlation 参数最终会传递给 Select.correlate（） 在强制对 expression 构造体进行强制转换后。

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

另请参阅

Select.correlate（） - v2 等效方法。

方法 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 返回一行，即 count 函数的聚合值;Query.count（） method 然后返回那个 single integer 值。

警告

需要注意的是，count（）返回的值与此 Query 将从 .all（）方法等方法返回。当要求返回完整实体时，Query 对象将根据主键删除重复的条目，这意味着如果相同的主键值在结果中多次出现，则只会存在该主键的一个对象。这不适用于针对单个列的查询。

另请参阅

我的 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 使用

方法 sqlalchemy.orm.Query 中。cte（name：strNone=None， 递归： bool = False， 嵌套： bool = False）→ CTE¶

返回由此表示的完整 SELECT 语句 表示为公共表表达式（CTE）的查询。

参数和用法与 SelectBase.cte（） 方法;有关更多详细信息，请参阅该方法。

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

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

方法 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"
)

警告

有关重要的注意事项和警告，包括将批量 UPDATE 和 DELETE 与 mapper 继承配置一起使用时的限制，请参阅 ORM-Enabled INSERT、UPDATE 和 DELETE 语句部分。

参数

synchronize_session¶ – 选择策略以更新属性。请参阅该部分启用 ORM 的 INSERT、UPDATE 和 DELETE 语句，用于讨论这些策略。
delete_args¶ –

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

2.0.37 新版功能.

结果

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

另请参阅

启用 ORM 的 INSERT、UPDATE 和 DELETE 语句

方法 sqlalchemy.orm.Query 中。distinct（*expr： _ColumnExpressionArgument[Any]）→ 自身¶

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

注意

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

2.0 版后已移除：此逻辑已弃用，并将在 SQLAlchemy 2.0 中删除。请参阅将 DISTINCT 与其他列一起使用，但仅选择实体有关 2.0 中此使用案例的描述。

另请参阅

Select.distinct（） - v2 等效方法。

参数

*expr¶ –

可选列表达式。如果存在，PostgreSQL 方言将呈现 DISTINCT ON （<expressions>） 构建。

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

方法 sqlalchemy.orm.Query 中。enable_assertions（value： bool）→ Self¶

控制是否生成断言。

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

应注意确保使用模式是可能的。例如，由 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 的 EXCEPT 。

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

另请参阅

Select.except_（） - v2 等效方法。

方法 sqlalchemy.orm.Query 中。except_all（*q：查询）→ 自身¶

针对一个或多个查询生成 EXCEPT ALL of this Query。

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

另请参阅

Select.except_all（） - v2 等效方法。

方法 sqlalchemy.orm.Query 中。execution_options（**kwargs： Any）→ 自身¶

设置非 SQL 选项，执行过程中生效。

此处允许的选项包括 Connection.execution_options() ，以及一系列特定于 ORM 的选项：

populate_existing=True - 等效于使用 Query.populate_existing（）

autoflush=True|False - 等效于使用 查询.autoflush（）

yield_per=<value> - 相当于使用 Query.yield_per（）

请注意，如果 stream_results 执行选项 Query.yield_per（） method 或 execution 选项。

在 1.4 版本加入： - 添加了 ORM 选项 Query.execution_options（）

当通过 Session.execution_options 参数。

警告

这 Connection.execution_options.stream_results parameter 不应在单个 ORM 级别使用语句执行，因为 Session 不会在单个 Session 中跟踪来自不同架构转换映射的对象。有关单个 Session 范围内的多个 schema 转换映射，请参阅水平分片。

另请参阅

使用服务器端游标（也称为流结果）

Query.get_execution_options（）

Select.execution_options（） - v2 等效方法。

方法 sqlalchemy.orm.Query 中。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）不允许在 SELECT 的 columns 子句中存在 EXISTS 表达式。要根据 exists 作为 WHERE 选择简单的布尔值，请使用 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 类似方法。

方法 sqlalchemy.orm.Query 中。first（）→_TNone¶

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

first（）在生成的 SQL 中应用一个限制，以便在服务器端只生成一个主实体行（请注意，如果存在联接加载的集合，则这可能由多个结果行组成）。

调用 Query.first（） 导致底层查询。

另请参阅

查询.one（）

Query.one_or_none（）

Result.first（） - v2 可比较的方法。

Result.scalars（） - v2 类似方法。

方法 sqlalchemy.orm.Query 中。from_statement（statement： ExecutableReturnsRows）→ Self¶

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

此方法绕过所有内部语句编译，并且不加修改地执行语句。

该语句通常是 text（） 或 select（） 结构，并且应该返回集合列数适合于此表示的实体类 Query 查询。

另请参阅

Select.from_statement（） - v2 可比较的方法。

方法 sqlalchemy.orm.Query 中。get（ident： _PKIdentityArgument）→AnyNone¶

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

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（） 仅用于返回单个 mapped 实例，而不是多个实例或单个列构造，并且严格在单个主键值上。原始 Query 必须以这种方式构建，即针对单个映射实体，无需额外的筛选条件。但是，可以通过 Query.options（） 加载选项，如果对象尚未在本地存在，则将使用此选项。

参数

识别¶ –

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

对于单列主键，标量调用形式通常是最方便的。如果一行的主键是值 “5”，则调用如下所示：

my_object = query.get(5)

元组形式包含主键值，通常位于它们与映射的 桌子 Object 的主键列，或者如果 Mapper.primary_key配置参数的 Sequences 中使用该参数。例如，如果一行的主键由整数数字 “5， 10” 表示，则调用将如下所示：

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

字典形式应包括与主键的每个元素对应的映射属性名称作为键。如果映射的类具有 attributes id， version_id 作为存储对象主键值的属性，则调用将如下所示：

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

1.3 新版功能： Query.get（） 方法现在可选接受 Values 的属性名称字典，以便指示主键标识符。

结果

对象实例或 None。

方法 sqlalchemy.orm.Query 中。get_children（*， omit_attrs：元组[str， ...] = （）， **kw： Any）→ Iterable[HasTraverseInternals]¶

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

返回紧接的子 HasTraverseInternals 元素中。

这用于访问遍历。

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

方法 sqlalchemy.orm.Query 中。get_execution_options（） → _ImmutableExecuteOptions¶: 获取将在执行过程中生效的非 SQL 选项。

在 1.3 版本加入.

另请参阅

Query.execution_options（）

Select.get_execution_options() - V2 可比较的方法。

属性 sqlalchemy.orm.Query。get_label_style¶: 检索当前标签样式。

在 1.4 版本加入.

另请参阅

Select.get_label_style（） - v2 等效方法。

方法 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。

所有现有的 GROUP BY 设置都可以通过传递 None 来隐藏 - 这也将隐藏在映射器上配置的任何 GROUP BY。

另请参阅

以下部分以 2.0 样式描述 GROUP BY ininvokecation 的调用，但也适用于 Query：

在 SQLAlchemy Unified 教程

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

Select.group_by（） - v2 等效方法。

方法 sqlalchemy.orm.Query 中。having（*having： _ColumnExpressionArgument[bool]）→ 自身¶

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

方法 sqlalchemy.orm.Query 中。instances（result_proxy： CursorResult[Any]， context：QueryContextNone=None）→ Any（任意）: 返回给定 CursorResult 的 ORM 结果，并且 QueryContext 的

2.0 版后已移除： Query.instances（） 方法已弃用，并将在未来版本中删除。请改用 Select.from_statement（）方法或 aliased（）结构与 Session.execute（）结合使用。

方法 sqlalchemy.orm.Query 中。intersect（*q：查询）→ Self¶

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

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

另请参阅

Select.intersect（） - v2 等效方法。

方法 sqlalchemy.orm.Query 中。intersect_all（*q：查询）→ 自我¶

针对一个或多个查询生成 INTERSECT ALL of this Query。

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

另请参阅

Select.intersect_all（） - v2 等效方法。

属性 sqlalchemy.orm.Query。is_single_entity¶

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

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

在 1.3.11 版本加入.

另请参阅

Query.only_return_tuples（）

方法 sqlalchemy.orm.Query 中。join（target： _JoinTargetArgument， onclause：_OnClauseArgumentNone=无， *， 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)

在上面，对 Query.join（） 的调用 User.addresses 将产生大致相当于以下 SQL 的 SQL：

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

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

要构造连接链，需要多个 Query.join（） 可以使用 CALLS。 relationship-bound 属性意味着两者同时连接 join 的左侧和右侧：

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

注意

如上例所示，每个调用 join（）方法很重要。 Query 不会、例如，如果我们要指定 User （用户），然后是 Item（项目），然后是 Order（订单），在我们的联接链中;在在这种情况下，根据传递的参数，它可能会引发错误，它不知道如何加入，或者它可能会产生无效 SQL 在这种情况下，数据库将引发错误。正确实践、 Query.join（） 方法的调用方式与我们希望 SQL 中的 JOIN 子句的呈现方式一致，并且每个调用都应该代表与前面的内容的明确链接。

联接到目标实体或可选

Query.join（） 的第二种形式允许任何映射的实体或 core selectable 构造作为目标。在此用法中， Query.join（） 将尝试沿着两个实体之间的自然外键关系创建一个 JOIN：

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

在上面的调用表单中，调用 Query.join（） 来自动为我们创建 “on 子句”。如果两个实体之间没有外键，或者目标实体与左侧已存在的一个或多个实体之间存在多个外键链接，因此创建联接需要更多信息，则此调用形式最终将引发错误。请注意，在没有任何 ON 子句的情况下指示对目标的联接时，不会考虑 ORM 配置的关系。

使用 ON 子句联接到 Target

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

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

上述表单也可以使用 relationship-bound 属性作为 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 == "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")
)

在 1.4 版本加入.

联接到表和子查询

联接的目标也可以是任何表或 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（） 将子查询链接到实体，可以实现根据特定关系和/或目标实体联接到子查询：

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))

控制要加入的内容

如果当前状态的左侧为 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。

方法 sqlalchemy.orm.Query 中。label（name：strNone）→ Label[任意]¶: 返回由此表示的完整 SELECT 语句 Query，转换为具有给定名称标签的标量子查询。

另请参阅

Select.label（） - v2 可比较的方法。

属性 sqlalchemy.orm.Query。lazy_loaded_from¶: 使用此 Query 的 InstanceState 用于延迟加载作。

1.4 版后已移除：此属性应通过 ORMExecuteState.lazy_loaded_from 属性，在 SessionEvents.do_orm_execute() 事件。

另请参阅

ORMExecuteState.lazy_loaded_from

方法 sqlalchemy.orm.Query 中。limit（limit： _LimitOffsetType）→ 自身¶: 将 LIMIT 应用于查询并返回新生成的 Query 查询。

另请参阅

Select.limit（） - v2 等效方法。

方法 sqlalchemy.orm.Query 中。merge_result（iterator：FrozenResult[Any]Iterable[Sequence[Any]]Iterable[object]， load： bool = True）→FrozenResult[Any]Iterable[Any]¶

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

2.0 版后已移除： Query.merge_result（） 方法在 SQLAlchemy 的 1.x 系列中被视为遗留方法，并在 2.0 中成为遗留结构。该方法被 merge_frozen_result（） 函数取代。（SQLAlchemy 2.0 的背景信息位于：SQLAlchemy 2.0 - 主要迁移指南）

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

结果的结构是根据此 Query 的列列表确定的 - 如果这些不对应，将发生未选中的错误。

'load' 参数与 Session.merge（） 的参数相同。

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

方法 sqlalchemy.orm.Query 中。offset（offset： _LimitOffsetType）→ 自身¶: 将 OFFSET 应用于查询并返回新生成的 Query 查询。

另请参阅

Select.offset（） - v2 等效方法。

方法 sqlalchemy.orm.Query 中。one（）→ _T¶

只返回一个结果或引发异常。

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

调用 one（） 会导致底层查询的执行。

另请参阅

查询.first（）

Query.one_or_none（）

Result.one（） - v2 类似方法。

Result.scalar_one（） - v2 类似方法。

方法 sqlalchemy.orm.Query 中。one_or_none（）→_TNone¶

最多返回一个结果或引发异常。

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

调用 Query.one_or_none（） 导致执行基础查询。

另请参阅

查询.first（）

查询.one（）

Result.one_or_none（） - v2 类似方法。

Result.scalar_one_or_none（） - v2 类似方法。

方法 sqlalchemy.orm.Query 中。only_return_tuples（value： bool）→ 查询¶

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

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

另请参阅

Query.tuples（） - 返回元组，但在类型级别也会将结果键入为 Tuple。

Query.is_single_entity（）

Result.tuples（） - v2 类似方法。

方法 sqlalchemy.orm.Query 中。options（*args： ExecutableOption）→ 自身¶

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

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

另请参阅

色谱柱加载选项

使用 Loader 选项进行关系加载

方法 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)

多次调用该方法相当于在所有子句串联的情况下调用一次。所有现有的 ORDER BY 条件都可以通过单独传递 None 来取消。然后可以通过再次调用 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 ininvokecation 的调用，但也适用于 Query：

ORDER BY - 在 SQLAlchemy Unified Tutorial 中

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

Select.order_by（） - v2 等效方法。

方法 sqlalchemy.orm.Query 中。outerjoin（target： _JoinTargetArgument， onclause：_OnClauseArgumentNone=无， *， full： bool = False）→ Self¶

根据此 Query 对象的条件创建左外部联接，并以生成方式应用，返回新生成的 Query。

用法与 join（） 方法相同。

另请参阅

Select.outerjoin（） - v2 等效方法。

方法 sqlalchemy.orm.Query 中。params（_Query__params：Dict[str，Any]None=None， **kw： Any）→ Self¶

为可能已在 filter（）中指定的绑定参数添加值。

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

方法 sqlalchemy.orm.Query 中。populate_existing（）→ 自身¶

返回查询 将过期并刷新所有实例当它们被加载或从当前 Session 中重用时。

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

方法 sqlalchemy.orm.Query 中。prefix_with（*前缀： _TextCoercedExpressionArgument[Any]， 方言： str = '*'）→ 自我¶

继承自HasPrefixes 的 HasPrefixes.prefix_with（） 方法

在 statement 关键字后添加一个或多个表达式，即 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（） 来指定多个前缀。

参数

前缀¶ – 文本或 ClauseElement 构造将在 INSERT、UPDATE 或 DELETE 之后呈现关键词。
dialect¶- 可选的字符串 dialect name，它将限制此前缀的渲染仅该方言。

方法 sqlalchemy.orm.Query 中。reset_joinpoint（）→ Self¶

返回一个新的 Query，其中 “join point” 已重置回查询的基本 FROM 实体。

此方法通常与 aliased=True 的 Query.join（） 功能方法。有关如何使用它，请参阅 Query.join（） 中的示例。

方法 sqlalchemy.orm.Query 中。scalar（）→ 任意¶

返回第一个结果的第一个元素，如果不存在行，则返回 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 可比较的方法。

方法 sqlalchemy.orm.Query 中。scalar_subquery（）→ ScalarSelect[任意]¶

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

类似于 SelectBase.scalar_subquery（） 中。

在 1.4 版本发生变更： Query.scalar_subquery（） method 替换 Query.as_scalar（） 方法。

另请参阅

Select.scalar_subquery（） - v2 可比较的方法。

方法 sqlalchemy.orm.Query 中。select_from（*from_obj：FromClauseRoleType[Any]Inspectable[_HasClauseElement[Any]]_HasClauseElement[Any]）→ 自身¶

显式设置此 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 元素（如子查询）。

另请参阅

查询.join（）

Query.select_entity_from（）

Select.select_from（） - v2 等效方法。

属性 sqlalchemy.orm.Query。可选¶

返回 this 发出的 Select 对象 Query 查询。

用于 inspect（） 兼容性，这相当于：

query.enable_eagerloads(False).with_labels().statement

方法 sqlalchemy.orm.Query 中。set_label_style（style： SelectLabelStyle）→ 自身¶

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

指示此 Query 的语句访问器应返回一个 SELECT 语句，该语句将标签应用于 _ 格式的所有列;这通常用于消除具有相同名称的多个表中的列的歧义。

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

方法 sqlalchemy.orm.Query 中。slice（start： int， stop： int）→ 自身¶

计算由给定索引表示的 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)

另请参阅

查询.limit（）

查询.offset（）

Select.slice（） - v2 等效方法。

属性 sqlalchemy.orm.Query。语句¶

此 Query 表示的完整 SELECT 语句。

默认情况下，该语句不会将消除歧义的标签应用于构造，除非首先调用 with_labels（True）。

方法 sqlalchemy.orm.Query 中。subquery（name：strNone=None， with_labels： bool = False， reduce_columns： bool = False）→ 子查询¶

返回此 Query 表示的完整 SELECT 语句，嵌入在 别名。

查询中的 Eager JOIN 生成处于禁用状态。

另请参阅

Select.subquery（） - v2 可比较的方法。

参数

name¶ – 要分配为别名的字符串名称;这被传递给 FromClause.alias（）。如果为 None，则将在编译时确定性地生成名称。
with_labels¶ – 如果为 True，则将首先在 Query 上调用 with_labels（） 以将表限定标签应用于所有列。
reduce_columns¶ – 如果为 True，将在生成的 select（） 结构上调用 Select.reduce_columns（），以删除同名列，其中一列也通过外键或 WHERE 子句等效性引用另一列。

方法 sqlalchemy.orm.Query 中。suffix_with（*suffixes： _TextCoercedExpressionArgument[Any]， 方言： str = '*'）→ 自我¶

继承自HasSuffixes 的 HasSuffixes.suffix_with（） 方法

在整个语句后面添加一个或多个表达式。

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

例如：

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

可以通过多次调用 HasSuffixes.suffix_with（） 来指定多个后缀。

参数

*suffixes¶– 文本或 ClauseElement 构造将在 Target 子句之后呈现。
dialect¶- 可选的字符串 dialect name，它将限制此后缀的渲染仅该方言。

方法 sqlalchemy.orm.Query 中。tuples（）→ 查询¶

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

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

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

2.0 版的新Function。

另请参阅

Result.tuples（） - v2 等效方法。

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

方法 sqlalchemy.orm.Query 中。union_all（*q：查询）→ 自我¶

针对一个或多个查询生成 UNION ALL of this Query。

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

另请参阅

Select.union_all（） - v2 等效方法。

方法 sqlalchemy.orm.Query 中。update（值： 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 语句部分。

参数

values¶—— 带有属性名称的字典，或者或者映射的属性或 SQL 表达式作为键，以及文字值或 SQL 表达式作为值。如果参数排序 mode 时，值可以作为 2 元组的列表传递;这要求 update.preserve_parameter_order flag 也会传递给 Query.update.update_args 字典。
synchronize_session¶ – 选择策略以更新属性。请参阅该部分启用 ORM 的 INSERT、UPDATE 和 DELETE 语句，用于讨论这些策略。
update_args¶ – 可选字典，如果存在，将作为 **kw 传递给底层的 update（） 结构对于对象。可用于传递特定于方言的参数，例如作为 mysql_limit，以及其他特殊参数（如 update.preserve_parameter_order 。

结果

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

另请参阅

启用 ORM 的 INSERT、UPDATE 和 DELETE 语句

方法 sqlalchemy.orm.Query 中。value（column： _ColumnExpressionArgument[Any]）→ Any¶: 返回与给定列表达式对应的标量结果。

1.4 版后已移除： Query.value（） 已弃用，并将在未来版本中删除。请将 Query.with_entities（） 与 Query.scalar（） 结合使用

方法 sqlalchemy.orm.Query 中。values（*columns： _ColumnsClauseArgument[Any]）→ Iterable[Any]¶: 返回一个迭代器，生成与给定列列表对应的结果元组

从 1.4 版本开始不推荐使用： Query.values（） 已弃用，并将在未来版本中删除。请使用 Query.with_entities（）

方法 sqlalchemy.orm.Query 中。其中（*criterion： _ColumnExpressionArgument[bool]）→ Self¶: Query.filter（） 的同义词。

在 1.4 版本加入.

另请参阅

Select.where（） - v2 等效方法。

属性 sqlalchemy.orm.Query。where子句¶

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

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

另请参阅

Select.whereclause - v2 等效属性。

方法 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：_ForUpdateOfArgumentNone=无，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

警告

SQLAlchemy 不正式支持或推荐在预先加载关系的上下文中使用 with_for_update，并且可能无法与各种数据库后端上的某些查询一起使用。当 with_for_update 与涉及 joinedload（）的查询成功使用时，SQLAlchemy 将尝试发出锁定所有相关表的 SQL。

注意

通常，将 Query.populate_existing（） 方法。 Query.with_for_update（） 方法。目的 Query.populate_existing（） 是强制将从 SELECT 读取的所有数据填充到返回的 ORM 对象中，即使这些对象已经在身份映射中。

另请参阅

GenerativeSelect.with_for_update() - 核心级别方法，其中完整的论点和行为描述。

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

方法 sqlalchemy.orm.Query 中。with_hint（可选：_FromClauseArgument，文本：str，dialect_name：str = '*'）→ 自身¶

继承自HasHints 的 HasHints.with_hint（） 方法

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

提示

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

提示的文本将相对于给定的 Table 或 Alias 呈现在正在使用的数据库后端的适当位置作为 selectable 参数。方言实现通常使用带有标记 %（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 数据库优化器提示

方法 sqlalchemy.orm.Query 中。with_labels（）→ 自身¶: 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¶

添加过滤条件，使用其属性 state 以及已建立的 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 本身的 “零” 实体。

方法 sqlalchemy.orm.Query 中。with_session（session： Session）→ 自身¶

返回将使用给定 会话。

当查询 Object 通常使用 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（） 方法的开放式 space 的 API API 中，或者对于特定于表的提示，可以使用 Select.with_hint（） ，它将提示放置在特定于方言的位置。

此方法类似于 Select.with_hint（） 不同之处在于它不需要单个 table，而是应用于整个语句。

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

另请参阅

Select.with_hint（）

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

方法 sqlalchemy.orm.Query 中。with_transformation（fn： Callable[[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¶

一次只生成 count 行。

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

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

另请参阅

使用 Yield Per 获取大型结果集

特定于 ORM 的查询结构¶

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

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy ORM

遗留查询 API¶

Query 对象¶

特定于 ORM 的查询结构¶