SQLAlchemy 2.0 文档

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

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

继承自 SelectBase.exists() 方法，该方法属于 SelectBase

返回此 selectable 的 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

返回一个新的 selectable，应用了给定的 FETCH FIRST 条件。

这是一个数值，通常在生成的 select 中呈现为 FETCH {FIRST | NEXT} [ count ] {ROW | ROWS} {ONLY | WITH TIES} 表达式。此功能目前在 Oracle Database、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

返回一个新的 selectable，应用了给定的 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。

一个示例是 Table 的 Alias 派生自该 Table。

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

返回此 selectable 的 “标量” 表示形式，嵌入为带有标签的子查询。

另请参阅

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

返回一个新的 selectable，应用了给定的 LIMIT 条件。

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

注意

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

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

另请参阅

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

继承自 GenerativeSelect.offset() 方法，该方法属于 GenerativeSelect

返回一个新的 selectable，应用了给定的 OFFSET 条件。

这是一个数值，通常在生成的 select 中呈现为 OFFSET 表达式。不支持 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

返回一个新的 selectable，应用了给定的 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 的副本。

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

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

inherited from the SelectBase.scalar_subquery() method of SelectBase

返回此 selectable 的 ‘scalar’ 表示形式，可以用作列表达式。

返回的对象是 ScalarSelect 的一个实例。

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

请注意，标量子查询与可以使用 SelectBase.subquery() 方法生成的 FROM 级别子查询区分开来。

另请参阅

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

method sqlalchemy.sql.expression.CompoundSelect.select(*arg: Any, **kw: Any) → Select¶: inherited from the SelectBase.select() method of SelectBase

Deprecated since version 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 应用 ‘grouping’（分组）。

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

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

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

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

返回具有指定标签样式的新 selectable。

有三种可用的 “label styles”（标签样式），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 集合中获得。

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

inherited from the GenerativeSelect.slice() method of GenerativeSelect

基于切片对此语句应用 LIMIT / OFFSET。

start 和 stop 索引的行为类似于 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)

注意

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

New in version 1.4: 添加了从 ORM 泛化的 GenerativeSelect.slice() 方法。

另请参阅

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¶ – 布尔值；将在 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。

class sqlalchemy.sql.expression.CTE¶

表示通用表表达式。

CTE 对象是使用任何 SELECT 语句的 SelectBase.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 特定专业化。

另请参阅

execution_options(), get_execution_options(), options()

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

返回一个新的 CTE，其中包含原始 CTE 与作为位置参数提供的给定 selectables 的 SQL UNION。

参数:

*other¶ –

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

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

另请参阅

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

方法 sqlalchemy.sql.expression.CTE.union_all(*other: _SelectStatementForCompoundArgument[Any]) → CTE¶

返回一个新的 CTE，它包含原始 CTE 与作为位置参数提供的给定 selectable 对象的 SQL UNION ALL 联合。

参数:

*other¶ –

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

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

另请参阅

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

类 sqlalchemy.sql.expression.Executable¶

将 ClauseElement 标记为支持执行。

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

成员

类签名

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

方法 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() 方法是 generative 的，应用于 Engine 和 Query 对象的方法也是如此，这意味着当调用该方法时，将返回对象的副本，该副本将给定的参数应用于该新副本，但保持原始对象不变

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

此行为的一个例外是 Connection 对象，其中 Connection.execution_options() 方法明确地不是 generative 的。

可以传递给 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() 上）以及 SQL 语句对象上的 Executable.execution_options() 接受，并且还被 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 特定的执行选项的文档

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

1.3 版本新增。

另请参阅

Executable.execution_options()

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

将选项应用于此语句。

从广义上讲，选项是任何可以被语句的 SQL 编译器解释的 Python 对象。这些选项可以被特定的方言或特定类型的编译器使用。

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

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

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

另请参阅

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

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

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

类签名

class 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 集合是使用表绑定或其他 selectable 绑定列构造 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。

一个示例是 Table 的 Alias 派生自该 Table。

方法 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 对象，也可能是 selectable 兼容的对象，例如 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 - 生成的对象类型

方法 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 对象，也可能是 selectable 兼容的对象，例如 ORM 映射的类。
onclause¶ – 表示连接的 ON 子句的 SQL 表达式。如果保留为 None，FromClause.join() 将尝试基于外键关系连接两个表。
full¶ – 如果为 True，则渲染 FULL OUTER JOIN 而不是 LEFT OUTER JOIN。

另请参阅

FromClause.join()

Join

属性 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 对象中，它被视为 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¶

返回一个新的 selectable，应用了给定的 FETCH FIRST 条件。

这是一个数值，通常在生成的 select 中呈现为 FETCH {FIRST | NEXT} [ count ] {ROW | ROWS} {ONLY | WITH TIES} 表达式。此功能目前在 Oracle Database、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¶

返回一个新的 selectable，应用了给定的 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¶

返回一个新的 selectable，应用了给定的 LIMIT 条件。

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

注意

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

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

另请参阅

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

返回一个新的 selectable，应用了给定的 OFFSET 条件。

这是一个数值，通常在生成的 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¶

返回一个新的 selectable，应用了给定的 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¶

返回具有指定标签样式的新 selectable。

有三种可用的 “label styles”（标签样式），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 集合中获得。

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

start 和 stop 索引的行为类似于 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)

注意

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

New in version 1.4: 添加了从 ORM 泛化的 GenerativeSelect.slice() 方法。

另请参阅

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¶ – 布尔值；将在 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。

class sqlalchemy.sql.expression.HasCTE¶

声明包含 CTE 支持的类的 Mixin。

成员

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 子句中被无条件地呈现，即使在该语句或任何子选择中的其他地方没有被引用。

可选的 HasCTE.add_cte.nest_here 参数设置为 True 时，将使每个给定的 CTE 在与此语句直接一起呈现的 WITH 子句中呈现，而不是被移动到最终呈现的语句的顶部，即使此语句在更大的语句中呈现为子查询。

此方法有两个一般用途。一种是嵌入 CTE 语句，这些语句在没有被显式引用的情况下服务于某些目的，例如将 DML 语句（如 INSERT 或 UPDATE）作为 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 构造。

Changed in version 2.0: 接受多个 CTE 实例
nest_here¶ –
如果为 True，则给定的 CTE 或 CTEs 将被呈现，就好像它们在添加到此 HasCTE 时，将 HasCTE.cte.nesting 标志指定为 True。假设给定的 CTEs 在外部封闭语句中也没有被引用，则当给定此标志时，给定的 CTEs 应在此语句的级别呈现。

2.0 版本新增。

另请参阅

HasCTE.cte.nesting

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

返回一个新的 CTE，或通用表表达式实例。

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

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

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

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

Changed in version 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，使用 UPDATE 和 INSERT 以及 CTE 的 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¶

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

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

例如：

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

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

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

参数:

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

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。

一个示例是 Table 的 Alias 派生自该 Table。

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 应用 ‘grouping’（分组）。

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

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

self_group() 的基本方法 ClauseElement 仅返回 self。

class sqlalchemy.sql.expression.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¶

核心构造的最基本类，这些构造具有可以表示行的列的概念。

虽然 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。

一个示例是 Table 的 Alias 派生自该 Table。

class sqlalchemy.sql.expression.ScalarSelect¶

表示标量子查询。

通过调用 SelectBase.scalar_subquery() 方法创建 ScalarSelect。然后，该对象作为 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 相关联。

此方法从底层 Select 的 Select.correlate() 方法镜像而来。该方法应用 :meth:_sql.Select.correlate` 方法，然后针对该语句返回一个新的 ScalarSelect。

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

New in version 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 属性的通用指南。

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

对此 ClauseElement 应用 ‘grouping’（分组）。

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

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

self_group() 的基本方法 ClauseElement 仅返回 self。

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

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

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

构造一个新的 Select。

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

方法 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 为中心的示例

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

inherited from the HasCTE.add_cte() method of HasCTE

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

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

可选的 HasCTE.add_cte.nest_here 参数设置为 True 时，将使每个给定的 CTE 在与此语句直接一起呈现的 WITH 子句中呈现，而不是被移动到最终呈现的语句的顶部，即使此语句在更大的语句中呈现为子查询。

此方法有两个一般用途。一种是嵌入 CTE 语句，这些语句在没有被显式引用的情况下服务于某些目的，例如将 DML 语句（如 INSERT 或 UPDATE）作为 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 构造。

Changed in version 2.0: 接受多个 CTE 实例
nest_here¶ –
如果为 True，则给定的 CTE 或 CTEs 将被呈现，就好像它们在添加到此 HasCTE 时，将 HasCTE.cte.nesting 标志指定为 True。假设给定的 CTEs 在外部封闭语句中也没有被引用，则当给定此标志时，给定的 CTEs 应在此语句的级别呈现。

2.0 版本新增。

另请参阅

HasCTE.cte.nesting

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

inherited from the SelectBase.alias() method of SelectBase

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

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

Changed in version 1.4: SelectBase.alias() 方法现在是 SelectBase.subquery() 方法的同义词。

方法 sqlalchemy.sql.expression.Select.as_scalar() → ScalarSelect[Any]¶: inherited from the SelectBase.as_scalar() method of SelectBase

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

属性 sqlalchemy.sql.expression.Select.c¶: inherited from the SelectBase.c attribute of SelectBase

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

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

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

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

例如：

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

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

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

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

此属性通常在使用 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 中更改: Select.column_descriptions 属性返回一个仅 Core 实体集的结构，而不仅仅是仅 ORM 实体。

另请参阅

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

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

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

1.4.23 版本新增。

另请参阅

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

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

方法 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 子句进行关联时，无论此 Select 对象相对于引用相同 FROM 对象的封闭 Select 嵌套有多深，FROM 元素都将成为关联的候选对象。这与 “自动关联” 的行为相反，后者仅与直接封闭的 Select 关联。多级关联确保封闭 Select 和封闭 Select 之间的链接始终至少通过一个 WHERE/ORDER BY/HAVING/列子句，以便进行关联。

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

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

另请参阅

Select.correlate_except()

标量和关联子查询

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

标量和关联子查询

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

inherited from the Selectable.corresponding_column() method of Selectable

给定一个 ColumnElement，从此 Selectable 的 Selectable.exported_columns 集合中返回导出的 ColumnElement 对象，该对象通过公共祖先列与原始 ColumnElement 对象相对应。

参数:

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

另请参阅

Selectable.exported_columns - 用于操作的 ColumnCollection。

ColumnCollection.corresponding_column() - 实现方法。

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

inherited from the HasCTE.cte() method of HasCTE

返回一个新的 CTE，或通用表表达式实例。

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

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

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

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

Changed in version 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，使用 UPDATE 和 INSERT 以及 CTE 的 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.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。

方法 sqlalchemy.sql.expression.Select.except_(*other: _SelectStatementForCompoundArgument[_TP]) → CompoundSelect[_TP]¶

返回此 select() 构造与作为位置参数提供的给定可选对象之间的 SQL EXCEPT。

参数:

*other¶ –

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

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

方法 sqlalchemy.sql.expression.Select.except_all(*other: _SelectStatementForCompoundArgument[_TP]) → CompoundSelect[_TP]¶

返回此 select() 构造与作为位置参数提供的给定可选对象之间的 SQL EXCEPT ALL。

参数:

*other¶ –

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

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

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

inherited from the Executable.execution_options() method of Executable

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

可以使用多种作用域设置执行选项，包括每个语句、每个连接或每次执行，使用 Connection.execution_options() 等方法，以及接受选项字典的参数，例如 Connection.execute.execution_options 和 Session.execute.execution_options。

执行选项的主要特征是，与其他类型的选项（如 ORM 加载程序选项）相比，执行选项永远不会影响查询的已编译 SQL，只会影响 SQL 语句本身的调用方式或结果的提取方式。也就是说，执行选项不是 SQL 编译所容纳内容的一部分，也不被视为语句的缓存状态的一部分。

Executable.execution_options() 方法是 generative 的，应用于 Engine 和 Query 对象的方法也是如此，这意味着当调用该方法时，将返回对象的副本，该副本将给定的参数应用于该新副本，但保持原始对象不变

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

此行为的一个例外是 Connection 对象，其中 Connection.execution_options() 方法明确地不是 generative 的。

可以传递给 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() 上）以及 SQL 语句对象上的 Executable.execution_options() 接受，并且还被 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 特定的执行选项的文档

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

继承自 SelectBase.exists() 方法，该方法属于 SelectBase

返回此 selectable 的 Exists 表示形式，可用作列表达式。

返回的对象是 Exists 的实例。

另请参阅

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

1.4 版本新增。

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

继承自 SelectBase.exported_columns 属性，该属性属于 SelectBase

一个 ColumnCollection，表示此 Selectable 的 “导出” 列，不包括 TextClause 构造。

对于 SelectBase 对象，“导出” 列与 SelectBase.selected_columns 集合同义。

1.4 版本新增。

另请参阅

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

继承自 GenerativeSelect.fetch() 方法，该方法属于 GenerativeSelect

返回一个新的 selectable，应用了给定的 FETCH FIRST 条件。

这是一个数值，通常在生成的 select 中呈现为 FETCH {FIRST | NEXT} [ count ] {ROW | ROWS} {ONLY | WITH TIES} 表达式。此功能目前在 Oracle Database、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

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

方法 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 元素列表。

Deprecated since version 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 的“columns”集合隐含的 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

返回一个新的 selectable，应用了给定的 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¶

将呈现到结果 SELECT 语句的 columns 子句中的所有 ColumnElement 表达式的迭代器。

此方法在 1.4 版本中已过时，已被 Select.exported_columns 集合取代。

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

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

参数:

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

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

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

返回此 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。

一个示例是 Table 的 Alias 派生自该 Table。

method 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

Changed in version 1.4: Select.join() 现在创建一个 Join 对象，该对象位于现有 SELECT 的 FROM 子句中的 FromClause 源和给定的目标 FromClause 之间，然后将此 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()

method 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_¶ – 连接的左侧，将在 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()

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

返回此 selectable 的 “标量” 表示形式，嵌入为带有标签的子查询。

另请参阅

SelectBase.scalar_subquery().

method 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

返回一个新的 selectable，应用了给定的 LIMIT 条件。

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

注意

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

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

另请参阅

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

继承自 GenerativeSelect.offset() 方法，该方法属于 GenerativeSelect

返回一个新的 selectable，应用了给定的 OFFSET 条件。

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

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

另请参阅

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

继承自 Executable.options() 方法，该方法属于 Executable

将选项应用于此语句。

从广义上讲，选项是任何可以被语句的 SQL 编译器解释的 Python 对象。这些选项可以被特定的方言或特定类型的编译器使用。

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

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

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

另请参阅

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

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

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

返回一个新的 selectable，应用了给定的 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 统一教程中

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

创建左外连接。

参数与 Select.join() 的参数相同。

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

这是一个向后不兼容的更改，因为先前的行为大多是无用的，在任何情况下都会产生大多数数据库拒绝的未命名子查询。新行为模仿了非常成功的 ORM 中的 Query.join() 方法，以便在使用带有 Session 的 Select 对象时支持 Query 的功能可用。

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

另请参阅

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

连接 - 在 ORM 查询指南中

Select.join()

方法 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() 的用法相同。

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

继承自 HasPrefixes.prefix_with() 方法，属于 HasPrefixes

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

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

例如：

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

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

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

参数:

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

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

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

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

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

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

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

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

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

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

inherited from the SelectBase.scalar_subquery() method of SelectBase

返回此 selectable 的 ‘scalar’ 表示形式，可以用作列表达式。

返回的对象是 ScalarSelect 的一个实例。

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

请注意，标量子查询与可以使用 SelectBase.subquery() 方法生成的 FROM 级别子查询区分开来。

另请参阅

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

方法 sqlalchemy.sql.expression.Select.select(*arg: Any, **kw: Any) → Select¶: inherited from the SelectBase.select() method of SelectBase

Deprecated since version 1.4: SelectBase.select() 方法已弃用，并将在未来的版本中移除；此方法隐式地创建了一个子查询，而这应该是显式的。请先调用 SelectBase.subquery() 以创建子查询，然后再进行选择。

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

返回一个新的 select() 构造，其中给定的 FROM 表达式合并到其 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() 的典型目的是使用 join 替换默认的派生 FROM 子句，但在 FROM 子句无法完全从 columns 子句派生的情况下，也可以使用单个表元素多次调用它。

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

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

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

此集合与 FromClause.columns 的 FromClause 集合不同，因为此集合中的列不能直接嵌套在另一个 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 对象，这些对象位于 from 元素的 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() 构造在 columns 子句中建立的表达式；这些表达式会从集合中静默省略。要在 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

返回具有指定标签样式的新 selectable。

有三种可用的 “label styles”（标签样式），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 集合中获得。

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

inherited from the GenerativeSelect.slice() method of GenerativeSelect

基于切片对此语句应用 LIMIT / OFFSET。

start 和 stop 索引的行为类似于 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)

注意

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

New in version 1.4: 添加了从 ORM 泛化的 GenerativeSelect.slice() 方法。

另请参阅

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[_TP]) → CompoundSelect[_TP]¶

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

参数:

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

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

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

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

参数:

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

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

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

attribute sqlalchemy.sql.expression.Select.whereclause¶

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

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

1.4 版本新增。

method 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。

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

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

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

提示

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

提示的文本在所用数据库后端的适当位置渲染，相对于作为 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

dialect_name 选项将特定提示的渲染限制为特定后端。例如，要同时为 Oracle 数据库和 MSSql 添加提示

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 数据库优化器提示

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

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

默认情况下，此方法与调用原始 select() 时使用给定实体完全等效。例如，语句

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

应与以下内容完全等效

s = select(table1.c.b)

在这种操作模式下，如果未显式声明语句的 FROM 子句，Select.with_only_columns() 还会动态更改语句的 FROM 子句。要维护现有 FROM 集合，包括当前 columns 子句隐含的 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)

以上参数执行将 columns 集合中的有效 FROM 传输到 Select.select_from() 方法的操作，就像调用了以下内容一样

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

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¶ –
布尔参数，它将确保从当前 columns 子句隐含的 FROM 列表将首先传输到 Select.select_from() 方法。

1.4.23 版本新增。

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

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

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

提示

Select.with_statement_hint() 通常在 SELECT 语句的尾部末端添加提示。要在 SELECT 关键字后的 SELECT 语句前端放置特定于方言的提示，例如优化器提示，请使用 Select.prefix_with() 方法以获得开放式空间，或者对于特定于表的提示，可以使用 Select.with_hint()，它将提示放置在特定于方言的位置。

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

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

另请参阅

Select.with_hint()

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

class sqlalchemy.sql.expression.Selectable¶

将类标记为可选择。

成员

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

类签名

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

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

给定一个 ColumnElement，从此 Selectable 的 Selectable.exported_columns 集合中返回导出的 ColumnElement 对象，该对象通过公共祖先列与原始 ColumnElement 对象相对应。

参数:

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

另请参阅

Selectable.exported_columns - 用于操作的 ColumnCollection。

ColumnCollection.corresponding_column() - 实现方法。

attribute sqlalchemy.sql.expression.Selectable.exported_columns¶

继承自 ReturnsRows.exported_columns 属性，属于 ReturnsRows

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

“导出” 列表示由该 SQL 构造呈现的 ColumnElement 表达式的集合。主要种类是 FROM 子句的 “FROM 子句列”，例如表、连接或子查询，“SELECTed 列”，即 SELECT 语句的 “列子句” 中的列，以及 DML 语句中的 RETURNING 列。

1.4 版本新增。

另请参阅

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

继承自 HasCacheKey.inherit_cache 属性，来自 HasCacheKey

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

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

如果与对象对应的 SQL 不会基于此类的局部属性（而不是其超类）而更改，则可以在特定类上将此标志设置为 True。

另请参阅

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

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

继承自 ReturnsRows.is_derived_from() 方法，属于 ReturnsRows

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

一个示例是 Table 的 Alias 派生自该 Table。

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

返回此 Selectable 的 LATERAL 别名。

返回值是由顶层 lateral() 函数提供的 Lateral 构造。

另请参阅

LATERAL 关联 - 用法概述。

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

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

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

类签名

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

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

inherited from the HasCTE.add_cte() method of HasCTE

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

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

可选的 HasCTE.add_cte.nest_here 参数设置为 True 时，将使每个给定的 CTE 在与此语句直接一起呈现的 WITH 子句中呈现，而不是被移动到最终呈现的语句的顶部，即使此语句在更大的语句中呈现为子查询。

此方法有两个一般用途。一种是嵌入 CTE 语句，这些语句在没有被显式引用的情况下服务于某些目的，例如将 DML 语句（如 INSERT 或 UPDATE）作为 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 构造。

Changed in version 2.0: 接受多个 CTE 实例
nest_here¶ –
如果为 True，则给定的 CTE 或 CTEs 将被呈现，就好像它们在添加到此 HasCTE 时，将 HasCTE.cte.nesting 标志指定为 True。假设给定的 CTEs 在外部封闭语句中也没有被引用，则当给定此标志时，给定的 CTEs 应在此语句的级别呈现。

2.0 版本新增。

另请参阅

HasCTE.cte.nesting

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

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

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

Changed in version 1.4: SelectBase.alias() 方法现在是 SelectBase.subquery() 方法的同义词。

method sqlalchemy.sql.expression.SelectBase.as_scalar() → ScalarSelect[Any]¶: Deprecated since version 1.4: SelectBase.as_scalar() 方法已弃用，并将在未来的版本中删除。请参考 SelectBase.scalar_subquery()。

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

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

inherited from the Selectable.corresponding_column() method of Selectable

给定一个 ColumnElement，从此 Selectable 的 Selectable.exported_columns 集合中返回导出的 ColumnElement 对象，该对象通过公共祖先列与原始 ColumnElement 对象相对应。

参数:

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

另请参阅

Selectable.exported_columns - 用于操作的 ColumnCollection。

ColumnCollection.corresponding_column() - 实现方法。

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

inherited from the HasCTE.cte() method of HasCTE

返回一个新的 CTE，或通用表表达式实例。

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

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

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

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

Changed in version 1.3.13: 添加了对前缀的支持。特别是 - MATERIALIZED 和 NOT MATERIALIZED。

参数:

name¶ – common table expression 的名称。类似于 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，使用 UPDATE 和 INSERT 以及 CTE 的 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.SelectBase.exists() → Exists¶

返回此 selectable 的 Exists 表示形式，可用作列表达式。

返回的对象是 Exists 的实例。

另请参阅

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

1.4 版本新增。

attribute sqlalchemy.sql.expression.SelectBase.exported_columns¶

一个 ColumnCollection，表示此 Selectable 的 “导出” 列，不包括 TextClause 构造。

对于 SelectBase 对象，“导出” 列与 SelectBase.selected_columns 集合同义。

1.4 版本新增。

另请参阅

Select.selected_columns

method sqlalchemy.sql.expression.SelectBase.get_label_style() → SelectLabelStyle¶

检索当前标签样式。

由子类实现。

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

继承自 HasCacheKey.inherit_cache 属性，来自 HasCacheKey

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

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

如果与对象对应的 SQL 不会基于此类的局部属性（而不是其超类）而更改，则可以在特定类上将此标志设置为 True。

另请参阅

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

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

继承自 ReturnsRows.is_derived_from() 方法，属于 ReturnsRows

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

一个示例是 Table 的 Alias 派生自该 Table。

method sqlalchemy.sql.expression.SelectBase.label(name: str | None) → Label[Any]¶: 返回此 selectable 的 “标量” 表示形式，嵌入为带有标签的子查询。

另请参阅

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 的副本。

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

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

返回此 selectable 的 ‘scalar’ 表示形式，可以用作列表达式。

返回的对象是 ScalarSelect 的一个实例。

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

请注意，标量子查询与可以使用 SelectBase.subquery() 方法生成的 FROM 级别子查询区分开来。

另请参阅

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

method sqlalchemy.sql.expression.SelectBase.select(*arg: Any, **kw: Any) → Select¶: Deprecated since version 1.4: SelectBase.select() 方法已弃用，并将在未来的版本中移除；此方法隐式地创建了一个子查询，而这应该是显式的。请先调用 SelectBase.subquery() 以创建子查询，然后再进行选择。

attribute sqlalchemy.sql.expression.SelectBase.selected_columns¶

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

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

注意

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

另请参阅

1.4 版本新增。

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

返回具有指定标签样式的新 selectable。

由子类实现。

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 子类（包括 Select、 CompoundSelect 和 TextualSelect）上调用 SelectBase.alias() 方法创建。当在 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 版本后已弃用: Subquery.as_scalar() 方法（在 1.4 版本之前为 Alias.as_scalar()）已弃用，将在未来的版本中删除；请在使用构造子查询对象之前，使用 Select.scalar_subquery() 方法（对于 select() 构造），或者对于 ORM，使用 Query.scalar_subquery() 方法。

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

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

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

如果与对象对应的 SQL 不会基于此类的局部属性（而不是其超类）而更改，则可以在特定类上将此标志设置为 True。

另请参阅

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

class 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 级服务的支持。它本身很有用，可以作为用于生成快速 SQL 语句的临时构造，而无需使用更完善的 Table。

类签名

class sqlalchemy.sql.expression.TableClause (sqlalchemy.sql.roles.DMLTableRole, sqlalchemy.sql.expression.Immutable, sqlalchemy.sql.expression.NamedFromClause)

method 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 表达式呈现为字符串，可能内联绑定参数？

attribute sqlalchemy.sql.expression.TableClause.c¶

继承自 FromClause.c 属性，属于 FromClause

是 FromClause.columns 的同义词

返回:: 一个 ColumnCollection

attribute sqlalchemy.sql.expression.TableClause.columns¶

继承自 FromClause.columns 属性，属于 FromClause

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

columns 或 c 集合是使用表绑定列或其他可选绑定列构造 SQL 表达式的入口点。

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

返回:: 一个 ColumnCollection 对象。

method 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¶ –
传递到所有“visit”方法中编译器内的其他可选参数字典。这允许将任何自定义标志传递到自定义编译构造，例如。它也用于传递 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¶

inherited from the Selectable.corresponding_column() method of Selectable

给定一个 ColumnElement，从此 Selectable 的 Selectable.exported_columns 集合中返回导出的 ColumnElement 对象，该对象通过公共祖先列与原始 ColumnElement 对象相对应。

参数:

column¶ – 目标 ColumnElement 以进行匹配。
require_embedded¶ – 仅当给定的 ColumnElement 实际存在于此 Selectable 的子元素中时，才返回给定 ColumnElement 的对应列。通常，如果列与此 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。

一个示例是 Table 的 Alias 派生自该 Table。

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 的副本。

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

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

继承自 FromClause.schema 属性，来自 FromClause

为此 FromClause 定义 ‘schema’ 属性。

对于大多数对象，这通常是 None，但 Table 对象除外，在 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 应用 ‘grouping’（分组）。

此方法被子类重写以返回 “grouping” 构造，即括号。特别是，当 “binary” 表达式放置到更大的表达式中时，以及当 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 Database 和 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() - 用法指南和参数

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

类签名

class sqlalchemy.sql.expression.TableSample (sqlalchemy.sql.expression.FromClauseAlias)

类 sqlalchemy.sql.expression.TableValuedAlias¶

针对“表值”SQL 函数的别名。

此构造提供了一个 SQL 函数，该函数返回要在 SELECT 语句的 FROM 子句中使用的列。该对象使用 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()

类签名

class 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¶: 返回设置了 lateral 标志的新的 TableValuedAlias，以便它呈现为 LATERAL。

另请参阅

lateral()

方法 sqlalchemy.sql.expression.TableValuedAlias.render_derived(name: str | None = None, with_types: bool = False) → TableValuedAlias¶

将 “render derived” 应用于此 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() 等。

TextualSelect 构造通过 TextClause.columns() 方法生成 - 有关详细信息，请参阅该方法。

在版本 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)

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

inherited from the HasCTE.add_cte() method of HasCTE

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

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

可选的 HasCTE.add_cte.nest_here 参数设置为 True 时，将使每个给定的 CTE 在与此语句直接一起呈现的 WITH 子句中呈现，而不是被移动到最终呈现的语句的顶部，即使此语句在更大的语句中呈现为子查询。

此方法有两个一般用途。一种是嵌入 CTE 语句，这些语句在没有被显式引用的情况下服务于某些目的，例如将 DML 语句（如 INSERT 或 UPDATE）作为 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 构造。

Changed in version 2.0: 接受多个 CTE 实例
nest_here¶ –
如果为 True，则给定的 CTE 或 CTEs 将被呈现，就好像它们在添加到此 HasCTE 时，将 HasCTE.cte.nesting 标志指定为 True。假设给定的 CTEs 在外部封闭语句中也没有被引用，则当给定此标志时，给定的 CTEs 应在此语句的级别呈现。

2.0 版本新增。

另请参阅

HasCTE.cte.nesting

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

inherited from the SelectBase.alias() method of SelectBase

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

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

Changed in version 1.4: SelectBase.alias() 方法现在是 SelectBase.subquery() 方法的同义词。

方法 sqlalchemy.sql.expression.TextualSelect.as_scalar() → ScalarSelect[Any]¶: inherited from the SelectBase.as_scalar() method of SelectBase

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

属性 sqlalchemy.sql.expression.TextualSelect.c¶: inherited from the SelectBase.c attribute of SelectBase

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

方法 sqlalchemy.sql.expression.TextualSelect.compare(other: ClauseElement, **kw: Any) → bool¶

继承自 ClauseElement.compare() 方法，属于 ClauseElement

将此 ClauseElement 与给定的 ClauseElement 进行比较。

子类应覆盖默认行为，即直接标识比较。

**kw 是子类 compare() 方法使用的参数，可用于修改比较的标准（请参阅 ColumnElement）。

方法 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¶ –
传递到所有“visit”方法中编译器内的其他可选参数字典。这允许将任何自定义标志传递到自定义编译构造，例如。它也用于传递 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 表达式呈现为字符串，可能内联绑定参数？

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

inherited from the Selectable.corresponding_column() method of Selectable

给定一个 ColumnElement，从此 Selectable 的 Selectable.exported_columns 集合中返回导出的 ColumnElement 对象，该对象通过公共祖先列与原始 ColumnElement 对象相对应。

参数:

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

另请参阅

Selectable.exported_columns - 用于操作的 ColumnCollection。

ColumnCollection.corresponding_column() - 实现方法。

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

inherited from the HasCTE.cte() method of HasCTE

返回一个新的 CTE，或通用表表达式实例。

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

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

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

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

Changed in version 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，使用 UPDATE 和 INSERT 以及 CTE 的 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.TextualSelect.execution_options(**kw: Any) → Self¶

inherited from the Executable.execution_options() method of Executable

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

可以使用多种作用域设置执行选项，包括每个语句、每个连接或每次执行，使用 Connection.execution_options() 等方法，以及接受选项字典的参数，例如 Connection.execute.execution_options 和 Session.execute.execution_options。

执行选项的主要特征是，与其他类型的选项（如 ORM 加载程序选项）相比，执行选项永远不会影响查询的已编译 SQL，只会影响 SQL 语句本身的调用方式或结果的提取方式。也就是说，执行选项不是 SQL 编译所容纳内容的一部分，也不被视为语句的缓存状态的一部分。

Executable.execution_options() 方法是 generative 的，应用于 Engine 和 Query 对象的方法也是如此，这意味着当调用该方法时，将返回对象的副本，该副本将给定的参数应用于该新副本，但保持原始对象不变

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

此行为的一个例外是 Connection 对象，其中 Connection.execution_options() 方法明确地不是 generative 的。

可以传递给 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() 上）以及 SQL 语句对象上的 Executable.execution_options() 接受，并且还被 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 特定的执行选项的文档

方法 sqlalchemy.sql.expression.TextualSelect.exists() → Exists¶

继承自 SelectBase.exists() 方法，该方法属于 SelectBase

返回此 selectable 的 Exists 表示形式，可用作列表达式。

返回的对象是 Exists 的实例。

另请参阅

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

1.4 版本新增。

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

继承自 SelectBase.exported_columns 属性，该属性属于 SelectBase

一个 ColumnCollection，表示此 Selectable 的 “导出” 列，不包括 TextClause 构造。

对于 SelectBase 对象，“导出” 列与 SelectBase.selected_columns 集合同义。

1.4 版本新增。

另请参阅

方法 sqlalchemy.sql.expression.TextualSelect.get_children(*, omit_attrs: Tuple[str, ...] = (), **kw: Any) → Iterable[HasTraverseInternals]¶

继承自 HasTraverseInternals.get_children() 方法，来自 HasTraverseInternals

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

这用于访问遍历。

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

方法 sqlalchemy.sql.expression.TextualSelect.get_execution_options() → _ExecuteOptions¶: 继承自 Executable.get_execution_options() 方法，该方法属于 Executable

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

1.3 版本新增。

另请参阅

Executable.execution_options()

方法 sqlalchemy.sql.expression.TextualSelect.get_label_style() → SelectLabelStyle¶

继承自 SelectBase.get_label_style() 方法，属于 SelectBase

检索当前标签样式。

由子类实现。

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

继承自 HasCacheKey.inherit_cache 属性，来自 HasCacheKey

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

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

如果与对象对应的 SQL 不会基于此类的局部属性（而不是其超类）而更改，则可以在特定类上将此标志设置为 True。

另请参阅

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

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

继承自 ReturnsRows.is_derived_from() 方法，属于 ReturnsRows

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

一个示例是 Table 的 Alias 派生自该 Table。

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

返回此 selectable 的 “标量” 表示形式，嵌入为带有标签的子查询。

另请参阅

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 的副本。

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

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

inherited from the SelectBase.scalar_subquery() method of SelectBase

返回此 selectable 的 ‘scalar’ 表示形式，可以用作列表达式。

返回的对象是 ScalarSelect 的一个实例。

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

请注意，标量子查询与可以使用 SelectBase.subquery() 方法生成的 FROM 级别子查询区分开来。

另请参阅

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

方法 sqlalchemy.sql.expression.TextualSelect.select(*arg: Any, **kw: Any) → Select¶: inherited from the SelectBase.select() method of SelectBase

Deprecated since version 1.4: SelectBase.select() 方法已弃用，并将在未来的版本中移除；此方法隐式地创建了一个子查询，而这应该是显式的。请先调用 SelectBase.subquery() 以创建子查询，然后再进行选择。

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

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

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

对于 TextualSelect 构造，此集合包含传递给构造函数的 ColumnElement 对象，通常通过 TextClause.columns() 方法传递。

1.4 版本新增。

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

继承自 ClauseElement.self_group() 方法，来自 ClauseElement

对此 ClauseElement 应用 ‘grouping’（分组）。

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

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

ClauseElement 的基本 self_group() 方法仅返回 self。

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

返回具有指定标签样式的新 selectable。

由子类实现。

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

表示可在语句中用作 FROM 元素的 VALUES 构造。

Values 对象由 values() 函数创建。

1.4 版本新增。

成员

alias(), data(), lateral(), scalar_values()

类签名

类 sqlalchemy.sql.expression.Values (sqlalchemy.sql.roles.InElementRole, sqlalchemy.sql.expression.Generative, sqlalchemy.sql.expression.LateralFromClause)

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

返回一个新的 Values 构造，它是此构造的副本，并带有给定的名称。

此方法是 FromClause.alias() 方法的 VALUES 特定专业化。

另请参阅