SqlAlchemy 2.0 中文文档（三十五）（5）

SqlAlchemy 2.0 中文文档（三十五）（4）https://developer.aliyun.com/article/1562894

可选择类文档

这里的类是使用 Selectable Foundational Constructors 和 Selectable Modifier Constructors 中列出的构造函数生成的。

class sqlalchemy.sql.expression.Alias

代表一个表或可选择的别名（AS）。

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

此对象可以通过alias()模块级函数以及所有FromClause子类上可用的FromClause.alias()方法构建。

另请参阅

FromClause.alias()

成员

inherit_cache

类签名

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

attribute inherit_cache: bool | None = True

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

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

如果与此类本地属性无关并且不是其超类，则可以将此标志设置为True。

参见

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

class sqlalchemy.sql.expression.AliasedReturnsRows

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

成员

描述，is_derived_from()，原始

类签名

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

attribute description

method is_derived_from(fromclause: FromClause | None) → bool

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

一个示例是来自该表的一个别名。

attribute original

适用于引用 Alias.original 的方言的旧版本。

class sqlalchemy.sql.expression.CompoundSelect

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

参见

union()

union_all()

intersect()

intersect_all()

except()

except_all()

成员

add_cte(), alias(), as_scalar(), c, corresponding_column(), cte(),  execution_options(), exists(), exported_columns, fetch(),  get_execution_options(), get_label_style(), group_by(),  is_derived_from(), label(), lateral(), limit(), offset(), options(),  order_by(), replace_selectable(), scalar_subquery(), select(),  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)

method add_cte(*ctes: CTE, nest_here: bool = False) → Self

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

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

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

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

此方法有两个常见用途。一个是嵌入 CTE 语句，这些语句具有某种用途，而不需要明确引用，例如，将 DML 语句（如 INSERT 或  UPDATE）作为 CTE 内联到可能间接从其结果中获得结果的主要语句中。另一个用途是提供对应于应该直接呈现为特定语句的一系列特定 CTE  构造的精确放置的控制，该语句可能嵌套在较大语句中。

例如：

from sqlalchemy import table, column, select
t = table('t', column('c1'), column('c2'))
ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
stmt = select(t).add_cte(ins)

将呈现为：

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

在上述示例中，“anon_1” CTE 没有在 SELECT 语句中被引用，但仍然完成了运行 INSERT 语句的任务。

类似地，在与 DML 相关的上下文中，使用 PostgreSQLInsert构造来生成“upsert”：

from sqlalchemy import table, column
from sqlalchemy.dialects.postgresql import insert
t = table("t", column("c1"), column("c2"))
delete_statement_cte = (
    t.delete().where(t.c.c1 < 1).cte("deletions")
)
insert_stmt = insert(t).values({"c1": 1, "c2": 2})
update_statement = insert_stmt.on_conflict_do_update(
    index_elements=[t.c.c1],
    set_={
        "c1": insert_stmt.excluded.c1,
        "c2": insert_stmt.excluded.c2,
    },
).add_cte(delete_statement_cte)
print(update_statement)

上述语句呈现为：

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

自版本 1.4.21 起新添加。

参数：

• *ctes* –
  零个或多个CTE构造。
  自版本 2.0 起更改：接受多个 CTE 实例
  
• nest_here –
  如果为 True，则给定的 CTE 或 CTE 将呈现为如果当它们被添加到此HasCTE时指定了HasCTE.cte.nesting标志为True。假设给定的 CTE 在外部封闭语句中也没有被引用，那么在给出此标志时，给定的 CTE 应在此语句的级别呈现。
  自版本 2.0 起新添加。
  另请参阅
  HasCTE.cte.nesting
  

method alias(name: str | None = None, flat: bool = False) → Subquery

继承自 SelectBase 的 SelectBase.alias() 方法

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

对于 SelectBase（与 FromClause 相对），此方法返回一个 Subquery 对象，其行为与用于 FromClause 的 Alias 对象大致相同。

自版本 1.4 起更改：SelectBase.alias() 方法现在是 SelectBase.subquery() 方法的同义词。

method as_scalar() → ScalarSelect[Any]

继承自 SelectBase.as_scalar() 方法的 SelectBase

自版本 1.4 起弃用：SelectBase.as_scalar() 方法已被弃用，并将在未来版本中移除。请参阅 SelectBase.scalar_subquery()。

attribute c

继承自 SelectBase.c 属性的 SelectBase

自版本 1.4 起弃用：SelectBase.c 和 SelectBase.columns 属性已被弃用，并将在未来版本中移除；这些属性隐式创建了一个应该明确的子查询。请首先调用 SelectBase.subquery() 来创建一个子查询，然后该子查询包含此属性。要访问此 SELECT 对象所选列，请使用 SelectBase.selected_columns 属性。

method corresponding_column(column: KeyedColumnElement[Any], require_embedded: bool = False) → KeyedColumnElement[Any] | None

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

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

参数：

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

另请参见

Selectable.exported_columns - 用于操作的ColumnCollection。

ColumnCollection.corresponding_column() - 实现方法。

method cte(name: str | None = None, recursive: bool = False, nesting: bool = False) → CTE

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

返回一个新的CTE，即公共表达式实例。

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

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

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

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

从版本 1.3.13 开始更改：增加了对前缀的支持。特别是 - MATERIALIZED 和 NOT MATERIALIZED。

参数：

• name – 给公共表达式指定的名称。与 FromClause.alias() 类似，名称可以留空，此时将在查询编译时使用匿名符号。
  
• recursive – 如果为 True，将渲染 WITH RECURSIVE。递归公共表达式旨在与 UNION ALL 结合使用，以从已选定的行中派生行。
  
• nesting –
  如果为 True，将在引用它的语句中本地渲染 CTE。对于更复杂的场景，还可以使用 HasCTE.add_cte() 方法，使用 HasCTE.add_cte.nest_here 参数更精确地控制特定 CTE 的精确放置位置。
  从版本 1.4.24 开始新增。
  另见
  HasCTE.add_cte()
  

以下示例包括两个来自 PostgreSQL 文档 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 进行 upsert：

from datetime import date
from sqlalchemy import (MetaData, Table, Column, Integer,
                        Date, select, literal, and_, exists)
metadata = MetaData()
visitors = Table('visitors', metadata,
    Column('product_id', Integer, primary_key=True),
    Column('date', Date, primary_key=True),
    Column('count', Integer),
)
# add 5 visitors for the product_id == 1
product_id = 1
day = date.today()
count = 5
update_cte = (
    visitors.update()
    .where(and_(visitors.c.product_id == product_id,
                visitors.c.date == day))
    .values(count=visitors.c.count + count)
    .returning(literal(1))
    .cte('update_cte')
)
upsert = visitors.insert().from_select(
    [visitors.c.product_id, visitors.c.date, visitors.c.count],
    select(literal(product_id), literal(day), literal(count))
        .where(~exists(update_cte.select()))
)
connection.execute(upsert)

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

value_a = select(
    literal("root").label("n")
).cte("value_a")
# A nested CTE with the same name as the root one
value_a_nested = select(
    literal("nesting").label("n")
).cte("value_a", nesting=True)
# Nesting CTEs takes ascendency locally
# over the CTEs at a higher level
value_b = select(value_a_nested.c.n).cte("value_b")
value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))

上述查询将第二个 CTE 嵌套在第一个内部，并显示为以下内联参数：

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

可以使用以下方法设置相同的 CTE：HasCTE.add_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 execution_options(**kw: Any) → Self

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

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

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

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

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

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

这种行为的一个例外是 Connection 对象，在这里 Connection.execution_options() 方法明确地 不是 生成的。

Executable.execution_options() 和其他相关方法以及参数字典可以接受的选项类型包括由 SQLAlchemy Core 或 ORM 明确使用的参数，以及未被 SQLAlchemy 定义的任意关键字参数。这意味着这些方法和/或参数字典可以用于与自定义代码交互的用户定义参数，可以使用诸如 Executable.get_execution_options() 和 Connection.get_execution_options() 这样的方法来访问参数，或者在选定的事件钩子中使用专用的 execution_options 事件参数，例如 ConnectionEvents.before_execute.execution_options 或 ORMExecuteState.execution_options，例如：

from sqlalchemy import event
@event.listens_for(some_engine, "before_execute")
def _process_opt(conn, statement, multiparams, params, execution_options):
    "run a SQL function before invoking a statement"
    if execution_options.get("do_special_thing", False):
        conn.exec_driver_sql("run_special_function()")

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

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

另请参见

Connection.execution_options()

Connection.execute.execution_options

Session.execute.execution_options

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

method exists() → Exists

继承自 SelectBase.exists() 方法的 SelectBase

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

返回对象是Exists的实例。

另请参阅

exists()

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

新版本 1.4 中推出。

attribute exported_columns

继承自 SelectBase.exported_columns 属性的 SelectBase

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

SelectBase对象的“导出”列与SelectBase.selected_columns集合是同义词。

新版本 1.4 中推出。

另请参阅

Select.exported_columns

Selectable.exported_columns

FromClause.exported_columns

method fetch(count: _LimitOffsetType, with_ties: bool = False, percent: bool = False) → Self

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

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

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

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

注意

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

版本 1.4 中新增。

参数：

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

另请参阅

GenerativeSelect.limit()

GenerativeSelect.offset()

method get_execution_options() → _ExecuteOptions

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

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

版本 1.3 中新增。

另请参阅

Executable.execution_options()

method get_label_style() → SelectLabelStyle

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

检索当前标签样式。

版本 1.4 中新增。

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

继承自 GenerativeSelect.group_by() 方法的参数 GenerativeSelect

返回一个应用了给定的 GROUP BY 条件列表的新可选择项。

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

例如：

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

参数：

*子句 – 一系列将用于生成 GROUP BY 子句的ColumnElement构造。

另请参阅

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

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

method is_derived_from(fromclause: FromClause | None) → bool

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

一个示例是，表的别名是从该表派生的。

method label(name: str | None) → Label[Any]

继承自 SelectBase.label() 方法的 SelectBase

返回此可选择项的“标量”表示，嵌入为带有标签的子查询。

另请参阅

SelectBase.scalar_subquery().

method lateral(name: str | None = None) → LateralFromClause

继承自 SelectBase.lateral() 方法的 SelectBase

返回此Selectable的 LATERAL 别名。

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

另请参阅

LATERAL 相关性 - 用法概述。

method limit(limit: _LimitOffsetType) → Self

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

返回一个应用给定 LIMIT 条件的新可选择项。

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

注意

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

参数：

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

另请参阅

GenerativeSelect.fetch()

GenerativeSelect.offset()

method offset(offset: _LimitOffsetType) → Self

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

返回一个应用了给定 OFFSET 条件的新可选择项。

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

参数：

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

另请参阅

GenerativeSelect.limit()

GenerativeSelect.fetch()

method options(*options: ExecutableOption) → Self

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

将选项应用于此语句。

从一般意义上讲，选项是任何 SQL 编译器可以解释的 Python 对象。这些选项可以被特定的方言或特定类型的编译器消耗。

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

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

自版本 1.4 更改：- 向核心语句对象添加Executable.options()，以实现统一的核心/ORM 查询功能的目标。

另请参阅

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

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

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

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

返回一个应用了给定 ORDER BY 条件列表的新可选择项。

例如：

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

多次调用此方法等同于一次调用，其中所有子句都被连接起来。 通过单独传递None可以取消所有现有的 ORDER BY 条件。 然后可以通过再次调用Query.order_by()来添加新的 ORDER BY 条件，例如：

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

参数：

*clauses – 一系列将用于生成 ORDER BY 子句的ColumnElement构造。

另请参阅

ORDER BY - 在 SQLAlchemy 统一教程中

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

method replace_selectable(old: FromClause, alias: Alias) → Self

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

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

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

method scalar_subquery() → ScalarSelect[Any]

继承自 SelectBase.scalar_subquery() 方法的 SelectBase

返回此可选择项的‘标量’表示，可用作列表达式。

返回的对象是ScalarSelect的实例。

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

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

另请参阅

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

method select(*arg: Any, **kw: Any) → Select

继承自 SelectBase.select() 方法的 SelectBase

自版本 1.4 开始不推荐使用：SelectBase.select() 方法已被弃用，并将在未来的版本中删除；此方法隐式创建了一个应明确表示的子查询。请先调用 SelectBase.subquery() 来创建子查询，然后再进行选择。

attribute selected_columns

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

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

参见

Select.selected_columns

版本 1.4 中的新内容。

method self_group(against: OperatorType | None = None) → GroupedElement

对此 ClauseElement 应用“分组”。

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

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

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

method set_label_style(style: SelectLabelStyle) → CompoundSelect

返回具有指定标签样式的新可选择项。

有三种“标签样式”可用，SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY，SelectLabelStyle.LABEL_STYLE_TABLENAME_PLUS_COL，以及SelectLabelStyle.LABEL_STYLE_NONE。默认样式是SelectLabelStyle.LABEL_STYLE_TABLENAME_PLUS_COL。

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

消除歧义的原因主要是，当创建子查询时，从给定的 FromClause.c 集合中可以使用所有列表达式。

从版本 1.4 新增：- GenerativeSelect.set_label_style() 方法替换了以前的 .apply_labels()、.with_labels() 和 use_labels=True 方法和/或参数的组合。

另请参阅

LABEL_STYLE_DISAMBIGUATE_ONLY

LABEL_STYLE_TABLENAME_PLUS_COL

LABEL_STYLE_NONE

LABEL_STYLE_DEFAULT

method slice(start: int, stop: int) → Self

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

根据片段将 LIMIT / OFFSET 应用于此语句。

起始和停止索引的行为类似于 Python 内置 range() 函数的参数。此方法提供了一种替代方法，用于使用 LIMIT/OFFSET 获取查询的片段。

例如，

stmt = select(User).order_by(User).id.slice(1, 3)

渲染为

SELECT  users.id  AS  users_id,
  users.name  AS  users_name
FROM  users  ORDER  BY  users.id
LIMIT  ?  OFFSET  ?
(2,  1)

注意

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

新版本 1.4 中新增：从 ORM 泛化的 GenerativeSelect.slice() 方法。

另请参阅

GenerativeSelect.limit()

GenerativeSelect.offset()

GenerativeSelect.fetch()

method subquery(name: str | None = None) → Subquery

继承自 SelectBase.subquery() 方法的 SelectBase

返回此 SelectBase 的子查询。

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

给定一个类似的 SELECT 语句：

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

上述语句可能看起来像：

SELECT table.id, table.name FROM table

单独的子查询形式呈现相同的方式，但是当嵌入到另一个 SELECT 语句的 FROM 子句中时，它变成了一个命名子元素：

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

上述呈现为：

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

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

新版本 1.4 中新增。

method with_for_update(*, nowait: bool = False, read: bool = False, of: _ForUpdateOfArgument | None = None, skip_locked: bool = False, key_share: bool = False) → Self

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

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

例如：

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

在像 PostgreSQL 或 Oracle 这样的数据库中，上述将呈现为类似于：

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

在其他后端，nowait 选项会被忽略，而会产生：

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

当没有参数调用时，语句将以后缀FOR UPDATE渲染。然后可以提供额外的参数，允许常见的特定于数据库的变体。

参数：

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

class sqlalchemy.sql.expression.CTE

代表一个公共表达式。

CTE对象是使用任何 SELECT 语句的SelectBase.cte()方法获得的。较少见的语法还允许在 DML 构造上存在的HasCTE.cte()方法的使用，例如Insert、Update和Delete。有关 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 alias(name: str | None = None, flat: bool = False) → CTE

返回此 CTE 的一个 Alias 。

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

另请参阅

使用别名

alias()

method union(*other: _SelectStatementForCompoundArgument) → CTE

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

参数:

*其他 –

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

在 1.4.28 版更改：现在接受多个元素。

另请参阅

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

method union_all(*other: _SelectStatementForCompoundArgument) → CTE

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

参数:

*其他 –

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

在 1.4.28 版更改：现在接受多个元素。

另请参阅

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

class sqlalchemy.sql.expression.Executable

将一个 ClauseElement 标记为支持执行。

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

成员

execution_options(), get_execution_options(), options()

类签名

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

method execution_options(**kw: Any) → Self

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

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

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

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

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

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

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

from sqlalchemy import event
@event.listens_for(some_engine, "before_execute")
def _process_opt(conn, statement, multiparams, params, execution_options):
    "run a SQL function before invoking a statement"
    if execution_options.get("do_special_thing", False):
        conn.exec_driver_sql("run_special_function()")

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

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

另请参见

Connection.execution_options()

Connection.execute.execution_options

Session.execute.execution_options

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

method get_execution_options() → _ExecuteOptions

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

1.3 版本中新增。

另请参见

Executable.execution_options()

method options(*options: ExecutableOption) → Self

将选项应用于此语句。

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

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

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

从 1.4 版本开始更改：- 向核心语句对象添加Executable.options()，以实现统一的核心/ORM 查询功能目标。

另请参见

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

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

class sqlalchemy.sql.expression.Exists

表示一个EXISTS子句。

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

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

成员

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

类签名

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

method correlate(*fromclauses: Literal[None, False] | _FromClauseArgument) → Self

将相关性应用于此Exists指定的子查询。

另请参见

ScalarSelect.correlate()

method correlate_except(*fromclauses: Literal[None, False] | _FromClauseArgument) → Self

将相关性应用于此Exists 指示的子查询。

另请参阅

ScalarSelect.correlate_except()

attribute inherit_cache: bool | None = True

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

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

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

另请参阅

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

method 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() - 允许任意列列表的通用方法。

method select_from(*froms: _FromClauseArgument) → Self

返回一个新的Exists 构造，将给定的表达式应用于所包含的选择语句的Select.select_from() 方法。

注意

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

method where(*clause: _ColumnExpressionArgument[bool]) → Self

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

注意

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

class sqlalchemy.sql.expression.FromClause

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

FromClause的最常见形式是Table和select()构造。所有FromClause对象共有的关键特征包括：

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

成员

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

类签名

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

method alias(name: str | None = None, flat: bool = False) → NamedFromClause

返回此FromClause的别名。

例如：

a2 = some_table.alias('a2')

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

另请参阅

使用别名

alias()

attribute c

FromClause.columns的同义词。

返回：

一个ColumnCollection。

attribute columns

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

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

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

返回：

一个ColumnCollection对象。

attribute description

这是FromClause的简要描述。

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

attribute entity_namespace

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

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

stmt.filter_by(address='some address')

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

attribute exported_columns

代表此Selectable的“导出”列的ColumnCollection。

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

版本 1.4 中的新功能。

另请参阅

Selectable.exported_columns

SelectBase.exported_columns

attribute foreign_keys

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

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

另请参阅

Table.foreign_key_constraints

method is_derived_from(fromclause: FromClause | None) → bool

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

一个示例是一个表的别名是从该表派生的。

method join(right: _FromClauseArgument, onclause: _ColumnExpressionArgument[bool] | None = None, isouter: bool = False, full: bool = False) → Join

从这个FromClause返回到另一个带有“isouter”标志设置为 True 的Join。

例如：

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

将会生成类似以下的 SQL：

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

参数：

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

另请参阅

join() - 独立函数

Join - 生成的对象类型

method outerjoin(right: _FromClauseArgument, onclause: _ColumnExpressionArgument[bool] | None = None, full: bool = False) → Join

从这个FromClause返回到另一个带有“isouter”标志设置为 True 的Join。

例如：

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

以上等同于：

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

参数：

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

另请参阅

FromClause.join()

Join

attribute primary_key

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

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

attribute schema: str | None = None

为此FromClause定义‘schema’属性。

对于大多数对象来说，这通常是None，除了Table对象，其中它被视为Table.schema参数的值。

method select() → Select

返回此FromClause的 SELECT。

例如：

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

另请参阅

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

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

返回此FromClause的 TABLESAMPLE 别名。

返回值是顶层tablesample()函数提供的TableSample构造。

另请参阅

tablesample() - 用法指南和参数

class sqlalchemy.sql.expression.GenerativeSelect

SELECT 语句的基类，可以添加额外的元素。

这用作 Select 和 CompoundSelect 的基础，其中可以添加诸如 ORDER BY、GROUP BY 等元素，并且可以控制列的呈现。与 TextualSelect 相比，它虽然是 SelectBase 的子类，也是一个 SELECT 构造，但代表一个固定的文本字符串，在这个级别无法更改，只能作为子查询包装。

成员

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

类签名

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

method fetch(count: _LimitOffsetType, with_ties: bool = False, percent: bool = False) → Self

返回一个应用了给定 FETCH FIRST 准则的新可选择项。

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

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

注意

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

版本 1.4 中新增。

参数：

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

另请参阅

GenerativeSelect.limit()

GenerativeSelect.offset()

method get_label_style() → SelectLabelStyle

检索当前标签样式。

自 1.4 版本新功能。

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

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

通过传递 None，可以取消所有现有的 GROUP BY 设置。

例如：

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

参数：

*clauses – 一系列将用于生成 GROUP BY 子句的 ColumnElement 构造。

另请参阅

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

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

method limit(limit: _LimitOffsetType) → Self

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

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

注意

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

参数：

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

另请参阅

GenerativeSelect.fetch()

GenerativeSelect.offset()

method offset(offset: _LimitOffsetType) → Self

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

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

参数：

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

另请参阅

GenerativeSelect.limit()

GenerativeSelect.fetch()

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

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

例如：

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

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

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

参数：

*clauses – 一系列用于生成 ORDER BY 子句的ColumnElement构造。

另请参阅

ORDER BY - 在 SQLAlchemy 统一教程中

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

method set_label_style(style: SelectLabelStyle) → Self

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

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

在现代 SQLAlchemy 中，通常不需要更改标签样式，因为通过使用 ColumnElement.label() 方法更有效地使用按表达式标记。在过去的版本中，LABEL_STYLE_TABLENAME_PLUS_COL 用于消除来自不同表、别名或子查询的同名列；较新的 LABEL_STYLE_DISAMBIGUATE_ONLY 现在仅对与现有名称冲突的名称应用标签，因此此标记的影响是最小的。

正确性歧义的原因主要是当创建子查询时，所有列表达式都可以从给定的FromClause.c集合中使用。

新于 1.4 版本： - GenerativeSelect.set_label_style() 方法替换了先前的 .apply_labels()、.with_labels() 和 use_labels=True 方法和/或参数的组合。

另请参阅

LABEL_STYLE_DISAMBIGUATE_ONLY

LABEL_STYLE_TABLENAME_PLUS_COL

LABEL_STYLE_NONE

LABEL_STYLE_DEFAULT

method slice(start: int, stop: int) → Self

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

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

例如，

stmt = select(User).order_by(User).id.slice(1, 3)

渲染为

SELECT  users.id  AS  users_id,
  users.name  AS  users_name
FROM  users  ORDER  BY  users.id
LIMIT  ?  OFFSET  ?
(2,  1)

注意

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

1.4 版中的新功能：从 ORM 泛化添加了 GenerativeSelect.slice() 方法。

另请参阅

GenerativeSelect.limit()

GenerativeSelect.offset()

GenerativeSelect.fetch()

method with_for_update(*, nowait: bool = False, read: bool = False, of: _ForUpdateOfArgument | None = None, skip_locked: bool = False, key_share: bool = False) → Self

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

例如：

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

在像 PostgreSQL 或 Oracle 这样的数据库上，以上内容将呈现为如下语句：

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

在其他后端上，nowait 选项将被忽略，而会产生如下结果：

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

调用时不带参数，语句将以后缀 FOR UPDATE 呈现。然后可以提供附加参数，允许使用常见的数据库特定变体。

参数：

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

class sqlalchemy.sql.expression.HasCTE

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

成员

add_cte(), cte()

类签名

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

method add_cte(*ctes: CTE, nest_here: bool = False) → Self

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

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

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

此方法有两个一般用途。一个是嵌入服务于某些目的而不被显式引用的 CTE 语句，比如将 DML 语句（比如 INSERT 或  UPDATE）作为 CTE 内联到可能间接从其结果中汲取的主语句中。另一个是提供对应特定语句的一系列 CTE  构造的确切放置的控制，这些构造应该保持直接渲染为嵌套在较大语句中的特定语句。

例如：

from sqlalchemy import table, column, select
t = table('t', column('c1'), column('c2'))
ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
stmt = select(t).add_cte(ins)

渲染如下：

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

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

类似地，在 DML 相关的上下文中，使用 PostgreSQL 的Insert构造生成“upsert”：

from sqlalchemy import table, column
from sqlalchemy.dialects.postgresql import insert
t = table("t", column("c1"), column("c2"))
delete_statement_cte = (
    t.delete().where(t.c.c1 < 1).cte("deletions")
)
insert_stmt = insert(t).values({"c1": 1, "c2": 2})
update_statement = insert_stmt.on_conflict_do_update(
    index_elements=[t.c.c1],
    set_={
        "c1": insert_stmt.excluded.c1,
        "c2": insert_stmt.excluded.c2,
    },
).add_cte(delete_statement_cte)
print(update_statement)

上述语句渲染为：

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

从版本 1.4.21 开始新增。

参数：

• *ctes -
  零个或多个CTE构造。
  从版本 2.0 开始更改：接受多个 CTE 实例
  
• nest_here -
  如果为 True，则给定的 CTE 或 CTE 将被渲染，就好像它们在添加到此 HasCTE 时指定了 HasCTE.cte.nesting 标志为 True 一样。假设给定的 CTE 在外层语句中也没有被引用，当给定此标志时，应该在此语句级别呈现这些 CTE。
  从版本 2.0 开始。
  另请参阅
  HasCTE.cte.nesting
  

method cte(name: str | None = None, recursive: bool = False, nesting: bool = False) → CTE

返回一个新的CTE，或公共表达式实例。

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

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

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

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

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

参数：

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

以下示例包括两个来自 PostgreSQL 文档的示例，网址为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 >