SELECT 和相关结构

术语 “selectable” 是指表示数据库行的任何对象。在 SQLAlchemy 中，这些对象源自 Selectable，最突出的是 Select，它表示 SQL SELECT 语句。Selectable 的子集是 FromClause，它表示可以位于 Select 语句的 FROM 子句中的对象。的显著特征 FromClause 是 FromClause.c attribute，它是 FROM 中包含的所有列的命名空间 子句（这些元素本身就是 ColumnElement 子类）。

可选择的基础构造函数

顶级 “FROM clause” 和 “SELECT” 构造函数。

对象名称	描述
except_（*选择）	返回多个可选项的 EXCEPT。
except_all（*选择）	返回多个可选对象的 EXCEPT ALL。
存在（[__argument]）	构造新的 Exists 构造。
intersect（*选择）	返回多个可选项的 INTERSECT。
intersect_all（*选择）	返回多个可选对象的 INTERSECT ALL。
select（*实体， **__kw）	构造一个新的 Select。
table（名称， *列， **kw）	生成新的 TableClause。
union（*选择）	返回多个可选项的 UNION。
union_all（*选择）	返回多个可选项的 UNION ALL。
值（*列， [名称， literal_binds]）	构造 Values 构造。

函数 sqlalchemy.sql.expression 中。except_（*选择： _SelectStatementForCompoundArgument）→ CompoundSelect

返回多个可选项的 EXCEPT。

返回的对象是 CompoundSelect 的 CompoundSelect 中。

参数

*selects—— Select 实例的列表。

函数 sqlalchemy.sql.expression 中。except_all（*选择： _SelectStatementForCompoundArgument）→ CompoundSelect

返回多个可选对象的 EXCEPT ALL。

返回的对象是 CompoundSelect 的 CompoundSelect 中。

参数

*selects—— Select 实例的列表。

函数 sqlalchemy.sql.expression 中。exists（__argument：_ColumnsClauseArgument[Any]SelectBaseScalarSelect[Any]None=None）→ 存在

构造新的 Exists 构造。

exists（） 可以自行调用以生成 Exists 结构，它将接受简单的 WHERE 条件：

exists_criteria = exists().where(table1.c.col1 == table2.c.col2)

但是，为了在构造 SELECT 时具有更大的灵活性，可以将现有的 Select 构造转换为 存在，最方便的是使用 SelectBase.exists（） 方法：

exists_criteria = (
    select(table2.c.col2).where(table1.c.col1 == table2.c.col2).exists()
)

然后，在封闭的 SELECT 中使用 EXISTS 条件：

stmt = select(table1.c.col1).where(exists_criteria)

上述声明将采用以下格式：

SELECT col1 FROM table1 WHERE EXISTS
(SELECT table2.col2 FROM table2 WHERE table2.col2 = table1.col1)

另请参阅

EXISTS 子查询 - 在 2.0 样式教程中。

SelectBase.exists（） - 将 SELECT 转换为 EXISTS 子句。

函数 sqlalchemy.sql.expression 中。intersect（*选择： _SelectStatementForCompoundArgument）→ CompoundSelect

返回多个可选项的 INTERSECT。

返回的对象是 CompoundSelect 的 CompoundSelect 中。

参数

*selects—— Select 实例的列表。

函数 sqlalchemy.sql.expression 中。intersect_all（*选择： _SelectStatementForCompoundArgument）→ CompoundSelect

返回多个可选对象的 INTERSECT ALL。

返回的对象是 CompoundSelect 的 CompoundSelect 中。

参数

*selects—— Select 实例的列表。

函数 sqlalchemy.sql.expression 中。select（*entities： _ColumnsClauseArgument[Any]， **__kw： Any）→ select[Any]

构造一个新的 Select。

在 1.4 版本加入： - select（） 函数现在按位置接受列参数。顶级 select（） 函数会自动使用 1.x 或 2.x 样式的 API，具体取决于 传入的参数;使用 select（） 从 sqlalchemy.future 模块将强制仅使用 2.x 样式的构造函数。

类似的功能也可以通过 FromClause.select（） 方法。 From子句。

另请参阅

使用 SELECT 语句 - 在 SQLAlchemy Unified 教程中

参数

实体 –

要从中选择的实体。对于 Core 用法，这通常是一系列 ColumnElement 和/或 From子句 对象，这些对象将构成结果的 columns 子句 陈述。 对于作为 FromClause（通常为 Table 或 Alias 对象）、FromClause.c 提取集合 以形成 ColumnElement 对象的集合。

此参数也将接受 TextClause 构造为 given，以及 ORM 映射的类。

函数 sqlalchemy.sql.expression 中。table（name： str， *columns： ColumnClause[Any]， **kw： 任意）→ TableClause

生成新的 TableClause。

返回的对象是 TableClause 的 表示 Schema 级别的 “syntactical” 部分 Table 对象。它可用于构造轻量级表构造。

参数

• 
  name- 表的名称。

• 
  columns- column（） 结构的集合。

• 
  架构 –

  
  此表的架构名称。

  
  在 1.3.18 版本加入： table（） 现在可以接受 schema 参数。

函数 sqlalchemy.sql.expression 中。union（*selects： _SelectStatementForCompoundArgument）→ CompoundSelect

返回多个可选项的 UNION。

返回的对象是 CompoundSelect 的 CompoundSelect 中。

类似的 union（） 方法在所有 FromClause 子类。

参数

• 
  *selects—— Select 实例的列表。

• 
  **kwargs —— 可用的关键字参数与 select（） 的

函数 sqlalchemy.sql.expression 中。union_all（*选择： _SelectStatementForCompoundArgument）→ CompoundSelect

返回多个可选项的 UNION ALL。

返回的对象是 CompoundSelect 的 CompoundSelect 中。

类似的 union_all（） 方法在所有 FromClause 子类。

参数

*selects—— Select 实例的列表。

函数 sqlalchemy.sql.expression 中。values（*columns： ColumnClause[Any]， name：strNone=None， literal_binds： bool = False）→ 值

构造 Values 构造。

的列表达式和实际数据 值分两个单独的步骤给出。 这 constructor 接收列表达式，通常为 column（） 结构、 然后，数据通过 Values.data（） 方法作为列表，可以多次调用以添加更多数据，例如：

from sqlalchemy import column
from sqlalchemy import values

value_expr = values(
    column("id", Integer),
    column("name", String),
    name="my_values",
).data([(1, "name1"), (2, "name2"), (3, "name3")])

参数

• 
  *columns —— 列表达式，通常由 column（） 对象。

• 
  name —— 这个 VALUES 结构的名称。如果省略，则 VALUES 构造将在 SQL 表达式中未命名。不同的后端可能有不同的要求。

• 
  literal_binds – 默认为 false。是否在 SQL 输出中内联呈现数据值，而不是使用绑定参数。

Selectable Modifier 构造函数

此处列出的函数更常作为 FromClause 和 Selectable 元素，例如，alias（） 函数通常通过 FromClause.alias（） 方法。

对象名称	描述
alias（selectable[， name， flat]）	返回给定 FromClause 的命名别名。
cte（selectable[， name， 递归]）	返回新的 CTE 或公用表表达式实例。
join（left， right[， onclause， isouter， ...]）	生成一个 Join 对象，给定两个 From子句 表达 式。
lateral（可选 [， 名称]）	返回 Lateral 对象。
outerjoin（left， right[， on子句， full]）	返回 OUTER JOIN 子句元素。
tablesample（可选， sampling[， name， seed]）	返回 TableSample 对象。

函数 sqlalchemy.sql.expression 中。alias（可选： FromClause， name：strNone=None， flat： bool = False）→ NamedFromClause

返回给定 FromClause 的命名别名。

对于 Table 和 Join 对象，返回类型为 Alias 对象。其他类型的 NamedFromClause 可以为其他类型的 FromClause 对象返回对象。

命名别名表示在 SQL 中分配了备用名称的任何 FromClause，通常在生成时使用 AS 子句，例如 SELECT * FROM table AS aliasname .

等效功能可通过 FromClause.alias（） 方法在所有 FromClause 对象上都可用。

参数

• 
  selectable —— 任何 FromClause 子类，比如表、select 语句等。

• 
  name – 要分配为别名的字符串名称。如果为 None，则将在编译时确定性地生成名称。确定性意味着保证该名称对于同一语句中使用的其他构造是唯一的，并且对于同一语句对象的每次连续编译，该名称也将相同。

• 
  flat – 如果给定的可选对象是 Join 的实例，则将被传递给 - 参见 Join.alias（） 了解详细信息。

函数 sqlalchemy.sql.expression 中。cte（可选：HasCTE，name：strNone=None，递归：bool = False）→ CTE

返回新的 CTE 或公用表表达式实例。

请参阅 HasCTE.cte（） 以了解有关 CTE 用法的详细信息。

函数 sqlalchemy.sql.expression 中。join（left： _FromClauseArgument， right： _FromClauseArgument， onclause：_OnClauseArgumentNone=None， isouter： bool = False， full： bool = False）→ 加入

生成一个 Join 对象，给定两个 From子句 表达 式。

例如：

j = join(
    user_table, 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

如果任何 FromClause 对象（例如，例如 表）使用 FromClause.join（） 方法。

参数

• 
  left- 联接的左侧。

• 
  right —— 连接线的右侧;这是任意的 FromClause 对象（例如 Table 对象，也可以是可选兼容的对象，例如 ORM 映射的类。

• 
  on子句– 表示联接的 ON 子句的 SQL 表达式。如果保留为 None，则 FromClause.join（） 将尝试 根据外键关系联接两个表。

• 
  isouter——如果为 True，则渲染 LEFT OUTER JOIN，而不是 JOIN。

• 
  full – 如果为 True，则渲染 FULL OUTER JOIN，而不是 JOIN。

另请参阅

FromClause.join（） - 基于给定左侧的方法形式。

Join - 生成的对象的类型。

函数 sqlalchemy.sql.expression 中。lateral（selectable：SelectBase_FromClauseArgument， name：strNone=None）→ LateralFromClause

返回 Lateral 对象。

Lateral 是别名 子类，该子类表示 应用了 LATERAL 关键字的子查询。

LATERAL 子查询的特殊行为是它出现在封闭 SELECT 的 FROM 子句中，但可能与该 SELECT 的其他 FROM 子句相关。这是 subquery 的特殊情况，仅受少数后端支持，目前是较新的 PostgreSQL 版本。

另请参阅

LATERAL correlation - 用法概述。

函数 sqlalchemy.sql.expression 中。outerjoin（left： _FromClauseArgument， right： _FromClauseArgument， onclause：_OnClauseArgumentNone=None， full： bool = False）→ 加入

返回 OUTER JOIN 子句元素。

返回的对象是 Join 的实例。

类似的功能也可以通过 FromClause.outerjoin（） 方法 From子句。

参数

• 
  left- 联接的左侧。

• 
  right- 联接的右侧。

• 
  on子句– ON 子句的可选标准，派生自左右之间建立的外键关系。

要将连接链接在一起，请使用 FromClause.join（） 或 FromClause.outerjoin（） 方法。 Join 对象。

函数 sqlalchemy.sql.expression 中。tablesample（selectable： _FromClauseArgument， sampling：floatFunction[Any]， name：strNone=None， seed：roles.ExpressionElementRole[Any]None=None）→ TableSample（表样本

返回 TableSample 对象。

TableSample 是别名 子类，该子类表示 应用了 TABLESAMPLE 子句的表。 表样本（） 也可从 FromClause 获得 类通过 FromClause.tablesample（） 方法。

TABLESAMPLE 子句允许从 table 中选择随机选择的大致行百分比。它支持多种采样方法，最常见的是 BERNOULLI 和 SYSTEM。

例如：

from sqlalchemy import func

selectable = people.tablesample(
    func.bernoulli(1), name="alias", seed=func.random()
)
stmt = select(selectable.c.people_id)

假设 people 的列people_id，上述语句将呈现为：

SELECT alias.people_id FROM
people AS alias TABLESAMPLE bernoulli(:bernoulli_1)
REPEATABLE (random())

参数

• 
  sampling—— 介于 0 和 100 之间的浮点百分比，或 功能。

• 
  name – 可选的别名

• 
  seed——任何实值 SQL 表达式。指定后，还会呈现 REPEATABLE 子子句。

可选类文档

此处的类是使用 可选择的 Foundational Constructors 和 Selectable 修饰符构造函数。

对象名称	描述
别名	表示表或可选别名 （AS）。
别名返回行	针对表、子查询和其他可选项的别名的基类。
CompoundSelect 化合物选择	构成 UNION、UNION ALL 和其他基于 SELECT 的集合作的基础。
CTE	表示公共表表达式。
可执行	将 ClauseElement 标记为支持执行。
存在	表示 EXISTS 子句。
From子句	表示可在 FROM 中使用的元素 子句。
生成选择	SELECT 语句的基类，可在其中添加其他元素。
哈斯 CTE	Mixin 声明一个类以包含 CTE 支持。
Has前缀
HasSuffixes
加入	表示两个之间的 JOIN 构造 From子句 元素。
侧面的	表示 LATERAL 子查询。
返回行	Core 构造的最基类，这些构造具有一些可以表示行的列的概念。
标量选择	表示标量子查询。
标量值	表示可用作语句中的 COLUMN 元素的标量 VALUES 构造。
选择	表示 SELECT 语句。
选择	将类标记为可选。
选择基地	SELECT 语句的基类。
子查询	表示 SELECT 的子查询。
TableClause	表示最小的 “table” 构造。
TableSample 表格	表示 TABLESAMPLE 子句。
TableValuedAlias	“table valued” SQL 函数的别名。
文本选择	将 TextClause 构造包装在 选择基地 接口。
值	表示可用作语句中的 FROM 元素的 VALUES 构造。

类 sqlalchemy.sql.expression 中。别名

表示表或可选别名 （AS）。

表示别名，通常使用 AS 关键字（或在某些数据库（如 Oracle Database）上不使用关键字）应用于 SQL 语句中的任何表或子 SELECT。

此对象由 alias（） 模块级函数以及 FromClause.alias（） 构造 可用方法 在所有 FromClause 子类上。

另请参阅

FromClause.alias（）

成员

inherit_cache

类签名

类 sqlalchemy.sql.expression.Alias （ sqlalchemy.sql.roles.DMLTableRole ， sqlalchemy.sql.expression.FromClauseAlias ）

属性 sqlalchemy.sql.expression.Alias. inherit_cache：boolNone = True

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

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

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

另请参阅

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

类 sqlalchemy.sql.expression 中。别名返回行

针对表、子查询和其他可选项的别名的基类。

成员

描述， is_derived_from（）， 原始

类签名

类 sqlalchemy.sql.expression.AliasedReturnsRows （ sqlalchemy.sql.expression.NoInit ， sqlalchemy.sql.expression.NamedFromClause ）

属性 sqlalchemy.sql.expression.AliasedReturnsRows. 说明

方法 sqlalchemy.sql.expression.AliasedReturnsRows. is_derived_from（fromclause：FromClauseNone）→ bool

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

例如，Table 的别名是从该 Table 派生的。

attribute original 属性 sqlalchemy.sql.expression.AliasedReturnsRows.

Legacy 用于引用 Alias.original 的方言。

类 sqlalchemy.sql.expression 中。CompoundSelect（复合选择

构成 UNION、UNION ALL 和其他基于 SELECT 的集合作的基础。

另请参阅

联合（）

union_all（）

相交（）

intersect_all（）

除外（）

except_all（）

成员

add_cte（）， 别名（）， as_scalar（）， c， corresponding_column（）， cte（）， execution_options（）， exists（）， exported_columns， fetch（）， get_execution_options（）， get_label_style（）， group_by（）， is_derived_from（）， 标签（）， 横向（）， 限制（）， 偏移（）， 选项（）， order_by（）， replace_selectable（）， scalar_subquery（）， 选择（）， selected_columns， self_group（）， set_label_style（）， slice（）、subquery（）、with_for_update（）

类签名

类 sqlalchemy.sql.expression.CompoundSelect （ sqlalchemy.sql.expression.HasCompileState ， sqlalchemy.sql.expression.GenerativeSelect ， sqlalchemy.sql.expression.ExecutableReturnsRows ）

方法 sqlalchemy.sql.expression.CompoundSelect. add_cte（*ctes： CTE， nest_here： bool = False）→ Self

继承自HasCTE 的 HasCTE.add_cte（） 方法

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

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

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

此方法有两个一般用途。一种是嵌入具有某种用途而不明确引用的 CTE 语句，例如将 DML 语句（如 INSERT 或 UPDATE）嵌入为 CTE 的用例，该 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 construct 生成 “upsert”：

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

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

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

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

print(update_statement)

上述语句呈现为：

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

在 1.4.21 版本加入.

参数

• *ctes –

  
  零个或多个 CTE 构造。

  
  在 2.0 版更改： 接受多个 CTE 实例

• nest_here –

  
  如果为 True，则给定的一个或多个 CTE 将呈现，就像它们在添加到此 HasCTE 时将 HasCTE.cte.nesting 标志指定为 True 一样。假设给定的 CTE 在外部封闭语句中也没有引用，则给定的 CTE 应在给定此标志时在此语句的级别呈现。

  
  2.0 版的新Function。

  
  另请参阅

  
  HasCTE.cte.嵌套

method sqlalchemy.sql.expression.CompoundSelect. alias（name：strNone=None， flat： bool = False）→ 子查询

继承自SelectBase 的 SelectBase.alias（） 方法

返回针对 this 的命名子查询 SelectBase 的 Pod 中。

对于 SelectBase（而不是 FromClause），这将返回一个 Subquery 对象，该对象的行为与与 From子句。

在 1.4 版本发生变更： SelectBase.alias（） method 现在是 SelectBase.subquery（） 方法的同义词。

方法 sqlalchemy.sql.expression.CompoundSelect. as_scalar（）→ ScalarSelect[Any]

继承自SelectBase 的 SelectBase.as_scalar（） 方法

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

属性 sqlalchemy.sql.expression.CompoundSelect. c

继承自SelectBase 的 SelectBase.c属性

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

方法 sqlalchemy.sql.expression.CompoundSelect. corresponding_column（column： KeyedColumnElement[Any]， require_embedded： bool = False）→KeyedColumnElement[任何]无

继承自 Selectable.corresponding_column() Selectable 的方法

给定一个 ColumnElement，返回导出的 ColumnElement 对象 Selectable.exported_columns collection 的 这与 原始 ColumnElement 通过公共上级列。

参数

• 
  column—— 目标 ColumnElement 进行匹配。

• 
  require_embedded —— 如果给定的 ColumnElement ColumnElement （列元素） 实际上存在于子元素中 的这个 Selectable。通常，如果该列仅与此 Selectable 的导出列之一共享一个共同的祖先，则该列将匹配。

另请参阅

Selectable.exported_columns - 的 ColumnCollection 系列 用于作。

ColumnCollection.corresponding_column() -实现 方法。

方法 sqlalchemy.sql.expression.CompoundSelect. cte（name：strNone=None， 递归： bool = False， 嵌套： bool = False）→ CTE

继承自HasCTE 的 HasCTE.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（） method 可能是 用于建立这些。

在 1.3.13 版本发生变更： 添加了对前缀的支持。特别是 - MATERIALIZED 和 NOT MATERIALIZED。

参数

• 
  name – 公共表表达式的名称。 喜欢 FromClause.alias（）中，名称可以保留为 none ，在这种情况下，将在查询编译时使用匿名符号。

• 
  recursive – 如果为 True，将渲染 WITH RECURSIVE。递归公用表表达式旨在与 UNION ALL 结合使用，以便从已选择的行中派生行。

• 
  嵌套 –

  
  如果为 True，则会在本地将 CTE 呈现到引用它的语句。对于更复杂的场景HasCTE.add_cte，使用 HasCTE.add_cte.nest_here 参数也可以更仔细地使用 控制特定 CTE 的确切位置。

  
  在 1.4.24 版本加入.

  
  另请参阅

  
  HasCTE.add_cte（）

以下示例包括 PostgreSQL 文档中的两个示例，网址为 https://www.postgresql.org/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 结合使用的更新插入：

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（） - 的 ORM 版本 HasCTE.cte（） 的

方法 sqlalchemy.sql.expression.CompoundSelect. execution_options（**kw： Any）→ Self

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

为语句设置非 SQL 选项，这些选项在执行过程中生效。

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

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

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

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

此行为的一个例外是 Connection object，其中该方法 Connection.execution_options() 明确不是生成式的。

可以传递给 Executable.execution_options() 和其他相关方法以及 参数字典包括显式使用的参数 by 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 parameter 的 Connection.execute（） 上，另外通过 Executable.execution_options() 在 SQL 语句对象上，以及通过 Session.execute（） 等 ORM 构造。

• 
  Connection.execution_options.compiled_cache - 表示将用作 SQL 编译缓存 对于 Connection 或 Engine，以及 Session.execute（） 等 ORM 方法。可以作为 None 传递以禁用语句的缓存。 此选项不被 Executable.execution_options() 因为不建议在 statement 对象中携带编译缓存。

• 
  Connection.execution_options.schema_translate_map - 使用的架构名称的映射 Schema Translate Map 功能，由 Connection、Engine、 Executable 以及 Session.execute（） 等 ORM 结构。

另请参阅

Connection.execution_options()

Connection.execute.execution_options

Session.execute.execution_options

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

method sqlalchemy.sql.expression.CompoundSelect. exists（）→ 存在

继承自SelectBase 的 SelectBase.exists（） 方法

返回此可选对象的 Exists 表示形式，该表示形式可用作列表达式。

返回的对象是 Exists 的实例。

另请参阅

存在（）

EXISTS 子查询 - 在 2.0 样式教程中。

在 1.4 版本加入.

属性 sqlalchemy.sql.expression.CompoundSelect. exported_columns

继承自SelectBase 的 SelectBase.exported_columns属性

一个 ColumnCollection 表示 “exported” 列，不包括 TextClause 构造。

SelectBase 的 “exported” 列 object 是同义词 与 SelectBase.selected_columns 系列。

在 1.4 版本加入.

另请参阅

Select.exported_columns

Selectable.exported_columns

FromClause.exported_columns

method sqlalchemy.sql.expression.CompoundSelect. fetch（count： _LimitOffsetType， with_ties： bool = False， percent： bool= false）→ Self

继承自 GenerativeSelect 的 GenerativeSelect.fetch（） 方法

返回应用了给定 FETCH FIRST 标准的新 selectable。

这是一个数值，通常在结果的 select 中呈现为 FETCH {FIRST | NEXT} [ count ] {ROW | ROWS} {ONLY | WITH TIES} expression。此功能目前已针对 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

另请参阅

生成选择.limit（）

生成选择.offset（）

方法 sqlalchemy.sql.expression.CompoundSelect. get_execution_options（）→ _ExecuteOptions

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

获取将在执行过程中生效的非 SQL 选项。

在 1.3 版本加入.

另请参阅

Executable.execution_options()

方法 sqlalchemy.sql.expression.CompoundSelect. get_label_style（）→ SelectLabelStyle

继承自 GenerativeSelect.get_label_style() GenerativeSelect 的方法

检索当前标签样式。

在 1.4 版本加入.

方法 sqlalchemy.sql.expression.CompoundSelect. group_by（_GenerativeSelect__first：Literal[None，_NoArg.NO_ARG]_ColumnExpressionOrStrLabelArgument[Any]=_NoArg.NO_ARG， *clauses： _ColumnExpressionOrStrLabelArgument[Any]）→ Self

继承自GenerativeSelect 的 GenerativeSelect.group_by（） 方法

返回应用了给定 GROUP BY 标准列表的新可选对象。

所有现有的 GROUP BY 设置都可以通过传递 None 来隐藏。

例如：

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

参数

子句—— 一系列 ColumnElement 构建 将用于生成 GROUP BY 子句。

另请参阅

在 SQLAlchemy Unified 教程

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

方法 sqlalchemy.sql.expression.CompoundSelect. is_derived_from（fromclause：FromClauseNone）→ bool

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

例如，Table 的别名是从该 Table 派生的。

方法 sqlalchemy.sql.expression.CompoundSelect. label（name：strNone）→ Label[Any]

继承自SelectBase 的 SelectBase.label（） 方法

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

另请参阅

SelectBase.scalar_subquery（） 中。

方法 sqlalchemy.sql.expression.CompoundSelect. lateral（name：strNone=None）→ LateralFromClause

继承自SelectBase 的 SelectBase.lateral（） 方法

返回此 Selectable 的 LATERAL 别名。

返回值是 Lateral 结构，也由顶级 lateral（） 函数提供。

另请参阅

LATERAL correlation - 用法概述。

method sqlalchemy.sql.expression.CompoundSelect. limit（limit： _LimitOffsetType）→ Self

继承自 GenerativeSelect 的 GenerativeSelect.limit（） 方法

返回应用了给定 LIMIT 标准的新可选对象。

这是一个数值，通常呈现为 LIMIT expression 在生成的 select 中。 不这样做的后端 support LIMIT 将尝试提供类似的功能。

注意

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

参数

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

另请参阅

生成 Select.fetch（）

生成选择.offset（）

方法 sqlalchemy.sql.expression.CompoundSelect. offset（offset： _LimitOffsetType）→ Self

继承自 GenerativeSelect 的 GenerativeSelect.offset（） 方法

返回应用了给定 OFFSET 条件的新可选对象。

这是一个数值，通常呈现为 OFFSET expression 在生成的 select 中。 不这样做的后端 support OFFSET 将尝试提供类似的功能。

参数

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

另请参阅

生成选择.limit（）

生成 Select.fetch（）

method sqlalchemy.sql.expression.CompoundSelect. options（*options： ExecutableOption）→ 自身

继承自Executable 的 Executable.options（） 方法

将选项应用于此语句。

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

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

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

在 1.4 版本发生变更： - 将 Executable.options（） 添加到 Core 语句对象中，以实现允许统一的 Core / ORM 查询功能的目标。

另请参阅

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

Relationship Loading with Loader Options - 指特定于 ORM 查询使用的选项

方法 sqlalchemy.sql.expression.CompoundSelect. order_by（_GenerativeSelect__first：Literal[None，_NoArg.NO_ARG]_ColumnExpressionOrStrLabelArgument[Any]=_NoArg.NO_ARG， *clauses： _ColumnExpressionOrStrLabelArgument[Any]）→ Self

继承自GenerativeSelect 的 GenerativeSelect.order_by（） 方法

返回应用了给定 ORDER BY 标准列表的新可选对象。

例如：

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

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

参数

子句—— 一系列 ColumnElement 构建 它将用于生成 ORDER BY 子句。

另请参阅

ORDER BY - 在 SQLAlchemy Unified Tutorial 中

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

方法 sqlalchemy.sql.expression.CompoundSelect. replace_selectable（旧： FromClause， 别名： Alias）→ Self

继承自 Selectable.replace_selectable() Selectable 的方法

替换 FromClause 的所有匹配项 'old' 替换为给定的别名 object，返回此 FromClause 的副本。

1.4 版后已移除： 该方法 Selectable.replace_selectable() 已弃用，并将在未来发行版中删除。可通过 sqlalchemy.sql.visitors 模块使用类似的功能。

方法 sqlalchemy.sql.expression.CompoundSelect. scalar_subquery（）→ ScalarSelect[Any]

继承自SelectBase 的 SelectBase.scalar_subquery（） 方法

返回此 selectable 的 'scalar' 表示，可用作列表达式。

返回的对象是 ScalarSelect 的实例。

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

请注意，标量子查询与 FROM 级别不同 子查询，可以使用 SelectBase.subquery（） 方法。

另请参阅

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

method sqlalchemy.sql.expression.CompoundSelect. select（*arg： Any， **kw： Any）→ Select

继承自SelectBase 的 SelectBase.select（） 方法

1.4 版后已移除： SelectBase.select（） 方法已弃用，并将在未来版本中删除;此方法隐式创建一个应该是显式的子查询。请先调用 SelectBase.subquery（） 以创建子查询，然后可以选择该子查询。

属性 sqlalchemy.sql.expression.CompoundSelect. selected_columns

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

对于 CompoundSelect， CompoundSelect.selected_columns 属性返回选定的 列中包含的第一个 SELECT 语句的 语句。

另请参阅

Select.selected_columns

在 1.4 版本加入.

方法 sqlalchemy.sql.expression.CompoundSelect. self_group（against：OperatorTypeNone=None）→ GroupedElement

将 'grouping' 应用于此 ClauseElement。

此方法被 subclasses 覆盖以返回 “grouping” 结构，即括号。特别是，当它被 “binary” 表达式用于在放入更大的表达式时提供围绕自身的分组，以及 select（） 构造 select（） 的（请注意，子查询通常应使用 Select.alias（） 方法创建，因为许多平台需要命名嵌套的 SELECT 语句）。

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

的 base self_group（） 方法 子句元素 只返回 self。

方法 sqlalchemy.sql.expression.CompoundSelect. set_label_style（style： SelectLabelStyle）→ CompoundSelect

返回具有指定标签样式的新可选对象。

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

在现代 SQLAlchemy 中，通常不需要更改标签样式，因为通过使用 ColumnElement.label（） 方法可以更有效地使用每个表达式的标签。在以前的版本中， LABEL_STYLE_TABLENAME_PLUS_COL 用于消除来自不同表、别名或子查询的同名列的歧义;较新的LABEL_STYLE_DISAMBIGUATE_ONLY现在仅将标签应用于与现有名称冲突的名称，因此此标签的影响最小。

消除歧义的基本原理主要是使所有列表达式都可以从给定的 FromClause.c 中获得 集合。

1.4 版本的新Function： - 该 GenerativeSelect.set_label_style() method 取代了之前 .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.CompoundSelect. slice（start： int， stop： int）→ Self

继承自 GenerativeSelect 的 GenerativeSelect.slice（） 方法

根据切片将 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（） 的子句。

1.4 版本中的新功能： 添加了 GenerativeSelect.slice（） 方法从 ORM 推广而来。

另请参阅

生成选择.limit（）

生成选择.offset（）

生成 Select.fetch（）

method sqlalchemy.sql.expression.CompoundSelect. subquery（name：strNone=None）→ 子查询

继承自SelectBase 的 SelectBase.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（） 等效于调用 FromClause.alias（） method 对 FROM 对象执行;然而 作为 SelectBase object 不是直接的 FROM 对象， SelectBase.subquery（） method 提供更清晰的语义。

在 1.4 版本加入.

method sqlalchemy.sql.expression.CompoundSelect. with_for_update（*， nowait： bool = False， read： bool = False， of：_ForUpdateOfArgumentNone=None， skip_locked： bool = False， key_share： bool = False）→ Self

继承自 GenerativeSelect.with_for_update() GenerativeSelect 的方法

为此指定 FOR UPDATE 子句 GenerativeSelect 的

例如：

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

在 PostgreSQL 或 Oracle Database 等数据库上，上述内容将呈现如下语句：

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， FOR SHARE 在 PostgreSQL 上。 在 PostgreSQL 上，当与 nowait 将呈现 FOR SHARE NOWAIT。

• 
  of- SQL 表达式或 SQL 表达式元素列表（通常是 Column 对象或兼容的表达式，对于某些后端也可能是表表达式），它将呈现为 FOR UPDATE OF 子句;受 PostgreSQL、Oracle Database、某些 MySQL 版本和其他版本支持。可以呈现为表或列，具体取决于后端。

• 
  skip_locked – 布尔值，将在 Oracle 数据库和 PostgreSQL 方言上呈现 FOR UPDATE SKIP LOCKED 或 FOR SHARE SKIP LOCKED 如果还指定了 read=True。

• 
  key_share —— 布尔值，将在 PostgreSQL 方言上呈现 FOR NO KEY UPDATE，或者如果与 read=True 结合使用，将呈现 FOR KEY SHARE。

类 sqlalchemy.sql.expression 中。CTE

表示公共表表达式。

CTE 对象是使用 SelectBase.cte（） 方法。不太常见的语法还允许使用 DML 结构中存在的 HasCTE.cte（） 方法，例如 Insert、 Update 和 删除。有关 CTE 的使用详情，请参阅 HasCTE.cte（） 方法。

另请参阅

子查询和 CTE - 在 2.0 教程中

HasCTE.cte（） - 调用样式示例

成员

alias（）、union（）、union_all（）

类签名

类 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：strNone=None， flat： bool = False）→ CTE

返回此的别名 CTE 的。

此方法是 FromClause.alias（） 方法。

另请参阅

使用别名

别名（）

方法 sqlalchemy.sql.expression.CTE. union（*other： _SelectStatementForCompoundArgument）→ CTE

返回具有 SQL UNION 的新 CTE 的原始 CTE 与提供的给定可选值 作为位置参数。

参数

*其他 –

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

在 1.4.28 版本发生变更： 现在接受多个元素。

另请参阅

HasCTE.cte（） - 调用样式示例

方法 sqlalchemy.sql.expression.CTE. union_all（*其他： _SelectStatementForCompoundArgument）→ CTE

返回带有 SQL UNION ALL 的新 CTE 的原始 CTE 与提供的给定可选值 作为位置参数。

参数

*其他 –

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

在 1.4.28 版本发生变更： 现在接受多个元素。

另请参阅

HasCTE.cte（） - 调用样式示例

类 sqlalchemy.sql.expression 中。可执行文件

将 ClauseElement 标记为支持执行。

Executable 是所有 “statement” 类型对象的超类，包括 select（）、delete（）、update（）、 insert（）、text（）来获取。

成员

execution_options（）、get_execution_options（）、选项（）

类签名

类 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 语句方式的因素 获取结果。也就是说，执行选项不是 SQL 编译所容纳的内容的一部分，也不被视为语句缓存状态的一部分。

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

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

此行为的一个例外是 Connection object，其中该方法 Connection.execution_options() 明确不是生成式的。

可以传递给 Executable.execution_options() 和其他相关方法以及 参数字典包括显式使用的参数 by 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 parameter 的 Connection.execute（） 上，另外通过 Executable.execution_options() 在 SQL 语句对象上，以及通过 Session.execute（） 等 ORM 构造。

• 
  Connection.execution_options.compiled_cache - 表示将用作 SQL 编译缓存 对于 Connection 或 Engine，以及 Session.execute（） 等 ORM 方法。可以作为 None 传递以禁用语句的缓存。 此选项不被 Executable.execution_options() 因为不建议在 statement 对象中携带编译缓存。

• 
  Connection.execution_options.schema_translate_map - 使用的架构名称的映射 Schema Translate Map 功能，由 Connection、Engine、 Executable 以及 Session.execute（） 等 ORM 结构。

另请参阅

Connection.execution_options()

Connection.execute.execution_options

Session.execute.execution_options

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

方法 sqlalchemy.sql.expression.Executable. get_execution_options（）→ _ExecuteOptions

获取将在执行过程中生效的非 SQL 选项。

在 1.3 版本加入.

另请参阅

Executable.execution_options()

method sqlalchemy.sql.expression.Executable. options（*options： ExecutableOption）→ 自身

将选项应用于此语句。

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

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

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

在 1.4 版本发生变更： - 将 Executable.options（） 添加到 Core 语句对象中，以实现允许统一的 Core / ORM 查询功能的目标。

另请参阅

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

Relationship Loading with Loader Options - 指特定于 ORM 查询使用的选项

类 sqlalchemy.sql.expression 中。存在

表示 EXISTS 子句。

有关用法的描述，请参见 exists（） 。

EXISTS 子句也可以从 select（） 构造 实例。

成员

correlate（）， correlate_except（）， inherit_cache， select（）， select_from（）， where（）

类签名

类 sqlalchemy.sql.expression.Exists （ sqlalchemy.sql.expression.UnaryExpression ）

method sqlalchemy.sql.expression.Exists. correlate（*fromclauses：Literal[None，False]_FromClauseArgument）→ Self

将关联应用于此记录的子查询 存在。

另请参阅

ScalarSelect.correlate（）

method sqlalchemy.sql.expression.Exists. correlate_except（*fromclauses：Literal[None，False]_FromClauseArgument）→ Self

将关联应用于此记录的子查询 存在。

另请参阅

ScalarSelect.correlate_except()

属性 sqlalchemy.sql.expression.Exists. inherit_cache：boolNone = True

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

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

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

另请参阅

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

方法 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_from（） select 方法 语句。

注意

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

method sqlalchemy.sql.expression.Exists. where（*clause： _ColumnExpressionArgument[bool]）→ Self

返回一个新的 exists（） 结构，其中给定的表达式添加到其 WHERE 子句中，并通过 AND 连接到现有子句（如果有）。

注意

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

类 sqlalchemy.sql.expression 中。From子句

表示可在 FROM 中使用的元素 子句。

FromClause 最常见的形式是 Table 和 select（） 结构。所有 FromClause 对象共有的主要功能包括：

• 
  c 集合，它提供对 ColumnElement 对象集合的按名称访问。

• 
  primary_key 属性，它是所有这些的集合 ColumnElement （列元素） 指示 primary_key 标志的对象。

• 
  生成 “from” 子句的各种派生的方法，包括 FromClause.alias（）中，则 FromClause.join（）中， FromClause.select（） 的 FromClause.select（） 中。

成员

alias（）， c， columns， description， entity_namespace， exported_columns， foreign_keys， is_derived_from（）， join（）， outerjoin（）， primary_key， schema， select（）， tablesample（）

类签名

类 sqlalchemy.sql.expression.FromClause （ sqlalchemy.sql.roles.AnonymizedFromClauseRole ， sqlalchemy.sql.expression.Selectable ）

method sqlalchemy.sql.expression.FromClause. alias（name：strNone=None， flat： bool = False）→ NamedFromClause

返回此 FromClause 的别名。

例如：

a2 = some_table.alias("a2")

上面的代码创建了一个别名 可以使用 作为任何 SELECT 语句中的 FROM 子句。

另请参阅

使用别名

别名（）

属性 sqlalchemy.sql.expression.FromClause. c

FromClause.columns 的同义词

结果

一个 ColumnCollection

属性 sqlalchemy.sql.expression.FromClause. 列

ColumnElement 的基于命名的集合 对象。

列或 c 集合是使用表绑定列或其他可选绑定列构造 SQL 表达式的网关：

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

结果

一个 ColumnCollection 对象。

属性 sqlalchemy.sql.expression.FromClause. 说明

此 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 表示 “exported” 列。

FromClause 的 “exported” 列 object 是同义词 替换为 FromClause.columns 集合。

在 1.4 版本加入.

另请参阅

Selectable.exported_columns

SelectBase.exported_columns

属性 sqlalchemy.sql.expression.FromClause. foreign_keys

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

每个 ForeignKey 都是 表范围 ForeignKeyConstraint 的 Constraint 对象。

另请参阅

Table.foreign_key_constraints

方法 sqlalchemy.sql.expression.FromClause. is_derived_from（fromclause：FromClauseNone）→ bool

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

例如，Table 的别名是从该 Table 派生的。

method sqlalchemy.sql.expression.FromClause. join（right： _FromClauseArgument， onclause：_ColumnExpressionArgument[bool]None=None， isouter： bool = False， full： bool = False）→ 加入

从此返回 Join From子句 转换为另一个 FromClause。

例如：

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 映射的类。

• 
  on子句– 表示联接的 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

从此返回 Join From子句 添加到另一个 FromClause，并将 “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 映射的类。

• 
  on子句– 表示联接的 ON 子句的 SQL 表达式。如果保留为 None，则 FromClause.join（） 将尝试 根据外键关系联接两个表。

• 
  full – 如果为 True，则渲染 FULL OUTER JOIN，而不是 LEFT OUTER JOIN。

另请参阅

FromClause.join（）

加入

属性 sqlalchemy.sql.expression.FromClause. primary_key

返回构成此_selectable的主键的 Column 对象的可迭代集合。From子句。

对于 Table 对象，此集合由 PrimaryKeyConstraint 表示，它本身是 Column 对象的可迭代集合。

attribute sqlalchemy.sql.expression.FromClause. schema：strNone = None（无

定义此 FromClause 的 'schema' 属性。

对于大多数对象，这通常为 None，但 Table 中，它被视为 Table.schema 参数。

方法 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：floatFunction[Any]， name：strNone=None， seed：roles.ExpressionElementRole[Any]None=None）→ TableSample

返回此 FromClause 的 TABLESAMPLE 别名。

返回值为 TableSample 还构建 由顶级 tablesample（） 函数提供。

另请参阅

tablesample（） - 使用指南和参数

类 sqlalchemy.sql.expression 中。生成选择

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

这是 Select 和 CompoundSelect 化合物选择 其中可以添加 ORDER BY、GROUP BY 等元素和 column 可以控制渲染。 比较对象 TextualSelect，虽然它是 SelectBase 的子类 并且也是 SELECT 结构， 表示在此级别无法更改的固定文本字符串， 仅包装为子查询。

成员

fetch（）， get_label_style（）， group_by（）， limit（）， offset（）， order_by（）， set_label_style（）， slice（）， with_for_update（）

类签名

类 sqlalchemy.sql.expression.GenerativeSelect （ sqlalchemy.sql.expression.SelectBase ， sqlalchemy.sql.expression.Generative ）

method sqlalchemy.sql.expression.GenerativeSelect. fetch（count： _LimitOffsetType， with_ties： bool = False， percent： bool= false）→ Self

返回应用了给定 FETCH FIRST 标准的新 selectable。

这是一个数值，通常在结果的 select 中呈现为 FETCH {FIRST | NEXT} [ count ] {ROW | ROWS} {ONLY | WITH TIES} expression。此功能目前已针对 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

另请参阅

生成选择.limit（）

生成选择.offset（）

方法 sqlalchemy.sql.expression.GenerativeSelect. get_label_style（）→ SelectLabelStyle

检索当前标签样式。

在 1.4 版本加入.

方法 sqlalchemy.sql.expression.GenerativeSelect. group_by（_GenerativeSelect__first：Literal[None，_NoArg.NO_ARG]_ColumnExpressionOrStrLabelArgument[Any]=_NoArg.NO_ARG， *clauses： _ColumnExpressionOrStrLabelArgument[Any]）→ Self

返回应用了给定 GROUP BY 标准列表的新可选对象。

所有现有的 GROUP BY 设置都可以通过传递 None 来隐藏。

例如：

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

参数

子句—— 一系列 ColumnElement 构建 将用于生成 GROUP BY 子句。

另请参阅

在 SQLAlchemy Unified 教程

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

method sqlalchemy.sql.expression.GenerativeSelect. limit（limit： _LimitOffsetType）→ Self

返回应用了给定 LIMIT 标准的新可选对象。

这是一个数值，通常呈现为 LIMIT expression 在生成的 select 中。 不这样做的后端 support LIMIT 将尝试提供类似的功能。

注意

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

参数

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

另请参阅

生成 Select.fetch（）

生成选择.offset（）

方法 sqlalchemy.sql.expression.GenerativeSelect. offset（offset： _LimitOffsetType）→ Self

返回应用了给定 OFFSET 条件的新可选对象。

这是一个数值，通常呈现为 OFFSET expression 在生成的 select 中。 不这样做的后端 support OFFSET 将尝试提供类似的功能。

参数

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

另请参阅

生成选择.limit（）

生成 Select.fetch（）

方法 sqlalchemy.sql.expression.GenerativeSelect. order_by（_GenerativeSelect__first：Literal[None，_NoArg.NO_ARG]_ColumnExpressionOrStrLabelArgument[Any]=_NoArg.NO_ARG， *clauses： _ColumnExpressionOrStrLabelArgument[Any]）→ Self

返回应用了给定 ORDER BY 标准列表的新可选对象。

例如：

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

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

参数

子句—— 一系列 ColumnElement 构建 它将用于生成 ORDER BY 子句。

另请参阅

ORDER BY - 在 SQLAlchemy Unified Tutorial 中

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

方法 sqlalchemy.sql.expression.GenerativeSelect. set_label_style（style： SelectLabelStyle）→ Self

返回具有指定标签样式的新可选对象。

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

在现代 SQLAlchemy 中，通常不需要更改标签样式，因为通过使用 ColumnElement.label（） 方法可以更有效地使用每个表达式的标签。在以前的版本中， LABEL_STYLE_TABLENAME_PLUS_COL 用于消除来自不同表、别名或子查询的同名列的歧义;较新的LABEL_STYLE_DISAMBIGUATE_ONLY现在仅将标签应用于与现有名称冲突的名称，因此此标签的影响最小。

消除歧义的基本原理主要是使所有列表达式都可以从给定的 FromClause.c 中获得 集合。

1.4 版本的新Function： - 该 GenerativeSelect.set_label_style() method 取代了之前 .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.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（） 的子句。

1.4 版本中的新功能： 添加了 GenerativeSelect.slice（） 方法从 ORM 推广而来。

另请参阅

生成选择.limit（）

生成选择.offset（）

生成 Select.fetch（）

method sqlalchemy.sql.expression.GenerativeSelect. with_for_update（*， nowait： bool = False， read： bool = False， of：_ForUpdateOfArgumentNone=None， skip_locked： bool = False， key_share： bool = False）→ Self

为此指定 FOR UPDATE 子句 GenerativeSelect 的

例如：

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

在 PostgreSQL 或 Oracle Database 等数据库上，上述内容将呈现如下语句：

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， FOR SHARE 在 PostgreSQL 上。 在 PostgreSQL 上，当与 nowait 将呈现 FOR SHARE NOWAIT。

• 
  of- SQL 表达式或 SQL 表达式元素列表（通常是 Column 对象或兼容的表达式，对于某些后端也可能是表表达式），它将呈现为 FOR UPDATE OF 子句;受 PostgreSQL、Oracle Database、某些 MySQL 版本和其他版本支持。可以呈现为表或列，具体取决于后端。

• 
  skip_locked – 布尔值，将在 Oracle 数据库和 PostgreSQL 方言上呈现 FOR UPDATE SKIP LOCKED 或 FOR SHARE SKIP LOCKED 如果还指定了 read=True。

• 
  key_share —— 布尔值，将在 PostgreSQL 方言上呈现 FOR NO KEY UPDATE，或者如果与 read=True 结合使用，将呈现 FOR KEY SHARE。

类 sqlalchemy.sql.expression 中。HasCTE

Mixin 声明一个类以包含 CTE 支持。

成员

add_cte（）， cte（）

类签名

类 sqlalchemy.sql.expression.HasCTE （ sqlalchemy.sql.roles.HasCTERole ， sqlalchemy.sql.expression.SelectsRows ）

方法 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 与可能间接提取其结果的主语句内联。另一种是提供对特定系列的 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 construct 生成 “upsert”：

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

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

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

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

print(update_statement)

上述语句呈现为：

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

在 1.4.21 版本加入.

参数

• *ctes –

  
  零个或多个 CTE 构造。

  
  在 2.0 版更改： 接受多个 CTE 实例

• nest_here –

  
  如果为 True，则给定的一个或多个 CTE 将呈现，就像它们在添加到此 HasCTE 时将 HasCTE.cte.nesting 标志指定为 True 一样。假设给定的 CTE 在外部封闭语句中也没有引用，则给定的 CTE 应在给定此标志时在此语句的级别呈现。

  
  2.0 版的新Function。

  
  另请参阅

  
  HasCTE.cte.嵌套

方法 sqlalchemy.sql.expression.HasCTE. cte（name：strNone=None， 递归： bool = False， 嵌套： 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（） method 可能是 用于建立这些。

在 1.3.13 版本发生变更： 添加了对前缀的支持。特别是 - MATERIALIZED 和 NOT MATERIALIZED。

参数

• 
  name – 公共表表达式的名称。 喜欢 FromClause.alias（）中，名称可以保留为 none ，在这种情况下，将在查询编译时使用匿名符号。

• 
  recursive – 如果为 True，将渲染 WITH RECURSIVE。递归公用表表达式旨在与 UNION ALL 结合使用，以便从已选择的行中派生行。

• 
  嵌套 –

  
  如果为 True，则会在本地将 CTE 呈现到引用它的语句。对于更复杂的场景HasCTE.add_cte，使用 HasCTE.add_cte.nest_here 参数也可以更仔细地使用 控制特定 CTE 的确切位置。

  
  在 1.4.24 版本加入.

  
  另请参阅

  
  HasCTE.add_cte（）

以下示例包括 PostgreSQL 文档中的两个示例，网址为 https://www.postgresql.org/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 结合使用的更新插入：

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（） - 的 ORM 版本 HasCTE.cte（） 的

类 sqlalchemy.sql.expression 中。HasPrefixes（哈斯前缀

成员

prefix_with（）

方法 sqlalchemy.sql.expression.HasPrefixes. prefix_with（*prefixes： _TextCoercedExpressionArgument[Any]， dialect： str = '*'）→ 自身

在 statement 关键字后添加一个或多个表达式，即 SELECT、INSERT、UPDATE 或 DELETE。生成。

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

例如：

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

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

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

参数

• 
  前缀 – 文本或 ClauseElement 构造 将在 INSERT、UPDATE 或 DELETE 之后呈现 关键词。

• 
  dialect- 可选的字符串 dialect name，它将限制此前缀的渲染仅该方言。

类 sqlalchemy.sql.expression 中。HasSuffixes

成员

suffix_with（）

方法 sqlalchemy.sql.expression.HasSuffixes. suffix_with（*suffixes： _TextCoercedExpressionArgument[Any]， 方言： str = '*'）→ 自身

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

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

例如：

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

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

参数

• 
  *suffixes– 文本或 ClauseElement 构造 将在 Target 子句之后呈现。

• 
  dialect- 可选的字符串 dialect name，它将限制此后缀的渲染仅该方言。

类 sqlalchemy.sql.expression 中。加入

表示两个之间的 JOIN 构造 From子句 元素。

Join 的公共构造函数 是模块级的 join（） 函数以及 FromClause.join（） 方法（例如 表）。

另请参阅

加入（）

FromClause.join（）

成员

__init__（）， 描述， is_derived_from（）， select（）， self_group（）

类签名

类 sqlalchemy.sql.expression.Join （ sqlalchemy.sql.roles.DMLTableRole ， sqlalchemy.sql.expression.FromClause ）

方法 sqlalchemy.sql.expression.Join. __init__（左：_FromClauseArgument，右：_FromClauseArgument，onclause：_OnClauseArgumentNone=None，isouter：bool = False， full： bool = False）

构造新的 Join。

这里通常的入口点是 join（） 函数或任何 FromClause 对象。

属性 sqlalchemy.sql.expression.Join. 说明

方法 sqlalchemy.sql.expression.Join. is_derived_from（fromclause：FromClauseNone）→ bool

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

例如，Table 的别名是从该 Table 派生的。

方法 sqlalchemy.sql.expression.Join. select（）→ Select

Create a Select from this （从此创建选择 加入。

例如：

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

方法 sqlalchemy.sql.expression.Join. self_group（against：OperatorTypeNone=None）→ FromGrouping

将 'grouping' 应用于此 ClauseElement。

此方法被 subclasses 覆盖以返回 “grouping” 结构，即括号。特别是，当它被 “binary” 表达式用于在放入更大的表达式时提供围绕自身的分组，以及 select（） 构造 select（） 的（请注意，子查询通常应使用 Select.alias（） 方法创建，因为许多平台需要命名嵌套的 SELECT 语句）。

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

的 base self_group（） 方法 子句元素 只返回 self。

类 sqlalchemy.sql.expression 中。横向

表示 LATERAL 子查询。

这个对象是由 lateral（） 模块级函数以及 FromClause.lateral（） 构造的 可用方法 在所有 FromClause 子类上。

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

另请参阅

LATERAL correlation - 用法概述。

成员

inherit_cache

类签名

类 sqlalchemy.sql.expression.Lateral （ sqlalchemy.sql.expression.FromClauseAlias ， sqlalchemy.sql.expression.LateralFromClause ）

属性 sqlalchemy.sql.expression.Lateral. inherit_cache：boolNone = True

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

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

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

另请参阅

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

类 sqlalchemy.sql.expression 中。返回行

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

虽然 SELECT 语句和 TABLE 是我们在此类别中考虑的主要内容，但 DML 如 INSERT、UPDATE 和 DELETE 也可以指定 RETURNING，这意味着它们可以用于 CTE 和其他形式，并且 PostgreSQL 也有返回行的函数。

在 1.4 版本加入.

成员

exported_columns， is_derived_from（）

类签名

类 sqlalchemy.sql.expression.ReturnsRows （ sqlalchemy.sql.roles.ReturnsRowsRole ， sqlalchemy.sql.expression.DQLDMLClauseElement ）

属性 sqlalchemy.sql.expression.ReturnsRows. exported_columns

一个 ColumnCollection 表示 “exported” 列的 ReturnsRows 中。

“exported” 列表示 ColumnElement （列元素） 此 SQL 呈现的表达式 构建。 主要品种是 FROM 子句的 “FROM 子句列”，例如 table、join 和 或子查询的 “SELECTed columns” ，即 SELECT 语句的 “columns 子句” 和 RETURNING 列在 DML 语句中..

在 1.4 版本加入.

另请参阅

FromClause.exported_columns

SelectBase.exported_columns

方法 sqlalchemy.sql.expression.ReturnsRows. is_derived_from（fromclause：FromClauseNone）→ bool

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

例如，Table 的别名是从该 Table 派生的。

类 sqlalchemy.sql.expression 中。标量选择

表示标量子查询。

ScalarSelect 是通过调用 SelectBase.scalar_subquery（） 方法。然后，该对象作为 ColumnElement 层次结构中的 SQL 列表达式参与其他 SQL 表达式。

另请参阅

SelectBase.scalar_subquery（）

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

成员

correlate（）， correlate_except（）， inherit_cache， self_group（）， 其中（）

类签名

类 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 的 API 语句。

1.4 版本中的新功能： 以前， ScalarSelect.correlate（） method 只能从 Select 中使用。

参数

from子句—— 一个或多个 From子句 结构或其他兼容的结构（即 ORM 映射的 类）成为 Correlate 集合的一部分。

另请参阅

ScalarSelect.correlate_except()

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

method sqlalchemy.sql.expression.ScalarSelect. correlate_except（*fromclauses：Literal[None，False]_FromClauseArgument）→ Self

返回新的 ScalarSelect 这将省略给定的 FROM 子句。

此方法是从 Select.correlate_except（） 方法。 选择。 该方法将 ：meth：_sql.Select.correlate_except“方法，则返回一个新的 ScalarSelect 的 API 语句。

1.4 版本中的新功能： 以前， ScalarSelect.correlate_except() method 只能从 Select 中使用。

参数

from子句—— 一个或多个 From子句 结构或其他兼容的结构（即 ORM 映射的 类）成为 correlate-exception 集合的一部分。

另请参阅

ScalarSelect.correlate（）

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

属性 sqlalchemy.sql.expression.ScalarSelect. inherit_cache：boolNone = True

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

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

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

另请参阅

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

方法 sqlalchemy.sql.expression.ScalarSelect. self_group（against：OperatorTypeNone=None）→ Self

将 'grouping' 应用于此 ClauseElement。

此方法被 subclasses 覆盖以返回 “grouping” 结构，即括号。特别是，当它被 “binary” 表达式用于在放入更大的表达式时提供围绕自身的分组，以及 select（） 构造 select（） 的（请注意，子查询通常应使用 Select.alias（） 方法创建，因为许多平台需要命名嵌套的 SELECT 语句）。

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

的 base self_group（） 方法 子句元素 只返回 self。

方法 sqlalchemy.sql.expression.ScalarSelect. where（crit： _ColumnExpressionArgument[bool]）→ Self

将 WHERE 子句应用于此 ScalarSelect 引用的 SELECT 语句。

类 sqlalchemy.sql.expression 中。选择

表示 SELECT 语句。

Select 对象通常使用 select（） 函数。有关详细信息，请参阅该函数。

另请参阅

选择 （）

使用 SELECT 语句 - 在 2.0 教程中

成员

__init__（）， add_columns（）， add_cte（）， 别名（）， as_scalar（）， c， 列（）， 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（）， 切片（）， 子查询（）， suffix_with（）， 联合（）， union_all（）， where（）， whereclause， with_for_update（）、with_hint（）、with_only_columns（）、with_statement_hint（）

类签名

类 sqlalchemy.sql.expression.Select （ sqlalchemy.sql.expression.HasPrefixes ， sqlalchemy.sql.expression.HasSuffixes ， sqlalchemy.sql.expression.HasHints ， sqlalchemy.sql.expression.HasCompileState ， sqlalchemy.sql.expression._SelectFromElements sqlalchemy.sql.expression.GenerativeSelect sqlalchemy.sql.expression.TypedReturnsRows ）

方法 sqlalchemy.sql.expression.Select. __init__（*entities： _ColumnsClauseArgument[Any]）

构造一个新的 Select。

Select 的公共构造函数是 select（） 函数。

方法 sqlalchemy.sql.expression.Select. add_columns（*entities： _ColumnsClauseArgument[Any]）→ Select[Any]

返回一个新的 select（） 结构，其中给定的实体附加到其 columns 子句中。

例如：

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

columns 子句中的原始表达式保持不变。 要将原始表达式替换为新表达式，请参阅方法 Select.with_only_columns（） 中。

参数

实体– 要添加到 columns 子句中的列、表或其他实体表达式

另请参阅

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

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

方法 sqlalchemy.sql.expression.Select. add_cte（*ctes： CTE， nest_here： bool = False）→ Self

继承自HasCTE 的 HasCTE.add_cte（） 方法

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

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

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

此方法有两个一般用途。一种是嵌入具有某种用途而不明确引用的 CTE 语句，例如将 DML 语句（如 INSERT 或 UPDATE）嵌入为 CTE 的用例，该 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 construct 生成 “upsert”：

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

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

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

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

print(update_statement)

上述语句呈现为：

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

在 1.4.21 版本加入.

参数

• *ctes –

  
  零个或多个 CTE 构造。

  
  在 2.0 版更改： 接受多个 CTE 实例

• nest_here –

  
  如果为 True，则给定的一个或多个 CTE 将呈现，就像它们在添加到此 HasCTE 时将 HasCTE.cte.nesting 标志指定为 True 一样。假设给定的 CTE 在外部封闭语句中也没有引用，则给定的 CTE 应在给定此标志时在此语句的级别呈现。

  
  2.0 版的新Function。

  
  另请参阅

  
  HasCTE.cte.嵌套

method sqlalchemy.sql.expression.Select. alias（name：strNone=None， flat： bool = False）→ 子查询

继承自SelectBase 的 SelectBase.alias（） 方法

返回针对 this 的命名子查询 SelectBase 的 Pod 中。

对于 SelectBase（而不是 FromClause），这将返回一个 Subquery 对象，该对象的行为与与 From子句。

在 1.4 版本发生变更： SelectBase.alias（） method 现在是 SelectBase.subquery（） 方法的同义词。

方法 sqlalchemy.sql.expression.Select. as_scalar（）→ ScalarSelect[Any]

继承自SelectBase 的 SelectBase.as_scalar（） 方法

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

属性 sqlalchemy.sql.expression.Select. c

继承自SelectBase 的 SelectBase.c属性

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

method sqlalchemy.sql.expression.Select. column（column： _ColumnsClauseArgument[Any]）→ Select[Any]

返回一个新的 select（） 结构，并将给定的列表达式添加到其 columns 子句中。

1.4 版后已移除： Select.column（） 方法已弃用，并将在未来版本中删除。请使用 Select.add_columns（）

例如：

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

请参阅以下文档 Select.with_only_columns（） 有关添加/替换 选择对象。

属性 sqlalchemy.sql.expression.Select. column_descriptions

返回一个启用插件的 'column descriptions' 结构，引用此语句 SELECT 的列。

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

对于 Core-only 语句，此访问器返回的结构 派生自 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 attribute 返回一组仅限 Core 的实体的结构， 而不仅仅是仅限 ORM 的实体。

另请参阅

UpdateBase.entity_description - insert（）、update（） 或 delete（） 的实体信息

检查支持 ORM 的 SELECT 和 DML 语句中的实体和列 - ORM 背景

属性 sqlalchemy.sql.expression.Select. columns_clause_froms

返回此 SELECT 语句的 columns 子句隐含的 FromClause 对象集。

在 1.4.23 版本加入.

另请参阅

Select.froms - “最终”FROM 列表，考虑完整声明

Select.with_only_columns（） - 使用此集合设置新的 FROM 列表

method sqlalchemy.sql.expression.Select. correlate（*fromclauses：Literal[None，False]_FromClauseArgument）→ Self

返回新的 Select 它将关联给定的 FROM 子句更改为封闭的 Select 的子句。

调用此方法将关闭 Select 对象的默认行为 “auto-correlation”。通常，出现在 Select 中的 FROM 元素 它通过 它的 WHERE 子句、ORDER BY、HAVING 或 columns 子句中将被省略 选择 object 的 FROM 子句。 使用 Select.correlate（） method 提供固定的 FROM 对象列表 这可能会在此过程中发生。

当 Select.correlate（） 用于应用特定的 FROM 子句 对于关联，FROM 元素成为 correlation 的 选择 object 是相对于封闭的 Select 它指的是 相同的 FROM 对象。 这与 “auto-correlation”，仅与立即封闭相关 选择。多级关联确保封闭 Select 和封闭 Select 之间的链接 始终通过 至少一个 WHERE/ORDER BY/HAVING/columns 子句，以便 关联。

如果传递 None，则选择 object will correlated 没有它的 FROM 条目，并且 all 都将无条件呈现 在本地 FROM 子句中。

参数

fromclauses—— 一个或多个 FromClause 或其他 与 FROM 兼容的结构，例如要成为一部分的 ORM 映射实体 的 correlate 集合;或者，传递单个值 None 删除所有现有关联。

另请参阅

Select.correlate_except（）

标量和相关子查询

method sqlalchemy.sql.expression.Select. correlate_except（*fromclauses：Literal[None，False]_FromClauseArgument）→ Self

返回新的 Select 这将省略给定的 FROM 子句。

调用 Select.correlate_except（） 会关闭 为给定的 FROM 元素选择对象的 “auto-correlation” 的默认行为。此处指定的元素将无条件地出现在 FROM 列表中，而所有其他 FROM 元素仍受正常的自相关行为的约束。

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

参数

from子句—— 一个或多个 From子句 结构或其他兼容的结构（即 ORM 映射的 类）成为 correlate-exception 集合的一部分。

另请参阅

Select.correlate（）

标量和相关子查询

方法 sqlalchemy.sql.expression.Select. corresponding_column（column： KeyedColumnElement[Any]， require_embedded： bool = False）→KeyedColumnElement[任何]无

继承自 Selectable.corresponding_column() Selectable 的方法

给定一个 ColumnElement，返回导出的 ColumnElement 对象 Selectable.exported_columns collection 的 这与 原始 ColumnElement 通过公共上级列。

参数

• 
  column—— 目标 ColumnElement 进行匹配。

• 
  require_embedded —— 如果给定的 ColumnElement ColumnElement （列元素） 实际上存在于子元素中 的这个 Selectable。通常，如果该列仅与此 Selectable 的导出列之一共享一个共同的祖先，则该列将匹配。

另请参阅

Selectable.exported_columns - 的 ColumnCollection 系列 用于作。

ColumnCollection.corresponding_column() -实现 方法。

方法 sqlalchemy.sql.expression.Select. cte（name：strNone=None， 递归： bool = False， 嵌套： bool = False）→ CTE

继承自HasCTE 的 HasCTE.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（） method 可能是 用于建立这些。

在 1.3.13 版本发生变更： 添加了对前缀的支持。特别是 - MATERIALIZED 和 NOT MATERIALIZED。

参数

• 
  name – 公共表表达式的名称。 喜欢 FromClause.alias（）中，名称可以保留为 none ，在这种情况下，将在查询编译时使用匿名符号。

• 
  recursive – 如果为 True，将渲染 WITH RECURSIVE。递归公用表表达式旨在与 UNION ALL 结合使用，以便从已选择的行中派生行。

• 
  嵌套 –

  
  如果为 True，则会在本地将 CTE 呈现到引用它的语句。对于更复杂的场景HasCTE.add_cte，使用 HasCTE.add_cte.nest_here 参数也可以更仔细地使用 控制特定 CTE 的确切位置。

  
  在 1.4.24 版本加入.

  
  另请参阅

  
  HasCTE.add_cte（）

以下示例包括 PostgreSQL 文档中的两个示例，网址为 https://www.postgresql.org/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 结合使用的更新插入：

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（） - 的 ORM 版本 HasCTE.cte（） 的

method sqlalchemy.sql.expression.Select. distinct（*expr： _ColumnExpressionArgument[Any]）→ Self

返回一个新的 select（） 结构，该结构将 DISTINCT 应用于整个 SELECT 语句。

例如：

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_（*其他： _SelectStatementForCompoundArgument）→ CompoundSelect

针对作为位置参数提供的给定 selectable 返回此 select（） 结构的 SQL EXCEPT。

参数

*其他 –

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

在 1.4.28 版本发生变更： 现在接受多个元素。

方法 sqlalchemy.sql.expression.Select. except_all（*其他： _SelectStatementForCompoundArgument）→ CompoundSelect

针对作为位置参数提供的给定可选择对象返回此 select（） 构造的所有 SQL EXCEPT ALL。

参数

*其他 –

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

在 1.4.28 版本发生变更： 现在接受多个元素。

方法 sqlalchemy.sql.expression.Select. execution_options（**kw： Any）→ Self

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

为语句设置非 SQL 选项，这些选项在执行过程中生效。

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

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

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

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

此行为的一个例外是 Connection object，其中该方法 Connection.execution_options() 明确不是生成式的。

可以传递给 Executable.execution_options() 和其他相关方法以及 参数字典包括显式使用的参数 by 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 parameter 的 Connection.execute（） 上，另外通过 Executable.execution_options() 在 SQL 语句对象上，以及通过 Session.execute（） 等 ORM 构造。

• 
  Connection.execution_options.compiled_cache - 表示将用作 SQL 编译缓存 对于 Connection 或 Engine，以及 Session.execute（） 等 ORM 方法。可以作为 None 传递以禁用语句的缓存。 此选项不被 Executable.execution_options() 因为不建议在 statement 对象中携带编译缓存。

• 
  Connection.execution_options.schema_translate_map - 使用的架构名称的映射 Schema Translate Map 功能，由 Connection、Engine、 Executable 以及 Session.execute（） 等 ORM 结构。

另请参阅

Connection.execution_options()

Connection.execute.execution_options

Session.execute.execution_options

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

method sqlalchemy.sql.expression.Select. exists（）→ 存在

继承自SelectBase 的 SelectBase.exists（） 方法

返回此可选对象的 Exists 表示形式，该表示形式可用作列表达式。

返回的对象是 Exists 的实例。

另请参阅

存在（）

EXISTS 子查询 - 在 2.0 样式教程中。

在 1.4 版本加入.

属性 sqlalchemy.sql.expression.Select. exported_columns

继承自SelectBase 的 SelectBase.exported_columns属性

一个 ColumnCollection 表示 “exported” 列，不包括 TextClause 构造。

SelectBase 的 “exported” 列 object 是同义词 与 SelectBase.selected_columns 系列。

在 1.4 版本加入.

另请参阅

Select.exported_columns

Selectable.exported_columns

FromClause.exported_columns

method sqlalchemy.sql.expression.Select. fetch（count： _LimitOffsetType， with_ties： bool = False， percent： bool= false）→ Self

继承自 GenerativeSelect 的 GenerativeSelect.fetch（） 方法

返回应用了给定 FETCH FIRST 标准的新 selectable。

这是一个数值，通常在结果的 select 中呈现为 FETCH {FIRST | NEXT} [ count ] {ROW | ROWS} {ONLY | WITH TIES} expression。此功能目前已针对 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

另请参阅

生成选择.limit（）

生成选择.offset（）

method sqlalchemy.sql.expression.Select. filter（*criteria： _ColumnExpressionArgument[bool]）→ Self

Select.where（） 方法的同义词。

方法 sqlalchemy.sql.expression.Select. filter_by（**kwargs： Any）→ Self

将给定的筛选条件作为 WHERE 子句应用于此 select。

方法 sqlalchemy.sql.expression.Select. from_statement（statement： ReturnsRowsRole）→ ExecutableReturnsRows

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

此作是特定于插件的，如果此 Select 不从启用插件的实体中进行选择，则会引发不支持的异常。

该语句通常是 text（） 或 select（） 结构，并且应该返回 列 选择。

另请参阅

从文本语句中获取 ORM 结果 - ORM Querying Guide 中的使用示例

属性 sqlalchemy.sql.expression.Select. 来源

返回显示的 FromClause 列表 元素。

从 1.4.23 版本开始已移除： Select.froms 属性已移至 Select.get_final_froms（） 方法。

方法 sqlalchemy.sql.expression.Select. get_children（**kw： Any）→ Iterable[ClauseElement]

返回紧接的子 HasTraverseInternals 元素中。

这用于访问遍历。

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

方法 sqlalchemy.sql.expression.Select. get_execution_options（）→ _ExecuteOptions

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

获取将在执行过程中生效的非 SQL 选项。

在 1.3 版本加入.

另请参阅

Executable.execution_options()

方法 sqlalchemy.sql.expression.Select. get_final_froms（）→ Sequence[FromClause]

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

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

对于 ORM 使用，此访问器返回 post 编译 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 参数。

1.4.23 版本中的新功能： - Select.get_final_froms（） method 替换了以前的 Select.froms 访问器，该访问器已弃用。

另请参阅

Select.columns_clause_froms

方法 sqlalchemy.sql.expression.Select. get_label_style（）→ SelectLabelStyle

继承自 GenerativeSelect.get_label_style() GenerativeSelect 的方法

检索当前标签样式。

在 1.4 版本加入.

方法 sqlalchemy.sql.expression.Select. group_by（_GenerativeSelect__first：Literal[None，_NoArg.NO_ARG]_ColumnExpressionOrStrLabelArgument[Any]=_NoArg.NO_ARG， *clauses： _ColumnExpressionOrStrLabelArgument[Any]）→ Self

继承自GenerativeSelect 的 GenerativeSelect.group_by（） 方法

返回应用了给定 GROUP BY 标准列表的新可选对象。

所有现有的 GROUP BY 设置都可以通过传递 None 来隐藏。

例如：

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

参数

子句—— 一系列 ColumnElement 构建 将用于生成 GROUP BY 子句。

另请参阅

在 SQLAlchemy Unified 教程

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

method sqlalchemy.sql.expression.Select. having（*having： _ColumnExpressionArgument[bool]）→ Self¶

返回一个新的 select（） 结构，其中给定的表达式添加到其 HAVING 子句中，并通过 AND 连接到现有子句（如果有）。

属性 sqlalchemy.sql.expression.Select. inherit_cache：boolNone = None

继承自HasCacheKey 的 HasCacheKey.inherit_cache属性

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

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

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

另请参阅

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

属性 sqlalchemy.sql.expression.Select. inner_columns

所有 ColumnElement 的迭代器 表达式，这些表达式将 呈现到生成的 SELECT 语句的 columns 子句中。

此方法是 1.4 的旧版方法，并被 Select.exported_columns 集合。

方法 sqlalchemy.sql.expression.Select. intersect（*other： _SelectStatementForCompoundArgument）→ CompoundSelect

针对作为位置参数提供的给定可选项返回此 select（） 构造的 SQL INTERSECT。

参数

• 
  *其他 –

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

  
  在 1.4.28 版本发生变更： 现在接受多个元素。

• 
  **kwargs – 关键字参数被转发到新创建的 CompoundSelect 对象的构造函数。

方法 sqlalchemy.sql.expression.Select. intersect_all（*其他： _SelectStatementForCompoundArgument）→ CompoundSelect

针对作为位置参数提供的给定可选择对象返回此 select（） 构造的 SQL INTERSECT ALL。

参数

• 
  *其他 –

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

  
  在 1.4.28 版本发生变更： 现在接受多个元素。

• 
  **kwargs – 关键字参数被转发到新创建的 CompoundSelect 对象的构造函数。

方法 sqlalchemy.sql.expression.Select. is_derived_from（fromclause：FromClauseNone）→ bool

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

例如，Table 的别名是从该 Table 派生的。

method sqlalchemy.sql.expression.Select. join（target： _JoinTargetArgument， onclause：_OnClauseArgumentNone=None， *， isouter： bool = False， full： bool = False）→ 自身

针对此 Select 创建 SQL JOIN 对象的标准 并生成式应用，返回新生成的 选择。

例如：

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

上述语句生成类似于以下内容的 SQL：

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

在 1.4 版本发生变更： Select.join（） 现在在 FromClause 之间创建一个 Join 对象 source 的 SELECT 的 FROM 子句中， 和给定的目标 FromClause，然后将此 Join 添加到新生成的 SELECT 语句。 这完全是从 behavior 重新设计的 在 1.3 中，它会创建一个包含整个 选择该子查询，然后将其联接到目标。

这是一个向后不兼容的更改，因为之前的行为大多是无用的，在任何情况下都会产生一个被大多数数据库拒绝的未命名子查询。新行为是按照 ORM 中非常成功的 Query.join（） 方法建模的，以支持 Query 的功能 通过使用 Select 对象和 会话。

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

参数

• 
  target —— 要联接的目标表

• 
  on子句- 联接的 ON 子句。如果省略，则基于 ForeignKey 自动生成 ON 子句 两个表格之间的联系，如果可以明确 determined，否则会引发错误。

• 
  isouter 如果为 True，则生成 LEFT OUTER join。 等同 Select.outerjoin（） 中。

• 
  full – 如果为 True，则生成 FULL OUTER join。

另请参阅

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

联接 - ORM Querying Guide 中的

Select.join_from（）

Select.outerjoin（）

方法 sqlalchemy.sql.expression.Select. join_from（from_： _FromClauseArgument， target： _JoinTargetArgument， onclause：_OnClauseArgumentNone=None， *， isouter： bool = False， full： bool = False）→ 自身

针对此 Select 创建 SQL JOIN 对象的标准 并生成式应用，返回新生成的 选择。

例如：

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 —— 要联接的目标表

• 
  on子句- 联接的 ON 子句。

• 
  isouter 如果为 True，则生成 LEFT OUTER join。 等同 Select.outerjoin（） 中。

• 
  full – 如果为 True，则生成 FULL OUTER join。

另请参阅

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

联接 - ORM Querying Guide 中的

Select.join（）

方法 sqlalchemy.sql.expression.Select. label（name：strNone）→ Label[Any]

继承自SelectBase 的 SelectBase.label（） 方法

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

另请参阅

SelectBase.scalar_subquery（） 中。

方法 sqlalchemy.sql.expression.Select. lateral（name：strNone=None）→ LateralFromClause

继承自SelectBase 的 SelectBase.lateral（） 方法

返回此 Selectable 的 LATERAL 别名。

返回值是 Lateral 结构，也由顶级 lateral（） 函数提供。

另请参阅

LATERAL correlation - 用法概述。

method sqlalchemy.sql.expression.Select. limit（limit： _LimitOffsetType）→ Self

继承自 GenerativeSelect 的 GenerativeSelect.limit（） 方法

返回应用了给定 LIMIT 标准的新可选对象。

这是一个数值，通常呈现为 LIMIT expression 在生成的 select 中。 不这样做的后端 support LIMIT 将尝试提供类似的功能。

注意

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

参数

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

另请参阅

生成 Select.fetch（）

生成选择.offset（）

方法 sqlalchemy.sql.expression.Select. offset（offset： _LimitOffsetType）→ Self

继承自 GenerativeSelect 的 GenerativeSelect.offset（） 方法

返回应用了给定 OFFSET 条件的新可选对象。

这是一个数值，通常呈现为 OFFSET expression 在生成的 select 中。 不这样做的后端 support OFFSET 将尝试提供类似的功能。

参数

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

另请参阅

生成选择.limit（）

生成 Select.fetch（）

method sqlalchemy.sql.expression.Select. options（*options： ExecutableOption）→ 自身

继承自Executable 的 Executable.options（） 方法

将选项应用于此语句。

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

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

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

在 1.4 版本发生变更： - 将 Executable.options（） 添加到 Core 语句对象中，以实现允许统一的 Core / ORM 查询功能的目标。

另请参阅

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

Relationship Loading with Loader Options - 指特定于 ORM 查询使用的选项

方法 sqlalchemy.sql.expression.Select. order_by（_GenerativeSelect__first：Literal[None，_NoArg.NO_ARG]_ColumnExpressionOrStrLabelArgument[Any]=_NoArg.NO_ARG， *clauses： _ColumnExpressionOrStrLabelArgument[Any]）→ Self

继承自GenerativeSelect 的 GenerativeSelect.order_by（） 方法

返回应用了给定 ORDER BY 标准列表的新可选对象。

例如：

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

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

参数

子句—— 一系列 ColumnElement 构建 它将用于生成 ORDER BY 子句。

另请参阅

ORDER BY - 在 SQLAlchemy Unified Tutorial 中

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

方法 sqlalchemy.sql.expression.Select. outerjoin（target： _JoinTargetArgument， onclause：_OnClauseArgumentNone=None， *， full： bool = False）→自我

创建 left outer 联接。

参数与 Select.join（） 相同。

在 1.4 版本发生变更： Select.outerjoin（） 现在在 FromClause 源，该源位于现有 SELECT 的 FROM 子句内，以及给定的目标 FromClause，然后将此 Join 添加到 新生成的 SELECT 语句。 这是完全重新设计的 从 1.3 中的行为，它将创建一个 整个 选择该子查询，然后将其联接到目标。

这是一个向后不兼容的更改，因为之前的行为大多是无用的，在任何情况下都会产生一个被大多数数据库拒绝的未命名子查询。新行为是按照 ORM 中非常成功的 Query.join（） 方法建模的，以支持 Query 的功能 通过使用 Select 对象和 会话。

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

另请参阅

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

联接 - ORM Querying Guide 中的

Select.join（）

方法 sqlalchemy.sql.expression.Select. outerjoin_from（from_： _FromClauseArgument， target： _JoinTargetArgument， onclause：_OnClauseArgumentNone=None， *， full： bool = false）→ 自身

针对此创建一个 SQL LEFT OUTER JOIN Select 对象的条件并生成性应用，返回新生成的 Select。

用法与 Select.join_from（） 相同。

方法 sqlalchemy.sql.expression.Select. prefix_with（*prefixes： _TextCoercedExpressionArgument[Any]， dialect： str = '*'）→ 自身

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

在 statement 关键字后添加一个或多个表达式，即 SELECT、INSERT、UPDATE 或 DELETE。生成。

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

例如：

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

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

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

参数

• 
  前缀 – 文本或 ClauseElement 构造 将在 INSERT、UPDATE 或 DELETE 之后呈现 关键词。

• 
  dialect- 可选的字符串 dialect name，它将限制此前缀的渲染仅该方言。

方法 sqlalchemy.sql.expression.Select. reduce_columns（only_synonyms： bool = True）→ 选择

返回一个新的 select（） 结构，其中包含从 columns 子句中删除的冗余命名、等值列。

这里的 “Redundant” 是指两列，其中一列指的是 其他 要么基于外键，要么通过简单的相等 比较。 主要目的 的方法是自动构造一个 SELECT 语句 替换为所有唯一命名的列，而无需使用 table 限定标签指定为 Select.set_label_style（） 确实。

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

参数

only_synonyms – 当为 True 时，将删除的列限制为与等效项同名的列。否则，将删除所有等效于其他列的列。

方法 sqlalchemy.sql.expression.Select. replace_selectable（旧： FromClause， 别名： Alias）→ Self

继承自 Selectable.replace_selectable() Selectable 的方法

替换 FromClause 的所有匹配项 'old' 替换为给定的别名 object，返回此 FromClause 的副本。

1.4 版后已移除： 该方法 Selectable.replace_selectable() 已弃用，并将在未来发行版中删除。可通过 sqlalchemy.sql.visitors 模块使用类似的功能。

方法 sqlalchemy.sql.expression.Select. scalar_subquery（）→ ScalarSelect[Any]

继承自SelectBase 的 SelectBase.scalar_subquery（） 方法

返回此 selectable 的 'scalar' 表示，可用作列表达式。

返回的对象是 ScalarSelect 的实例。

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

请注意，标量子查询与 FROM 级别不同 子查询，可以使用 SelectBase.subquery（） 方法。

另请参阅

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

method sqlalchemy.sql.expression.Select. select（*arg： Any， **kw： Any）→ Select

继承自SelectBase 的 SelectBase.select（） 方法

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 或其他可选将具有 隐藏该 selectable 作为 渲染的 FROM 列表中的单个元素，而不是 将其呈现为 JOIN 子句。

虽然 Select.select_from（） 的典型用途 是 将默认的派生 FROM 子句替换为 join，它可以 也可以使用单个 table 元素多次调用 如果需要，在 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 集合不会 包括在 columns 子句中使用 text（） 结构;这些在 收集。要在 选择 construct，使用 literal_column（） 构建。

在 1.4 版本加入.

方法 sqlalchemy.sql.expression.Select. self_group（against：OperatorTypeNone=None）→SelectStatementGroupingSelf

根据 ClauseElement 规范。

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

方法 sqlalchemy.sql.expression.Select. set_label_style（style： SelectLabelStyle）→ Self

继承自 GenerativeSelect.set_label_style() GenerativeSelect 的方法

返回具有指定标签样式的新可选对象。

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

在现代 SQLAlchemy 中，通常不需要更改标签样式，因为通过使用 ColumnElement.label（） 方法可以更有效地使用每个表达式的标签。在以前的版本中， LABEL_STYLE_TABLENAME_PLUS_COL 用于消除来自不同表、别名或子查询的同名列的歧义;较新的LABEL_STYLE_DISAMBIGUATE_ONLY现在仅将标签应用于与现有名称冲突的名称，因此此标签的影响最小。

消除歧义的基本原理主要是使所有列表达式都可以从给定的 FromClause.c 中获得 集合。

1.4 版本的新Function： - 该 GenerativeSelect.set_label_style() method 取代了之前 .apply_labels（）、.with_labels（） 和 use_labels=True 方法和/或参数。

另请参阅

LABEL_STYLE_DISAMBIGUATE_ONLY

LABEL_STYLE_TABLENAME_PLUS_COL

LABEL_STYLE_NONE

LABEL_STYLE_DEFAULT

方法 sqlalchemy.sql.expression.Select. slice（start： int， stop： int）→ Self

继承自 GenerativeSelect 的 GenerativeSelect.slice（） 方法

根据切片将 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（） 的子句。

1.4 版本中的新功能： 添加了 GenerativeSelect.slice（） 方法从 ORM 推广而来。

另请参阅

生成选择.limit（）

生成选择.offset（）

生成 Select.fetch（）

method sqlalchemy.sql.expression.Select. subquery（name：strNone=None）→ 子查询

继承自SelectBase 的 SelectBase.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（） 等效于调用 FromClause.alias（） method 对 FROM 对象执行;然而 作为 SelectBase object 不是直接的 FROM 对象， SelectBase.subquery（） method 提供更清晰的语义。

在 1.4 版本加入.

方法 sqlalchemy.sql.expression.Select. suffix_with（*suffixes： _TextCoercedExpressionArgument[Any]， 方言： str = '*'）→ 自身

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

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

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

例如：

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

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

参数

• 
  *suffixes– 文本或 ClauseElement 构造 将在 Target 子句之后呈现。

• 
  dialect- 可选的字符串 dialect name，它将限制此后缀的渲染仅该方言。

方法 sqlalchemy.sql.expression.Select. union（*other： _SelectStatementForCompoundArgument）→ CompoundSelect

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

参数

• 
  *其他 –

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

  
  在 1.4.28 版本发生变更： 现在接受多个元素。

• 
  **kwargs – 关键字参数被转发到新创建的 CompoundSelect 对象的构造函数。

方法 sqlalchemy.sql.expression.Select. union_all（*其他： _SelectStatementForCompoundArgument）→ CompoundSelect

针对作为位置参数提供的给定可选择对象返回此 select（） 构造的 SQL UNION ALL。

参数

• 
  *其他 –

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

  
  在 1.4.28 版本发生变更： 现在接受多个元素。

• 
  **kwargs – 关键字参数被转发到新创建的 CompoundSelect 对象的构造函数。

method sqlalchemy.sql.expression.Select. where（*whereclause： _ColumnExpressionArgument[bool]）→ Self

返回一个新的 select（） 结构，其中给定的表达式添加到其 WHERE 子句中，并通过 AND 连接到现有子句（如果有）。

属性 sqlalchemy.sql.expression.Select. where子句

返回 this 的已完成的 WHERE 子句 Select 语句。

这会将 WHERE 条件的当前集合组合到单个 BooleanClauseList 构造中。

在 1.4 版本加入.

method sqlalchemy.sql.expression.Select. with_for_update（*， nowait： bool = False， read： bool = False， of：_ForUpdateOfArgumentNone=None， skip_locked： bool = False， key_share： bool = False）→ Self

继承自 GenerativeSelect.with_for_update() GenerativeSelect 的方法

为此指定 FOR UPDATE 子句 GenerativeSelect 的

例如：

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

在 PostgreSQL 或 Oracle Database 等数据库上，上述内容将呈现如下语句：

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， FOR SHARE 在 PostgreSQL 上。 在 PostgreSQL 上，当与 nowait 将呈现 FOR SHARE NOWAIT。

• 
  of- SQL 表达式或 SQL 表达式元素列表（通常是 Column 对象或兼容的表达式，对于某些后端也可能是表表达式），它将呈现为 FOR UPDATE OF 子句;受 PostgreSQL、Oracle Database、某些 MySQL 版本和其他版本支持。可以呈现为表或列，具体取决于后端。

• 
  skip_locked – 布尔值，将在 Oracle 数据库和 PostgreSQL 方言上呈现 FOR UPDATE SKIP LOCKED 或 FOR SHARE SKIP LOCKED 如果还指定了 read=True。

• 
  key_share —— 布尔值，将在 PostgreSQL 方言上呈现 FOR NO KEY UPDATE，或者如果与 read=True 结合使用，将呈现 FOR KEY SHARE。

方法 sqlalchemy.sql.expression.Select. with_hint（可选：_FromClauseArgument、文本：str、dialect_name：str = '*'）→ 自身

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

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

提示

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

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

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

将 SQL 呈现为：

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

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

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

另请参阅

Select.with_statement_hint（）

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

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

在此作模式下，Select.with_only_columns（） 还将动态更改 声明（如果未明确说明）。 要维护现有的 FROM 集，包括 current columns 子句中，添加 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 parameter 使用 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 –

  
  boolean 参数，该参数将确保 current columns 子句中隐含的 FROM 列表将首先传输到 Select.select_from（） 方法。

  
  在 1.4.23 版本加入.

方法 sqlalchemy.sql.expression.Select. with_statement_hint（text： str， dialect_name： str = '*'）→ Self

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

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

提示

Select.with_statement_hint（） 通常会添加提示 在 SELECT 语句的尾端。要将特定于方言的提示（如优化器提示）放在 在 SELECT 关键字后的 SELECT 语句中，使用 Select.prefix_with（） 方法的开放式 space 的 API API 中，或者对于特定于表的提示， 可以使用 Select.with_hint（） ，它将提示放置在特定于方言的位置。

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

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

另请参阅

Select.with_hint（）

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

类 sqlalchemy.sql.expression 中。可选

将类标记为可选。

成员

corresponding_column（）、exported_columns、inherit_cache、is_derived_from（）、横向（）、replace_selectable（）

类签名

类 sqlalchemy.sql.expression.Selectable （ sqlalchemy.sql.expression.ReturnsRows ）

方法 sqlalchemy.sql.expression.Selectable. corresponding_column（column： KeyedColumnElement[Any]， require_embedded： bool = False）→KeyedColumnElement[任何]无

给定一个 ColumnElement，返回导出的 ColumnElement 对象 Selectable.exported_columns collection 的 这与 原始 ColumnElement 通过公共上级列。

参数

• 
  column—— 目标 ColumnElement 进行匹配。

• 
  require_embedded —— 如果给定的 ColumnElement ColumnElement （列元素） 实际上存在于子元素中 的这个 Selectable。通常，如果该列仅与此 Selectable 的导出列之一共享一个共同的祖先，则该列将匹配。

另请参阅

Selectable.exported_columns - 的 ColumnCollection 系列 用于作。

ColumnCollection.corresponding_column() -实现 方法。

属性 sqlalchemy.sql.expression.Selectable. exported_columns

继承自ReturnsRows 的 ReturnsRows.exported_columns属性

一个 ColumnCollection 表示 “exported” 列的 ReturnsRows 中。

“exported” 列表示 ColumnElement （列元素） 此 SQL 呈现的表达式 构建。 主要品种是 FROM 子句的 “FROM 子句列”，例如 table、join 和 或子查询的 “SELECTed columns” ，即 SELECT 语句的 “columns 子句” 和 RETURNING 列在 DML 语句中..

在 1.4 版本加入.

另请参阅

FromClause.exported_columns

SelectBase.exported_columns

属性 sqlalchemy.sql.expression.Selectable. inherit_cache：boolNone = None

继承自HasCacheKey 的 HasCacheKey.inherit_cache属性

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

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

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

另请参阅

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

方法 sqlalchemy.sql.expression.Selectable. is_derived_from（fromclause：FromClauseNone）→ bool

继承自ReturnsRows 的 ReturnsRows.is_derived_from（） 方法

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

例如，Table 的别名是从该 Table 派生的。

方法 sqlalchemy.sql.expression.Selectable. lateral（name：strNone=None）→ LateralFromClause

返回此 Selectable 的 LATERAL 别名。

返回值是 Lateral 结构，也由顶级 lateral（） 函数提供。

另请参阅

LATERAL correlation - 用法概述。

方法 sqlalchemy.sql.expression.Selectable. replace_selectable（旧： FromClause， 别名： Alias）→ Self

替换 FromClause 的所有匹配项 'old' 替换为给定的别名 object，返回此 FromClause 的副本。

1.4 版后已移除： 该方法 Selectable.replace_selectable() 已弃用，并将在未来发行版中删除。可通过 sqlalchemy.sql.visitors 模块使用类似的功能。

类 sqlalchemy.sql.expression 中。SelectBase

SELECT 语句的基类。

这包括 Select、 CompoundSelect 和 TextualSelect 的

成员

add_cte（）， 别名（）， as_scalar（）， c， corresponding_column（）， cte（）， exists（）， exported_columns， get_label_style（）， inherit_cache， is_derived_from（）， label（）， lateral（）， replace_selectable（）、scalar_subquery（）、select（）、selected_columns、set_label_style（）、subquery（）

类签名

类 sqlalchemy.sql.expression.SelectBase （ sqlalchemy.sql.roles.SelectStatementRole ， sqlalchemy.sql.roles.DMLSelectRole ， sqlalchemy.sql.roles.CompoundElementRole ， sqlalchemy.sql.roles.InElementRole ， sqlalchemy.sql.expression.HasCTE sqlalchemy.sql.annotation.SupportsCloneAnnotations sqlalchemy.sql.expression.Selectable ）

方法 sqlalchemy.sql.expression.SelectBase. add_cte（*ctes： CTE， nest_here： bool = False）→ Self

继承自HasCTE 的 HasCTE.add_cte（） 方法

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

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

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

此方法有两个一般用途。一种是嵌入具有某种用途而不明确引用的 CTE 语句，例如将 DML 语句（如 INSERT 或 UPDATE）嵌入为 CTE 的用例，该 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 construct 生成 “upsert”：

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

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

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

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

print(update_statement)

上述语句呈现为：

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

在 1.4.21 版本加入.

参数

• *ctes –

  
  零个或多个 CTE 构造。

  
  在 2.0 版更改： 接受多个 CTE 实例

• nest_here –

  
  如果为 True，则给定的一个或多个 CTE 将呈现，就像它们在添加到此 HasCTE 时将 HasCTE.cte.nesting 标志指定为 True 一样。假设给定的 CTE 在外部封闭语句中也没有引用，则给定的 CTE 应在给定此标志时在此语句的级别呈现。

  
  2.0 版的新Function。

  
  另请参阅

  
  HasCTE.cte.嵌套

method sqlalchemy.sql.expression.SelectBase. alias（name：strNone=None， flat： bool = False）→ 子查询

返回针对 this 的命名子查询 SelectBase 的 Pod 中。

对于 SelectBase（而不是 FromClause），这将返回一个 Subquery 对象，该对象的行为与与 From子句。

在 1.4 版本发生变更： SelectBase.alias（） method 现在是 SelectBase.subquery（） 方法的同义词。

方法 sqlalchemy.sql.expression.SelectBase. as_scalar（）→ ScalarSelect[Any]

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

属性 sqlalchemy.sql.expression.SelectBase. c

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

方法 sqlalchemy.sql.expression.SelectBase. corresponding_column（column： KeyedColumnElement[Any]， require_embedded： bool = False）→KeyedColumnElement[任何]无

继承自 Selectable.corresponding_column() Selectable 的方法

给定一个 ColumnElement，返回导出的 ColumnElement 对象 Selectable.exported_columns collection 的 这与 原始 ColumnElement 通过公共上级列。

参数

• 
  column—— 目标 ColumnElement 进行匹配。

• 
  require_embedded —— 如果给定的 ColumnElement ColumnElement （列元素） 实际上存在于子元素中 的这个 Selectable。通常，如果该列仅与此 Selectable 的导出列之一共享一个共同的祖先，则该列将匹配。

另请参阅

Selectable.exported_columns - 的 ColumnCollection 系列 用于作。

ColumnCollection.corresponding_column() -实现 方法。

方法 sqlalchemy.sql.expression.SelectBase. cte（name：strNone=None， 递归： bool = False， 嵌套： bool = False）→ CTE

继承自HasCTE 的 HasCTE.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（） method 可能是 用于建立这些。

在 1.3.13 版本发生变更： 添加了对前缀的支持。特别是 - MATERIALIZED 和 NOT MATERIALIZED。

参数

• 
  name – 公共表表达式的名称。 喜欢 FromClause.alias（）中，名称可以保留为 none ，在这种情况下，将在查询编译时使用匿名符号。

• 
  recursive – 如果为 True，将渲染 WITH RECURSIVE。递归公用表表达式旨在与 UNION ALL 结合使用，以便从已选择的行中派生行。

• 
  嵌套 –

  
  如果为 True，则会在本地将 CTE 呈现到引用它的语句。对于更复杂的场景HasCTE.add_cte，使用 HasCTE.add_cte.nest_here 参数也可以更仔细地使用 控制特定 CTE 的确切位置。

  
  在 1.4.24 版本加入.

  
  另请参阅

  
  HasCTE.add_cte（）

以下示例包括 PostgreSQL 文档中的两个示例，网址为 https://www.postgresql.org/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 结合使用的更新插入：

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（） - 的 ORM 版本 HasCTE.cte（） 的

method sqlalchemy.sql.expression.SelectBase. exists（）→ 存在

返回此可选对象的 Exists 表示形式，该表示形式可用作列表达式。

返回的对象是 Exists 的实例。

另请参阅

存在（）

EXISTS 子查询 - 在 2.0 样式教程中。

在 1.4 版本加入.

属性 sqlalchemy.sql.expression.SelectBase. exported_columns

一个 ColumnCollection 表示 “exported” 列，不包括 TextClause 构造。

SelectBase 的 “exported” 列 object 是同义词 与 SelectBase.selected_columns 系列。

在 1.4 版本加入.

另请参阅

Select.exported_columns

Selectable.exported_columns

FromClause.exported_columns

方法 sqlalchemy.sql.expression.SelectBase. get_label_style（）→ SelectLabelStyle

检索当前标签样式。

由子类实现。

属性 sqlalchemy.sql.expression.SelectBase. inherit_cache：boolNone = None

继承自HasCacheKey 的 HasCacheKey.inherit_cache属性

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

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

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

另请参阅

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

方法 sqlalchemy.sql.expression.SelectBase. is_derived_from（fromclause：FromClauseNone）→ bool

继承自ReturnsRows 的 ReturnsRows.is_derived_from（） 方法

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

例如，Table 的别名是从该 Table 派生的。

方法 sqlalchemy.sql.expression.SelectBase. label（name：strNone）→ Label[Any]

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

另请参阅

SelectBase.scalar_subquery（） 中。

方法 sqlalchemy.sql.expression.SelectBase. lateral（name：strNone=None）→ LateralFromClause

返回此 Selectable 的 LATERAL 别名。

返回值是 Lateral 结构，也由顶级 lateral（） 函数提供。

另请参阅

LATERAL correlation - 用法概述。

方法 sqlalchemy.sql.expression.SelectBase. replace_selectable（旧： FromClause， 别名： Alias）→ Self

继承自 Selectable.replace_selectable() Selectable 的方法

替换 FromClause 的所有匹配项 'old' 替换为给定的别名 object，返回此 FromClause 的副本。

1.4 版后已移除： 该方法 Selectable.replace_selectable() 已弃用，并将在未来发行版中删除。可通过 sqlalchemy.sql.visitors 模块使用类似的功能。

方法 sqlalchemy.sql.expression.SelectBase. scalar_subquery（）→ ScalarSelect[Any]

返回此 selectable 的 'scalar' 表示，可用作列表达式。

返回的对象是 ScalarSelect 的实例。

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

请注意，标量子查询与 FROM 级别不同 子查询，可以使用 SelectBase.subquery（） 方法。

另请参阅

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

method sqlalchemy.sql.expression.SelectBase. select（*arg： Any， **kw： Any）→ Select

1.4 版后已移除： SelectBase.select（） 方法已弃用，并将在未来版本中删除;此方法隐式创建一个应该是显式的子查询。请先调用 SelectBase.subquery（） 以创建子查询，然后可以选择该子查询。

属性 sqlalchemy.sql.expression.SelectBase. selected_columns

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

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

注意

SelectBase.selected_columns 集合不会 包括在 columns 子句中使用 text（） 结构;这些在 收集。要在 选择 construct，使用 literal_column（） 构建。

另请参阅

Select.selected_columns

在 1.4 版本加入.

方法 sqlalchemy.sql.expression.SelectBase. set_label_style（style： SelectLabelStyle）→ Self

返回具有指定标签样式的新可选对象。

由子类实现。

method sqlalchemy.sql.expression.SelectBase. subquery（name：strNone=None）→ 子查询

返回此 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（） 等效于调用 FromClause.alias（） method 对 FROM 对象执行;然而 作为 SelectBase object 不是直接的 FROM 对象， SelectBase.subquery（） method 提供更清晰的语义。

在 1.4 版本加入.

类 sqlalchemy.sql.expression 中。子查询

表示 SELECT 的子查询。

通过调用 SelectBase.subquery（） 方法，或者为方便起见，使用 SelectBase.alias（） 方法，在任何 SelectBase 子类，其中包括 Select、 CompoundSelect 和 TextualSelect 的在 FROM 子句中呈现时，它表示括号内 SELECT 语句的主体，后跟定义所有“别名”对象的常用“AS <somename>”。

Subquery 对象与 别名 object 的 intent 和可以以等效方式使用。 之间的区别 别名和子查询是 别名始终包含一个 FromClause 对象，而 子查询 始终包含一个 SelectBase 对象。

1.4 版本中的新功能： 添加了 Subquery 类，该类现在用于提供 SELECT 语句的别名版本。

成员

as_scalar（）， inherit_cache

类签名

类 sqlalchemy.sql.expression.Subquery （ sqlalchemy.sql.expression.AliasedReturnsRows ）

方法 sqlalchemy.sql.expression.Subquery. as_scalar（）→ ScalarSelect[Any]

1.4 版后已移除： 之前在 1.4 版本之前为 Alias.as_scalar（） 的 Subquery.as_scalar（） 方法已弃用，并将在未来版本中删除;在构造子查询对象之前，请使用 select（） 构造的 Select.scalar_subquery（） 方法，或者在 ORM 中使用 Query.scalar_subquery（） 方法。

属性 sqlalchemy.sql.expression.Subquery. inherit_cache：boolNone = True

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

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

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

另请参阅

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

类 sqlalchemy.sql.expression 中。Table子句

表示最小的 “table” 构造。

这是一个轻量级的表对象，只有一个名称、一个列的集合（通常由 column（） 函数生成）和一个架构：

from sqlalchemy import table, column

user = table(
    "user",
    column("id"),
    column("name"),
    column("description"),
)

TableClause 结构用作更常用的 Table 对象的基础，提供通常的 FromClause 服务集，包括 .c. 集合和语句生成方法。

它不提供 Table 的所有其他 schema 级服务，包括约束、对其他表的引用或对 MetaData 级服务的支持。它本身作为一个临时结构很有用，当一个更完整的 Table 不在手头。

成员

alias（）， c， columns， compare（）， compile（）， corresponding_column（）， delete（）， description， entity_namespace， exported_columns， foreign_keys， get_children（）， implicit_returning， inherit_cache， insert（）， is_derived_from（）， join（）， lateral（）， outerjoin（）， params（）， primary_key， replace_selectable（）， schema， select（）， self_group（）， table_valued（）， tablesample（）、unique_params（）、update（）

类签名

类 sqlalchemy.sql.expression.TableClause （ sqlalchemy.sql.roles.DMLTableRole ， sqlalchemy.sql.expression.Immutable ， sqlalchemy.sql.expression.NamedFromClause ）

method sqlalchemy.sql.expression.TableClause. alias（name：strNone=None， flat： bool = False）→ NamedFromClause

继承自FromClause 的 FromClause.alias（） 方法

返回此 FromClause 的别名。

例如：

a2 = some_table.alias("a2")

上面的代码创建了一个别名 可以使用 作为任何 SELECT 语句中的 FROM 子句。

另请参阅

使用别名

别名（）

属性 sqlalchemy.sql.expression.TableClause. c

继承自FromClause 的 FromClause.c 属性

FromClause.columns 的同义词

结果

一个 ColumnCollection

属性 sqlalchemy.sql.expression.TableClause. 列

继承自FromClause 的 FromClause.columns属性

ColumnElement 的基于命名的集合 对象。

列或 c 集合是使用表绑定列或其他可选绑定列构造 SQL 表达式的网关：

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

结果

一个 ColumnCollection 对象。

method sqlalchemy.sql.expression.TableClause. compare（other： ClauseElement， **kw： Any）→ bool

继承自ClauseElement 的 ClauseElement.compare（） 方法

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

子类应覆盖默认行为，即直接的恒等比较。

**kw 是子类 compare（） 方法使用的参数，可用于修改比较条件（参见 ColumnElement）。

method sqlalchemy.sql.expression.TableClause. compile（bind：_HasDialectNone=None， dialect：DialectNone=None， **kw： Any）→ 已编译

继承自CompilerElement 的 CompilerElement.compile（） 方法

编译此 SQL 表达式。

返回值是一个 Compiled 对象。对返回值调用 str（） 或 unicode（） 将产生一个 string 表示形式。这 Compiled 对象还可以使用 params 访问器返回绑定参数名称和值的字典。

参数

• 
  bind– 一个 Connection 或 Engine，可以提供 Dialect 以生成 Compiled 对象。如果 bind 和 dialect 参数都省略了，而是使用默认的 SQL 编译器。

• 
  column_keys – 用于 INSERT 和 UPDATE 语句，编译语句的 VALUES 子句中应存在的列名列表。如果为 None，则呈现目标表对象中的所有列。

• 
  dialect- 一个可以生成 Compiled 对象的 Dialect 实例。此参数优先于 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.TableClause. corresponding_column（column： KeyedColumnElement[Any]， require_embedded： bool = False）→KeyedColumnElement[任何]无

继承自 Selectable.corresponding_column() Selectable 的方法

给定一个 ColumnElement，返回导出的 ColumnElement 对象 Selectable.exported_columns collection 的 这与 原始 ColumnElement 通过公共上级列。

参数

• 
  column—— 目标 ColumnElement 进行匹配。

• 
  require_embedded —— 如果给定的 ColumnElement ColumnElement （列元素） 实际上存在于子元素中 的这个 Selectable。通常，如果该列仅与此 Selectable 的导出列之一共享一个共同的祖先，则该列将匹配。

另请参阅

Selectable.exported_columns - 的 ColumnCollection 系列 用于作。

ColumnCollection.corresponding_column() -实现 方法。

method sqlalchemy.sql.expression.TableClause. ： delete（）→ 删除

针对 this 生成 delete（） 构造 TableClause 的

例如：

table.delete().where(table.c.id == 7)

有关参数和使用信息，请参阅 delete（） 。

属性 sqlalchemy.sql.expression.TableClause. 说明

属性 sqlalchemy.sql.expression.TableClause. entity_namespace

继承自FromClause 的 FromClause.entity_namespace属性

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

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

stmt.filter_by(address="some address")

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

属性 sqlalchemy.sql.expression.TableClause. exported_columns

继承自FromClause 的 FromClause.exported_columns属性

一个 ColumnCollection 表示 “exported” 列。

FromClause 的 “exported” 列 object 是同义词 替换为 FromClause.columns 集合。

在 1.4 版本加入.

另请参阅

Selectable.exported_columns

SelectBase.exported_columns

属性 sqlalchemy.sql.expression.TableClause. foreign_keys

继承自FromClause 的 FromClause.foreign_keys属性

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

每个 ForeignKey 都是 表范围 ForeignKeyConstraint 的 Constraint 对象。

另请参阅

Table.foreign_key_constraints

方法 sqlalchemy.sql.expression.TableClause. get_children（*， omit_attrs： Tuple[str， ...] = （）， **kw： Any）→ Iterable[HasTraverseInternals]

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

返回紧接的子 HasTraverseInternals 元素中。

这用于访问遍历。

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

属性 sqlalchemy.sql.expression.TableClause. implicit_returning = False

TableClause 不支持使用主键或列 -level 默认值，因此隐式返回不适用。

属性 sqlalchemy.sql.expression.TableClause. inherit_cache：boolNone = None

继承自HasCacheKey 的 HasCacheKey.inherit_cache属性

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

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

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

另请参阅

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

方法 sqlalchemy.sql.expression.TableClause. insert（）→ 插入

针对此生成 Insert 构造 TableClause 的

例如：

table.insert().values(name="foo")

有关参数和使用信息，请参阅 insert（） 。

方法 sqlalchemy.sql.expression.TableClause. is_derived_from（fromclause：FromClauseNone）→ bool

继承自FromClause 的 FromClause.is_derived_from（） 方法

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

例如，Table 的别名是从该 Table 派生的。

method sqlalchemy.sql.expression.TableClause. join（right： _FromClauseArgument， onclause：_ColumnExpressionArgument[bool]None=None， isouter： bool = False， full： bool = False）→ 加入

继承自FromClause 的 FromClause.join（） 方法

从此返回 Join From子句 转换为另一个 FromClause。

例如：

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 映射的类。

• 
  on子句– 表示联接的 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.TableClause. lateral（name：strNone=None）→ LateralFromClause

继承自Selectable 的 Selectable.lateral（） 方法

返回此 Selectable 的 LATERAL 别名。

返回值是 Lateral 结构，也由顶级 lateral（） 函数提供。

另请参阅

LATERAL correlation - 用法概述。

方法 sqlalchemy.sql.expression.TableClause. outerjoin（right： _FromClauseArgument， onclause：_ColumnExpressionArgument[bool]None=None， full： bool = False）→ Join

继承自FromClause 的 FromClause.outerjoin（） 方法

从此返回 Join From子句 添加到另一个 FromClause，并将 “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 映射的类。

• 
  on子句– 表示联接的 ON 子句的 SQL 表达式。如果保留为 None，则 FromClause.join（） 将尝试 根据外键关系联接两个表。

• 
  full – 如果为 True，则渲染 FULL OUTER JOIN，而不是 LEFT OUTER JOIN。

另请参阅

FromClause.join（）

加入

method sqlalchemy.sql.expression.TableClause. params（*optionaldict， **kwargs）

继承自Immutable 的 Immutable.params（） 方法

返回替换了 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.TableClause. primary_key

继承自FromClause 的 FromClause.primary_key属性

返回构成此_selectable的主键的 Column 对象的可迭代集合。From子句。

对于 Table 对象，此集合由 PrimaryKeyConstraint 表示，它本身是 Column 对象的可迭代集合。

方法 sqlalchemy.sql.expression.TableClause. replace_selectable（旧： FromClause， 别名： Alias）→ Self

继承自 Selectable.replace_selectable() Selectable 的方法

替换 FromClause 的所有匹配项 'old' 替换为给定的别名 object，返回此 FromClause 的副本。

1.4 版后已移除： 该方法 Selectable.replace_selectable() 已弃用，并将在未来发行版中删除。可通过 sqlalchemy.sql.visitors 模块使用类似的功能。

attribute sqlalchemy.sql.expression.TableClause. schema：strNone = None（无

继承自FromClause 的 FromClause.schema属性

定义此 FromClause 的 'schema' 属性。

对于大多数对象，这通常为 None，但 Table 中，它被视为 Table.schema 参数。

方法 sqlalchemy.sql.expression.TableClause. select（）→ Select

继承自FromClause 的 FromClause.select（） 方法

返回此 FromClause 的 SELECT。

例如：

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

另请参阅

select（） - 允许任意列列表的通用方法。

方法 sqlalchemy.sql.expression.TableClause. self_group（against：OperatorTypeNone=None）→ ClauseElement

继承自ClauseElement 的 ClauseElement.self_group（） 方法

将 'grouping' 应用于此 ClauseElement。

此方法被 subclasses 覆盖以返回 “grouping” 结构，即括号。特别是，当它被 “binary” 表达式用于在放入更大的表达式时提供围绕自身的分组，以及 select（） 构造 select（） 的（请注意，子查询通常应使用 Select.alias（） 方法创建，因为许多平台需要命名嵌套的 SELECT 语句）。

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

的 base self_group（） 方法 子句元素 只返回 self。

方法 sqlalchemy.sql.expression.TableClause. table_valued（）→ TableValuedColumn[Any]

继承自 NamedFromClause.table_valued() NamedFromClause 的方法

为此返回一个 TableValuedColumn 对象 From子句。

TableValuedColumn 是表示表中完整行的 ColumnElement。对此结构的支持取决于后端，并且 PostgreSQL、Oracle Database 和 SQL Server 等后端以各种形式支持。

例如：

>>> from sqlalchemy import select, 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 版本的新Function。

另请参阅

使用 SQL 函数 - 在 SQLAlchemy Unified 教程中

method sqlalchemy.sql.expression.TableClause. tablesample（sampling：floatFunction[Any]， name：strNone=None， seed：roles.ExpressionElementRole[Any]None=None）→ TableSample

继承自FromClause 的 FromClause.tablesample（）方法

返回此 FromClause 的 TABLESAMPLE 别名。

返回值为 TableSample 还构建 由顶级 tablesample（） 函数提供。

另请参阅

tablesample（） - 使用指南和参数

方法 sqlalchemy.sql.expression.TableClause. unique_params（*optionaldict， **kwargs）

继承自Immutable 的 Immutable.unique_params（） 方法

返回替换了 bindparam（） 元素的副本。

与 ClauseElement.params（） 功能相同，但添加了 unique=True 添加到受影响的绑定参数中，以便多个语句可以 使用。

方法 sqlalchemy.sql.expression.TableClause. update（）→ Update

针对此生成 update（） 构造 TableClause 的

例如：

table.update().where(table.c.id == 7).values(name="foo")

有关参数和使用信息，请参见 update（） 。

类 sqlalchemy.sql.expression 中。TableSample

表示 TABLESAMPLE 子句。

此对象由 tablesample（） 模块级函数以及 FromClause.tablesample（） 构造 方法 在所有 FromClause 子类中可用。

另请参阅

表样本（）

类签名

类 sqlalchemy.sql.expression.TableSample （ sqlalchemy.sql.expression.FromClauseAlias ）

类 sqlalchemy.sql.expression 中。TableValued别名

“table valued” SQL 函数的别名。

此构造提供了一个 SQL 函数，该函数返回要在 SELECT 语句的 FROM 子句中使用的列。该对象是使用 FunctionElement.table_valued() 方法，例如：

>>> from sqlalchemy import select, 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 版本的新Function。

另请参阅

表值函数 - 在 SQLAlchemy Unified 教程中

成员

alias（）， column， lateral（）， render_derived（）

类签名

类 sqlalchemy.sql.expression.TableValuedAlias （ sqlalchemy.sql.expression.LateralFromClause ， sqlalchemy.sql.expression.Alias ）

method sqlalchemy.sql.expression.TableValuedAlias. alias（name：strNone=None， flat： bool = False）→ TableValuedAlias

返回此 TableValuedAlias 的新别名。

这将创建一个不同的 FROM 对象，该对象在 SQL 语句中使用时将与原始对象区分开来。

attribute sqlalchemy.sql.expression.TableValuedAlias. 列

返回表示此的列表达式 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：strNone=None）→ LateralFromClause

返回设置了 lateral 标志的新 TableValuedAlias，以便它呈现为 LATERAL。

另请参阅

横向（）

方法 sqlalchemy.sql.expression.TableValuedAlias. render_derived（name：strNone=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 构造包装在 选择基地 接口。

这允许 TextClause 对象获得 .c 集合 以及其他类似 FROM 的功能，例如 FromClause.alias（）中，则 SelectBase.cte（） 等。

TextualSelect 构造是通过 TextClause.columns（） method - 有关详细信息，请参阅该方法。

在 1.4 版本发生变更： TextualSelect class 已重命名 从 TextAsFrom 开始，以更准确地适应其作为面向 SELECT 的对象而不是 FROM 子句的角色。

另请参阅

文本（）

TextClause.columns（） - 主创建界面。

成员

add_cte（）， 别名（）， as_scalar（）， c， compare（）， compile（）， corresponding_column（）， cte（）， execution_options（）， exists（）， exported_columns， get_children（）， get_execution_options（）， get_label_style（）， inherit_cache， is_derived_from（）， label（）， lateral（）， options（）， params（）， replace_selectable（）， scalar_subquery（）， select（）， selected_columns， self_group（）， set_label_style（）、subquery（）、unique_params（）

类签名

类 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

继承自HasCTE 的 HasCTE.add_cte（） 方法

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

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

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

此方法有两个一般用途。一种是嵌入具有某种用途而不明确引用的 CTE 语句，例如将 DML 语句（如 INSERT 或 UPDATE）嵌入为 CTE 的用例，该 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 construct 生成 “upsert”：

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

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

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

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

print(update_statement)

上述语句呈现为：

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

在 1.4.21 版本加入.

参数

• *ctes –

  
  零个或多个 CTE 构造。

  
  在 2.0 版更改： 接受多个 CTE 实例

• nest_here –

  
  如果为 True，则给定的一个或多个 CTE 将呈现，就像它们在添加到此 HasCTE 时将 HasCTE.cte.nesting 标志指定为 True 一样。假设给定的 CTE 在外部封闭语句中也没有引用，则给定的 CTE 应在给定此标志时在此语句的级别呈现。

  
  2.0 版的新Function。

  
  另请参阅

  
  HasCTE.cte.嵌套

method sqlalchemy.sql.expression.TextualSelect. alias（name：strNone=None， flat： bool = False）→ 子查询

继承自SelectBase 的 SelectBase.alias（） 方法

返回针对 this 的命名子查询 SelectBase 的 Pod 中。

对于 SelectBase（而不是 FromClause），这将返回一个 Subquery 对象，该对象的行为与与 From子句。

在 1.4 版本发生变更： SelectBase.alias（） method 现在是 SelectBase.subquery（） 方法的同义词。

方法 sqlalchemy.sql.expression.TextualSelect. as_scalar（）→ ScalarSelect[Any]

继承自SelectBase 的 SelectBase.as_scalar（） 方法

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

属性 sqlalchemy.sql.expression.TextualSelect. c

继承自SelectBase 的 SelectBase.c属性

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

method sqlalchemy.sql.expression.TextualSelect. compare（other： ClauseElement， **kw： Any）→ bool

继承自ClauseElement 的 ClauseElement.compare（） 方法

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

子类应覆盖默认行为，即直接的恒等比较。

**kw 是子类 compare（） 方法使用的参数，可用于修改比较条件（参见 ColumnElement）。

method sqlalchemy.sql.expression.TextualSelect. compile（bind：_HasDialectNone=None， dialect：DialectNone=None， **kw： Any）→ 已编译

继承自CompilerElement 的 CompilerElement.compile（） 方法

编译此 SQL 表达式。

返回值是一个 Compiled 对象。对返回值调用 str（） 或 unicode（） 将产生一个 string 表示形式。这 Compiled 对象还可以使用 params 访问器返回绑定参数名称和值的字典。

参数

• 
  bind– 一个 Connection 或 Engine，可以提供 Dialect 以生成 Compiled 对象。如果 bind 和 dialect 参数都省略了，而是使用默认的 SQL 编译器。

• 
  column_keys – 用于 INSERT 和 UPDATE 语句，编译语句的 VALUES 子句中应存在的列名列表。如果为 None，则呈现目标表对象中的所有列。

• 
  dialect- 一个可以生成 Compiled 对象的 Dialect 实例。此参数优先于 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[任何]无

继承自 Selectable.corresponding_column() Selectable 的方法

给定一个 ColumnElement，返回导出的 ColumnElement 对象 Selectable.exported_columns collection 的 这与 原始 ColumnElement 通过公共上级列。

参数

• 
  column—— 目标 ColumnElement 进行匹配。

• 
  require_embedded —— 如果给定的 ColumnElement ColumnElement （列元素） 实际上存在于子元素中 的这个 Selectable。通常，如果该列仅与此 Selectable 的导出列之一共享一个共同的祖先，则该列将匹配。

另请参阅

Selectable.exported_columns - 的 ColumnCollection 系列 用于作。

ColumnCollection.corresponding_column() -实现 方法。

方法 sqlalchemy.sql.expression.TextualSelect. cte（name：strNone=None， 递归： bool = False， 嵌套： bool = False）→ CTE

继承自HasCTE 的 HasCTE.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（） method 可能是 用于建立这些。

在 1.3.13 版本发生变更： 添加了对前缀的支持。特别是 - MATERIALIZED 和 NOT MATERIALIZED。

参数

• 
  name – 公共表表达式的名称。 喜欢 FromClause.alias（）中，名称可以保留为 none ，在这种情况下，将在查询编译时使用匿名符号。

• 
  recursive – 如果为 True，将渲染 WITH RECURSIVE。递归公用表表达式旨在与 UNION ALL 结合使用，以便从已选择的行中派生行。

• 
  嵌套 –

  
  如果为 True，则会在本地将 CTE 呈现到引用它的语句。对于更复杂的场景HasCTE.add_cte，使用 HasCTE.add_cte.nest_here 参数也可以更仔细地使用 控制特定 CTE 的确切位置。

  
  在 1.4.24 版本加入.

  
  另请参阅

  
  HasCTE.add_cte（）

以下示例包括 PostgreSQL 文档中的两个示例，网址为 https://www.postgresql.org/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 结合使用的更新插入：

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（） - 的 ORM 版本 HasCTE.cte（） 的

方法 sqlalchemy.sql.expression.TextualSelect. execution_options（**kw： Any）→ Self

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

为语句设置非 SQL 选项，这些选项在执行过程中生效。

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

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

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

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

此行为的一个例外是 Connection object，其中该方法 Connection.execution_options() 明确不是生成式的。

可以传递给 Executable.execution_options() 和其他相关方法以及 参数字典包括显式使用的参数 by 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 parameter 的 Connection.execute（） 上，另外通过 Executable.execution_options() 在 SQL 语句对象上，以及通过 Session.execute（） 等 ORM 构造。

• 
  Connection.execution_options.compiled_cache - 表示将用作 SQL 编译缓存 对于 Connection 或 Engine，以及 Session.execute（） 等 ORM 方法。可以作为 None 传递以禁用语句的缓存。 此选项不被 Executable.execution_options() 因为不建议在 statement 对象中携带编译缓存。

• 
  Connection.execution_options.schema_translate_map - 使用的架构名称的映射 Schema Translate Map 功能，由 Connection、Engine、 Executable 以及 Session.execute（） 等 ORM 结构。

另请参阅

Connection.execution_options()

Connection.execute.execution_options

Session.execute.execution_options

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

method sqlalchemy.sql.expression.TextualSelect. exists（）→ 存在

继承自SelectBase 的 SelectBase.exists（） 方法

返回此可选对象的 Exists 表示形式，该表示形式可用作列表达式。

返回的对象是 Exists 的实例。

另请参阅

存在（）

EXISTS 子查询 - 在 2.0 样式教程中。

在 1.4 版本加入.

属性 sqlalchemy.sql.expression.TextualSelect. exported_columns

继承自SelectBase 的 SelectBase.exported_columns属性

一个 ColumnCollection 表示 “exported” 列，不包括 TextClause 构造。

SelectBase 的 “exported” 列 object 是同义词 与 SelectBase.selected_columns 系列。

在 1.4 版本加入.

另请参阅

Select.exported_columns

Selectable.exported_columns

FromClause.exported_columns

方法 sqlalchemy.sql.expression.TextualSelect. get_children（*， omit_attrs： Tuple[str， ...] = （）， **kw： Any）→ Iterable[HasTraverseInternals]

继承自 HasTraverseInternals.get_children() 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 的 SelectBase.get_label_style（） 方法

检索当前标签样式。

由子类实现。

属性 sqlalchemy.sql.expression.TextualSelect. inherit_cache：boolNone = None

继承自HasCacheKey 的 HasCacheKey.inherit_cache属性

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

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

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

另请参阅

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

方法 sqlalchemy.sql.expression.TextualSelect. is_derived_from（fromclause：FromClauseNone）→ bool

继承自ReturnsRows 的 ReturnsRows.is_derived_from（） 方法

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

例如，Table 的别名是从该 Table 派生的。

方法 sqlalchemy.sql.expression.TextualSelect. label（name：strNone）→ Label[Any]

继承自SelectBase 的 SelectBase.label（） 方法

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

另请参阅

SelectBase.scalar_subquery（） 中。

方法 sqlalchemy.sql.expression.TextualSelect. lateral（name：strNone=None）→ LateralFromClause

继承自SelectBase 的 SelectBase.lateral（） 方法

返回此 Selectable 的 LATERAL 别名。

返回值是 Lateral 结构，也由顶级 lateral（） 函数提供。

另请参阅

LATERAL correlation - 用法概述。

method sqlalchemy.sql.expression.TextualSelect. options（*options： ExecutableOption）→ 自身

继承自Executable 的 Executable.options（） 方法

将选项应用于此语句。

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

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

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

在 1.4 版本发生变更： - 将 Executable.options（） 添加到 Core 语句对象中，以实现允许统一的 Core / ORM 查询功能的目标。

另请参阅

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

Relationship Loading with Loader Options - 指特定于 ORM 查询使用的选项

method sqlalchemy.sql.expression.TextualSelect. params（_ClauseElement__optionaldict：Mapping[str，Any]None=None， **kwargs： Any）→ Self

继承自ClauseElement 的 ClauseElement.params（） 方法

返回替换了 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（旧： FromClause， 别名： Alias）→ Self

继承自 Selectable.replace_selectable() Selectable 的方法

替换 FromClause 的所有匹配项 'old' 替换为给定的别名 object，返回此 FromClause 的副本。

1.4 版后已移除： 该方法 Selectable.replace_selectable() 已弃用，并将在未来发行版中删除。可通过 sqlalchemy.sql.visitors 模块使用类似的功能。

方法 sqlalchemy.sql.expression.TextualSelect. scalar_subquery（）→ ScalarSelect[Any]

继承自SelectBase 的 SelectBase.scalar_subquery（） 方法

返回此 selectable 的 'scalar' 表示，可用作列表达式。

返回的对象是 ScalarSelect 的实例。

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

请注意，标量子查询与 FROM 级别不同 子查询，可以使用 SelectBase.subquery（） 方法。

另请参阅

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

method sqlalchemy.sql.expression.TextualSelect. select（*arg： Any， **kw： Any）→ Select

继承自SelectBase 的 SelectBase.select（） 方法

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：OperatorTypeNone=None）→ ClauseElement

继承自ClauseElement 的 ClauseElement.self_group（） 方法

将 'grouping' 应用于此 ClauseElement。

此方法被 subclasses 覆盖以返回 “grouping” 结构，即括号。特别是，当它被 “binary” 表达式用于在放入更大的表达式时提供围绕自身的分组，以及 select（） 构造 select（） 的（请注意，子查询通常应使用 Select.alias（） 方法创建，因为许多平台需要命名嵌套的 SELECT 语句）。

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

的 base self_group（） 方法 子句元素 只返回 self。

方法 sqlalchemy.sql.expression.TextualSelect. set_label_style（style： SelectLabelStyle）→ TextualSelect

返回具有指定标签样式的新可选对象。

由子类实现。

method sqlalchemy.sql.expression.TextualSelect. subquery（name：strNone=None）→ 子查询

继承自SelectBase 的 SelectBase.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（） 等效于调用 FromClause.alias（） method 对 FROM 对象执行;然而 作为 SelectBase object 不是直接的 FROM 对象， SelectBase.subquery（） method 提供更清晰的语义。

在 1.4 版本加入.

方法 sqlalchemy.sql.expression.TextualSelect. unique_params（_ClauseElement__optionaldict：Dict[str，Any]None=None， **kwargs： Any）→ Self

继承自ClauseElement 的 ClauseElement.unique_params（） 方法

返回替换了 bindparam（） 元素的副本。

与 ClauseElement.params（） 功能相同，但添加了 unique=True 添加到受影响的绑定参数中，以便多个语句可以 使用。

类 sqlalchemy.sql.expression 中。值

表示可用作语句中的 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 ）

method sqlalchemy.sql.expression.Values. alias（name：strNone=None， flat： bool = False）→ Self

返回新 Values 构造，该构造是 this 的副本 一个具有给定名称的 ONE。

此方法是 FromClause.alias（） 方法。

另请参阅

使用别名

别名（）

method sqlalchemy.sql.expression.Values. data（values： Sequence[Tuple[Any， ...]]）→ 自我

返回一个新的 Values 结构，将给定的数据添加到数据列表中。

例如：

my_values = my_values.data([(1, "value 1"), (2, "value2")])

参数

values—— 映射到 Values 中给出的列表达式的元组序列（即列表） 构造 函数。

方法 sqlalchemy.sql.expression.Values. lateral（name：strNone=None）→ LateralFromClause

返回一个设置了 lateral 标志的新 Value，以便它呈现为 LATERAL。

另请参阅

横向（）

方法 sqlalchemy.sql.expression.Values. scalar_values（）→ ScalarValues

返回可用作语句中的 COLUMN 元素的标量 VALUES 构造。

2.0.0b4 版本的新Function。

类 sqlalchemy.sql.expression 中。标量值

表示可用作语句中的 COLUMN 元素的标量 VALUES 构造。

ScalarValues 对象是从 Values.scalar_values（） 方法。当 Values 用于 IN 或 NOT IN 条件时，也会自动生成它。

2.0.0b4 版本的新Function。

类签名

类 sqlalchemy.sql.expression.ScalarValues （ sqlalchemy.sql.roles.InElementRole ， sqlalchemy.sql.expression.GroupedElement ， sqlalchemy.sql.expression.ColumnElement ）

标签样式常量

与 GenerativeSelect.set_label_style() 方法。

对象名称	描述
选择 LabelStyle	可以传递给 Select.set_label_style（） 中。

类 sqlalchemy.sql.expression 中。SelectLabelStyle（选择标签样式

可以传递给 Select.set_label_style（） 中。

成员

LABEL_STYLE_DEFAULT、LABEL_STYLE_DISAMBIGUATE_ONLY、LABEL_STYLE_NONE LABEL_STYLE_TABLENAME_PLUS_COL

类签名

class sqlalchemy.sql.expression.SelectLabelStyle （enum.枚举）

属性 sqlalchemy.sql.expression.SelectLabelStyle. LABEL_STYLE_DEFAULT = 2

默认标签样式是指 LABEL_STYLE_DISAMBIGUATE_ONLY。

在 1.4 版本加入.

属性 sqlalchemy.sql.expression.SelectLabelStyle. LABEL_STYLE_DISAMBIGUATE_ONLY = 2

在生成 SELECT 语句的 columns 子句时，如果表示名称与已有名称冲突的列，则应使用半匿名标签进行标签标记。

在下面，大多数列名都不受影响，除了第二次出现的名称 columna，该名称使用标签 columna_1 进行标记，以消除它与 tablea.columna 的歧义：

>>> from sqlalchemy import (
...     table,
...     column,
...     select,
...     true,
...     LABEL_STYLE_DISAMBIGUATE_ONLY,
... )
>>> table1 = table("table1", column("columna"), column("columnb"))
>>> table2 = table("table2", column("columna"), column("columnc"))
>>> print(
...     select(table1, table2)
...     .join(table2, true())
...     .set_label_style(LABEL_STYLE_DISAMBIGUATE_ONLY)
... )
SELECT table1.columna, table1.columnb, table2.columna AS columna_1, table2.columnc
FROM table1 JOIN table2 ON true

与 GenerativeSelect.set_label_style() 方法 LABEL_STYLE_DISAMBIGUATE_ONLY 是 1.x 样式 ORM 查询之外的所有 SELECT 语句的默认标签样式。

在 1.4 版本加入.

属性 sqlalchemy.sql.expression.SelectLabelStyle. LABEL_STYLE_NONE = 0

指示不应将自动标签的标签样式应用于 SELECT 语句的 columns 子句。

下面，名为 columna 的列都按原样呈现，这意味着名称 columna 只能引用此名称在结果集中的第一次出现，以及该语句用作子查询：

>>> from sqlalchemy import table, column, select, true, LABEL_STYLE_NONE
>>> table1 = table("table1", column("columna"), column("columnb"))
>>> table2 = table("table2", column("columna"), column("columnc"))
>>> print(
...     select(table1, table2)
...     .join(table2, true())
...     .set_label_style(LABEL_STYLE_NONE)
... )
SELECT table1.columna, table1.columnb, table2.columna, table2.columnc
FROM table1 JOIN table2 ON true

与 Select.set_label_style（） 方法一起使用。

在 1.4 版本加入.

属性 sqlalchemy.sql.expression.SelectLabelStyle. LABEL_STYLE_TABLENAME_PLUS_COL = 1

指示所有列都应标记为 <tablename>_<columnname> 在生成 SELECT 语句的 columns 子句时，以消除从不同表、别名或子查询引用的同名列的歧义。

下面，所有列名都被赋予了一个标签，以便两个同名列 columna 的歧义为 table1_columna 和 table2_columna：

>>> from sqlalchemy import (
...     table,
...     column,
...     select,
...     true,
...     LABEL_STYLE_TABLENAME_PLUS_COL,
... )
>>> table1 = table("table1", column("columna"), column("columnb"))
>>> table2 = table("table2", column("columna"), column("columnc"))
>>> print(
...     select(table1, table2)
...     .join(table2, true())
...     .set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
... )
SELECT table1.columna AS table1_columna, table1.columnb AS table1_columnb, table2.columna AS table2_columna, table2.columnc AS table2_columnc
FROM table1 JOIN table2 ON true

与 GenerativeSelect.set_label_style() 方法一起使用。等同于遗留方法 Select.apply_labels（）; LABEL_STYLE_TABLENAME_PLUS_COL 是 SQLAlchemy 的传统自动标记样式。LABEL_STYLE_DISAMBIGUATE_ONLY 提供了一种侵入性较小的方法来消除同名列表达式的歧义。

在 1.4 版本加入.

另请参阅

Select.set_label_style（）

Select.get_label_style（）