SQLAlchemy 2.0 文档

ORM 执行选项 - 所有 ORM 特定执行选项的文档

method sqlalchemy.sql.expression.CompoundSelect.exists() → Exists¶

继承自 SelectBase.exists() 方法 SelectBase

返回此可选择项的 Exists 表示形式，可以用作列表达式。

返回的对象是 Exists 的实例。

另请参阅

EXISTS 子查询 - 在 2.0 风格教程中。

版本 1.4 中的新功能。

attribute sqlalchemy.sql.expression.CompoundSelect.exported_columns¶

继承自 SelectBase.exported_columns 属性 SelectBase

一个 ColumnCollection，它代表此 Selectable 的“导出”列，不包括 TextClause 结构。

一个 SelectBase 对象的“导出”列与 SelectBase.selected_columns 集合相同。

版本 1.4 中的新功能。

另请参阅

method sqlalchemy.sql.expression.CompoundSelect.fetch(count: _LimitOffsetType, with_ties: bool = False, percent: bool = False) → Self¶

继承自 GenerativeSelect.fetch() 方法 GenerativeSelect

返回一个新的可选择项，其中应用了给定的 FETCH FIRST 条件。

这是一个数值，通常呈现为 FETCH {FIRST | NEXT} [ count ] {ROW | ROWS} {ONLY | WITH TIES} 表达式，在结果选择中。此功能目前针对 Oracle、PostgreSQL、MSSQL 实现。

使用 GenerativeSelect.offset() 指定偏移量。

注意

GenerativeSelect.fetch() 方法将替换使用 GenerativeSelect.limit() 应用的任何子句。

版本 1.4 中的新功能。

参数:

count¶ – 一个整数 COUNT 参数，或提供整数结果的 SQL 表达式。当 percent=True 时，它将表示要返回的行百分比，而不是绝对值。传递 None 重置它。
with_ties¶ – 当 True 时，使用 WITH TIES 选项返回任何其他行，这些行根据 ORDER BY 子句在结果集中并列最后一名。在这种情况下，ORDER BY 可能是强制性的。默认值为 False
percent¶ – 当 True 时，count 表示要返回的选择行总数的百分比。默认值为 False

另请参阅

method sqlalchemy.sql.expression.CompoundSelect.get_execution_options() → _ExecuteOptions¶: 继承自 Executable.get_execution_options() 方法 Executable

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

版本 1.3 中新增。

另请参阅

Executable.execution_options()

method sqlalchemy.sql.expression.CompoundSelect.get_label_style() → SelectLabelStyle¶: 继承自 GenerativeSelect.get_label_style() 方法 GenerativeSelect

检索当前标签样式。

版本 1.4 中的新功能。

method sqlalchemy.sql.expression.CompoundSelect.group_by(_GenerativeSelect__first: Literal[None, _NoArg.NO_ARG] | _ColumnExpressionOrStrLabelArgument[Any] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any]) → Self¶

继承自 GenerativeSelect.group_by() 方法 GenerativeSelect

返回一个新的可选择对象，其中应用了给定的 GROUP BY 条件列表。

可以通过传递 None 来抑制所有现有的 GROUP BY 设置。

例如。

stmt = select(table.c.name, func.max(table.c.stat)).\
group_by(table.c.name)

参数:: *clauses¶ – 一系列 ColumnElement 结构，它们将用于生成 GROUP BY 子句。

另请参阅

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

method sqlalchemy.sql.expression.CompoundSelect.is_derived_from(fromclause: FromClause | None) → bool¶

如果此 ReturnsRows ‘派生’ 自给定的 FromClause，则返回 True。

例如，表的别名将从该表派生。

method sqlalchemy.sql.expression.CompoundSelect.label(name: str | None) → Label[Any]¶: 继承自 SelectBase.label() 方法 SelectBase

返回此可选择对象的 ‘标量’ 表示形式，嵌入为带有标签的子查询。

另请参阅

SelectBase.scalar_subquery().

method sqlalchemy.sql.expression.CompoundSelect.lateral(name: str | None = None) → LateralFromClause¶

继承自 SelectBase.lateral() 方法 SelectBase

返回此 Selectable 的 LATERAL 别名。

返回值是 Lateral 结构，它也由顶层 lateral() 函数提供。

另请参阅

LATERAL 关联 - 用法概述。

method sqlalchemy.sql.expression.CompoundSelect.limit(limit: _LimitOffsetType) → Self¶

继承自 GenerativeSelect.limit() 方法 GenerativeSelect

返回一个新的可选择对象，其中应用了给定的 LIMIT 条件。

这是一个数值，通常在结果选择中呈现为 LIMIT 表达式。不支持 LIMIT 的后端将尝试提供类似的功能。

注意

GenerativeSelect.limit() 方法将替换使用 GenerativeSelect.fetch() 应用的任何子句。

参数:: limit¶ – 一个整数 LIMIT 参数，或提供整数结果的 SQL 表达式。传递 None 重置它。

另请参阅

method sqlalchemy.sql.expression.CompoundSelect.offset(offset: _LimitOffsetType) → Self¶

继承自 GenerativeSelect.offset() 方法 GenerativeSelect

返回一个新的可选择对象，应用了给定的偏移量准则。

这是一个数值，通常在生成的 SELECT 中呈现为 OFFSET 表达式。不支持 OFFSET 的后端会尝试提供类似的功能。

参数:: offset¶ – 整数偏移量参数，或提供整数结果的 SQL 表达式。传递 None 以重置它。

另请参阅

method sqlalchemy.sql.expression.CompoundSelect.options(*options: ExecutableOption) → Self¶

继承自 Executable.options() 方法 Executable

将选项应用于此语句。

一般来说，选项是任何可以被 SQL 编译器用于语句的 Python 对象。这些选项可以被特定方言或特定类型的编译器使用。

最常见的选项是 ORM 级别的选项，它们将“急切加载”和其他加载行为应用于 ORM 查询。但是，理论上选项可以用于许多其他目的。

有关特定类型语句的特定选项的信息，请参阅这些选项对象的文档。

在版本 1.4 中变更: - 向 Core 语句对象添加了 Executable.options()，以实现统一的 Core / ORM 查询功能。

另请参阅

列加载选项 - 指的是特定于 ORM 查询使用的选项

使用加载器选项的关联加载 - 指的是特定于 ORM 查询使用的选项

method sqlalchemy.sql.expression.CompoundSelect.order_by(_GenerativeSelect__first: Literal[None, _NoArg.NO_ARG] | _ColumnExpressionOrStrLabelArgument[Any] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any]) → Self¶

继承自 GenerativeSelect.order_by() 方法 GenerativeSelect

返回一个新的可选择对象，应用了给定的 ORDER BY 准则列表。

例如。

stmt = select(table).order_by(table.c.id, table.c.name)

多次调用此方法等效于一次调用它，并将所有子句连接在一起。通过传递 None 本身可以取消所有现有的 ORDER BY 准则。然后可以通过再次调用 Query.order_by() 添加新的 ORDER BY 准则，例如：

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

参数:: *clauses¶ – 一系列 ColumnElement 结构，将用于生成 ORDER BY 子句。

另请参阅

ORDER BY - 在 SQLAlchemy 统一教程中

Select.selected_columns

method sqlalchemy.sql.expression.CompoundSelect.replace_selectable(old: FromClause, alias: Alias) → Self¶: 继承自 Selectable.replace_selectable() 方法 Selectable

将所有出现的 FromClause ‘old’ 替换为给定的 Alias 对象，返回此 FromClause 的副本。

自版本 1.4 起弃用: The Selectable.replace_selectable() 方法已弃用，将在未来的版本中移除。类似的功能可以通过 sqlalchemy.sql.visitors 模块获得。

method sqlalchemy.sql.expression.CompoundSelect.scalar_subquery() → ScalarSelect[Any]¶

继承自 SelectBase.scalar_subquery() 方法 SelectBase

返回此可选择对象的“标量”表示，它可以用作列表达式。

返回的对象是 ScalarSelect 的实例。

通常，在它的列子句中只有一个列的 SELECT 语句有资格用作标量表达式。然后，标量子查询可以在封闭的 SELECT 的 WHERE 子句或列子句中使用。

请注意，标量子查询不同于使用 SelectBase.subquery() 方法生成的 FROM 级子查询。

另请参阅

标量和关联子查询 - 在 2.0 教程中

method sqlalchemy.sql.expression.CompoundSelect.select(*arg: Any, **kw: Any) → Select¶: 继承自 SelectBase.select() 方法 SelectBase

从版本 1.4 开始弃用： SelectBase.select() 方法已弃用，将在未来版本中删除；此方法隐式创建子查询，应明确使用。请先调用 SelectBase.subquery() 以创建子查询，然后才能对其进行选择。

attribute sqlalchemy.sql.expression.CompoundSelect.selected_columns¶

一个 ColumnCollection 表示此 SELECT 语句或类似构造在结果集中返回的列，不包括 TextClause 构造。

对于 CompoundSelect，CompoundSelect.selected_columns 属性返回包含在集合操作中的一系列语句中的第一个 SELECT 语句中选择的所有列。

另请参阅

版本 1.4 中的新功能。

method sqlalchemy.sql.expression.CompoundSelect.self_group(against: OperatorType | None = None) → GroupedElement¶

对这个 ClauseElement 应用“分组”。

此方法被子类覆盖以返回“分组”构造，即括号。特别是它被“二元”表达式用于在放置到更大的表达式中时在其周围提供分组，以及被 select() 构造在放置到另一个 select() 的 FROM 子句中时使用。(注意，子查询通常应该使用 Select.alias() 方法创建，因为许多平台要求嵌套的 SELECT 语句被命名).

当表达式组合在一起时，self_group() 的应用是自动的 - 终端用户代码永远不需要直接使用此方法。请注意，SQLAlchemy 的子句构造会考虑运算符优先级 - 因此括号可能不需要，例如，在像 x OR (y AND z) 这样的表达式中 - AND 的优先级高于 OR。

的基类 self_group() 方法 ClauseElement 只返回 self。

method sqlalchemy.sql.expression.CompoundSelect.set_label_style(style: SelectLabelStyle) → CompoundSelect¶

返回一个具有指定标签样式的新可选。

有三种可用的“标签样式”： SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY、 SelectLabelStyle.LABEL_STYLE_TABLENAME_PLUS_COL 和 SelectLabelStyle.LABEL_STYLE_NONE。默认样式为 SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY.

在现代 SQLAlchemy 中，通常不需要更改标签样式，因为通过使用 ColumnElement.label() 方法，每个表达式标签都可以更有效地使用。在过去的版本中， LABEL_STYLE_TABLENAME_PLUS_COL 用于区分来自不同表、别名或子查询的同名列；较新的 LABEL_STYLE_DISAMBIGUATE_ONLY 现在只对与现有名称冲突的名称应用标签，以便这种标签的影响最小。

消除歧义的基本原理主要是使所有列表达式都可以在创建子查询时从给定的 FromClause.c 集合中获取。

版本 1.4 中的新功能： - GenerativeSelect.set_label_style() 方法取代了以前 .apply_labels()、 .with_labels() 和 use_labels=True 方法和/或参数的组合。

另请参阅

LABEL_STYLE_DISAMBIGUATE_ONLY

LABEL_STYLE_TABLENAME_PLUS_COL

LABEL_STYLE_NONE

LABEL_STYLE_DEFAULT

method sqlalchemy.sql.expression.CompoundSelect.slice(start: int, stop: int) → Self¶

继承自 GenerativeSelect.slice() 方法 GenerativeSelect

根据切片对该语句应用 LIMIT / OFFSET。

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

例如，

stmt = select(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)

注意

The GenerativeSelect.slice() method will replace any clause applied with GenerativeSelect.fetch().

New in version 1.4: Added the GenerativeSelect.slice() method generalized from the ORM.

另请参阅

method sqlalchemy.sql.expression.CompoundSelect.subquery(name: str | None = None) → Subquery¶

inherited from the SelectBase.subquery() method of SelectBase

返回此SelectBase 的子查询。

从 SQL 的角度来看，子查询是一个带括号的、命名的构造，可以放在另一个 SELECT 语句的 FROM 子句中。

给定一个 SELECT 语句，例如

stmt = select(table.c.id, table.c.name)

上面的语句可能看起来像

SELECT table.id, table.name FROM table

子查询形式本身以相同的方式呈现，但是当嵌入到另一个 SELECT 语句的 FROM 子句中时，它成为一个命名的子元素

subq = stmt.subquery()
new_stmt = select(subq)

上面的语句呈现为

SELECT anon_1.id, anon_1.name
FROM (SELECT table.id, table.name FROM table) AS anon_1

从历史上看，SelectBase.subquery() 等效于在 FROM 对象上调用 FromClause.alias() 方法；但是，由于 SelectBase 对象不是直接的 FROM 对象，因此 SelectBase.subquery() 方法提供了更清晰的语义。

版本 1.4 中的新功能。

method sqlalchemy.sql.expression.CompoundSelect.with_for_update(*, nowait: bool = False, read: bool = False, of: _ForUpdateOfArgument | None = None, skip_locked: bool = False, key_share: bool = False) → Self¶

inherited from the GenerativeSelect.with_for_update() method of GenerativeSelect

为这个 GenerativeSelect 指定一个 FOR UPDATE 子句。

例如：

stmt = select(table).with_for_update(nowait=True)

在 PostgreSQL 或 Oracle 等数据库上，上面的语句将呈现一个类似于

SELECT table.a, table.b FROM table FOR UPDATE NOWAIT

在其他后端，nowait 选项将被忽略，而是会生成

SELECT table.a, table.b FROM table FOR UPDATE

当不带任何参数调用时，该语句将用后缀 FOR UPDATE 呈现。然后可以提供其他参数，这些参数允许使用常见的数据库特定变体。

参数:

nowait¶ – boolean; 在 Oracle 和 PostgreSQL 方言中将呈现 FOR UPDATE NOWAIT。
read¶ – boolean; 在 MySQL 中将呈现 LOCK IN SHARE MODE，在 PostgreSQL 中将呈现 FOR SHARE。在 PostgreSQL 上，当与 nowait 组合使用时，将呈现 FOR SHARE NOWAIT。
of¶ – SQL 表达式或 SQL 表达式元素列表（通常是 Column 对象或兼容表达式，对于某些后端也可能是表表达式），它们将呈现为 FOR UPDATE OF 子句；由 PostgreSQL、Oracle、某些 MySQL 版本以及可能的其他版本支持。可能会根据后端呈现为表或列。
skip_locked¶ – boolean，在 Oracle 和 PostgreSQL 方言中将呈现 FOR UPDATE SKIP LOCKED，或者如果也指定了 read=True，则将呈现 FOR SHARE SKIP LOCKED。
key_share¶ – boolean，在 PostgreSQL 方言中将呈现 FOR NO KEY UPDATE，或者如果与 read=True 组合使用，则将呈现 FOR KEY SHARE。

class sqlalchemy.sql.expression.CTE¶

表示一个通用表表达式。

可以使用 SelectBase.cte() 方法从任何 SELECT 语句中获得 CTE 对象。不常用的语法也允许使用 HasCTE.cte() 方法，该方法存在于 DML 结构中，例如 Insert、Update 和 Delete。有关 CTE 用法的详细信息，请参阅 HasCTE.cte() 方法。

另请参阅

子查询和 CTE - 在 2.0 教程中

HasCTE.cte() - 调用样式示例

成员

alias()、union()、union_all()

类签名

class sqlalchemy.sql.expression.CTE (sqlalchemy.sql.roles.DMLTableRole, sqlalchemy.sql.roles.IsCTERole, sqlalchemy.sql.expression.Generative, sqlalchemy.sql.expression.HasPrefixes, sqlalchemy.sql.expression.HasSuffixes, sqlalchemy.sql.expression.AliasedReturnsRows)

method sqlalchemy.sql.expression.CTE.alias(name: str | None = None, flat: bool = False) → CTE¶

返回此 CTE 的 Alias。

此方法是 FromClause.alias() 方法的 CTE 特定专门化。

另请参阅

method sqlalchemy.sql.expression.CTE.union(*other: _SelectStatementForCompoundArgument) → CTE¶

返回一个新的 CTE，该 CTE 对作为位置参数提供的给定可选择项执行原始 CTE 的 SQL UNION。

参数:

*other¶ –

用于创建 UNION 的一个或多个元素。

Changed in version 1.4.28: 现在接受多个元素。

另请参阅

HasCTE.cte() - 调用样式示例

method sqlalchemy.sql.expression.CTE.union_all(*other: _SelectStatementForCompoundArgument) → CTE¶

返回一个新的 CTE，该 CTE 对作为位置参数提供的给定可选择项执行原始 CTE 的 SQL UNION ALL。

参数:

*other¶ –

用于创建 UNION 的一个或多个元素。

Changed in version 1.4.28: 现在接受多个元素。

另请参阅

HasCTE.cte() - 调用样式示例

class sqlalchemy.sql.expression.Executable¶

将 ClauseElement 标记为支持执行。

Executable 是所有“语句”类型对象的超类，包括 select()、delete()、update()、insert()、text()。

成员

execution_options()、get_execution_options()、options()

类签名

class sqlalchemy.sql.expression.Executable (sqlalchemy.sql.roles.StatementRole)

method sqlalchemy.sql.expression.Executable.execution_options(**kw: Any) → Self¶

为语句设置在执行期间生效的非 SQL 选项。

执行选项可以在许多范围内设置，包括每个语句、每个连接或每个执行，使用诸如 Connection.execution_options() 和接受选项字典的参数，例如 Connection.execute.execution_options 和 Session.execute.execution_options。

执行选项的主要特征（与其他类型的选项不同，例如 ORM 加载器选项）是 **执行选项从不影响查询的编译 SQL，而仅影响如何调用 SQL 语句本身或如何获取结果**。也就是说，执行选项不是 SQL 编译所容纳的部分，也不被视为语句的缓存状态的一部分。

Executable.execution_options() 方法是生成式的，就像应用于 Engine 和 Query 对象的方法一样，这意味着当调用该方法时，将返回对象的副本，该副本将给定的参数应用于该新副本，但保留原始副本不变

statement = select(table.c.x, table.c.y)
new_statement = statement.execution_options(my_option=True)

这种行为的一个例外是 Connection 对象，其中 Connection.execution_options() 方法显式地 **不是** 生成式。

传递给 Executable.execution_options() 和其他相关方法以及参数字典的选项类型包括 SQLAlchemy Core 或 ORM 显式使用的参数，以及 SQLAlchemy 未定义的任意关键字参数，这意味着这些方法和/或参数字典可用于与自定义代码交互的用户定义参数，这些参数可以通过诸如 Executable.get_execution_options() 和 Connection.get_execution_options() 之类的方法访问，或在使用专用 execution_options 事件参数（如 ConnectionEvents.before_execute.execution_options 或 ORMExecuteState.execution_options）的选定事件钩子中，例如

from sqlalchemy import event

@event.listens_for(some_engine, "before_execute")
def _process_opt(conn, statement, multiparams, params, execution_options):
    "run a SQL function before invoking a statement"

    if execution_options.get("do_special_thing", False):
        conn.exec_driver_sql("run_special_function()")

在 SQLAlchemy 显式识别的选项范围内，大多数选项适用于特定类别的对象，而其他选项则不适用。最常见的执行选项包括

Connection.execution_options.isolation_level - 通过 Engine 设置连接或连接类的隔离级别。此选项仅被 Connection 或 Engine 接受。
Connection.execution_options.stream_results - 指示结果应使用服务器端游标获取；此选项被 Connection、Connection.execute.execution_options 参数（在 Connection.execute() 上）以及 Executable.execution_options() （在 SQL 语句对象上）以及 ORM 结构（如 Session.execute()）接受。
Connection.execution_options.compiled_cache - 指示一个字典，该字典将用作 SQL 编译缓存，用于 Connection 或 Engine，以及 ORM 方法（如 Session.execute()）。可以作为 None 传递以禁用语句的缓存。此选项不被 Executable.execution_options() 接受，因为在语句对象中携带编译缓存是不明智的。
Connection.execution_options.schema_translate_map - 架构转换映射特性使用的架构名称映射，被 Connection、Engine、Executable 以及 ORM 结构（如 Session.execute()）接受。

另请参阅

ORM 执行选项 - 所有 ORM 特定执行选项的文档

method sqlalchemy.sql.expression.Executable.get_execution_options() → _ExecuteOptions¶: 获取执行期间生效的非 SQL 选项。

版本 1.3 中新增。

另请参阅

Executable.execution_options()

method sqlalchemy.sql.expression.Executable.options(*options: ExecutableOption) → Self¶

将选项应用于此语句。

一般来说，选项是任何可以被 SQL 编译器用于语句的 Python 对象。这些选项可以被特定方言或特定类型的编译器使用。

最常见的选项是 ORM 级别的选项，它们将“急切加载”和其他加载行为应用于 ORM 查询。但是，理论上选项可以用于许多其他目的。

有关特定类型语句的特定选项的信息，请参阅这些选项对象的文档。

在版本 1.4 中变更: - 向 Core 语句对象添加了 Executable.options()，以实现统一的 Core / ORM 查询功能。

另请参阅

列加载选项 - 指的是特定于 ORM 查询使用的选项

使用加载器选项的关联加载 - 指的是特定于 ORM 查询使用的选项

class sqlalchemy.sql.expression.Exists¶

表示一个 EXISTS 子句。

有关用法的描述，请参阅 exists()。

一个 EXISTS 子句也可以从一个 select() 实例构建，通过调用 SelectBase.exists()。

成员

correlate(), correlate_except(), inherit_cache, select(), select_from(), where()

类签名

class sqlalchemy.sql.expression.Exists (sqlalchemy.sql.expression.UnaryExpression)

方法 sqlalchemy.sql.expression.Exists.correlate(*fromclauses: Literal[None, False] | _FromClauseArgument) → Self¶: 将关联应用于此 Exists 表示的子查询。

另请参阅

ScalarSelect.correlate()

方法 sqlalchemy.sql.expression.Exists.correlate_except(*fromclauses: Literal[None, False] | _FromClauseArgument) → Self¶: 将关联应用于此 Exists 表示的子查询。

另请参阅

ScalarSelect.correlate_except()

属性 sqlalchemy.sql.expression.Exists.inherit_cache: bool | None = True¶

指示此 HasCacheKey 实例是否应使用其直接父类使用的缓存键生成方案。

该属性默认为 None，这表明构造尚未考虑其是否适合参与缓存；这在功能上等同于将值设置为 False，只是还会发出警告。

如果与对象对应的 SQL 不会根据此类本身的属性（而非其父类）而发生变化，则可以在特定类上将此标志设置为 True。

另请参阅

为自定义构造启用缓存支持 - 为第三方或用户定义的 SQL 构造设置 HasCacheKey.inherit_cache 属性的一般指南。

方法 sqlalchemy.sql.expression.Exists.select() → Select¶

返回此 Exists 的一个 SELECT。

例如。

stmt = exists(some_table.c.id).where(some_table.c.id == 5).select()

这将生成类似于下面的语句

SELECT EXISTS (SELECT id FROM some_table WHERE some_table = :param) AS anon_1

另请参阅

select() - 通用方法，允许使用任意列列表。

方法 sqlalchemy.sql.expression.Exists.select_from(*froms: _FromClauseArgument) → Self¶: 返回一个新的 Exists 结构，将给定的表达式应用于所包含的 SELECT 语句的 Select.select_from() 方法。

注意

通常最好先构建一个 Select 语句，包括所需的 WHERE 子句，然后使用 SelectBase.exists() 方法一次性生成一个 Exists 对象。

方法 sqlalchemy.sql.expression.Exists.where(*clause: _ColumnExpressionArgument[bool]) → Self¶: 返回一个新的 exists() 结构，将给定的表达式添加到其 WHERE 子句中，并与现有的子句（如果有）通过 AND 连接。

注意

通常最好先构建一个 Select 语句，包括所需的 WHERE 子句，然后使用 SelectBase.exists() 方法一次性生成一个 Exists 对象。

类 sqlalchemy.sql.expression.FromClause¶

表示一个可以在 SELECT 语句的 FROM 子句中使用的元素。

最常见的 FromClause 类型是 Table 和 select() 结构。所有 FromClause 对象的共同关键特性包括

一个 c 集合，它提供对 ColumnElement 对象集合的按名称访问。
一个 primary_key 属性，它是一个包含所有指示 primary_key 标志的 ColumnElement 对象的集合。
生成 “from” 子句的各种派生形式的方法，包括 FromClause.alias()、FromClause.join()、FromClause.select()。

成员

alias(), c, columns, description, entity_namespace, exported_columns, foreign_keys, is_derived_from(), join(), outerjoin(), primary_key, schema, select(), tablesample()

类签名

类 sqlalchemy.sql.expression.FromClause (sqlalchemy.sql.roles.AnonymizedFromClauseRole, sqlalchemy.sql.expression.Selectable)

方法 sqlalchemy.sql.expression.FromClause.alias(name: str | None = None, flat: bool = False) → NamedFromClause¶

返回此 FromClause 的别名。

例如：

a2 = some_table.alias('a2')

以上代码创建了一个 Alias 对象，该对象可以用作任何 SELECT 语句中的 FROM 子句。

另请参阅

属性 sqlalchemy.sql.expression.FromClause.c¶

是 FromClause.columns 的同义词

返回值:: 一个 ColumnCollection

属性 sqlalchemy.sql.expression.FromClause.columns¶

此 FromClause 所维护的 ColumnElement 对象的基于名称的集合。

该 columns 或 c 集合，是使用与表绑定的或其他可选择的绑定的列构建 SQL 表达式的入口。

select(mytable).where(mytable.c.somecolumn == 5)

返回值:: 一个 ColumnCollection 对象。

属性 sqlalchemy.sql.expression.FromClause.description¶

此 FromClause 的简短描述。

主要用于错误消息格式化。

属性 sqlalchemy.sql.expression.FromClause.entity_namespace¶

返回在 SQL 表达式中用于基于名称访问的命名空间。

这是用于解析“filter_by()”类型表达式的命名空间，例如

stmt.filter_by(address='some address')

它默认为 .c 集合，但内部可以使用“entity_namespace”注释来覆盖它以提供替代结果。

属性 sqlalchemy.sql.expression.FromClause.exported_columns¶

一个 ColumnCollection，它表示此 Selectable 的“导出”列。

一个 FromClause 对象的“导出”列与 FromClause.columns 集合是同义词。

版本 1.4 中的新功能。

另请参阅

Table.foreign_key_constraints

属性 sqlalchemy.sql.expression.FromClause.foreign_keys¶

返回此 FromClause 引用的 ForeignKey 标记对象集合。

每个 ForeignKey 都是 Table 范围内的 ForeignKeyConstraint 的成员。

另请参阅

方法 sqlalchemy.sql.expression.FromClause.is_derived_from(fromclause: FromClause | None) → bool¶

如果此 FromClause 是从给定的 FromClause “派生”的，则返回 True。

例如，表的别名将从该表派生。

方法 sqlalchemy.sql.expression.FromClause.join(right: _FromClauseArgument, onclause: _ColumnExpressionArgument[bool] | None = None, isouter: bool = False, full: bool = False) → Join¶

从此 FromClause 返回到另一个 FromClause 的 Join。

例如：

from sqlalchemy import join

j = user_table.join(address_table,
                user_table.c.id == address_table.c.user_id)
stmt = select(user_table).select_from(j)

将发出类似于以下内容的 SQL

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

参数:

right¶ – 连接的右侧；这可以是任何 FromClause 对象，例如 Table 对象，也可以是与选择器兼容的对象，例如 ORM 映射的类。
onclause¶ – 表示连接的 ON 子句的 SQL 表达式。如果保留为 None，FromClause.join() 将尝试基于外键关系连接两个表。
isouter¶ – 如果为 True，则渲染 LEFT OUTER JOIN，而不是 JOIN。
full¶ – 如果为 True，则渲染 FULL OUTER JOIN，而不是 LEFT OUTER JOIN。意味着 FromClause.join.isouter。

另请参阅

join() - 独立函数

Join - 生成的对象类型

method sqlalchemy.sql.expression.FromClause.outerjoin(right: _FromClauseArgument, onclause: _ColumnExpressionArgument[bool] | None = None, full: bool = False) → Join¶

从该 FromClause 到另一个 FromClause 返回一个 Join，并将“isouter”标志设置为 True。

例如：

from sqlalchemy import outerjoin

j = user_table.outerjoin(address_table,
                user_table.c.id == address_table.c.user_id)

以上等同于

j = user_table.join(
    address_table,
    user_table.c.id == address_table.c.user_id,
    isouter=True)

参数:

right¶ – 连接的右侧；这可以是任何 FromClause 对象，例如 Table 对象，也可以是可选择兼容的对象，例如 ORM 映射类。
onclause¶ – 表示连接的 ON 子句的 SQL 表达式。如果保留为 None，FromClause.join() 将尝试基于外键关系连接两个表。
full¶ – 如果为 True，则渲染 FULL OUTER JOIN，而不是 LEFT OUTER JOIN。

另请参阅

FromClause.join()

Join

attribute sqlalchemy.sql.expression.FromClause.primary_key¶

返回组成此 _selectable.FromClause 主键的 Column 对象的可迭代集合。

对于 Table 对象，此集合由 PrimaryKeyConstraint 表示，该约束本身是一个可迭代的 Column 对象集合。

attribute sqlalchemy.sql.expression.FromClause.schema: str | None = None¶

为该 FromClause 定义 'schema' 属性。

这通常对于大多数对象都是 None，除了 Table 对象，它采用 Table.schema 参数的值。

method sqlalchemy.sql.expression.FromClause.select() → Select¶

返回该 FromClause 的 SELECT。

例如。

stmt = some_table.select().where(some_table.c.id == 5)

另请参阅

select() - 通用方法，允许使用任意列列表。

method sqlalchemy.sql.expression.FromClause.tablesample(sampling: float | Function[Any], name: str | None = None, seed: roles.ExpressionElementRole[Any] | None = None) → TableSample¶

返回该 FromClause 的 TABLESAMPLE 别名。

返回值是 TableSample 结构，该结构也由顶层 tablesample() 函数提供。

另请参阅

tablesample() - 用法指南和参数

class sqlalchemy.sql.expression.GenerativeSelect¶

SELECT 语句的基类，其中可以添加其他元素。

它作为 Select 和 CompoundSelect 的基础，可以添加 ORDER BY、GROUP BY 等元素，并控制列的渲染。与 TextualSelect 相比，虽然它也是 SelectBase 的子类，也是一个 SELECT 结构，但它表示一个固定的文本字符串，不能在当前级别修改，只能作为子查询包装。

成员

fetch(), get_label_style(), group_by(), limit(), offset(), order_by(), set_label_style(), slice(), with_for_update()

类签名

class sqlalchemy.sql.expression.GenerativeSelect (sqlalchemy.sql.expression.SelectBase, sqlalchemy.sql.expression.Generative)

method sqlalchemy.sql.expression.GenerativeSelect.fetch(count: _LimitOffsetType, with_ties: bool = False, percent: bool = False) → Self¶

返回一个新的可选择项，其中应用了给定的 FETCH FIRST 条件。

这是一个数值，通常呈现为 FETCH {FIRST | NEXT} [ count ] {ROW | ROWS} {ONLY | WITH TIES} 表达式，在结果选择中。此功能目前针对 Oracle、PostgreSQL、MSSQL 实现。

使用 GenerativeSelect.offset() 指定偏移量。

注意

GenerativeSelect.fetch() 方法将替换使用 GenerativeSelect.limit() 应用的任何子句。

版本 1.4 中的新功能。

参数:

count¶ – 整数 COUNT 参数，或提供整数结果的 SQL 表达式。当 percent=True 时，这将表示返回的行数的百分比，而不是绝对值。传递 None 以重置它。
with_ties¶ – 当 True 时，使用 WITH TIES 选项返回根据 ORDER BY 子句在结果集中排名最后的所有其他行。在这种情况下，ORDER BY 可能为必需。默认值为 False
percent¶ – 当 True 时，count 表示返回的选定行总数的百分比。默认值为 False

另请参阅

method sqlalchemy.sql.expression.GenerativeSelect.get_label_style() → SelectLabelStyle¶: 检索当前标签样式。

版本 1.4 中的新功能。

method sqlalchemy.sql.expression.GenerativeSelect.group_by(_GenerativeSelect__first: Literal[None, _NoArg.NO_ARG] | _ColumnExpressionOrStrLabelArgument[Any] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any]) → Self¶

返回一个新的可选择对象，其中应用了给定的 GROUP BY 条件列表。

可以通过传递 None 来抑制所有现有的 GROUP BY 设置。

例如。

stmt = select(table.c.name, func.max(table.c.stat)).\
group_by(table.c.name)

参数:: *clauses¶ – 一系列 ColumnElement 结构，将用于生成 GROUP BY 子句。

另请参阅

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

method sqlalchemy.sql.expression.GenerativeSelect.limit(limit: _LimitOffsetType) → Self¶

返回一个新的可选择对象，其中应用了给定的 LIMIT 条件。

这是一个数值，通常在结果选择中呈现为 LIMIT 表达式。不支持 LIMIT 的后端将尝试提供类似的功能。

注意

GenerativeSelect.limit() 方法将替换使用 GenerativeSelect.fetch() 应用的任何子句。

参数:: limit¶ – 整数 LIMIT 参数，或提供整数结果的 SQL 表达式。传递 None 以重置它。

另请参阅

method sqlalchemy.sql.expression.GenerativeSelect.offset(offset: _LimitOffsetType) → Self¶

返回一个新的可选择对象，应用了给定的偏移量准则。

这是一个数值，通常在生成的 SELECT 中呈现为 OFFSET 表达式。不支持 OFFSET 的后端会尝试提供类似的功能。

参数:: offset¶ – 整数 OFFSET 参数，或提供整数结果的 SQL 表达式。传递 None 以重置它。

另请参阅

method sqlalchemy.sql.expression.GenerativeSelect.order_by(_GenerativeSelect__first: Literal[None, _NoArg.NO_ARG] | _ColumnExpressionOrStrLabelArgument[Any] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any]) → Self¶

返回一个新的可选择对象，应用了给定的 ORDER BY 准则列表。

例如。

stmt = select(table).order_by(table.c.id, table.c.name)

多次调用此方法等效于一次调用它，并将所有子句连接在一起。通过传递 None 本身可以取消所有现有的 ORDER BY 准则。然后可以通过再次调用 Query.order_by() 添加新的 ORDER BY 准则，例如：

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

参数:: *clauses¶ – 一系列 ColumnElement 结构，将用于生成 ORDER BY 子句。

另请参阅

ORDER BY - 在 SQLAlchemy 统一教程中

method sqlalchemy.sql.expression.GenerativeSelect.set_label_style(style: SelectLabelStyle) → Self¶

返回一个具有指定标签样式的新可选。

有三种可用的“标签样式”： SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY、 SelectLabelStyle.LABEL_STYLE_TABLENAME_PLUS_COL 和 SelectLabelStyle.LABEL_STYLE_NONE。默认样式为 SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY.

在现代 SQLAlchemy 中，通常不需要更改标签样式，因为通过使用 ColumnElement.label() 方法，每个表达式标签都可以更有效地使用。在过去的版本中， LABEL_STYLE_TABLENAME_PLUS_COL 用于区分来自不同表、别名或子查询的同名列；较新的 LABEL_STYLE_DISAMBIGUATE_ONLY 现在只对与现有名称冲突的名称应用标签，以便这种标签的影响最小。

消除歧义的基本原理主要是使所有列表达式都可以在创建子查询时从给定的 FromClause.c 集合中获取。

版本 1.4 中的新功能： - GenerativeSelect.set_label_style() 方法取代了以前 .apply_labels()、 .with_labels() 和 use_labels=True 方法和/或参数的组合。

另请参阅

LABEL_STYLE_DISAMBIGUATE_ONLY

LABEL_STYLE_TABLENAME_PLUS_COL

LABEL_STYLE_NONE

LABEL_STYLE_DEFAULT

method sqlalchemy.sql.expression.GenerativeSelect.slice(start: int, stop: int) → Self¶

根据切片对该语句应用 LIMIT / OFFSET。

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

例如，

stmt = select(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)

注意

The GenerativeSelect.slice() method will replace any clause applied with GenerativeSelect.fetch().

New in version 1.4: Added the GenerativeSelect.slice() method generalized from the ORM.

另请参阅

exported_columns，is_derived_from()

method sqlalchemy.sql.expression.GenerativeSelect.with_for_update(*, nowait: bool = False, read: bool = False, of: _ForUpdateOfArgument | None = None, skip_locked: bool = False, key_share: bool = False) → Self¶

为这个 GenerativeSelect 指定一个 FOR UPDATE 子句。

例如：

stmt = select(table).with_for_update(nowait=True)

在 PostgreSQL 或 Oracle 等数据库上，上面的语句将呈现一个类似于

SELECT table.a, table.b FROM table FOR UPDATE NOWAIT

在其他后端，nowait 选项将被忽略，而是会生成

SELECT table.a, table.b FROM table FOR UPDATE

当不带任何参数调用时，该语句将用后缀 FOR UPDATE 呈现。然后可以提供其他参数，这些参数允许使用常见的数据库特定变体。

参数:

nowait¶ – boolean; will render FOR UPDATE NOWAIT on Oracle and PostgreSQL dialects.
read¶ – boolean; will render LOCK IN SHARE MODE on MySQL, FOR SHARE on PostgreSQL. On PostgreSQL, when combined with nowait, will render FOR SHARE NOWAIT.
of¶ – SQL expression or list of SQL expression elements, (typically Column objects or a compatible expression, for some backends may also be a table expression) which will render into a FOR UPDATE OF clause; supported by PostgreSQL, Oracle, some MySQL versions and possibly others. May render as a table or as a column depending on backend.
skip_locked¶ – boolean, will render FOR UPDATE SKIP LOCKED on Oracle and PostgreSQL dialects or FOR SHARE SKIP LOCKED if read=True is also specified.
key_share¶ – boolean, will render FOR NO KEY UPDATE, or if combined with read=True will render FOR KEY SHARE, on the PostgreSQL dialect.

class sqlalchemy.sql.expression.HasCTE¶

混合类，声明一个类包含 CTE 支持。

成员

add_cte(), cte()

类签名

class sqlalchemy.sql.expression.HasCTE (sqlalchemy.sql.roles.HasCTERole, sqlalchemy.sql.expression.SelectsRows)

method sqlalchemy.sql.expression.HasCTE.add_cte(*ctes: CTE, nest_here: bool = False) → Self¶

将一个或多个 CTE 构造添加到此语句。

此方法将与给定的 CTE 构造关联父语句，以便它们将在最终语句的 WITH 子句中无条件地渲染，即使在语句或任何子选择中没有其他地方引用它们。

当设置为 True 时，可选的 HasCTE.add_cte.nest_here 参数将具有以下效果：每个给定的 CTE 将在直接与该语句一起渲染的 WITH 子句中渲染，而不是被移动到最终渲染语句的顶部，即使该语句在更大的语句中以子查询的形式渲染。

此方法有两个一般用途。一种是嵌入用于某些目的的 CTE 语句，而无需显式引用它们，例如将 INSERT 或 UPDATE 等 DML 语句作为 CTE 嵌入到可能间接从其结果中获取数据的初级语句中的用例。另一种是提供对应该在可能嵌套在更大的语句中的特定语句方面直接渲染的特定一系列 CTE 构造的精确位置的控制。

例如：

from sqlalchemy import table, column, select
t = table('t', column('c1'), column('c2'))

ins = t.insert().values({"c1": "x", "c2": "y"}).cte()

stmt = select(t).add_cte(ins)

将渲染

WITH anon_1 AS
(INSERT INTO t (c1, c2) VALUES (:param_1, :param_2))
SELECT t.c1, t.c2
FROM t

在上面，"anon_1" CTE 在 SELECT 语句中没有被引用，但是仍然完成了运行 INSERT 语句的任务。

同样在与 DML 相关的上下文中，使用 PostgreSQL Insert 构造生成 "upsert"

from sqlalchemy import table, column
from sqlalchemy.dialects.postgresql import insert

t = table("t", column("c1"), column("c2"))

delete_statement_cte = (
    t.delete().where(t.c.c1 < 1).cte("deletions")
)

insert_stmt = insert(t).values({"c1": 1, "c2": 2})
update_statement = insert_stmt.on_conflict_do_update(
    index_elements=[t.c.c1],
    set_={
        "c1": insert_stmt.excluded.c1,
        "c2": insert_stmt.excluded.c2,
    },
).add_cte(delete_statement_cte)

print(update_statement)

上面的语句渲染为

WITH deletions AS
(DELETE FROM t WHERE t.c1 < %(c1_1)s)
INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2

版本 1.4.21 中的新功能。

参数:

*ctes¶ –
零个或多个 CTE 构造。

在版本 2.0 中更改: 接受多个 CTE 实例
nest_here¶ –
如果为 True，则给定的 CTE 或 CTE 将被渲染为它们指定了 HasCTE.cte.nesting 标志为 True 时添加到此 HasCTE。假设给定的 CTE 在外部封闭语句中也没有被引用，则在给出此标志时，给定的 CTE 应该在该语句的级别进行渲染。

2.0 版中的新增功能。

另请参阅

HasCTE.cte.nesting

method sqlalchemy.sql.expression.HasCTE.cte(name: str | None = None, recursive: bool = False, nesting: bool = False) → CTE¶

返回一个新的 CTE 或 Common Table Expression 实例。

公共表表达式是 SQL 标准，其中 SELECT 语句可以利用与主语句一起指定的辅助语句，使用称为“WITH”的子句。还可以使用有关 UNION 的特殊语义来允许“递归”查询，其中 SELECT 语句可以利用先前已选择的行集。

CTE 也可以应用于某些数据库上的 DML 结构 UPDATE、INSERT 和 DELETE，作为 CTE 行的来源（当与 RETURNING 组合时）以及 CTE 行的使用者。

SQLAlchemy 检测 CTE 对象，这些对象与 Alias 对象类似，被视为特殊元素，传递给语句的 FROM 子句以及语句顶部的 WITH 子句。

对于特殊前缀（如 PostgreSQL 的“MATERIALIZED”和“NOT MATERIALIZED”），可以使用 CTE.prefix_with() 方法来建立这些前缀。

在版本 1.3.13 中更改: 添加了对前缀的支持。尤其是 - MATERIALIZED 和 NOT MATERIALIZED。

参数:

name¶ – name given to the common table expression. Like FromClause.alias(), the name can be left as None in which case an anonymous symbol will be used at query compile time.
recursive¶ – if True, will render WITH RECURSIVE. A recursive common table expression is intended to be used in conjunction with UNION ALL in order to derive rows from those already selected.
nesting¶ –
如果为 True，将把 CTE 呈现在引用它的语句中。对于更复杂的情况，可以使用 HasCTE.add_cte() 方法，使用 HasCTE.add_cte.nest_here 参数也可以更仔细地控制特定 CTE 的确切位置。

版本 1.4.24 中新增。

另请参阅

HasCTE.add_cte()

以下示例包括两个来自 PostgreSQL 文档的示例，位于 https://postgresql.ac.cn/docs/current/static/queries-with.html，以及其他示例。

示例 1，非递归

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
    Column('region', String),
    Column('amount', Integer),
    Column('product', String),
    Column('quantity', Integer)
)

regional_sales = select(
                    orders.c.region,
                    func.sum(orders.c.amount).label('total_sales')
                ).group_by(orders.c.region).cte("regional_sales")


top_regions = select(regional_sales.c.region).\
        where(
            regional_sales.c.total_sales >
            select(
                func.sum(regional_sales.c.total_sales) / 10
            )
        ).cte("top_regions")

statement = select(
            orders.c.region,
            orders.c.product,
            func.sum(orders.c.quantity).label("product_units"),
            func.sum(orders.c.amount).label("product_sales")
    ).where(orders.c.region.in_(
        select(top_regions.c.region)
    )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

示例 2，WITH RECURSIVE

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
    Column('part', String),
    Column('sub_part', String),
    Column('quantity', Integer),
)

included_parts = select(\
    parts.c.sub_part, parts.c.part, parts.c.quantity\
    ).\
    where(parts.c.part=='our part').\
    cte(recursive=True)


incl_alias = included_parts.alias()
parts_alias = parts.alias()
included_parts = included_parts.union_all(
    select(
        parts_alias.c.sub_part,
        parts_alias.c.part,
        parts_alias.c.quantity
    ).\
    where(parts_alias.c.part==incl_alias.c.sub_part)
)

statement = select(
            included_parts.c.sub_part,
            func.sum(included_parts.c.quantity).
              label('total_quantity')
        ).\
        group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

示例 3，使用 CTE 的 UPDATE 和 INSERT 进行 upsert

from datetime import date
from sqlalchemy import (MetaData, Table, Column, Integer,
                        Date, select, literal, and_, exists)

metadata = MetaData()

visitors = Table('visitors', metadata,
    Column('product_id', Integer, primary_key=True),
    Column('date', Date, primary_key=True),
    Column('count', Integer),
)

# add 5 visitors for the product_id == 1
product_id = 1
day = date.today()
count = 5

update_cte = (
    visitors.update()
    .where(and_(visitors.c.product_id == product_id,
                visitors.c.date == day))
    .values(count=visitors.c.count + count)
    .returning(literal(1))
    .cte('update_cte')
)

upsert = visitors.insert().from_select(
    [visitors.c.product_id, visitors.c.date, visitors.c.count],
    select(literal(product_id), literal(day), literal(count))
        .where(~exists(update_cte.select()))
)

connection.execute(upsert)

示例 4，嵌套 CTE（SQLAlchemy 1.4.24 及更高版本）

value_a = select(
    literal("root").label("n")
).cte("value_a")

# A nested CTE with the same name as the root one
value_a_nested = select(
    literal("nesting").label("n")
).cte("value_a", nesting=True)

# Nesting CTEs takes ascendency locally
# over the CTEs at a higher level
value_b = select(value_a_nested.c.n).cte("value_b")

value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))

上述查询将呈现嵌套在第一个 CTE 内的第二个 CTE，如下所示，带有内联参数

WITH
    value_a AS
        (SELECT 'root' AS n),
    value_b AS
        (WITH value_a AS
            (SELECT 'nesting' AS n)
        SELECT value_a.n AS n FROM value_a)
SELECT value_a.n AS a, value_b.n AS b
FROM value_a, value_b

可以使用 HasCTE.add_cte() 方法设置相同的 CTE（SQLAlchemy 2.0 及更高版本）

value_a = select(
    literal("root").label("n")
).cte("value_a")

# A nested CTE with the same name as the root one
value_a_nested = select(
    literal("nesting").label("n")
).cte("value_a")

# Nesting CTEs takes ascendency locally
# over the CTEs at a higher level
value_b = (
    select(value_a_nested.c.n).
    add_cte(value_a_nested, nest_here=True).
    cte("value_b")
)

value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))

示例 5，非线性 CTE（SQLAlchemy 1.4.28 及更高版本）

edge = Table(
    "edge",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("left", Integer),
    Column("right", Integer),
)

root_node = select(literal(1).label("node")).cte(
    "nodes", recursive=True
)

left_edge = select(edge.c.left).join(
    root_node, edge.c.right == root_node.c.node
)
right_edge = select(edge.c.right).join(
    root_node, edge.c.left == root_node.c.node
)

subgraph_cte = root_node.union(left_edge, right_edge)

subgraph = select(subgraph_cte)

上述查询将呈现递归 CTE 内的 2 个 UNION

WITH RECURSIVE nodes(node) AS (
        SELECT 1 AS node
    UNION
        SELECT edge."left" AS "left"
        FROM edge JOIN nodes ON edge."right" = nodes.node
    UNION
        SELECT edge."right" AS "right"
        FROM edge JOIN nodes ON edge."left" = nodes.node
)
SELECT nodes.node FROM nodes

另请参阅

Query.cte() - HasCTE.cte() 的 ORM 版本。

class sqlalchemy.sql.expression.HasPrefixes¶

成员

prefix_with()

method sqlalchemy.sql.expression.HasPrefixes.prefix_with(*prefixes: _TextCoercedExpressionArgument[Any], dialect: str = '*') → Self¶

Add one or more expressions following the statement keyword, i.e. SELECT, INSERT, UPDATE, or DELETE. Generative.

This is used to support backend-specific prefix keywords such as those provided by MySQL.

例如：

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

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

Multiple prefixes can be specified by multiple calls to HasPrefixes.prefix_with().

参数:

*prefixes¶ – textual or ClauseElement construct which will be rendered following the INSERT, UPDATE, or DELETE keyword.
dialect¶ – optional string dialect name which will limit rendering of this prefix to only that dialect.

class sqlalchemy.sql.expression.HasSuffixes¶

成员

suffix_with()

method sqlalchemy.sql.expression.HasSuffixes.suffix_with(*suffixes: _TextCoercedExpressionArgument[Any], dialect: str = '*') → Self¶

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

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

例如：

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

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

参数:

*suffixes¶ – 文本或 ClauseElement 构造，将在目标子句之后呈现。
dialect¶ – 可选的字符串方言名称，将限制此后缀的呈现，使其仅适用于该方言。

class sqlalchemy.sql.expression.Join¶

表示两个 FromClause 元素之间的 JOIN 结构。

Join 的公共构造函数是模块级 join() 函数，以及任何 FromClause（例如 Table）的 FromClause.join() 方法。

另请参阅

join()

FromClause.join()

成员

__init__(), description, is_derived_from(), select(), self_group()

类签名

class sqlalchemy.sql.expression.Join (sqlalchemy.sql.roles.DMLTableRole, sqlalchemy.sql.expression.FromClause)

method sqlalchemy.sql.expression.Join.__init__(left: _FromClauseArgument, right: _FromClauseArgument, onclause: _OnClauseArgument | None = None, isouter: bool = False, full: bool = False)¶

构造一个新的 Join。

通常的入口点是 join() 函数或任何 FromClause 对象的 FromClause.join() 方法。

attribute sqlalchemy.sql.expression.Join.description¶

method sqlalchemy.sql.expression.Join.is_derived_from(fromclause: FromClause | None) → bool¶

如果此 FromClause 是从给定的 FromClause “派生”的，则返回 True。

例如，表的别名将从该表派生。

method sqlalchemy.sql.expression.Join.select() → Select¶

从此 Join 创建一个 Select。

例如：

stmt = table_a.join(table_b, table_a.c.id == table_b.c.a_id)

stmt = stmt.select()

以上将生成类似于以下 SQL 字符串

SELECT table_a.id, table_a.col, table_b.id, table_b.a_id
FROM table_a JOIN table_b ON table_a.id = table_b.a_id

method sqlalchemy.sql.expression.Join.self_group(against: OperatorType | None = None) → FromGrouping¶

对这个 ClauseElement 应用“分组”。

此方法被子类覆盖以返回“分组”构造，即括号。特别是它被“二元”表达式用于在放置到更大的表达式中时在其周围提供分组，以及被 select() 构造在放置到另一个 select() 的 FROM 子句中时使用。(注意，子查询通常应该使用 Select.alias() 方法创建，因为许多平台要求嵌套的 SELECT 语句被命名).

当表达式组合在一起时，self_group() 的应用是自动的 - 用户代码永远不需要直接使用此方法。请注意，SQLAlchemy 的子句构造考虑了运算符优先级 - 因此，例如，在表达式 x OR (y AND z) 中，可能不需要括号 - AND 的优先级高于 OR。

ClauseElement 的基本 self_group() 方法只返回自身。

class sqlalchemy.sql.expression.Lateral¶

表示 LATERAL 子查询。

此对象由 lateral() 模块级函数以及所有 FromClause 子类的 FromClause.lateral() 方法构造。

虽然 LATERAL 是 SQL 标准的一部分，但目前只有较新的 PostgreSQL 版本支持此关键字。

另请参阅

LATERAL 关联 - 用法概述。

成员

inherit_cache

类签名

class sqlalchemy.sql.expression.Lateral (sqlalchemy.sql.expression.FromClauseAlias, sqlalchemy.sql.expression.LateralFromClause)

attribute sqlalchemy.sql.expression.Lateral.inherit_cache: bool | None = True¶

指示此 HasCacheKey 实例是否应使用其直接父类使用的缓存键生成方案。

该属性默认为 None，这表明构造尚未考虑其是否适合参与缓存；这在功能上等同于将值设置为 False，只是还会发出警告。

如果与对象对应的 SQL 不会根据此类本身的属性（而非其父类）而发生变化，则可以在特定类上将此标志设置为 True。

另请参阅

为自定义构造启用缓存支持 - 为第三方或用户定义的 SQL 构造设置 HasCacheKey.inherit_cache 属性的一般指南。

class sqlalchemy.sql.expression.ReturnsRows¶

具有某种列概念的 Core 结构的最基本类，这些列可以表示行。

虽然 SELECT 语句和 TABLE 是我们在这个类别中首先想到的，但像 INSERT、UPDATE 和 DELETE 这样的 DML 也可以指定 RETURNING，这意味着它们可以用于 CTE 和其他形式，而 PostgreSQL 也拥有返回行的函数。

版本 1.4 中的新功能。

成员

类签名

class sqlalchemy.sql.expression.ReturnsRows (sqlalchemy.sql.roles.ReturnsRowsRole, sqlalchemy.sql.expression.DQLDMLClauseElement)

attribute sqlalchemy.sql.expression.ReturnsRows.exported_columns¶

一个 ColumnCollection，它代表此 ReturnsRows 的“导出”列。

“导出”列表示此 SQL 结构呈现的 ColumnElement 表达式的集合。主要类型包括 FROM 子句的“FROM 子句列”，例如表、联接或子查询，以及“SELECTed 列”，即 SELECT 语句“列子句”中的列，以及 DML 语句中的 RETURNING 列。

版本 1.4 中的新功能。

另请参阅

SelectBase.scalar_subquery()

method sqlalchemy.sql.expression.ReturnsRows.is_derived_from(fromclause: FromClause | None) → bool¶

如果此 ReturnsRows ‘派生’ 自给定的 FromClause，则返回 True。

例如，表的别名将从该表派生。

class sqlalchemy.sql.expression.ScalarSelect¶

表示一个标量子查询。

一个 ScalarSelect 是通过调用 SelectBase.scalar_subquery() 方法创建的。然后该对象作为 ColumnElement 层次结构中的 SQL 列表达式参与其他 SQL 表达式。

另请参阅

标量和关联子查询 - 在 2.0 教程中

成员

correlate()，correlate_except()，inherit_cache，self_group()，where()

类签名

class sqlalchemy.sql.expression.ScalarSelect (sqlalchemy.sql.roles.InElementRole, sqlalchemy.sql.expression.Generative, sqlalchemy.sql.expression.GroupedElement, sqlalchemy.sql.expression.ColumnElement)

method sqlalchemy.sql.expression.ScalarSelect.correlate(*fromclauses: Literal[None, False] | _FromClauseArgument) → Self¶

返回一个新的 ScalarSelect，它将使给定的 FROM 子句与封闭的 Select 的 FROM 子句相关联。

此方法反映了基础 Select 的 Select.correlate() 方法。该方法应用 :meth:_sql.Select.correlate` 方法，然后返回一个针对该语句的新 ScalarSelect。

版本 1.4 中的新功能：以前，ScalarSelect.correlate() 方法只能从 Select 中获得。

参数:: *fromclauses¶ – 一个或多个 FromClause 结构的列表，或其他兼容结构（例如 ORM 映射类），将成为相关集合的一部分。

另请参阅

ScalarSelect.correlate_except()

标量和关联子查询 - 在 2.0 教程中

method sqlalchemy.sql.expression.ScalarSelect.correlate_except(*fromclauses: Literal[None, False] | _FromClauseArgument) → Self¶

返回一个新的 ScalarSelect，它将从自动相关联过程中省略给定的 FROM 子句。

此方法反映了基础 Select 的 Select.correlate_except() 方法。该方法应用 :meth:_sql.Select.correlate_except` 方法，然后返回一个针对该语句的新 ScalarSelect。

版本 1.4 中的新功能：以前，ScalarSelect.correlate_except() 方法只能从 Select 中获得。

参数:: *fromclauses¶ – 一个或多个 FromClause 结构的列表，或其他兼容结构（例如 ORM 映射类），将成为相关联异常集合的一部分。

另请参阅

ScalarSelect.correlate()

标量和关联子查询 - 在 2.0 教程中

attribute sqlalchemy.sql.expression.ScalarSelect.inherit_cache: bool | None = True¶

指示此 HasCacheKey 实例是否应使用其直接父类使用的缓存键生成方案。

该属性默认为 None，这表明构造尚未考虑其是否适合参与缓存；这在功能上等同于将值设置为 False，只是还会发出警告。

如果与对象对应的 SQL 不会根据此类本身的属性（而非其父类）而发生变化，则可以在特定类上将此标志设置为 True。

另请参阅

为自定义构造启用缓存支持 - 为第三方或用户定义的 SQL 构造设置 HasCacheKey.inherit_cache 属性的一般指南。

方法 sqlalchemy.sql.expression.ScalarSelect.self_group(against: OperatorType | None = None) → Self¶

对这个 ClauseElement 应用“分组”。

此方法被子类覆盖以返回“分组”构造，即括号。特别是它被“二元”表达式用于在放置到更大的表达式中时在其周围提供分组，以及被 select() 构造在放置到另一个 select() 的 FROM 子句中时使用。(注意，子查询通常应该使用 Select.alias() 方法创建，因为许多平台要求嵌套的 SELECT 语句被命名).

当表达式组合在一起时，self_group() 的应用是自动的 - 终端用户代码永远不需要直接使用此方法。请注意，SQLAlchemy 的子句构造会考虑运算符优先级 - 因此，例如，在 x OR (y AND z) 这样的表达式中可能不需要括号 - AND 优先于 OR。

self_group() 的基础方法 ClauseElement 只是返回自身。

方法 sqlalchemy.sql.expression.ScalarSelect.where(crit: _ColumnExpressionArgument[bool]) → Self¶: 对由此 ScalarSelect 引用的 SELECT 语句应用 WHERE 子句。

类 sqlalchemy.sql.expression.Select¶

表示一个 SELECT 语句。

Select 对象通常使用 select() 函数构造。有关详细信息，请参阅该函数。

另请参阅

select()

使用 SELECT 语句 - 在 2.0 教程中

成员

__init__(), add_columns(), add_cte(), alias(), as_scalar(), c, column(), column_descriptions, columns_clause_froms, correlate(), correlate_except(), corresponding_column(), cte(), distinct(), except_(), except_all(), execution_options(), exists(), exported_columns, fetch(), filter(), filter_by(), from_statement(), froms, get_children(), get_execution_options(), get_final_froms(), get_label_style(), group_by(), having(), inherit_cache, inner_columns, intersect(), intersect_all(), is_derived_from(), join(), join_from(), label(), lateral(), limit(), offset(), options(), order_by(), outerjoin(), outerjoin_from(), prefix_with(), reduce_columns(), replace_selectable(), scalar_subquery(), select(), select_from(), selected_columns, self_group(), set_label_style(), slice(), subquery(), suffix_with(), union(), union_all(), where(), whereclause, with_for_update(), with_hint(), with_only_columns(), with_statement_hint()

类签名

class sqlalchemy.sql.expression.Select (sqlalchemy.sql.expression.HasPrefixes, sqlalchemy.sql.expression.HasSuffixes, sqlalchemy.sql.expression.HasHints, sqlalchemy.sql.expression.HasCompileState, sqlalchemy.sql.expression._SelectFromElements, sqlalchemy.sql.expression.GenerativeSelect, sqlalchemy.sql.expression.TypedReturnsRows)

方法 sqlalchemy.sql.expression.Select.__init__(*entities: _ColumnsClauseArgument[Any])¶

构造一个新的 Select。

Select 的公共构造函数是 select() 函数。

method sqlalchemy.sql.expression.Select.add_columns(*entities: _ColumnsClauseArgument[Any]) → Select[Any]¶

返回一个新的 select() 结构，其列子句中添加了给定的实体。

例如：

my_select = my_select.add_columns(table.c.new_column)

列子句中的原始表达式将保留在原位。要用新的表达式替换原始表达式，请参见方法 Select.with_only_columns()。

参数:: *entities¶ – 要添加到列子句的列、表或其他实体表达式

另请参阅

Select.with_only_columns() - 替换现有表达式，而不是追加。

同时选择多个 ORM 实体 - 以 ORM 为中心的示例

method sqlalchemy.sql.expression.Select.add_cte(*ctes: CTE, nest_here: bool = False) → Self¶

继承自 HasCTE.add_cte() 方法 HasCTE

将一个或多个 CTE 构造添加到此语句。

此方法将与给定的 CTE 构造关联父语句，以便它们将在最终语句的 WITH 子句中无条件地渲染，即使在语句或任何子选择中没有其他地方引用它们。

当设置为 True 时，可选的 HasCTE.add_cte.nest_here 参数将具有以下效果：每个给定的 CTE 将在直接与该语句一起渲染的 WITH 子句中渲染，而不是被移动到最终渲染语句的顶部，即使该语句在更大的语句中以子查询的形式渲染。

此方法有两个一般用途。一种是嵌入用于某些目的的 CTE 语句，而无需显式引用它们，例如将 INSERT 或 UPDATE 等 DML 语句作为 CTE 嵌入到可能间接从其结果中获取数据的初级语句中的用例。另一种是提供对应该在可能嵌套在更大的语句中的特定语句方面直接渲染的特定一系列 CTE 构造的精确位置的控制。

例如：

from sqlalchemy import table, column, select
t = table('t', column('c1'), column('c2'))

ins = t.insert().values({"c1": "x", "c2": "y"}).cte()

stmt = select(t).add_cte(ins)

将渲染

WITH anon_1 AS
(INSERT INTO t (c1, c2) VALUES (:param_1, :param_2))
SELECT t.c1, t.c2
FROM t

在上面，"anon_1" CTE 在 SELECT 语句中没有被引用，但是仍然完成了运行 INSERT 语句的任务。

同样在与 DML 相关的上下文中，使用 PostgreSQL Insert 构造生成 "upsert"

from sqlalchemy import table, column
from sqlalchemy.dialects.postgresql import insert

t = table("t", column("c1"), column("c2"))

delete_statement_cte = (
    t.delete().where(t.c.c1 < 1).cte("deletions")
)

insert_stmt = insert(t).values({"c1": 1, "c2": 2})
update_statement = insert_stmt.on_conflict_do_update(
    index_elements=[t.c.c1],
    set_={
        "c1": insert_stmt.excluded.c1,
        "c2": insert_stmt.excluded.c2,
    },
).add_cte(delete_statement_cte)

print(update_statement)

上面的语句渲染为

WITH deletions AS
(DELETE FROM t WHERE t.c1 < %(c1_1)s)
INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2

版本 1.4.21 中的新功能。

参数:

*ctes¶ –
零个或多个 CTE 构造。

在版本 2.0 中更改: 接受多个 CTE 实例
nest_here¶ –
如果为 True，则给定的 CTE 或 CTE 将被渲染为它们指定了 HasCTE.cte.nesting 标志为 True 时添加到此 HasCTE。假设给定的 CTE 在外部封闭语句中也没有被引用，则在给出此标志时，给定的 CTE 应该在该语句的级别进行渲染。

2.0 版中的新增功能。

另请参阅

HasCTE.cte.nesting

method sqlalchemy.sql.expression.Select.alias(name: str | None = None, flat: bool = False) → Subquery¶

继承自 SelectBase.alias() 方法 SelectBase

返回针对此 SelectBase 的命名子查询。

对于 SelectBase（而不是 FromClause），这将返回一个 Subquery 对象，该对象的运行方式与 Alias 对象（用于 FromClause）基本相同。

在 1.4 版中变更: The SelectBase.alias() 方法现在是 SelectBase.subquery() 方法的同义词。

method sqlalchemy.sql.expression.Select.as_scalar() → ScalarSelect[Any]¶: 继承自 SelectBase.as_scalar() 方法 SelectBase

自 1.4 版起弃用: The SelectBase.as_scalar() 方法已弃用，将在未来版本中删除。请参阅 SelectBase.scalar_subquery().

attribute sqlalchemy.sql.expression.Select.c¶: 继承自 SelectBase.c 属性 SelectBase

自 1.4 版起弃用: The SelectBase.c 和 SelectBase.columns 属性已弃用，将在未来版本中删除；这些属性隐式地创建一个子查询，而该子查询应该是显式的。请先调用 SelectBase.subquery() 以创建一个子查询，然后该子查询包含此属性。要访问此 SELECT 对象 SELECT 的列，请使用 SelectBase.selected_columns 属性。

method sqlalchemy.sql.expression.Select.column(column: _ColumnsClauseArgument[Any]) → Select[Any]¶

返回一个新的 select() 结构，其列子句中添加了给定的列表达式。

自版本 1.4 起弃用: The Select.column() 方法已弃用，将在未来版本中删除。请使用 Select.add_columns()

例如：

my_select = my_select.column(table.c.new_column)

有关添加/替换 Select 对象列的指南，请参见 Select.with_only_columns() 的文档。

attribute sqlalchemy.sql.expression.Select.column_descriptions¶

返回一个插件启用的“列描述”结构，该结构引用此语句所选择的列。

此属性在使用 ORM 时通常很有用，因为它返回一个扩展结构，其中包含有关映射实体的信息。从 ORM 启用的 SELECT 和 DML 语句检查实体和列部分包含更多背景。

对于仅限 Core 的语句，此访问器返回的结构派生自 Select.selected_columns 访问器返回的相同对象，格式化为包含键 name、type 和 expr 的字典列表，这些键表示要选择的列表达式

>>> stmt = select(user_table)
>>> stmt.column_descriptions
[
    {
        'name': 'id',
        'type': Integer(),
        'expr': Column('id', Integer(), ...)},
    {
        'name': 'name',
        'type': String(length=30),
        'expr': Column('name', String(length=30), ...)}
]

版本 1.4.33 中的更改: The Select.column_descriptions 属性返回仅限 Core 的实体集的结构，而不仅仅是仅限 ORM 的实体。

另请参阅

UpdateBase.entity_description - insert()、update() 或 delete() 的实体信息

从 ORM 启用的 SELECT 和 DML 语句检查实体和列 - ORM 背景

attribute sqlalchemy.sql.expression.Select.columns_clause_froms¶: 返回此 SELECT 语句的列子句所隐含的 FromClause 对象集。

版本 1.4.23 中的新增内容。

另请参阅

Select.froms - 考虑完整语句的“最终”FROM 列表

Select.with_only_columns() - 利用此集合设置新的 FROM 列表

method sqlalchemy.sql.expression.Select.correlate(*fromclauses: Literal[None, False] | _FromClauseArgument) → Self¶

返回一个新的 Select，它将给定的 FROM 子句与包含的 Select 的 FROM 子句相关联。

调用此方法将关闭Select对象的“自动关联”的默认行为。通常，出现在通过其WHERE 子句、ORDER BY、HAVING 或列子句包含此 Select的 Select中的 FROM 元素将从此 Select对象的FROM 子句中省略。使用Select.correlate()方法设置显式关联集合将提供一个固定的 FROM 对象列表，这些对象可能在此过程中发生。

当Select.correlate()用于应用特定于关联的 FROM 子句时，FROM 元素将成为关联的候选项，无论此Select对象相对于引用相同 FROM 对象的包含Select嵌套多深。这与“自动关联”的行为形成对比，后者只与直接包含的Select相关联。多级关联确保包含和包含的 Select之间的链接始终通过至少一个 WHERE/ORDER BY/HAVING/列子句，以便关联发生。

如果传递了None，Select对象将不会关联其任何 FROM 条目，并且所有条目都将在本地 FROM 子句中无条件呈现。

参数:: *fromclauses¶ – 一个或多个FromClause或其他与 FROM 兼容的结构，例如 ORM 映射的实体，以成为关联集合的一部分；或者传递单个值None以删除所有现有的关联。

另请参阅

Select.correlate_except()

标量和关联子查询

method sqlalchemy.sql.expression.Select.correlate_except(*fromclauses: Literal[None, False] | _FromClauseArgument) → Self¶

返回一个新的Select，它将从自动关联过程中省略给定的 FROM 子句。

调用Select.correlate_except()将关闭给定 FROM 元素的 Select对象的“自动关联”的默认行为。此处指定的元素将无条件地出现在 FROM 列表中，而所有其他 FROM 元素将仍然遵循正常的自动关联行为。

如果传递了None，或者没有传递任何参数，Select对象将关联其所有 FROM 条目。

参数:: *fromclauses¶ – 一个或多个 FromClause构造的列表，或其他兼容的构造（例如 ORM 映射的类），以成为关联异常集合的一部分。

另请参阅

Select.correlate()

标量和关联子查询

method sqlalchemy.sql.expression.Select.corresponding_column(column: KeyedColumnElement[Any], require_embedded: bool = False) → KeyedColumnElement[Any] | None¶

继承自 Selectable.corresponding_column() 方法 Selectable

给定一个 ColumnElement，返回来自此 Selectable 的 ColumnElement 对象，该对象通过公共祖先列对应于该原始 ColumnElement。

参数:

column¶ – 要匹配的目标ColumnElement。
require_embedded¶ – 仅针对给定 ColumnElement返回对应的列，如果给定的 ColumnElement实际上存在于此Selectable的子元素中。通常，如果该列与该Selectable的导出列之一共享一个共同的祖先，那么该列将匹配。

另请参阅

Selectable.exported_columns - 用于该操作的 ColumnCollection。

ColumnCollection.corresponding_column() - 实现方法。

method sqlalchemy.sql.expression.Select.cte(name: str | None = None, recursive: bool = False, nesting: bool = False) → CTE¶

继承自 HasCTE.cte() 方法的 HasCTE

返回一个新的 CTE 或 Common Table Expression 实例。

公共表表达式是 SQL 标准，其中 SELECT 语句可以利用与主语句一起指定的辅助语句，使用称为“WITH”的子句。还可以使用有关 UNION 的特殊语义来允许“递归”查询，其中 SELECT 语句可以利用先前已选择的行集。

CTE 也可以应用于某些数据库上的 DML 结构 UPDATE、INSERT 和 DELETE，作为 CTE 行的来源（当与 RETURNING 组合时）以及 CTE 行的使用者。

SQLAlchemy 检测 CTE 对象，这些对象与 Alias 对象类似，被视为特殊元素，传递给语句的 FROM 子句以及语句顶部的 WITH 子句。

对于特殊前缀（如 PostgreSQL 的“MATERIALIZED”和“NOT MATERIALIZED”），可以使用 CTE.prefix_with() 方法来建立这些前缀。

在版本 1.3.13 中更改: 添加了对前缀的支持。尤其是 - MATERIALIZED 和 NOT MATERIALIZED。

参数:

name¶ – 给定于公用表表达式的名称。类似于FromClause.alias()，该名称可以保留为None，在这种情况下，将在查询编译时使用匿名符号。
recursive¶ – 如果为True，将呈现WITH RECURSIVE。递归公用表表达式旨在与 UNION ALL 结合使用，以便从已选择的行中派生行。
nesting¶ –
如果为 True，将把 CTE 呈现在引用它的语句中。对于更复杂的情况，可以使用 HasCTE.add_cte() 方法，使用 HasCTE.add_cte.nest_here 参数也可以更仔细地控制特定 CTE 的确切位置。

版本 1.4.24 中新增。

另请参阅

HasCTE.add_cte()

以下示例包括两个来自 PostgreSQL 文档的示例，位于 https://postgresql.ac.cn/docs/current/static/queries-with.html，以及其他示例。

示例 1，非递归

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
    Column('region', String),
    Column('amount', Integer),
    Column('product', String),
    Column('quantity', Integer)
)

regional_sales = select(
                    orders.c.region,
                    func.sum(orders.c.amount).label('total_sales')
                ).group_by(orders.c.region).cte("regional_sales")


top_regions = select(regional_sales.c.region).\
        where(
            regional_sales.c.total_sales >
            select(
                func.sum(regional_sales.c.total_sales) / 10
            )
        ).cte("top_regions")

statement = select(
            orders.c.region,
            orders.c.product,
            func.sum(orders.c.quantity).label("product_units"),
            func.sum(orders.c.amount).label("product_sales")
    ).where(orders.c.region.in_(
        select(top_regions.c.region)
    )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

示例 2，WITH RECURSIVE

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
    Column('part', String),
    Column('sub_part', String),
    Column('quantity', Integer),
)

included_parts = select(\
    parts.c.sub_part, parts.c.part, parts.c.quantity\
    ).\
    where(parts.c.part=='our part').\
    cte(recursive=True)


incl_alias = included_parts.alias()
parts_alias = parts.alias()
included_parts = included_parts.union_all(
    select(
        parts_alias.c.sub_part,
        parts_alias.c.part,
        parts_alias.c.quantity
    ).\
    where(parts_alias.c.part==incl_alias.c.sub_part)
)

statement = select(
            included_parts.c.sub_part,
            func.sum(included_parts.c.quantity).
              label('total_quantity')
        ).\
        group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

示例 3，使用 CTE 的 UPDATE 和 INSERT 进行 upsert

from datetime import date
from sqlalchemy import (MetaData, Table, Column, Integer,
                        Date, select, literal, and_, exists)

metadata = MetaData()

visitors = Table('visitors', metadata,
    Column('product_id', Integer, primary_key=True),
    Column('date', Date, primary_key=True),
    Column('count', Integer),
)

# add 5 visitors for the product_id == 1
product_id = 1
day = date.today()
count = 5

update_cte = (
    visitors.update()
    .where(and_(visitors.c.product_id == product_id,
                visitors.c.date == day))
    .values(count=visitors.c.count + count)
    .returning(literal(1))
    .cte('update_cte')
)

upsert = visitors.insert().from_select(
    [visitors.c.product_id, visitors.c.date, visitors.c.count],
    select(literal(product_id), literal(day), literal(count))
        .where(~exists(update_cte.select()))
)

connection.execute(upsert)

示例 4，嵌套 CTE（SQLAlchemy 1.4.24 及更高版本）

value_a = select(
    literal("root").label("n")
).cte("value_a")

# A nested CTE with the same name as the root one
value_a_nested = select(
    literal("nesting").label("n")
).cte("value_a", nesting=True)

# Nesting CTEs takes ascendency locally
# over the CTEs at a higher level
value_b = select(value_a_nested.c.n).cte("value_b")

value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))

上述查询将呈现嵌套在第一个 CTE 内的第二个 CTE，如下所示，带有内联参数

WITH
    value_a AS
        (SELECT 'root' AS n),
    value_b AS
        (WITH value_a AS
            (SELECT 'nesting' AS n)
        SELECT value_a.n AS n FROM value_a)
SELECT value_a.n AS a, value_b.n AS b
FROM value_a, value_b

可以使用 HasCTE.add_cte() 方法设置相同的 CTE（SQLAlchemy 2.0 及更高版本）

value_a = select(
    literal("root").label("n")
).cte("value_a")

# A nested CTE with the same name as the root one
value_a_nested = select(
    literal("nesting").label("n")
).cte("value_a")

# Nesting CTEs takes ascendency locally
# over the CTEs at a higher level
value_b = (
    select(value_a_nested.c.n).
    add_cte(value_a_nested, nest_here=True).
    cte("value_b")
)

value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))

示例 5，非线性 CTE（SQLAlchemy 1.4.28 及更高版本）

edge = Table(
    "edge",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("left", Integer),
    Column("right", Integer),
)

root_node = select(literal(1).label("node")).cte(
    "nodes", recursive=True
)

left_edge = select(edge.c.left).join(
    root_node, edge.c.right == root_node.c.node
)
right_edge = select(edge.c.right).join(
    root_node, edge.c.left == root_node.c.node
)

subgraph_cte = root_node.union(left_edge, right_edge)

subgraph = select(subgraph_cte)

上述查询将呈现递归 CTE 内的 2 个 UNION

WITH RECURSIVE nodes(node) AS (
        SELECT 1 AS node
    UNION
        SELECT edge."left" AS "left"
        FROM edge JOIN nodes ON edge."right" = nodes.node
    UNION
        SELECT edge."right" AS "right"
        FROM edge JOIN nodes ON edge."left" = nodes.node
)
SELECT nodes.node FROM nodes

另请参阅

Query.cte() - HasCTE.cte() 的 ORM 版本。

method sqlalchemy.sql.expression.Select.distinct(*expr: _ColumnExpressionArgument[Any]) → Self¶

返回一个新的 select() 结构，它将对整个 SELECT 语句应用 DISTINCT。

例如：

from sqlalchemy import select
stmt = select(users_table.c.id, users_table.c.name).distinct()

以上将生成一个类似于以下的语句

SELECT DISTINCT user.id, user.name FROM user

该方法还接受一个 *expr 参数，该参数会生成 PostgreSQL 方言特定的 DISTINCT ON 表达式。在不支持此语法的其他后端上使用此参数将引发错误。

参数:

*expr¶ –

可选的列表达式。如果存在，PostgreSQL 方言将呈现一个 DISTINCT ON (<expressions>) 结构。在其他后端上，将发出弃用警告和/或 CompileError。

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

method sqlalchemy.sql.expression.Select.except_(*other: _SelectStatementForCompoundArgument) → CompoundSelect¶

返回此 select() 结构与作为位置参数提供的给定可选择的 SQL EXCEPT。

参数:

*other¶ –

用于创建 UNION 的一个或多个元素。

Changed in version 1.4.28: 现在接受多个元素。

method sqlalchemy.sql.expression.Select.except_all(*other: _SelectStatementForCompoundArgument) → CompoundSelect¶

返回此 select() 结构与作为位置参数提供的给定可选择的 SQL EXCEPT ALL。

参数:

*other¶ –

用于创建 UNION 的一个或多个元素。

Changed in version 1.4.28: 现在接受多个元素。

method sqlalchemy.sql.expression.Select.execution_options(**kw: Any) → Self¶

继承自 Executable.execution_options() 方法的 Executable

为语句设置在执行期间生效的非 SQL 选项。

执行选项可以在许多范围内设置，包括每个语句、每个连接或每个执行，使用诸如 Connection.execution_options() 和接受选项字典的参数，例如 Connection.execute.execution_options 和 Session.execute.execution_options。

执行选项的主要特征（与其他类型的选项不同，例如 ORM 加载器选项）是 **执行选项从不影响查询的编译 SQL，而仅影响如何调用 SQL 语句本身或如何获取结果**。也就是说，执行选项不是 SQL 编译所容纳的部分，也不被视为语句的缓存状态的一部分。

Executable.execution_options() 方法是生成式的，就像应用于 Engine 和 Query 对象的方法一样，这意味着当调用该方法时，将返回对象的副本，该副本将给定的参数应用于该新副本，但保留原始副本不变

statement = select(table.c.x, table.c.y)
new_statement = statement.execution_options(my_option=True)

这种行为的一个例外是 Connection 对象，其中 Connection.execution_options() 方法显式地 **不是** 生成式。

传递给 Executable.execution_options() 和其他相关方法以及参数字典的选项类型包括 SQLAlchemy Core 或 ORM 显式使用的参数，以及 SQLAlchemy 未定义的任意关键字参数，这意味着这些方法和/或参数字典可用于与自定义代码交互的用户定义参数，这些参数可以通过诸如 Executable.get_execution_options() 和 Connection.get_execution_options() 之类的方法访问，或在使用专用 execution_options 事件参数（如 ConnectionEvents.before_execute.execution_options 或 ORMExecuteState.execution_options）的选定事件钩子中，例如

from sqlalchemy import event

@event.listens_for(some_engine, "before_execute")
def _process_opt(conn, statement, multiparams, params, execution_options):
    "run a SQL function before invoking a statement"

    if execution_options.get("do_special_thing", False):
        conn.exec_driver_sql("run_special_function()")

在 SQLAlchemy 显式识别的选项范围内，大多数选项适用于特定类别的对象，而其他选项则不适用。最常见的执行选项包括

Connection.execution_options.isolation_level - 通过 Engine 设置连接或连接类的隔离级别。此选项仅被 Connection 或 Engine 接受。
Connection.execution_options.stream_results - 指示结果应使用服务器端游标获取；此选项被 Connection、Connection.execute.execution_options 参数（在 Connection.execute() 上）以及 Executable.execution_options() （在 SQL 语句对象上）以及 ORM 结构（如 Session.execute()）接受。
Connection.execution_options.compiled_cache - 指示一个字典，该字典将用作 SQL 编译缓存，用于 Connection 或 Engine，以及 ORM 方法（如 Session.execute()）。可以作为 None 传递以禁用语句的缓存。此选项不被 Executable.execution_options() 接受，因为在语句对象中携带编译缓存是不明智的。
Connection.execution_options.schema_translate_map - 架构转换映射特性使用的架构名称映射，被 Connection、Engine、Executable 以及 ORM 结构（如 Session.execute()）接受。

另请参阅

ORM 执行选项 - 所有 ORM 特定执行选项的文档

method sqlalchemy.sql.expression.Select.exists() → Exists¶

继承自 SelectBase.exists() 方法 SelectBase

返回此可选择项的 Exists 表示形式，可以用作列表达式。

返回的对象是 Exists 的实例。

另请参阅

EXISTS 子查询 - 在 2.0 风格教程中。

版本 1.4 中的新功能。

attribute sqlalchemy.sql.expression.Select.exported_columns¶

继承自 SelectBase.exported_columns 属性 SelectBase

一个 ColumnCollection，它代表此 Selectable 的“导出”列，不包括 TextClause 结构。

一个 SelectBase 对象的“导出”列与 SelectBase.selected_columns 集合相同。

版本 1.4 中的新功能。

另请参阅

method sqlalchemy.sql.expression.Select.fetch(count: _LimitOffsetType, with_ties: bool = False, percent: bool = False) → Self¶

继承自 GenerativeSelect.fetch() 方法 GenerativeSelect

返回一个新的可选择项，其中应用了给定的 FETCH FIRST 条件。

这是一个数值，通常呈现为 FETCH {FIRST | NEXT} [ count ] {ROW | ROWS} {ONLY | WITH TIES} 表达式，在结果选择中。此功能目前针对 Oracle、PostgreSQL、MSSQL 实现。

使用 GenerativeSelect.offset() 指定偏移量。

注意

GenerativeSelect.fetch() 方法将替换使用 GenerativeSelect.limit() 应用的任何子句。

版本 1.4 中的新功能。

参数:

count¶ – 一个整数 COUNT 参数，或提供整数结果的 SQL 表达式。当 percent=True 时，这将表示要返回的行数的百分比，而不是绝对值。传递 None 以将其重置。
with_ties¶ – 当 True 时，将使用 WITH TIES 选项返回根据 ORDER BY 子句在结果集中排在最后的所有其他行。在这种情况下，ORDER BY 可能是强制性的。默认值为 False
percent¶ – 当 True 时，count 表示要返回的已选择行总数的百分比。默认值为 False

另请参阅

Select.columns_clause_froms

method sqlalchemy.sql.expression.Select.filter(*criteria: _ColumnExpressionArgument[bool]) → Self¶: Select.where() 方法的同义词。

method sqlalchemy.sql.expression.Select.filter_by(**kwargs: Any) → Self¶: 将给定的过滤条件作为 WHERE 子句应用于此 select。

method sqlalchemy.sql.expression.Select.from_statement(statement: ReturnsRowsRole) → ExecutableReturnsRows¶

将此 Select 将选择的列应用到另一个语句。

此操作是特定于插件的，如果此 Select 没有从启用插件的实体中选择，它将引发不支持的异常。

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

另请参阅

从文本语句获取 ORM 结果 - ORM 查询指南中的用法示例

attribute sqlalchemy.sql.expression.Select.froms¶: 返回 FromClause 元素的显示列表。

从版本 1.4.23 开始弃用：Select.froms 属性已移至 Select.get_final_froms() 方法。

method sqlalchemy.sql.expression.Select.get_children(**kw: Any) → Iterable[ClauseElement]¶

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

这用于访问遍历。

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

method sqlalchemy.sql.expression.Select.get_execution_options() → _ExecuteOptions¶: 继承自 Executable.get_execution_options() 方法 Executable

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

版本 1.3 中新增。

另请参阅

Executable.execution_options()

method sqlalchemy.sql.expression.Select.get_final_froms() → Sequence[FromClause]¶

计算最终显示的 FromClause 元素列表。

此方法将执行确定将在生成的 SELECT 语句中显示的 FROM 元素所需的完整计算，包括使用 JOIN 对象隐藏单个表，以及针对 ORM 用例的完整计算，包括预加载子句。

对于 ORM 使用，此访问器返回 FROM 对象的编译后列表；此集合将包含预加载的表和连接等元素。这些对象不会启用 ORM 并且不能作为 Select.select_froms() 集合的替代；此外，对于启用了 ORM 的语句，此方法的性能不佳，因为它将导致完整的 ORM 构造过程。

要检索由传递给 Select 的“列”集合隐含的 FROM 列表，请使用 Select.columns_clause_froms 访问器。

要从一组替代列中选择，同时保持 FROM 列表，请使用 Select.with_only_columns() 方法并传递 Select.with_only_columns.maintain_column_froms 参数。

New in version 1.4.23: - Select.get_final_froms() 方法替换了之前已弃用的 Select.froms 访问器。

另请参阅

method sqlalchemy.sql.expression.Select.get_label_style() → SelectLabelStyle¶: 继承自 GenerativeSelect.get_label_style() 方法 GenerativeSelect

检索当前标签样式。

版本 1.4 中的新功能。

method sqlalchemy.sql.expression.Select.group_by(_GenerativeSelect__first: Literal[None, _NoArg.NO_ARG] | _ColumnExpressionOrStrLabelArgument[Any] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any]) → Self¶

继承自 GenerativeSelect.group_by() 方法 GenerativeSelect

返回一个新的可选择对象，其中应用了给定的 GROUP BY 条件列表。

可以通过传递 None 来抑制所有现有的 GROUP BY 设置。

例如。

stmt = select(table.c.name, func.max(table.c.stat)).\
group_by(table.c.name)

参数:: *clauses¶ – 一系列 ColumnElement 结构，它们将用于生成 GROUP BY 子句。

另请参阅

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

method sqlalchemy.sql.expression.Select.having(*having: _ColumnExpressionArgument[bool]) → Self¶: 返回一个新的 select() 结构，其中给定的表达式被添加到其 HAVING 子句中，如果存在，则通过 AND 连接到现有子句。

attribute sqlalchemy.sql.expression.Select.inherit_cache: bool | None = None¶

继承自 HasCacheKey.inherit_cache 属性的 HasCacheKey

指示此 HasCacheKey 实例是否应使用其直接父类使用的缓存键生成方案。

该属性默认为 None，这表明构造尚未考虑其是否适合参与缓存；这在功能上等同于将值设置为 False，只是还会发出警告。

如果与对象对应的 SQL 不会根据此类本身的属性（而非其父类）而发生变化，则可以在特定类上将此标志设置为 True。

另请参阅

为自定义构造启用缓存支持 - 为第三方或用户定义的 SQL 构造设置 HasCacheKey.inherit_cache 属性的一般指南。

attribute sqlalchemy.sql.expression.Select.inner_columns¶

所有 ColumnElement 表达式的迭代器，这些表达式将被渲染到生成的 SELECT 语句的列子句中。

此方法从 1.4 开始已过时，并被 Select.exported_columns 集合取代。

method sqlalchemy.sql.expression.Select.intersect(*other: _SelectStatementForCompoundArgument) → CompoundSelect¶

返回此 select() 结构与作为位置参数提供的给定可选择项的 SQL INTERSECT。

参数:

*other¶ –
用于创建 UNION 的一个或多个元素。

Changed in version 1.4.28: 现在接受多个元素。
**kwargs¶ – 关键字参数被转发到为新创建的 CompoundSelect 对象的构造函数。

method sqlalchemy.sql.expression.Select.intersect_all(*other: _SelectStatementForCompoundArgument) → CompoundSelect¶

返回此 select() 结构与作为位置参数提供的给定可选择项的 SQL INTERSECT ALL。

参数:

*other¶ –
用于创建 UNION 的一个或多个元素。

Changed in version 1.4.28: 现在接受多个元素。
**kwargs¶ – 关键字参数被转发到为新创建的 CompoundSelect 对象的构造函数。

method sqlalchemy.sql.expression.Select.is_derived_from(fromclause: FromClause | None) → bool¶

如果此 ReturnsRows ‘派生’ 自给定的 FromClause，则返回 True。

例如，表的别名将从该表派生。

方法 sqlalchemy.sql.expression.Select.join(target: _JoinTargetArgument, onclause: _OnClauseArgument | None = None, *, isouter: bool = False, full: bool = False) → Self¶

对该 Select 对象的标准进行 SQL JOIN 操作并生成性地应用，返回新生成的 Select。

例如：

stmt = select(user_table).join(address_table, user_table.c.id == address_table.c.user_id)

上面的语句生成的 SQL 类似于

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

在版本 1.4 中更改: Select.join() 现在会在现有的 SELECT 语句的 FROM 子句内的 FromClause 源和给定的目标 FromClause 之间创建一个 Join 对象，然后将这个 Join 添加到新生成的 SELECT 语句的 FROM 子句中。这与 1.3 中的行为完全不同，1.3 中会创建一个整个 Select 的子查询，然后将该子查询与目标进行连接。

这是一个 **向后不兼容的更改**，因为以前的行为基本上毫无用处，产生了大多数数据库都会拒绝的未命名子查询。新行为是根据 ORM 中非常成功的 Query.join() 方法建模的，目的是为了支持使用具有 Session 的 Select 对象来实现 Query 的功能。

有关此更改的说明，请参阅 select().join() 和 outerjoin() 将 JOIN 条件添加到当前查询，而不是创建子查询。

参数:

target¶ – 要连接到的目标表
onclause¶ – JOIN 的 ON 子句。如果省略，则会根据两个表之间的 ForeignKey 链接自动生成 ON 子句，如果可以明确确定，否则会引发错误。
isouter¶ – 如果为 True，则生成 LEFT OUTER JOIN。与 Select.outerjoin() 相同。
full¶ – 如果为 True，则生成 FULL OUTER JOIN。

另请参阅

显式 FROM 子句和 JOIN - 在 SQLAlchemy 统一教程中

联接 - 在 ORM 查询指南中

Select.join_from()

Select.outerjoin()

方法 sqlalchemy.sql.expression.Select.join_from(from_: _FromClauseArgument, target: _JoinTargetArgument, onclause: _OnClauseArgument | None = None, *, isouter: bool = False, full: bool = False) → Self¶

对该 Select 对象的标准进行 SQL JOIN 操作并生成性地应用，返回新生成的 Select。

例如：

stmt = select(user_table, address_table).join_from(
    user_table, address_table, user_table.c.id == address_table.c.user_id
)

上面的语句生成的 SQL 类似于

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

版本 1.4 中的新功能。

参数:

from_¶ – JOIN 的左侧，将在 FROM 子句中呈现，大致等效于使用 Select.select_from() 方法。
target¶ – 要连接到的目标表
onclause¶ – JOIN 的 ON 子句。
isouter¶ – 如果为 True，则生成 LEFT OUTER JOIN。与 Select.outerjoin() 相同。
full¶ – 如果为 True，则生成 FULL OUTER JOIN。

另请参阅

显式 FROM 子句和 JOIN - 在 SQLAlchemy 统一教程中

联接 - 在 ORM 查询指南中

Select.join()

方法 sqlalchemy.sql.expression.Select.label(name: str | None) → Label[Any]¶: 继承自 SelectBase.label() 方法 SelectBase

返回此可选择对象的 ‘标量’ 表示形式，嵌入为带有标签的子查询。

另请参阅

SelectBase.scalar_subquery().

方法 sqlalchemy.sql.expression.Select.lateral(name: str | None = None) → LateralFromClause¶

继承自 SelectBase.lateral() 方法 SelectBase

返回此 Selectable 的 LATERAL 别名。

返回值是 Lateral 结构，它也由顶层 lateral() 函数提供。

另请参阅

LATERAL 关联 - 用法概述。

method sqlalchemy.sql.expression.Select.limit(limit: _LimitOffsetType) → Self¶

继承自 GenerativeSelect.limit() 方法 GenerativeSelect

返回一个新的可选择对象，其中应用了给定的 LIMIT 条件。

这是一个数值，通常在结果选择中呈现为 LIMIT 表达式。不支持 LIMIT 的后端将尝试提供类似的功能。

注意

GenerativeSelect.limit() 方法将替换使用 GenerativeSelect.fetch() 应用的任何子句。

参数:: limit¶ – 整数 LIMIT 参数，或提供整数结果的 SQL 表达式。传递 None 以重置它。

另请参阅

method sqlalchemy.sql.expression.Select.offset(offset: _LimitOffsetType) → Self¶

继承自 GenerativeSelect.offset() 方法 GenerativeSelect

返回一个新的可选择对象，应用了给定的偏移量准则。

这是一个数值，通常在生成的 SELECT 中呈现为 OFFSET 表达式。不支持 OFFSET 的后端会尝试提供类似的功能。

参数:: offset¶ – 整数 OFFSET 参数，或提供整数结果的 SQL 表达式。传递 None 以重置它。

另请参阅

method sqlalchemy.sql.expression.Select.options(*options: ExecutableOption) → Self¶

继承自 Executable.options() 方法 Executable

将选项应用于此语句。

一般来说，选项是任何可以被 SQL 编译器用于语句的 Python 对象。这些选项可以被特定方言或特定类型的编译器使用。

最常见的选项是 ORM 级别的选项，它们将“急切加载”和其他加载行为应用于 ORM 查询。但是，理论上选项可以用于许多其他目的。

有关特定类型语句的特定选项的信息，请参阅这些选项对象的文档。

在版本 1.4 中变更: - 向 Core 语句对象添加了 Executable.options()，以实现统一的 Core / ORM 查询功能。

另请参阅

列加载选项 - 指的是特定于 ORM 查询使用的选项

使用加载器选项的关联加载 - 指的是特定于 ORM 查询使用的选项

method sqlalchemy.sql.expression.Select.order_by(_GenerativeSelect__first: Literal[None, _NoArg.NO_ARG] | _ColumnExpressionOrStrLabelArgument[Any] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any]) → Self¶

继承自 GenerativeSelect.order_by() 方法 GenerativeSelect

返回一个新的可选择对象，应用了给定的 ORDER BY 准则列表。

例如。

stmt = select(table).order_by(table.c.id, table.c.name)

多次调用此方法等效于一次调用它，并将所有子句连接在一起。通过传递 None 本身可以取消所有现有的 ORDER BY 准则。然后可以通过再次调用 Query.order_by() 添加新的 ORDER BY 准则，例如：

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

参数:: *clauses¶ – 一系列 ColumnElement 构造，用于生成 ORDER BY 子句。

另请参阅

ORDER BY - 在 SQLAlchemy 统一教程中

method sqlalchemy.sql.expression.Select.outerjoin(target: _JoinTargetArgument, onclause: _OnClauseArgument | None = None, *, full: bool = False) → Self¶

创建左外连接。

参数与 Select.join() 相同。

在版本 1.4 中更改： Select.outerjoin() 现在在现有 SELECT 的 FROM 子句中的 FromClause 源和给定的目标 FromClause 之间创建 Join 对象，然后将这个 Join 添加到新生成的 SELECT 语句的 FROM 子句中。这与 1.3 中的行为完全不同，1.3 中会创建一个整个 Select 的子查询，然后将该子查询连接到目标。

这是一个 **向后不兼容的更改**，因为以前的行为基本上毫无用处，产生了大多数数据库都会拒绝的未命名子查询。新行为是根据 ORM 中非常成功的 Query.join() 方法建模的，目的是为了支持使用具有 Session 的 Select 对象来实现 Query 的功能。

有关此更改的说明，请参阅 select().join() 和 outerjoin() 将 JOIN 条件添加到当前查询，而不是创建子查询。

另请参阅

显式 FROM 子句和 JOIN - 在 SQLAlchemy 统一教程中

联接 - 在 ORM 查询指南中

Select.join()

method sqlalchemy.sql.expression.Select.outerjoin_from(from_: _FromClauseArgument, target: _JoinTargetArgument, onclause: _OnClauseArgument | None = None, *, full: bool = False) → Self¶

对这个 Select 对象的标准创建 SQL LEFT OUTER JOIN 并以生成方式应用，返回新产生的 Select。

用法与 Select.join_from() 相同。

method sqlalchemy.sql.expression.Select.prefix_with(*prefixes: _TextCoercedExpressionArgument[Any], dialect: str = '*') → Self¶

从 HasPrefixes.prefix_with() 方法继承 HasPrefixes

Add one or more expressions following the statement keyword, i.e. SELECT, INSERT, UPDATE, or DELETE. Generative.

This is used to support backend-specific prefix keywords such as those provided by MySQL.

例如：

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

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

Multiple prefixes can be specified by multiple calls to HasPrefixes.prefix_with().

参数:

*prefixes¶ – 文本或 ClauseElement 构造，将在 INSERT、UPDATE 或 DELETE 关键字后呈现。
dialect¶ – 可选的字符串方言名称，这将限制仅在该方言中呈现该前缀。

method sqlalchemy.sql.expression.Select.reduce_columns(only_synonyms: bool = True) → Select¶

返回一个新的 select() 构造，其中从列子句中删除了冗余命名的、等效值的列。

这里的“冗余”是指两列，其中一列基于外键引用另一列，或者通过语句的 WHERE 子句中的简单相等比较引用另一列。此方法的主要目的是自动构建一个具有所有唯一命名列的 select 语句，而无需像 Select.set_label_style() 那样使用表限定标签。

当基于外键省略列时，被引用的列是保留的列。当基于 WHERE 等效性省略列时，列子句中的第一列是保留的列。

参数:: only_synonyms¶ – 当为 True 时，将列的删除限制为那些与等效列具有相同名称的列。否则，将删除所有等效于另一列的列。

方法 sqlalchemy.sql.expression.Select.replace_selectable(old: FromClause, alias: Alias) → Self¶: 继承自 Selectable.replace_selectable() 方法 Selectable

将所有出现的 FromClause ‘old’ 替换为给定的 Alias 对象，返回此 FromClause 的副本。

自版本 1.4 起弃用: The Selectable.replace_selectable() 方法已弃用，将在未来的版本中移除。类似的功能可以通过 sqlalchemy.sql.visitors 模块获得。

方法 sqlalchemy.sql.expression.Select.scalar_subquery() → ScalarSelect[Any]¶

继承自 SelectBase.scalar_subquery() 方法 SelectBase

返回此可选择对象的“标量”表示，它可以用作列表达式。

返回的对象是 ScalarSelect 的实例。

通常，在它的列子句中只有一个列的 SELECT 语句有资格用作标量表达式。然后，标量子查询可以在封闭的 SELECT 的 WHERE 子句或列子句中使用。

请注意，标量子查询不同于使用 SelectBase.subquery() 方法生成的 FROM 级子查询。

另请参阅

标量和关联子查询 - 在 2.0 教程中

方法 sqlalchemy.sql.expression.Select.select(*arg: Any, **kw: Any) → Select¶: 继承自 SelectBase.select() 方法 SelectBase

从版本 1.4 开始弃用： SelectBase.select() 方法已弃用，将在未来版本中删除；此方法隐式创建子查询，应明确使用。请先调用 SelectBase.subquery() 以创建子查询，然后才能对其进行选择。

方法 sqlalchemy.sql.expression.Select.select_from(*froms: _FromClauseArgument) → Self¶

返回一个新的 select() 结构，其中给定的 FROM 表达式(s) 已合并到其 FROM 对象列表中。

例如：

table1 = table('t1', column('a'))
table2 = table('t2', column('b'))
s = select(table1.c.a).\
    select_from(
        table1.join(table2, table1.c.a==table2.c.b)
    )

“from” 列表是每个元素身份的唯一集合，因此添加已存在的 Table 或其他可选择项将不会产生任何效果。传递引用已存在的 Table 或其他可选择项的 Join 将隐藏该可选择项作为渲染的 FROM 列表中的单个元素，而是将其渲染为 JOIN 子句。

虽然 Select.select_from() 的典型用途是使用联接替换默认的派生 FROM 子句，但如果 FROM 子句无法完全从列子句中派生出来，也可以使用单独的表格元素多次调用它。

select(func.count('*')).select_from(table1)

属性 sqlalchemy.sql.expression.Select.selected_columns¶

一个 ColumnCollection 表示此 SELECT 语句或类似构造在结果集中返回的列，不包括 TextClause 构造。

此集合不同于 FromClause.columns 集合，因为此集合中的列不能直接嵌套在另一个 SELECT 语句中；必须先应用子查询，这样才能提供 SQL 所需的括号。

对于 select() 结构，此处的集合正是将在“SELECT”语句中渲染的内容，并且 ColumnElement 对象直接以它们被提供的方式出现，例如：

col1 = column('q', Integer)
col2 = column('p', Integer)
stmt = select(col1, col2)

在上面，stmt.selected_columns 将是一个包含 col1 和 col2 对象的集合。对于针对 Table 或其他 FromClause 的语句，该集合将使用 ColumnElement 对象，这些对象位于来自元素的 FromClause.c 集合中。

Select.selected_columns 集合的一个用例是允许在添加其他条件时引用现有列，例如：

def filter_on_id(my_select, id):
    return my_select.where(my_select.selected_columns['id'] == id)

stmt = select(MyModel)

# adds "WHERE id=:param" to the statement
stmt = filter_on_id(stmt, 42)

注意

Select.selected_columns 集合不包括使用 text() 结构在列子句中建立的表达式；这些表达式将从集合中静默省略。要在 Select 结构中使用纯文本列表达式，请使用 literal_column() 结构。

版本 1.4 中的新功能。

方法 sqlalchemy.sql.expression.Select.self_group(against: OperatorType | None = None) → SelectStatementGrouping | Self¶

根据 ClauseElement 规范返回“分组”结构。

这会生成一个可以嵌入表达式的元素。请注意，在构造表达式时，此方法会根据需要自动调用，不需要显式使用。

方法 sqlalchemy.sql.expression.Select.set_label_style(style: SelectLabelStyle) → Self¶

从 GenerativeSelect.set_label_style() 方法继承而来，该方法属于 GenerativeSelect。

返回一个具有指定标签样式的新可选。

有三种可用的“标签样式”： SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY、 SelectLabelStyle.LABEL_STYLE_TABLENAME_PLUS_COL 和 SelectLabelStyle.LABEL_STYLE_NONE。默认样式为 SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY.

在现代 SQLAlchemy 中，通常不需要更改标签样式，因为通过使用 ColumnElement.label() 方法，每个表达式标签都可以更有效地使用。在过去的版本中， LABEL_STYLE_TABLENAME_PLUS_COL 用于区分来自不同表、别名或子查询的同名列；较新的 LABEL_STYLE_DISAMBIGUATE_ONLY 现在只对与现有名称冲突的名称应用标签，以便这种标签的影响最小。

消除歧义的基本原理主要是使所有列表达式都可以在创建子查询时从给定的 FromClause.c 集合中获取。

版本 1.4 中的新功能： - GenerativeSelect.set_label_style() 方法取代了以前 .apply_labels()、 .with_labels() 和 use_labels=True 方法和/或参数的组合。

另请参阅

LABEL_STYLE_DISAMBIGUATE_ONLY

LABEL_STYLE_TABLENAME_PLUS_COL

LABEL_STYLE_NONE

LABEL_STYLE_DEFAULT

方法 sqlalchemy.sql.expression.Select.slice(start: int, stop: int) → Self¶

继承自 GenerativeSelect.slice() 方法 GenerativeSelect

根据切片对该语句应用 LIMIT / OFFSET。

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

例如，

stmt = select(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)

注意

The GenerativeSelect.slice() method will replace any clause applied with GenerativeSelect.fetch().

New in version 1.4: Added the GenerativeSelect.slice() method generalized from the ORM.

另请参阅

Select.with_statement_hint()

方法 sqlalchemy.sql.expression.Select.subquery(name: str | None = None) → Subquery¶

inherited from the SelectBase.subquery() method of SelectBase

返回此SelectBase 的子查询。

从 SQL 的角度来看，子查询是一个带括号的、命名的构造，可以放在另一个 SELECT 语句的 FROM 子句中。

给定一个 SELECT 语句，例如

stmt = select(table.c.id, table.c.name)

上面的语句可能看起来像

SELECT table.id, table.name FROM table

子查询形式本身以相同的方式呈现，但是当嵌入到另一个 SELECT 语句的 FROM 子句中时，它成为一个命名的子元素

subq = stmt.subquery()
new_stmt = select(subq)

上面的语句呈现为

SELECT anon_1.id, anon_1.name
FROM (SELECT table.id, table.name FROM table) AS anon_1

从历史上看，SelectBase.subquery() 等效于在 FROM 对象上调用 FromClause.alias() 方法；但是，由于 SelectBase 对象不是直接的 FROM 对象，因此 SelectBase.subquery() 方法提供了更清晰的语义。

版本 1.4 中的新功能。

方法 sqlalchemy.sql.expression.Select.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¶ – 可选的字符串方言名称，仅在该方言下才会呈现此后缀。

方法 sqlalchemy.sql.expression.Select.union(*other: _SelectStatementForCompoundArgument) → CompoundSelect¶

返回此 select() 构造与作为位置参数提供的给定可选择内容的 SQL UNION。

参数:

*other¶ –
用于创建 UNION 的一个或多个元素。

Changed in version 1.4.28: 现在接受多个元素。
**kwargs¶ – 关键字参数将转发到新创建的 CompoundSelect 对象的构造函数。

方法 sqlalchemy.sql.expression.Select.union_all(*other: _SelectStatementForCompoundArgument) → CompoundSelect¶

返回此 select() 构造与作为位置参数提供的给定可选择内容的 SQL UNION ALL。

参数:

*other¶ –
用于创建 UNION 的一个或多个元素。

Changed in version 1.4.28: 现在接受多个元素。
**kwargs¶ – 关键字参数将转发到新创建的 CompoundSelect 对象的构造函数。

方法 sqlalchemy.sql.expression.Select.where(*whereclause: _ColumnExpressionArgument[bool]) → Self¶: 返回一个新的 select() 构造，将给定的表达式添加到其 WHERE 子句，如果存在，则通过 AND 连接到现有子句。

属性 sqlalchemy.sql.expression.Select.whereclause¶

返回此 Select 语句的完整 WHERE 子句。

这将当前的 WHERE 条件集合组装成一个单个 BooleanClauseList 构造。

版本 1.4 中的新功能。

方法 sqlalchemy.sql.expression.Select.with_for_update(*, nowait: bool = False, read: bool = False, of: _ForUpdateOfArgument | None = None, skip_locked: bool = False, key_share: bool = False) → Self¶

inherited from the GenerativeSelect.with_for_update() method of GenerativeSelect

为这个 GenerativeSelect 指定一个 FOR UPDATE 子句。

例如：

stmt = select(table).with_for_update(nowait=True)

在 PostgreSQL 或 Oracle 等数据库上，上面的语句将呈现一个类似于

SELECT table.a, table.b FROM table FOR UPDATE NOWAIT

在其他后端，nowait 选项将被忽略，而是会生成

SELECT table.a, table.b FROM table FOR UPDATE

当不带任何参数调用时，该语句将用后缀 FOR UPDATE 呈现。然后可以提供其他参数，这些参数允许使用常见的数据库特定变体。

参数:

nowait¶ – 布尔值；将在 Oracle 和 PostgreSQL 方言上呈现 FOR UPDATE NOWAIT。
read¶ – 布尔值；将在 MySQL 上呈现 LOCK IN SHARE MODE，在 PostgreSQL 上呈现 FOR SHARE。在 PostgreSQL 上，当与 nowait 结合使用时，将呈现 FOR SHARE NOWAIT。
of¶ – SQL 表达式或 SQL 表达式元素列表，（通常是 Column 对象或兼容表达式，对于某些后端也可以是表表达式）这将呈现为 FOR UPDATE OF 子句；由 PostgreSQL、Oracle、某些 MySQL 版本以及可能的其他版本支持。可能会根据后端呈现为表或列。
skip_locked¶ – 布尔值，将在 Oracle 和 PostgreSQL 方言上呈现 FOR UPDATE SKIP LOCKED 或如果也指定了 read=True，则呈现 FOR SHARE SKIP LOCKED。
key_share¶ – 布尔值，将在 PostgreSQL 方言上呈现 FOR NO KEY UPDATE，或者如果与 read=True 结合使用，将呈现 FOR KEY SHARE。

方法 sqlalchemy.sql.expression.Select.with_hint(selectable: _FromClauseArgument, text: str, dialect_name: str = '*') → Self¶

继承自 HasHints.with_hint() 方法 HasHints

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

提示

The Select.with_hint() 方法添加针对单个表的提示，在特定于方言的位置。

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

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

将呈现 SQL 为

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

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

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

另请参阅

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

方法 sqlalchemy.sql.expression.Select.with_only_columns(*entities: _ColumnsClauseArgument[Any], maintain_column_froms: bool = False, **_Select__kw: Any) → Select[Any]¶

返回一个新的 select() 构造，其列子句被替换为给定的实体。

默认情况下，此方法等效于使用给定实体调用原始 select()。

s = select(table1.c.a, table1.c.b)
s = s.with_only_columns(table1.c.b)

应该与以下完全相同

s = select(table1.c.b)

在此操作模式下，Select.with_only_columns() 还会动态地改变语句的 FROM 子句，如果它没有明确声明。要保持现有的一组 FROM，包括当前列子句隐含的那些，请添加 Select.with_only_columns.maintain_column_froms 参数

s = select(table1.c.a, table2.c.b)
s = s.with_only_columns(table1.c.a, maintain_column_froms=True)

上面的参数将列集合中的有效 FROM 传输到 Select.select_from() 方法，就好像以下被调用一样

s = select(table1.c.a, table2.c.b)
s = s.select_from(table1, table2).with_only_columns(table1.c.a)

The Select.with_only_columns.maintain_column_froms 参数利用了 Select.columns_clause_froms 集合，并执行与以下等效的操作

s = select(table1.c.a, table2.c.b)
s = s.select_from(*s.columns_clause_froms).with_only_columns(table1.c.a)

参数:

*entities¶ – 要使用的列表达式。
maintain_column_froms¶ –
布尔参数，它将确保当前列子句隐含的 FROM 列表将首先传输到 Select.select_from() 方法。

版本 1.4.23 中的新增内容。

方法 sqlalchemy.sql.expression.Select.with_statement_hint(text: str, dialect_name: str = '*') → Self¶

继承自 HasHints.with_statement_hint() 方法 HasHints

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

提示

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

类 sqlalchemy.sql.expression.Selectable¶

将一个类标记为可选择。

成员

corresponding_column(), exported_columns, inherit_cache, is_derived_from(), lateral(), replace_selectable()

类签名

类 sqlalchemy.sql.expression.Selectable (sqlalchemy.sql.expression.ReturnsRows)

方法 sqlalchemy.sql.expression.Selectable.corresponding_column(column: KeyedColumnElement[Any], require_embedded: bool = False) → KeyedColumnElement[Any] | None¶

给定一个 ColumnElement，返回来自此 Selectable 的 ColumnElement 对象，该对象通过公共祖先列对应于该原始 ColumnElement。

参数:

column¶ – 目标 ColumnElement 要匹配。
require_embedded¶ – 仅为给定 ColumnElement 返回相应列，如果给定 ColumnElement 实际上存在于此 Selectable 的子元素中。通常，如果该列与该 Selectable 的一个导出列共享一个公共祖先，则该列将匹配。

另请参阅

Selectable.exported_columns - 用于该操作的 ColumnCollection。

ColumnCollection.corresponding_column() - 实现方法。

属性 sqlalchemy.sql.expression.Selectable.exported_columns¶

继承自 ReturnsRows.exported_columns 的属性 ReturnsRows

一个 ColumnCollection，它代表此 ReturnsRows 的“导出”列。

“导出”列表示此 SQL 结构呈现的 ColumnElement 表达式的集合。主要类型包括 FROM 子句的“FROM 子句列”，例如表、联接或子查询，以及“SELECTed 列”，即 SELECT 语句“列子句”中的列，以及 DML 语句中的 RETURNING 列。

版本 1.4 中的新功能。

另请参阅

属性 sqlalchemy.sql.expression.Selectable.inherit_cache: bool | None = None¶

继承自 HasCacheKey.inherit_cache 属性的 HasCacheKey

指示此 HasCacheKey 实例是否应使用其直接父类使用的缓存键生成方案。

该属性默认为 None，这表明构造尚未考虑其是否适合参与缓存；这在功能上等同于将值设置为 False，只是还会发出警告。

如果与对象对应的 SQL 不会根据此类本身的属性（而非其父类）而发生变化，则可以在特定类上将此标志设置为 True。

另请参阅

为自定义构造启用缓存支持 - 为第三方或用户定义的 SQL 构造设置 HasCacheKey.inherit_cache 属性的一般指南。

方法 sqlalchemy.sql.expression.Selectable.is_derived_from(fromclause: FromClause | None) → bool¶

继承自 ReturnsRows.is_derived_from() 的方法 ReturnsRows

如果此 ReturnsRows ‘派生’ 自给定的 FromClause，则返回 True。

例如，表的别名将从该表派生。

方法 sqlalchemy.sql.expression.Selectable.lateral(name: str | None = None) → LateralFromClause¶

返回此 Selectable 的 LATERAL 别名。

返回值是 Lateral 结构，它也由顶层 lateral() 函数提供。

另请参阅

LATERAL 关联 - 用法概述。

方法 sqlalchemy.sql.expression.Selectable.replace_selectable(old: FromClause, alias: Alias) → Self¶: 将所有出现的 FromClause ‘old’ 替换为给定的 Alias 对象，返回此 FromClause 的副本。

自版本 1.4 起弃用: The Selectable.replace_selectable() 方法已弃用，将在未来的版本中移除。类似的功能可以通过 sqlalchemy.sql.visitors 模块获得。

类 sqlalchemy.sql.expression.SelectBase¶

SELECT 语句的基类。

这包括 Select，CompoundSelect 和 TextualSelect。

成员

add_cte()，alias()，as_scalar()，c，corresponding_column()，cte()，exists()，exported_columns，get_label_style()，inherit_cache，is_derived_from()，label()，lateral()，replace_selectable()，scalar_subquery()，select()，selected_columns，set_label_style()，subquery()

类签名

类 sqlalchemy.sql.expression.SelectBase (sqlalchemy.sql.roles.SelectStatementRole, sqlalchemy.sql.roles.DMLSelectRole, sqlalchemy.sql.roles.CompoundElementRole, sqlalchemy.sql.roles.InElementRole, sqlalchemy.sql.expression.HasCTE, sqlalchemy.sql.annotation.SupportsCloneAnnotations, sqlalchemy.sql.expression.Selectable)

方法 sqlalchemy.sql.expression.SelectBase.add_cte(*ctes: CTE, nest_here: bool = False) → Self¶

继承自 HasCTE.add_cte() 方法 HasCTE

将一个或多个 CTE 构造添加到此语句。

此方法将与给定的 CTE 构造关联父语句，以便它们将在最终语句的 WITH 子句中无条件地渲染，即使在语句或任何子选择中没有其他地方引用它们。

当设置为 True 时，可选的 HasCTE.add_cte.nest_here 参数将具有以下效果：每个给定的 CTE 将在直接与该语句一起渲染的 WITH 子句中渲染，而不是被移动到最终渲染语句的顶部，即使该语句在更大的语句中以子查询的形式渲染。

此方法有两个一般用途。一种是嵌入用于某些目的的 CTE 语句，而无需显式引用它们，例如将 INSERT 或 UPDATE 等 DML 语句作为 CTE 嵌入到可能间接从其结果中获取数据的初级语句中的用例。另一种是提供对应该在可能嵌套在更大的语句中的特定语句方面直接渲染的特定一系列 CTE 构造的精确位置的控制。

例如：

from sqlalchemy import table, column, select
t = table('t', column('c1'), column('c2'))

ins = t.insert().values({"c1": "x", "c2": "y"}).cte()

stmt = select(t).add_cte(ins)

将渲染

WITH anon_1 AS
(INSERT INTO t (c1, c2) VALUES (:param_1, :param_2))
SELECT t.c1, t.c2
FROM t

在上面，"anon_1" CTE 在 SELECT 语句中没有被引用，但是仍然完成了运行 INSERT 语句的任务。

同样在与 DML 相关的上下文中，使用 PostgreSQL Insert 构造生成 "upsert"

from sqlalchemy import table, column
from sqlalchemy.dialects.postgresql import insert

t = table("t", column("c1"), column("c2"))

delete_statement_cte = (
    t.delete().where(t.c.c1 < 1).cte("deletions")
)

insert_stmt = insert(t).values({"c1": 1, "c2": 2})
update_statement = insert_stmt.on_conflict_do_update(
    index_elements=[t.c.c1],
    set_={
        "c1": insert_stmt.excluded.c1,
        "c2": insert_stmt.excluded.c2,
    },
).add_cte(delete_statement_cte)

print(update_statement)

上面的语句渲染为

WITH deletions AS
(DELETE FROM t WHERE t.c1 < %(c1_1)s)
INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2

版本 1.4.21 中的新功能。

参数:

*ctes¶ –
零个或多个 CTE 构造。

在版本 2.0 中更改: 接受多个 CTE 实例
nest_here¶ –
如果为 True，则给定的 CTE 或 CTE 将被渲染为它们指定了 HasCTE.cte.nesting 标志为 True 时添加到此 HasCTE。假设给定的 CTE 在外部封闭语句中也没有被引用，则在给出此标志时，给定的 CTE 应该在该语句的级别进行渲染。

2.0 版中的新增功能。

另请参阅

HasCTE.cte.nesting

方法 sqlalchemy.sql.expression.SelectBase.alias(name: str | None = None, flat: bool = False) → Subquery¶

返回针对此 SelectBase 的命名子查询。

对于 SelectBase（而不是 FromClause），这将返回一个 Subquery 对象，该对象的运行方式与 Alias 对象（用于 FromClause）基本相同。

在 1.4 版中变更: The SelectBase.alias() 方法现在是 SelectBase.subquery() 方法的同义词。

方法 sqlalchemy.sql.expression.SelectBase.as_scalar() → ScalarSelect[Any]¶: 自 1.4 版起弃用: The SelectBase.as_scalar() 方法已弃用，将在未来版本中删除。请参阅 SelectBase.scalar_subquery().

属性 sqlalchemy.sql.expression.SelectBase.c¶: 自 1.4 版起弃用: The SelectBase.c 和 SelectBase.columns 属性已弃用，将在未来版本中删除；这些属性隐式地创建一个子查询，而该子查询应该是显式的。请先调用 SelectBase.subquery() 以创建一个子查询，然后该子查询包含此属性。要访问此 SELECT 对象 SELECT 的列，请使用 SelectBase.selected_columns 属性。

方法 sqlalchemy.sql.expression.SelectBase.corresponding_column(column: KeyedColumnElement[Any], require_embedded: bool = False) → KeyedColumnElement[Any] | None¶

继承自 Selectable.corresponding_column() 方法 Selectable

给定一个 ColumnElement，返回来自此 Selectable 的 ColumnElement 对象，该对象通过公共祖先列对应于该原始 ColumnElement。

参数:

column¶ – 要匹配的目标 ColumnElement。
require_embedded¶ – 仅针对给定的 ColumnElement 返回对应列，如果给定的 ColumnElement 实际上存在于此 Selectable 的子元素中。通常，如果列与该 Selectable 的导出列之一具有共同的祖先，则列将匹配。

另请参阅

Selectable.exported_columns - 用于该操作的 ColumnCollection。

ColumnCollection.corresponding_column() - 实现方法。

方法 sqlalchemy.sql.expression.SelectBase.cte(name: str | None = None, recursive: bool = False, nesting: bool = False) → CTE¶

继承自 HasCTE.cte() 方法的 HasCTE

返回一个新的 CTE 或 Common Table Expression 实例。

公共表表达式是 SQL 标准，其中 SELECT 语句可以利用与主语句一起指定的辅助语句，使用称为“WITH”的子句。还可以使用有关 UNION 的特殊语义来允许“递归”查询，其中 SELECT 语句可以利用先前已选择的行集。

CTE 也可以应用于某些数据库上的 DML 结构 UPDATE、INSERT 和 DELETE，作为 CTE 行的来源（当与 RETURNING 组合时）以及 CTE 行的使用者。

SQLAlchemy 检测 CTE 对象，这些对象与 Alias 对象类似，被视为特殊元素，传递给语句的 FROM 子句以及语句顶部的 WITH 子句。

对于特殊前缀（如 PostgreSQL 的“MATERIALIZED”和“NOT MATERIALIZED”），可以使用 CTE.prefix_with() 方法来建立这些前缀。

在版本 1.3.13 中更改: 添加了对前缀的支持。尤其是 - MATERIALIZED 和 NOT MATERIALIZED。

参数:

name¶ – 给公共表表达式命名的名称。与 FromClause.alias() 一样，名称可以保留为 None，在这种情况下，查询编译时将使用匿名符号。
recursive¶ – 如果为 True，将呈现 WITH RECURSIVE。递归公共表表达式旨在与 UNION ALL 结合使用，以便从已选择的那些行中派生行。
nesting¶ –
如果为 True，将把 CTE 呈现在引用它的语句中。对于更复杂的情况，可以使用 HasCTE.add_cte() 方法，使用 HasCTE.add_cte.nest_here 参数也可以更仔细地控制特定 CTE 的确切位置。

版本 1.4.24 中新增。

另请参阅

HasCTE.add_cte()

以下示例包括两个来自 PostgreSQL 文档的示例，位于 https://postgresql.ac.cn/docs/current/static/queries-with.html，以及其他示例。

示例 1，非递归

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
    Column('region', String),
    Column('amount', Integer),
    Column('product', String),
    Column('quantity', Integer)
)

regional_sales = select(
                    orders.c.region,
                    func.sum(orders.c.amount).label('total_sales')
                ).group_by(orders.c.region).cte("regional_sales")


top_regions = select(regional_sales.c.region).\
        where(
            regional_sales.c.total_sales >
            select(
                func.sum(regional_sales.c.total_sales) / 10
            )
        ).cte("top_regions")

statement = select(
            orders.c.region,
            orders.c.product,
            func.sum(orders.c.quantity).label("product_units"),
            func.sum(orders.c.amount).label("product_sales")
    ).where(orders.c.region.in_(
        select(top_regions.c.region)
    )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

示例 2，WITH RECURSIVE

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
    Column('part', String),
    Column('sub_part', String),
    Column('quantity', Integer),
)

included_parts = select(\
    parts.c.sub_part, parts.c.part, parts.c.quantity\
    ).\
    where(parts.c.part=='our part').\
    cte(recursive=True)


incl_alias = included_parts.alias()
parts_alias = parts.alias()
included_parts = included_parts.union_all(
    select(
        parts_alias.c.sub_part,
        parts_alias.c.part,
        parts_alias.c.quantity
    ).\
    where(parts_alias.c.part==incl_alias.c.sub_part)
)

statement = select(
            included_parts.c.sub_part,
            func.sum(included_parts.c.quantity).
              label('total_quantity')
        ).\
        group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

示例 3，使用 CTE 的 UPDATE 和 INSERT 进行 upsert

from datetime import date
from sqlalchemy import (MetaData, Table, Column, Integer,
                        Date, select, literal, and_, exists)

metadata = MetaData()

visitors = Table('visitors', metadata,
    Column('product_id', Integer, primary_key=True),
    Column('date', Date, primary_key=True),
    Column('count', Integer),
)

# add 5 visitors for the product_id == 1
product_id = 1
day = date.today()
count = 5

update_cte = (
    visitors.update()
    .where(and_(visitors.c.product_id == product_id,
                visitors.c.date == day))
    .values(count=visitors.c.count + count)
    .returning(literal(1))
    .cte('update_cte')
)

upsert = visitors.insert().from_select(
    [visitors.c.product_id, visitors.c.date, visitors.c.count],
    select(literal(product_id), literal(day), literal(count))
        .where(~exists(update_cte.select()))
)

connection.execute(upsert)

示例 4，嵌套 CTE（SQLAlchemy 1.4.24 及更高版本）

value_a = select(
    literal("root").label("n")
).cte("value_a")

# A nested CTE with the same name as the root one
value_a_nested = select(
    literal("nesting").label("n")
).cte("value_a", nesting=True)

# Nesting CTEs takes ascendency locally
# over the CTEs at a higher level
value_b = select(value_a_nested.c.n).cte("value_b")

value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))

上述查询将呈现嵌套在第一个 CTE 内的第二个 CTE，如下所示，带有内联参数

WITH
    value_a AS
        (SELECT 'root' AS n),
    value_b AS
        (WITH value_a AS
            (SELECT 'nesting' AS n)
        SELECT value_a.n AS n FROM value_a)
SELECT value_a.n AS a, value_b.n AS b
FROM value_a, value_b

可以使用 HasCTE.add_cte() 方法设置相同的 CTE（SQLAlchemy 2.0 及更高版本）

value_a = select(
    literal("root").label("n")
).cte("value_a")

# A nested CTE with the same name as the root one
value_a_nested = select(
    literal("nesting").label("n")
).cte("value_a")

# Nesting CTEs takes ascendency locally
# over the CTEs at a higher level
value_b = (
    select(value_a_nested.c.n).
    add_cte(value_a_nested, nest_here=True).
    cte("value_b")
)

value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))

示例 5，非线性 CTE（SQLAlchemy 1.4.28 及更高版本）

edge = Table(
    "edge",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("left", Integer),
    Column("right", Integer),
)

root_node = select(literal(1).label("node")).cte(
    "nodes", recursive=True
)

left_edge = select(edge.c.left).join(
    root_node, edge.c.right == root_node.c.node
)
right_edge = select(edge.c.right).join(
    root_node, edge.c.left == root_node.c.node
)

subgraph_cte = root_node.union(left_edge, right_edge)

subgraph = select(subgraph_cte)

上述查询将呈现递归 CTE 内的 2 个 UNION

WITH RECURSIVE nodes(node) AS (
        SELECT 1 AS node
    UNION
        SELECT edge."left" AS "left"
        FROM edge JOIN nodes ON edge."right" = nodes.node
    UNION
        SELECT edge."right" AS "right"
        FROM edge JOIN nodes ON edge."left" = nodes.node
)
SELECT nodes.node FROM nodes

另请参阅

Query.cte() - HasCTE.cte() 的 ORM 版本。

方法 sqlalchemy.sql.expression.SelectBase.exists() → Exists¶

返回此可选择项的 Exists 表示形式，可以用作列表达式。

返回的对象是 Exists 的实例。

另请参阅

EXISTS 子查询 - 在 2.0 风格教程中。

版本 1.4 中的新功能。

属性 sqlalchemy.sql.expression.SelectBase.exported_columns¶

一个 ColumnCollection，它代表此 Selectable 的“导出”列，不包括 TextClause 结构。

一个 SelectBase 对象的“导出”列与 SelectBase.selected_columns 集合相同。

版本 1.4 中的新功能。

另请参阅

Select.selected_columns

方法 sqlalchemy.sql.expression.SelectBase.get_label_style() → SelectLabelStyle¶

检索当前标签样式。

由子类实现。

属性 sqlalchemy.sql.expression.SelectBase.inherit_cache: bool | None = None¶

继承自 HasCacheKey.inherit_cache 属性的 HasCacheKey

指示此 HasCacheKey 实例是否应使用其直接父类使用的缓存键生成方案。

该属性默认为 None，这表明构造尚未考虑其是否适合参与缓存；这在功能上等同于将值设置为 False，只是还会发出警告。

如果与对象对应的 SQL 不会根据此类本身的属性（而非其父类）而发生变化，则可以在特定类上将此标志设置为 True。

另请参阅

为自定义构造启用缓存支持 - 为第三方或用户定义的 SQL 构造设置 HasCacheKey.inherit_cache 属性的一般指南。

方法 sqlalchemy.sql.expression.SelectBase.is_derived_from(fromclause: FromClause | None) → bool¶

继承自 ReturnsRows.is_derived_from() 的方法 ReturnsRows

如果此 ReturnsRows ‘派生’ 自给定的 FromClause，则返回 True。

例如，表的别名将从该表派生。

method sqlalchemy.sql.expression.SelectBase.label(name: str | None) → Label[Any]¶: 返回此可选择对象的 ‘标量’ 表示形式，嵌入为带有标签的子查询。

另请参阅

SelectBase.scalar_subquery().

method sqlalchemy.sql.expression.SelectBase.lateral(name: str | None = None) → LateralFromClause¶

返回此 Selectable 的 LATERAL 别名。

返回值是 Lateral 结构，它也由顶层 lateral() 函数提供。

另请参阅

LATERAL 关联 - 用法概述。

method sqlalchemy.sql.expression.SelectBase.replace_selectable(old: FromClause, alias: Alias) → Self¶: 继承自 Selectable.replace_selectable() 方法 Selectable

将所有出现的 FromClause ‘old’ 替换为给定的 Alias 对象，返回此 FromClause 的副本。

自版本 1.4 起弃用: The Selectable.replace_selectable() 方法已弃用，将在未来的版本中移除。类似的功能可以通过 sqlalchemy.sql.visitors 模块获得。

method sqlalchemy.sql.expression.SelectBase.scalar_subquery() → ScalarSelect[Any]¶

返回此可选择对象的“标量”表示，它可以用作列表达式。

返回的对象是 ScalarSelect 的实例。

通常，在它的列子句中只有一个列的 SELECT 语句有资格用作标量表达式。然后，标量子查询可以在封闭的 SELECT 的 WHERE 子句或列子句中使用。

请注意，标量子查询不同于使用 SelectBase.subquery() 方法生成的 FROM 级子查询。

另请参阅

标量和关联子查询 - 在 2.0 教程中

method sqlalchemy.sql.expression.SelectBase.select(*arg: Any, **kw: Any) → Select¶: 从版本 1.4 开始弃用： SelectBase.select() 方法已弃用，将在未来版本中删除；此方法隐式创建子查询，应明确使用。请先调用 SelectBase.subquery() 以创建子查询，然后才能对其进行选择。

attribute sqlalchemy.sql.expression.SelectBase.selected_columns¶

一个 ColumnCollection，表示此 SELECT 语句或类似构造在结果集中返回的列。

此集合不同于 FromClause.columns 集合，因为此集合中的列不能直接嵌套在另一个 SELECT 语句中；必须先应用子查询，这样才能提供 SQL 所需的括号。

注意

该 SelectBase.selected_columns 集合不包括在 columns 子句中使用 text() 构造建立的表达式；这些表达式会从集合中静默省略。要在 Select 构造中使用纯文本列表达式，请使用 literal_column() 构造。

另请参阅

版本 1.4 中的新功能。

method sqlalchemy.sql.expression.SelectBase.set_label_style(style: SelectLabelStyle) → Self¶

返回一个具有指定标签样式的新可选。

由子类实现。

method sqlalchemy.sql.expression.SelectBase.subquery(name: str | None = None) → Subquery¶

返回此SelectBase 的子查询。

从 SQL 的角度来看，子查询是一个带括号的、命名的构造，可以放在另一个 SELECT 语句的 FROM 子句中。

给定一个 SELECT 语句，例如

stmt = select(table.c.id, table.c.name)

上面的语句可能看起来像

SELECT table.id, table.name FROM table

子查询形式本身以相同的方式呈现，但是当嵌入到另一个 SELECT 语句的 FROM 子句中时，它成为一个命名的子元素

subq = stmt.subquery()
new_stmt = select(subq)

上面的语句呈现为

SELECT anon_1.id, anon_1.name
FROM (SELECT table.id, table.name FROM table) AS anon_1

从历史上看，SelectBase.subquery() 等效于在 FROM 对象上调用 FromClause.alias() 方法；但是，由于 SelectBase 对象不是直接的 FROM 对象，因此 SelectBase.subquery() 方法提供了更清晰的语义。

版本 1.4 中的新功能。

class sqlalchemy.sql.expression.Subquery¶

表示 SELECT 语句的子查询。

一个 Subquery 是通过调用 SelectBase.subquery() 方法，或者为了方便起见，调用 SelectBase.alias() 方法，在任何 SelectBase 子类（包括 Select、CompoundSelect 和 TextualSelect）上创建的。在 FROM 子句中呈现时，它代表括号内的 SELECT 语句主体，后面跟着通常的“AS <somename>” 用于定义所有“别名”对象。

该 Subquery 对象与 Alias 对象非常相似，可以用等效的方式使用。Alias 和 Subquery 之间的区别在于，Alias 始终包含一个 FromClause 对象，而 Subquery 始终包含一个 SelectBase 对象。

在版本 1.4 中添加：添加了 Subquery 类，它现在用于提供 SELECT 语句的别名版本。

成员

as_scalar(), inherit_cache

类签名

class sqlalchemy.sql.expression.Subquery (sqlalchemy.sql.expression.AliasedReturnsRows)

method sqlalchemy.sql.expression.Subquery.as_scalar() → ScalarSelect[Any]¶: 从版本 1.4 开始弃用：以前在 1.4 版之前为 Alias.as_scalar() 的 Subquery.as_scalar() 方法已弃用，将在未来版本中删除；请使用 Select.scalar_subquery() 方法来构建子查询对象之前的 select() 结构，或使用 ORM 使用 Query.scalar_subquery() 方法。

属性 sqlalchemy.sql.expression.Subquery.inherit_cache: bool | None = True¶

指示此 HasCacheKey 实例是否应使用其直接父类使用的缓存键生成方案。

该属性默认为 None，这表明构造尚未考虑其是否适合参与缓存；这在功能上等同于将值设置为 False，只是还会发出警告。

如果与对象对应的 SQL 不会根据此类本身的属性（而非其父类）而发生变化，则可以在特定类上将此标志设置为 True。

另请参阅

为自定义构造启用缓存支持 - 为第三方或用户定义的 SQL 构造设置 HasCacheKey.inherit_cache 属性的一般指南。

类 sqlalchemy.sql.expression.TableClause¶

表示最小的“表”结构。

这是一个轻量级的表对象，它只有名称、列的集合（通常由 column() 函数生成）和模式

from sqlalchemy import table, column

user = table("user",
        column("id"),
        column("name"),
        column("description"),
)

TableClause 结构是更常用的 Table 对象的基础，提供通常的 FromClause 服务，包括 .c. 集合和语句生成方法。

它不提供 Table 的所有其他模式级服务，包括约束、对其他表的引用或对 MetaData 级服务的支持。它本身用作临时结构很有用，用于在没有更完整的 Table 的情况下生成快速 SQL 语句。

类签名

类 sqlalchemy.sql.expression.TableClause (sqlalchemy.sql.roles.DMLTableRole, sqlalchemy.sql.expression.Immutable, sqlalchemy.sql.expression.NamedFromClause)

方法 sqlalchemy.sql.expression.TableClause.alias(name: str | None = None, flat: bool = False) → NamedFromClause¶

继承自 FromClause.alias() 方法的 FromClause

返回此 FromClause 的别名。

例如：

a2 = some_table.alias('a2')

以上代码创建了一个 Alias 对象，该对象可以用作任何 SELECT 语句中的 FROM 子句。

另请参阅

如何将 SQL 表达式呈现为字符串，可能包含内联的绑定参数？

属性 sqlalchemy.sql.expression.TableClause.c¶

继承自 FromClause.c 属性的 FromClause

是 FromClause.columns 的同义词

返回值:: 一个 ColumnCollection

属性 sqlalchemy.sql.expression.TableClause.columns¶

继承自 FromClause.columns 属性的 FromClause

此 FromClause 所维护的 ColumnElement 对象的基于名称的集合。

columns 或 c 集合是使用表绑定或其他可选择绑定列构建 SQL 表达式的网关

select(mytable).where(mytable.c.somecolumn == 5)

返回值:: 一个 ColumnCollection 对象。

方法 sqlalchemy.sql.expression.TableClause.compare(other: ClauseElement, **kw: Any) → bool¶

继承自 ClauseElement.compare() 方法的 ClauseElement

将此 ClauseElement 与给定的 ClauseElement 进行比较。

子类应该覆盖默认行为，默认行为是直接身份比较。

**kw 是子类 compare() 方法消耗的参数，可用于修改比较标准（参见 ColumnElement）。

method sqlalchemy.sql.expression.TableClause.compile(bind: _HasDialect | None = None, dialect: Dialect | None = None, **kw: Any) → Compiled¶

继承自 CompilerElement.compile() 方法 CompilerElement

编译此 SQL 表达式。

返回值是一个 Compiled 对象。对返回值调用 str() 或 unicode() 将产生结果的字符串表示形式。该 Compiled 对象还可以使用 params 访问器返回绑定参数名称和值的字典。

参数:

bind¶ – 一个 Connection 或 Engine 它可以提供一个 Dialect 以便生成一个 Compiled 对象。如果 bind 和 dialect 参数都被省略，则使用默认的 SQL 编译器。
column_keys¶ – 用于 INSERT 和 UPDATE 语句，一个列名列表，这些列名应出现在已编译语句的 VALUES 子句中。如果为 None，则从目标表对象渲染所有列。
dialect¶ – 一个 Dialect 实例，它可以生成一个 Compiled 对象。此参数优先于 bind 参数。
compile_kwargs¶ –
可选的附加参数字典，这些参数将传递到所有“访问”方法中的编译器中。这允许将任何自定义标志传递给自定义编译结构，例如。它也用于传递 literal_binds 标志的情况
```
from sqlalchemy.sql import table, column, select

t = table('t', column('x'))

s = select(t).where(t.c.x == 5)

print(s.compile(compile_kwargs={"literal_binds": True}))
```

另请参阅

method sqlalchemy.sql.expression.TableClause.corresponding_column(column: KeyedColumnElement[Any], require_embedded: bool = False) → KeyedColumnElement[Any] | None¶

继承自 Selectable.corresponding_column() 方法 Selectable

给定一个 ColumnElement，返回来自此 Selectable 的 ColumnElement 对象，该对象通过公共祖先列对应于该原始 ColumnElement。

参数:

column¶ – 目标 ColumnElement 要匹配。
require_embedded¶ – 仅为给定 ColumnElement 返回对应列，如果给定 ColumnElement 实际上存在于此 Selectable 的子元素中。通常，如果该列与该 Selectable 的任何导出的列共享一个共同的祖先，则该列将匹配。

另请参阅

Selectable.exported_columns - 用于该操作的 ColumnCollection。

ColumnCollection.corresponding_column() - 实现方法。

method sqlalchemy.sql.expression.TableClause.delete() → Delete¶

针对此 TableClause 生成一个 delete() 结构。

例如：

table.delete().where(table.c.id==7)

有关参数和用法信息，请参阅 delete()。

attribute sqlalchemy.sql.expression.TableClause.description¶

attribute sqlalchemy.sql.expression.TableClause.entity_namespace¶

继承自 FromClause.entity_namespace 属性 FromClause

返回在 SQL 表达式中用于基于名称访问的命名空间。

这是用于解析“filter_by()”类型表达式的命名空间，例如

stmt.filter_by(address='some address')

它默认为 .c 集合，但内部可以使用“entity_namespace”注释来覆盖它以提供替代结果。

attribute sqlalchemy.sql.expression.TableClause.exported_columns¶

继承自 FromClause.exported_columns 属性 FromClause

一个 ColumnCollection，它表示此 Selectable 的“导出”列。

一个 FromClause 对象的“导出”列与 FromClause.columns 集合是同义词。

版本 1.4 中的新功能。

另请参阅

Table.foreign_key_constraints

attribute sqlalchemy.sql.expression.TableClause.foreign_keys¶

继承自 FromClause.foreign_keys 属性 FromClause

返回此 FromClause 引用的 ForeignKey 标记对象集合。

每个 ForeignKey 都是 Table 范围内的 ForeignKeyConstraint 的成员。

另请参阅

method sqlalchemy.sql.expression.TableClause.get_children(*, omit_attrs: Tuple[str, ...] = (), **kw: Any) → Iterable[HasTraverseInternals]¶

继承自 HasTraverseInternals.get_children() 方法 HasTraverseInternals

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

这用于访问遍历。

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

attribute sqlalchemy.sql.expression.TableClause.implicit_returning = False¶: TableClause 不支持主键或列级默认值，因此不适用隐式返回。

attribute sqlalchemy.sql.expression.TableClause.inherit_cache: bool | None = None¶

继承自 HasCacheKey.inherit_cache 属性的 HasCacheKey

指示此 HasCacheKey 实例是否应使用其直接父类使用的缓存键生成方案。

该属性默认为 None，这表明构造尚未考虑其是否适合参与缓存；这在功能上等同于将值设置为 False，只是还会发出警告。

如果与对象对应的 SQL 不会根据此类本身的属性（而非其父类）而发生变化，则可以在特定类上将此标志设置为 True。

另请参阅

为自定义构造启用缓存支持 - 为第三方或用户定义的 SQL 构造设置 HasCacheKey.inherit_cache 属性的一般指南。

method sqlalchemy.sql.expression.TableClause.insert() → Insert¶

为该 TableClause 生成一个 Insert 结构。

例如：

table.insert().values(name='foo')

有关参数和用法信息，请参见 insert()。

method sqlalchemy.sql.expression.TableClause.is_derived_from(fromclause: FromClause | None) → bool¶

继承自 FromClause.is_derived_from() 方法 FromClause

如果此 FromClause 是从给定的 FromClause “派生”的，则返回 True。

例如，表的别名将从该表派生。

method sqlalchemy.sql.expression.TableClause.join(right: _FromClauseArgument, onclause: _ColumnExpressionArgument[bool] | None = None, isouter: bool = False, full: bool = False) → Join¶

继承自 FromClause.join() 方法 FromClause

从此 FromClause 返回到另一个 FromClause 的 Join。

例如：

from sqlalchemy import join

j = user_table.join(address_table,
                user_table.c.id == address_table.c.user_id)
stmt = select(user_table).select_from(j)

将发出类似于以下内容的 SQL

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

参数:

right¶ – 连接的右侧；这是任何 FromClause 对象，例如 Table 对象，也可以是可选择兼容的对象，例如 ORM 映射类。
onclause¶ – 表示连接 ON 子句的 SQL 表达式。如果保留为 None，FromClause.join() 将尝试根据外键关系连接这两个表。
isouter¶ – 如果为 True，则呈现 LEFT OUTER JOIN，而不是 JOIN。
full¶ – 如果为 True，则呈现 FULL OUTER JOIN，而不是 LEFT OUTER JOIN。意味着 FromClause.join.isouter。

另请参阅

join() - 独立函数

Join - 生成的对象类型

method sqlalchemy.sql.expression.TableClause.lateral(name: str | None = None) → LateralFromClause¶

继承自 Selectable.lateral() 方法 Selectable

返回此 Selectable 的 LATERAL 别名。

返回值是 Lateral 结构，它也由顶层 lateral() 函数提供。

另请参阅

LATERAL 关联 - 用法概述。

method sqlalchemy.sql.expression.TableClause.outerjoin(right: _FromClauseArgument, onclause: _ColumnExpressionArgument[bool] | None = None, full: bool = False) → Join¶

继承自 FromClause.outerjoin() 方法 FromClause

从该 FromClause 到另一个 FromClause 返回一个 Join，并将“isouter”标志设置为 True。

例如：

from sqlalchemy import outerjoin

j = user_table.outerjoin(address_table,
                user_table.c.id == address_table.c.user_id)

以上等同于

j = user_table.join(
    address_table,
    user_table.c.id == address_table.c.user_id,
    isouter=True)

参数:

right¶ – 连接的右侧；这是任何 FromClause 对象，例如 Table 对象，也可以是可选择兼容的对象，例如 ORM 映射类。
onclause¶ – 表示连接的 ON 子句的 SQL 表达式。如果保留为 None，FromClause.join() 将尝试根据外键关系连接两个表。
full¶ – 如果为 True，则呈现 FULL OUTER JOIN，而不是 LEFT OUTER JOIN。

另请参阅

FromClause.join()

Join

method sqlalchemy.sql.expression.TableClause.params(*optionaldict, **kwargs)¶

继承自 Immutable.params() 方法 Immutable

返回带有 bindparam() 元素替换的副本。

返回此 ClauseElement 的副本，其中 bindparam() 元素被从给定字典中获取的值替换。

>>> clause = column('x') + bindparam('foo')
>>> print(clause.compile().params)
{'foo':None}
>>> print(clause.params({'foo':7}).compile().params)
{'foo':7}

attribute sqlalchemy.sql.expression.TableClause.primary_key¶

继承自 FromClause.primary_key 属性 FromClause

返回组成此 _selectable.FromClause 主键的 Column 对象的可迭代集合。

对于 Table 对象，此集合由 PrimaryKeyConstraint 表示，该约束本身是一个可迭代的 Column 对象集合。

method sqlalchemy.sql.expression.TableClause.replace_selectable(old: FromClause, alias: Alias) → Self¶: 继承自 Selectable.replace_selectable() 方法 Selectable

将所有出现的 FromClause ‘old’ 替换为给定的 Alias 对象，返回此 FromClause 的副本。

自版本 1.4 起弃用: The Selectable.replace_selectable() 方法已弃用，将在未来的版本中移除。类似的功能可以通过 sqlalchemy.sql.visitors 模块获得。

attribute sqlalchemy.sql.expression.TableClause.schema: str | None = None¶

继承自 FromClause.schema 属性 FromClause

为该 FromClause 定义 'schema' 属性。

这通常对于大多数对象都是 None，除了 Table 对象，它采用 Table.schema 参数的值。

method sqlalchemy.sql.expression.TableClause.select() → Select¶

继承自 FromClause.select() 方法 FromClause

返回该 FromClause 的 SELECT。

例如。

stmt = some_table.select().where(some_table.c.id == 5)

另请参阅

select() - 通用方法，允许使用任意列列表。

method sqlalchemy.sql.expression.TableClause.self_group(against: OperatorType | None = None) → ClauseElement¶

继承自 ClauseElement.self_group() 方法 ClauseElement

对这个 ClauseElement 应用“分组”。

此方法被子类覆盖以返回“分组”构造，即括号。特别是它被“二元”表达式用于在放置到更大的表达式中时在其周围提供分组，以及被 select() 构造在放置到另一个 select() 的 FROM 子句中时使用。(注意，子查询通常应该使用 Select.alias() 方法创建，因为许多平台要求嵌套的 SELECT 语句被命名).

当表达式组合在一起时，self_group() 的应用是自动的 - 用户代码永远不需要直接使用此方法。请注意，SQLAlchemy 的子句构造会考虑运算符优先级 - 因此括号可能不需要，例如，在 x OR (y AND z) 这样的表达式中 - AND 的优先级高于 OR。

的 self_group() 方法 ClauseElement 只是返回 self。

method sqlalchemy.sql.expression.TableClause.table_valued() → TableValuedColumn[Any]¶

继承自 NamedFromClause.table_valued() 方法 NamedFromClause

为该 FromClause 返回一个 TableValuedColumn 对象。

一个 TableValuedColumn 是一个 ColumnElement，它表示表中的一整行。对该构造的支持取决于后端，并以各种形式由 PostgreSQL、Oracle 和 SQL Server 等后端支持。

例如：

>>> fromsqlalchemyimportselect,column,func,table>>> a=table("a",column("id"),column("x"),column("y"))>>> stmt=select(func.row_to_json(a.table_valued()))>>> print(stmt)SELECT row_to_json(a) AS row_to_json_1
FROM a

版本 1.4.0b2 中新增。

另请参阅

使用 SQL 函数 - 在 SQLAlchemy 统一教程中

method sqlalchemy.sql.expression.TableClause.tablesample(sampling: float | Function[Any], name: str | None = None, seed: roles.ExpressionElementRole[Any] | None = None) → TableSample¶

继承自 FromClause.tablesample() 方法的 FromClause

返回该 FromClause 的 TABLESAMPLE 别名。

返回值是 TableSample 结构，该结构也由顶层 tablesample() 函数提供。

另请参阅

tablesample() - 用法指南和参数

方法 sqlalchemy.sql.expression.TableClause.unique_params(*optionaldict, **kwargs)¶

继承自 Immutable.unique_params() 方法的 Immutable

返回带有 bindparam() 元素替换的副本。

与 ClauseElement.params() 的功能相同，但会将 unique=True 添加到受影响的绑定参数，以便可以使用多个语句。

方法 sqlalchemy.sql.expression.TableClause.update() → Update¶

针对此 TableClause 生成一个 update() 结构。

例如：

table.update().where(table.c.id==7).values(name='foo')

有关参数和使用信息，请参阅 update()。

类 sqlalchemy.sql.expression.TableSample¶

表示 TABLESAMPLE 子句。

此对象由 tablesample() 模块级函数以及所有 FromClause 子类上可用的 FromClause.tablesample() 方法构造。

另请参阅

tablesample()

类签名

类 sqlalchemy.sql.expression.TableSample (sqlalchemy.sql.expression.FromClauseAlias)

类 sqlalchemy.sql.expression.TableValuedAlias¶

针对“表值” SQL 函数的别名。

此构造提供了用于返回要在 SELECT 语句的 FROM 子句中使用的列的 SQL 函数。该对象使用 FunctionElement.table_valued() 方法生成，例如

>>> fromsqlalchemyimportselect,func>>> fn=func.json_array_elements_text('["one", "two", "three"]').table_valued("value")>>> print(select(fn.c.value))SELECT anon_1.value
FROM json_array_elements_text(:json_array_elements_text_1) AS anon_1

版本 1.4.0b2 中新增。

另请参阅

表值函数 - 在 SQLAlchemy 统一教程中

成员

alias(), column, lateral(), render_derived()

类签名

类 sqlalchemy.sql.expression.TableValuedAlias (sqlalchemy.sql.expression.LateralFromClause, sqlalchemy.sql.expression.Alias)

方法 sqlalchemy.sql.expression.TableValuedAlias.alias(name: str | None = None, flat: bool = False) → TableValuedAlias¶

返回此 TableValuedAlias 的新别名。

这将创建一个不同的 FROM 对象，该对象在 SQL 语句中使用时将与原始对象区分开来。

属性 sqlalchemy.sql.expression.TableValuedAlias.column¶

返回表示此 TableValuedAlias 的列表达式。

此访问器用于实现 FunctionElement.column_valued() 方法。有关更多详细信息，请参阅该方法。

例如：

>>> print(select(func.some_func().table_valued("value").column))SELECT anon_1 FROM some_func() AS anon_1

另请参阅

FunctionElement.column_valued()

方法 sqlalchemy.sql.expression.TableValuedAlias.lateral(name: str | None = None) → LateralFromClause¶: 返回一个新的 TableValuedAlias，其中设置了 lateral 标志，以便它呈现为 LATERAL。

另请参阅

lateral()

方法 sqlalchemy.sql.expression.TableValuedAlias.render_derived(name: str | None = None, with_types: bool = False) → TableValuedAlias¶

将“渲染派生”应用于此 TableValuedAlias。

这将使“AS”序列中别名名称后面的单个列名称列出，例如

>>> print(...     select(...         func.unnest(array(["one", "two", "three"])).            table_valued("x", with_ordinality="o").render_derived()...     )... )SELECT anon_1.x, anon_1.o
FROM unnest(ARRAY[%(param_1)s, %(param_2)s, %(param_3)s]) WITH ORDINALITY AS anon_1(x, o)

with_types 关键字将在别名表达式中内联渲染列类型（此语法目前适用于 PostgreSQL 数据库）

>>> print(...     select(...         func.json_to_recordset(...             '[{"a":1,"b":"foo"},{"a":"2","c":"bar"}]'...         )...         .table_valued(column("a", Integer), column("b", String))...         .render_derived(with_types=True)...     )... )SELECT anon_1.a, anon_1.b FROM json_to_recordset(:json_to_recordset_1)
AS anon_1(a INTEGER, b VARCHAR)

参数:

name¶ – 可选的字符串名称，将应用于生成的别名。如果保留为 None，将使用唯一的匿名名称。
with_types¶ – 如果为 True，则派生列将在每个列中包含数据类型规范。这是一种特殊的语法，目前已知 PostgreSQL 的某些 SQL 函数需要。

类 sqlalchemy.sql.expression.TextualSelect¶

在 TextClause 结构中包装一个 SelectBase 接口。

这使得 TextClause 对象获得 .c 集合和其他类似 FROM 的功能，例如 FromClause.alias()，SelectBase.cte() 等。

通过 TextClause.columns() 方法生成 TextualSelect 结构 - 有关详细信息，请参见该方法。

1.4 版本变更: TextualSelect 类已从 TextAsFrom 重命名，以更准确地符合其作为面向 SELECT 的对象而不是 FROM 子句的作用。

另请参阅

text()

TextClause.columns() - 主要创建接口。

类签名

class sqlalchemy.sql.expression.TextualSelect (sqlalchemy.sql.expression.SelectBase, sqlalchemy.sql.expression.ExecutableReturnsRows, sqlalchemy.sql.expression.Generative)

method sqlalchemy.sql.expression.TextualSelect.add_cte(*ctes: CTE, nest_here: bool = False) → Self¶

继承自 HasCTE.add_cte() 方法 HasCTE

将一个或多个 CTE 构造添加到此语句。

此方法将与给定的 CTE 构造关联父语句，以便它们将在最终语句的 WITH 子句中无条件地渲染，即使在语句或任何子选择中没有其他地方引用它们。

当设置为 True 时，可选的 HasCTE.add_cte.nest_here 参数将具有以下效果：每个给定的 CTE 将在直接与该语句一起渲染的 WITH 子句中渲染，而不是被移动到最终渲染语句的顶部，即使该语句在更大的语句中以子查询的形式渲染。

此方法有两个一般用途。一种是嵌入用于某些目的的 CTE 语句，而无需显式引用它们，例如将 INSERT 或 UPDATE 等 DML 语句作为 CTE 嵌入到可能间接从其结果中获取数据的初级语句中的用例。另一种是提供对应该在可能嵌套在更大的语句中的特定语句方面直接渲染的特定一系列 CTE 构造的精确位置的控制。

例如：

from sqlalchemy import table, column, select
t = table('t', column('c1'), column('c2'))

ins = t.insert().values({"c1": "x", "c2": "y"}).cte()

stmt = select(t).add_cte(ins)

将渲染

WITH anon_1 AS
(INSERT INTO t (c1, c2) VALUES (:param_1, :param_2))
SELECT t.c1, t.c2
FROM t

在上面，"anon_1" CTE 在 SELECT 语句中没有被引用，但是仍然完成了运行 INSERT 语句的任务。

同样在与 DML 相关的上下文中，使用 PostgreSQL Insert 构造生成 "upsert"

from sqlalchemy import table, column
from sqlalchemy.dialects.postgresql import insert

t = table("t", column("c1"), column("c2"))

delete_statement_cte = (
    t.delete().where(t.c.c1 < 1).cte("deletions")
)

insert_stmt = insert(t).values({"c1": 1, "c2": 2})
update_statement = insert_stmt.on_conflict_do_update(
    index_elements=[t.c.c1],
    set_={
        "c1": insert_stmt.excluded.c1,
        "c2": insert_stmt.excluded.c2,
    },
).add_cte(delete_statement_cte)

print(update_statement)

上面的语句渲染为

WITH deletions AS
(DELETE FROM t WHERE t.c1 < %(c1_1)s)
INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2

版本 1.4.21 中的新功能。

参数:

*ctes¶ –
零个或多个 CTE 构造。

在版本 2.0 中更改: 接受多个 CTE 实例
nest_here¶ –
如果为 True，则给定的 CTE 或 CTE 将被渲染为它们指定了 HasCTE.cte.nesting 标志为 True 时添加到此 HasCTE。假设给定的 CTE 在外部封闭语句中也没有被引用，则在给出此标志时，给定的 CTE 应该在该语句的级别进行渲染。

2.0 版中的新增功能。

另请参阅

HasCTE.cte.nesting

method sqlalchemy.sql.expression.TextualSelect.alias(name: str | None = None, flat: bool = False) → Subquery¶

继承自 SelectBase.alias() 方法 SelectBase

返回针对此 SelectBase 的命名子查询。

对于 SelectBase（而不是 FromClause），这将返回一个 Subquery 对象，该对象的运行方式与 Alias 对象（用于 FromClause）基本相同。

在 1.4 版中变更: The SelectBase.alias() 方法现在是 SelectBase.subquery() 方法的同义词。

method sqlalchemy.sql.expression.TextualSelect.as_scalar() → ScalarSelect[Any]¶: 继承自 SelectBase.as_scalar() 方法 SelectBase

自 1.4 版起弃用: The SelectBase.as_scalar() 方法已弃用，将在未来版本中删除。请参阅 SelectBase.scalar_subquery().

attribute sqlalchemy.sql.expression.TextualSelect.c¶: 继承自 SelectBase.c 属性 SelectBase

自 1.4 版起弃用: The SelectBase.c 和 SelectBase.columns 属性已弃用，将在未来版本中删除；这些属性隐式地创建一个子查询，而该子查询应该是显式的。请先调用 SelectBase.subquery() 以创建一个子查询，然后该子查询包含此属性。要访问此 SELECT 对象 SELECT 的列，请使用 SelectBase.selected_columns 属性。

method sqlalchemy.sql.expression.TextualSelect.compare(other: ClauseElement, **kw: Any) → bool¶

继承自 ClauseElement.compare() 方法的 ClauseElement

将此 ClauseElement 与给定的 ClauseElement 进行比较。

子类应该覆盖默认行为，默认行为是直接身份比较。

**kw 是子类 compare() 方法消耗的参数，可用于修改比较标准（参见 ColumnElement）。

method sqlalchemy.sql.expression.TextualSelect.compile(bind: _HasDialect | None = None, dialect: Dialect | None = None, **kw: Any) → Compiled¶

继承自 CompilerElement.compile() 方法 CompilerElement

编译此 SQL 表达式。

返回值是一个 Compiled 对象。对返回值调用 str() 或 unicode() 将产生结果的字符串表示形式。该 Compiled 对象还可以使用 params 访问器返回绑定参数名称和值的字典。

参数:

bind¶ – 一个 Connection 或 Engine，它可以提供 Dialect 以生成 Compiled 对象。如果省略了 bind 和 dialect 参数，则使用默认的 SQL 编译器。
column_keys¶ – 用于 INSERT 和 UPDATE 语句，一个包含应出现在编译语句的 VALUES 子句中的列名称的列表。如果为 None，则会渲染目标表对象的所有列。
dialect¶ – 一个 Dialect 实例，可以生成一个 Compiled 对象。此参数优先于 bind 参数。
compile_kwargs¶ –
可选的附加参数字典，这些参数将传递到所有“访问”方法中的编译器中。这允许将任何自定义标志传递给自定义编译结构，例如。它也用于传递 literal_binds 标志的情况
```
from sqlalchemy.sql import table, column, select

t = table('t', column('x'))

s = select(t).where(t.c.x == 5)

print(s.compile(compile_kwargs={"literal_binds": True}))
```

另请参阅

如何将 SQL 表达式呈现为字符串，可能包含内联的绑定参数？

method sqlalchemy.sql.expression.TextualSelect.corresponding_column(column: KeyedColumnElement[Any], require_embedded: bool = False) → KeyedColumnElement[Any] | None¶

继承自 Selectable.corresponding_column() 方法 Selectable

给定一个 ColumnElement，返回来自此 Selectable 的 ColumnElement 对象，该对象通过公共祖先列对应于该原始 ColumnElement。

参数:

column¶ – 要匹配的目标 ColumnElement。
require_embedded¶ – 仅返回给定 ColumnElement 的对应列，如果给定的 ColumnElement 实际上存在于此 Selectable 的子元素中。通常，如果该列与此 Selectable 的导出列之一具有共同的祖先，则该列将匹配。

另请参阅

Selectable.exported_columns - 用于该操作的 ColumnCollection。

ColumnCollection.corresponding_column() - 实现方法。

method sqlalchemy.sql.expression.TextualSelect.cte(name: str | None = None, recursive: bool = False, nesting: bool = False) → CTE¶

继承自 HasCTE.cte() 方法的 HasCTE

返回一个新的 CTE 或 Common Table Expression 实例。

公共表表达式是 SQL 标准，其中 SELECT 语句可以利用与主语句一起指定的辅助语句，使用称为“WITH”的子句。还可以使用有关 UNION 的特殊语义来允许“递归”查询，其中 SELECT 语句可以利用先前已选择的行集。

CTE 也可以应用于某些数据库上的 DML 结构 UPDATE、INSERT 和 DELETE，作为 CTE 行的来源（当与 RETURNING 组合时）以及 CTE 行的使用者。

SQLAlchemy 检测 CTE 对象，这些对象与 Alias 对象类似，被视为特殊元素，传递给语句的 FROM 子句以及语句顶部的 WITH 子句。

对于特殊前缀（如 PostgreSQL 的“MATERIALIZED”和“NOT MATERIALIZED”），可以使用 CTE.prefix_with() 方法来建立这些前缀。

在版本 1.3.13 中更改: 添加了对前缀的支持。尤其是 - MATERIALIZED 和 NOT MATERIALIZED。

参数:

name¶ – 给定给通用表表达式的名称。像 FromClause.alias() 一样，该名称可以保留为 None，在这种情况下，在查询编译时将使用一个匿名符号。
recursive¶ – 如果为 True，将渲染 WITH RECURSIVE。递归通用表表达式旨在与 UNION ALL 结合使用，以从已选定行中派生行。
nesting¶ –
如果为 True，将把 CTE 呈现在引用它的语句中。对于更复杂的情况，可以使用 HasCTE.add_cte() 方法，使用 HasCTE.add_cte.nest_here 参数也可以更仔细地控制特定 CTE 的确切位置。

版本 1.4.24 中新增。

另请参阅

HasCTE.add_cte()

以下示例包括两个来自 PostgreSQL 文档的示例，位于 https://postgresql.ac.cn/docs/current/static/queries-with.html，以及其他示例。

示例 1，非递归

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
    Column('region', String),
    Column('amount', Integer),
    Column('product', String),
    Column('quantity', Integer)
)

regional_sales = select(
                    orders.c.region,
                    func.sum(orders.c.amount).label('total_sales')
                ).group_by(orders.c.region).cte("regional_sales")


top_regions = select(regional_sales.c.region).\
        where(
            regional_sales.c.total_sales >
            select(
                func.sum(regional_sales.c.total_sales) / 10
            )
        ).cte("top_regions")

statement = select(
            orders.c.region,
            orders.c.product,
            func.sum(orders.c.quantity).label("product_units"),
            func.sum(orders.c.amount).label("product_sales")
    ).where(orders.c.region.in_(
        select(top_regions.c.region)
    )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

示例 2，WITH RECURSIVE

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
    Column('part', String),
    Column('sub_part', String),
    Column('quantity', Integer),
)

included_parts = select(\
    parts.c.sub_part, parts.c.part, parts.c.quantity\
    ).\
    where(parts.c.part=='our part').\
    cte(recursive=True)


incl_alias = included_parts.alias()
parts_alias = parts.alias()
included_parts = included_parts.union_all(
    select(
        parts_alias.c.sub_part,
        parts_alias.c.part,
        parts_alias.c.quantity
    ).\
    where(parts_alias.c.part==incl_alias.c.sub_part)
)

statement = select(
            included_parts.c.sub_part,
            func.sum(included_parts.c.quantity).
              label('total_quantity')
        ).\
        group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

示例 3，使用 CTE 的 UPDATE 和 INSERT 进行 upsert

from datetime import date
from sqlalchemy import (MetaData, Table, Column, Integer,
                        Date, select, literal, and_, exists)

metadata = MetaData()

visitors = Table('visitors', metadata,
    Column('product_id', Integer, primary_key=True),
    Column('date', Date, primary_key=True),
    Column('count', Integer),
)

# add 5 visitors for the product_id == 1
product_id = 1
day = date.today()
count = 5

update_cte = (
    visitors.update()
    .where(and_(visitors.c.product_id == product_id,
                visitors.c.date == day))
    .values(count=visitors.c.count + count)
    .returning(literal(1))
    .cte('update_cte')
)

upsert = visitors.insert().from_select(
    [visitors.c.product_id, visitors.c.date, visitors.c.count],
    select(literal(product_id), literal(day), literal(count))
        .where(~exists(update_cte.select()))
)

connection.execute(upsert)

示例 4，嵌套 CTE（SQLAlchemy 1.4.24 及更高版本）

value_a = select(
    literal("root").label("n")
).cte("value_a")

# A nested CTE with the same name as the root one
value_a_nested = select(
    literal("nesting").label("n")
).cte("value_a", nesting=True)

# Nesting CTEs takes ascendency locally
# over the CTEs at a higher level
value_b = select(value_a_nested.c.n).cte("value_b")

value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))

上述查询将呈现嵌套在第一个 CTE 内的第二个 CTE，如下所示，带有内联参数

WITH
    value_a AS
        (SELECT 'root' AS n),
    value_b AS
        (WITH value_a AS
            (SELECT 'nesting' AS n)
        SELECT value_a.n AS n FROM value_a)
SELECT value_a.n AS a, value_b.n AS b
FROM value_a, value_b

可以使用 HasCTE.add_cte() 方法设置相同的 CTE（SQLAlchemy 2.0 及更高版本）

value_a = select(
    literal("root").label("n")
).cte("value_a")

# A nested CTE with the same name as the root one
value_a_nested = select(
    literal("nesting").label("n")
).cte("value_a")

# Nesting CTEs takes ascendency locally
# over the CTEs at a higher level
value_b = (
    select(value_a_nested.c.n).
    add_cte(value_a_nested, nest_here=True).
    cte("value_b")
)

value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))

示例 5，非线性 CTE（SQLAlchemy 1.4.28 及更高版本）

edge = Table(
    "edge",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("left", Integer),
    Column("right", Integer),
)

root_node = select(literal(1).label("node")).cte(
    "nodes", recursive=True
)

left_edge = select(edge.c.left).join(
    root_node, edge.c.right == root_node.c.node
)
right_edge = select(edge.c.right).join(
    root_node, edge.c.left == root_node.c.node
)

subgraph_cte = root_node.union(left_edge, right_edge)

subgraph = select(subgraph_cte)

上述查询将呈现递归 CTE 内的 2 个 UNION

WITH RECURSIVE nodes(node) AS (
        SELECT 1 AS node
    UNION
        SELECT edge."left" AS "left"
        FROM edge JOIN nodes ON edge."right" = nodes.node
    UNION
        SELECT edge."right" AS "right"
        FROM edge JOIN nodes ON edge."left" = nodes.node
)
SELECT nodes.node FROM nodes

另请参阅

Query.cte() - HasCTE.cte() 的 ORM 版本。

method sqlalchemy.sql.expression.TextualSelect.execution_options(**kw: Any) → Self¶

继承自 Executable.execution_options() 方法的 Executable

为语句设置在执行期间生效的非 SQL 选项。

执行选项可以在许多范围内设置，包括每个语句、每个连接或每个执行，使用诸如 Connection.execution_options() 和接受选项字典的参数，例如 Connection.execute.execution_options 和 Session.execute.execution_options。

执行选项的主要特征（与其他类型的选项不同，例如 ORM 加载器选项）是 **执行选项从不影响查询的编译 SQL，而仅影响如何调用 SQL 语句本身或如何获取结果**。也就是说，执行选项不是 SQL 编译所容纳的部分，也不被视为语句的缓存状态的一部分。

Executable.execution_options() 方法是生成式的，就像应用于 Engine 和 Query 对象的方法一样，这意味着当调用该方法时，将返回对象的副本，该副本将给定的参数应用于该新副本，但保留原始副本不变

statement = select(table.c.x, table.c.y)
new_statement = statement.execution_options(my_option=True)

这种行为的一个例外是 Connection 对象，其中 Connection.execution_options() 方法显式地 **不是** 生成式。

传递给 Executable.execution_options() 和其他相关方法以及参数字典的选项类型包括 SQLAlchemy Core 或 ORM 显式使用的参数，以及 SQLAlchemy 未定义的任意关键字参数，这意味着这些方法和/或参数字典可用于与自定义代码交互的用户定义参数，这些参数可以通过诸如 Executable.get_execution_options() 和 Connection.get_execution_options() 之类的方法访问，或在使用专用 execution_options 事件参数（如 ConnectionEvents.before_execute.execution_options 或 ORMExecuteState.execution_options）的选定事件钩子中，例如

from sqlalchemy import event

@event.listens_for(some_engine, "before_execute")
def _process_opt(conn, statement, multiparams, params, execution_options):
    "run a SQL function before invoking a statement"

    if execution_options.get("do_special_thing", False):
        conn.exec_driver_sql("run_special_function()")

在 SQLAlchemy 显式识别的选项范围内，大多数选项适用于特定类别的对象，而其他选项则不适用。最常见的执行选项包括

Connection.execution_options.isolation_level - 通过 Engine 设置连接或连接类的隔离级别。此选项仅被 Connection 或 Engine 接受。
Connection.execution_options.stream_results - 指示结果应使用服务器端游标获取；此选项被 Connection、Connection.execute.execution_options 参数（在 Connection.execute() 上）以及 Executable.execution_options() （在 SQL 语句对象上）以及 ORM 结构（如 Session.execute()）接受。
Connection.execution_options.compiled_cache - 指示一个字典，该字典将用作 SQL 编译缓存，用于 Connection 或 Engine，以及 ORM 方法（如 Session.execute()）。可以作为 None 传递以禁用语句的缓存。此选项不被 Executable.execution_options() 接受，因为在语句对象中携带编译缓存是不明智的。
Connection.execution_options.schema_translate_map - 架构转换映射特性使用的架构名称映射，被 Connection、Engine、Executable 以及 ORM 结构（如 Session.execute()）接受。

另请参阅

ORM 执行选项 - 所有 ORM 特定执行选项的文档

method sqlalchemy.sql.expression.TextualSelect.exists() → Exists¶

继承自 SelectBase.exists() 方法 SelectBase

返回此可选择项的 Exists 表示形式，可以用作列表达式。

返回的对象是 Exists 的实例。

另请参阅

EXISTS 子查询 - 在 2.0 风格教程中。

版本 1.4 中的新功能。

attribute sqlalchemy.sql.expression.TextualSelect.exported_columns¶

继承自 SelectBase.exported_columns 属性 SelectBase

一个 ColumnCollection，它代表此 Selectable 的“导出”列，不包括 TextClause 结构。

一个 SelectBase 对象的“导出”列与 SelectBase.selected_columns 集合相同。

版本 1.4 中的新功能。

另请参阅

method sqlalchemy.sql.expression.TextualSelect.get_children(*, omit_attrs: Tuple[str, ...] = (), **kw: Any) → Iterable[HasTraverseInternals]¶

继承自 HasTraverseInternals.get_children() 方法 HasTraverseInternals

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

这用于访问遍历。

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

method sqlalchemy.sql.expression.TextualSelect.get_execution_options() → _ExecuteOptions¶: 继承自 Executable.get_execution_options() 方法 Executable

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

版本 1.3 中新增。

另请参阅

Executable.execution_options()

method sqlalchemy.sql.expression.TextualSelect.get_label_style() → SelectLabelStyle¶

继承自 SelectBase.get_label_style() 方法 SelectBase

检索当前标签样式。

由子类实现。

attribute sqlalchemy.sql.expression.TextualSelect.inherit_cache: bool | None = None¶

继承自 HasCacheKey.inherit_cache 属性的 HasCacheKey

指示此 HasCacheKey 实例是否应使用其直接父类使用的缓存键生成方案。

该属性默认为 None，这表明构造尚未考虑其是否适合参与缓存；这在功能上等同于将值设置为 False，只是还会发出警告。

如果与对象对应的 SQL 不会根据此类本身的属性（而非其父类）而发生变化，则可以在特定类上将此标志设置为 True。

另请参阅

为自定义构造启用缓存支持 - 为第三方或用户定义的 SQL 构造设置 HasCacheKey.inherit_cache 属性的一般指南。

method sqlalchemy.sql.expression.TextualSelect.is_derived_from(fromclause: FromClause | None) → bool¶

继承自 ReturnsRows.is_derived_from() 的方法 ReturnsRows

如果此 ReturnsRows ‘派生’ 自给定的 FromClause，则返回 True。

例如，表的别名将从该表派生。

方法 sqlalchemy.sql.expression.TextualSelect.label(name: str | None) → Label[Any]¶: 继承自 SelectBase.label() 方法 SelectBase

返回此可选择对象的 ‘标量’ 表示形式，嵌入为带有标签的子查询。

另请参阅

SelectBase.scalar_subquery().

方法 sqlalchemy.sql.expression.TextualSelect.lateral(name: str | None = None) → LateralFromClause¶

继承自 SelectBase.lateral() 方法 SelectBase

返回此 Selectable 的 LATERAL 别名。

返回值是 Lateral 结构，它也由顶层 lateral() 函数提供。

另请参阅

LATERAL 关联 - 用法概述。

方法 sqlalchemy.sql.expression.TextualSelect.options(*options: ExecutableOption) → Self¶

继承自 Executable.options() 方法 Executable

将选项应用于此语句。

一般来说，选项是任何可以被 SQL 编译器用于语句的 Python 对象。这些选项可以被特定方言或特定类型的编译器使用。

最常见的选项是 ORM 级别的选项，它们将“急切加载”和其他加载行为应用于 ORM 查询。但是，理论上选项可以用于许多其他目的。

有关特定类型语句的特定选项的信息，请参阅这些选项对象的文档。

在版本 1.4 中变更: - 向 Core 语句对象添加了 Executable.options()，以实现统一的 Core / ORM 查询功能。

另请参阅

列加载选项 - 指的是特定于 ORM 查询使用的选项

使用加载器选项的关联加载 - 指的是特定于 ORM 查询使用的选项

方法 sqlalchemy.sql.expression.TextualSelect.params(_ClauseElement__optionaldict: Mapping[str, Any] | None = None, **kwargs: Any) → Self¶

继承自 ClauseElement.params() 方法 ClauseElement

返回带有 bindparam() 元素替换的副本。

返回此 ClauseElement 的副本，其中 bindparam() 元素被从给定字典中获取的值替换。

>>> clause = column('x') + bindparam('foo')
>>> print(clause.compile().params)
{'foo':None}
>>> print(clause.params({'foo':7}).compile().params)
{'foo':7}

方法 sqlalchemy.sql.expression.TextualSelect.replace_selectable(old: FromClause, alias: Alias) → Self¶: 继承自 Selectable.replace_selectable() 方法 Selectable

将所有出现的 FromClause ‘old’ 替换为给定的 Alias 对象，返回此 FromClause 的副本。

自版本 1.4 起弃用: The Selectable.replace_selectable() 方法已弃用，将在未来的版本中移除。类似的功能可以通过 sqlalchemy.sql.visitors 模块获得。

方法 sqlalchemy.sql.expression.TextualSelect.scalar_subquery() → ScalarSelect[Any]¶

继承自 SelectBase.scalar_subquery() 方法 SelectBase

返回此可选择对象的“标量”表示，它可以用作列表达式。

返回的对象是 ScalarSelect 的实例。

通常，在它的列子句中只有一个列的 SELECT 语句有资格用作标量表达式。然后，标量子查询可以在封闭的 SELECT 的 WHERE 子句或列子句中使用。

请注意，标量子查询不同于使用 SelectBase.subquery() 方法生成的 FROM 级子查询。

另请参阅

标量和关联子查询 - 在 2.0 教程中

方法 sqlalchemy.sql.expression.TextualSelect.select(*arg: Any, **kw: Any) → Select¶: 继承自 SelectBase.select() 方法 SelectBase

从版本 1.4 开始弃用： SelectBase.select() 方法已弃用，将在未来版本中删除；此方法隐式创建子查询，应明确使用。请先调用 SelectBase.subquery() 以创建子查询，然后才能对其进行选择。

属性 sqlalchemy.sql.expression.TextualSelect.selected_columns¶

一个 ColumnCollection 表示此 SELECT 语句或类似构造在结果集中返回的列，不包括 TextClause 构造。

此集合不同于 FromClause.columns 集合，因为此集合中的列不能直接嵌套在另一个 SELECT 语句中；必须先应用子查询，这样才能提供 SQL 所需的括号。

对于 TextualSelect 结构，该集合包含传递给构造函数的 ColumnElement 对象，通常通过 TextClause.columns() 方法。

版本 1.4 中的新功能。

方法 sqlalchemy.sql.expression.TextualSelect.self_group(against: OperatorType | None = None) → ClauseElement¶

继承自 ClauseElement.self_group() 方法 ClauseElement

对这个 ClauseElement 应用“分组”。

此方法被子类覆盖以返回“分组”构造，即括号。特别是它被“二元”表达式用于在放置到更大的表达式中时在其周围提供分组，以及被 select() 构造在放置到另一个 select() 的 FROM 子句中时使用。(注意，子查询通常应该使用 Select.alias() 方法创建，因为许多平台要求嵌套的 SELECT 语句被命名).

当表达式组合在一起时，self_group() 的应用是自动的 - 用户代码永远不需要直接使用此方法。请注意，SQLAlchemy 的子句构造考虑了运算符优先级 - 因此括号可能不需要，例如，在像 x OR (y AND z) 这样的表达式中 - AND 的优先级高于 OR。

基本 self_group() 方法 ClauseElement 仅返回自身。

方法 sqlalchemy.sql.expression.TextualSelect.set_label_style(style: SelectLabelStyle) → TextualSelect¶

返回一个具有指定标签样式的新可选。

由子类实现。

方法 sqlalchemy.sql.expression.TextualSelect.subquery(name: str | None = None) → Subquery¶

inherited from the SelectBase.subquery() method of SelectBase

返回此SelectBase 的子查询。

从 SQL 的角度来看，子查询是一个带括号的、命名的构造，可以放在另一个 SELECT 语句的 FROM 子句中。

给定一个 SELECT 语句，例如

stmt = select(table.c.id, table.c.name)

上面的语句可能看起来像

SELECT table.id, table.name FROM table

子查询形式本身以相同的方式呈现，但是当嵌入到另一个 SELECT 语句的 FROM 子句中时，它成为一个命名的子元素

subq = stmt.subquery()
new_stmt = select(subq)

上面的语句呈现为

SELECT anon_1.id, anon_1.name
FROM (SELECT table.id, table.name FROM table) AS anon_1

从历史上看，SelectBase.subquery() 等效于在 FROM 对象上调用 FromClause.alias() 方法；但是，由于 SelectBase 对象不是直接的 FROM 对象，因此 SelectBase.subquery() 方法提供了更清晰的语义。

版本 1.4 中的新功能。

方法 sqlalchemy.sql.expression.TextualSelect.unique_params(_ClauseElement__optionaldict: Dict[str, Any] | None = None, **kwargs: Any) → Self¶

继承自 ClauseElement.unique_params() 方法 ClauseElement

返回带有 bindparam() 元素替换的副本。

与 ClauseElement.params() 的功能相同，但会将 unique=True 添加到受影响的绑定参数，以便可以使用多个语句。

类 sqlalchemy.sql.expression.Values¶

表示一个 VALUES 结构，它可以用作语句中的 FROM 元素。

Values 对象由 values() 函数创建。

版本 1.4 中的新功能。

成员

alias(), data(), lateral(), scalar_values()

类签名

class sqlalchemy.sql.expression.Values (sqlalchemy.sql.roles.InElementRole, sqlalchemy.sql.expression.Generative, sqlalchemy.sql.expression.LateralFromClause)

method sqlalchemy.sql.expression.Values.alias(name: str | None = None, flat: bool = False) → Self¶

返回一个新的 Values 结构，它是该结构的副本，带有给定的名称。

此方法是 FromClause.alias() 方法的 VALUES 专用特化。

另请参阅