SqlAlchemy 2.0 中文文档（三十五）（4）-阿里云开发者社区

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

例如：

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

以上等同于：

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

参数：

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

另请参见

FromClause.join()

Join

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

attribute primary_key

继承自 FromClause 的 FromClause.primary_key 属性

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

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

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

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

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

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

attribute schema: str | None = None

继承自 FromClause.schema 属性的 FromClause

为此 FromClause 定义‘schema’属性。

对于大多数对象来说，这通常是None，除了 Table，在这种情况下，它被视为 Table.schema 参数的值。

method select() → Select

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

返回此 FromClause 的 SELECT。

例如：

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

另请参阅

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

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

继承自 ClauseElement.self_group() 方法的 ClauseElement

对此ClauseElement应用一个‘分组’。

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

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

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

method table_valued() → TableValuedColumn[Any]

继承自 NamedFromClause的NamedFromClause.table_valued() *方法。

为此FromClause返回一个TableValuedColumn对象。

TableValuedColumn是一个代表表中完整行的ColumnElement。对此构造的支持取决于后端，并且由后端（如 PostgreSQL、Oracle 和 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 中的新功能。

另请参见

使用 SQL 函数 - 在 SQLAlchemy 统一教程中

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

继承自 FromClause.tablesample() 方法的 FromClause

为此FromClause返回一个 TABLESAMPLE 别名。

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

另请参见

tablesample() - 用法指南和参数

method unique_params(*optionaldict, **kwargs)

继承自 Immutable 的 Immutable.unique_params() 方法

返回一个副本，其中的bindparam()元素被替换。

与ClauseElement.params()具有相同的功能，只是将 unique=True 添加到受影响的绑定参数中，以便可以使用多个语句。

method update() → Update

根据此TableClause生成一个update()构造。

例如：

table.update().where(table.c.id==7).values(name='foo')

有关参数和用法信息，请参阅update()。

class sqlalchemy.sql.expression.TableSample

代表一个 TABLESAMPLE 子句。

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

另请参阅

tablesample()

类签名

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

class sqlalchemy.sql.expression.TableValuedAlias

对“表值”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 中引入。

另请参阅

表值函数 - 在 SQLAlchemy 统一教程中

成员

alias(), column, lateral(), render_derived()

类签名

类sqlalchemy.sql.expression.TableValuedAlias (sqlalchemy.sql.expression.LateralFromClause, sqlalchemy.sql.expression.Alias)

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

返回此TableValuedAlias的新别名。

这将创建一个独特的 FROM 对象，当在 SQL 语句中使用时，它将与原始对象区分开。

attribute column

返回表示此TableValuedAlias的列表达式。

此访问器用于实现FunctionElement.column_valued()方法。有关详细信息，请参阅该方法。

例如：

>>> print(select(func.some_func().table_valued("value").column))
SELECT  anon_1  FROM  some_func()  AS  anon_1

另请参阅

FunctionElement.column_valued()

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

返回一个带有 LATERAL 标志设置的新TableValuedAlias，以便在渲染时呈现为 LATERAL。

另请参阅

lateral()

method render_derived(name: str | None = None, with_types: bool = False) → TableValuedAlias

将“render derived”应用于此TableValuedAlias。

这将导致在别名名称后按“AS”顺序列出各个列名，例如：

>>> print(
...     select(
...         func.unnest(array(["one", "two", "three"])).
 table_valued("x", with_ordinality="o").render_derived()
...     )
... )
SELECT  anon_1.x,  anon_1.o
FROM  unnest(ARRAY[%(param_1)s,  %(param_2)s,  %(param_3)s])  WITH  ORDINALITY  AS  anon_1(x,  o)

with_types关键字将在别名表达式中内联呈现列类型（此语法目前适用于 PostgreSQL 数据库）:

>>> print(
...     select(
...         func.json_to_recordset(
...             '[{"a":1,"b":"foo"},{"a":"2","c":"bar"}]'
...         )
...         .table_valued(column("a", Integer), column("b", String))
...         .render_derived(with_types=True)
...     )
... )
SELECT  anon_1.a,  anon_1.b  FROM  json_to_recordset(:json_to_recordset_1)
AS  anon_1(a  INTEGER,  b  VARCHAR)

参数：

name – 将应用于生成的别名的可选字符串名称。如果保持为 None，则将使用唯一的匿名化名称。
with_types – 如果为 True，则派生列将包括每个列的数据类型规范。这是当前已知对于某些 SQL 函数在 PostgreSQL 中所需的一种特殊语法。

class sqlalchemy.sql.expression.TextualSelect

在SelectBase接口中包装一个TextClause构造。

这允许TextClause对象获得一个.c集合和其他类似 FROM 的功能，例如FromClause.alias()，SelectBase.cte()等。

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

从版本 1.4 开始更改：TextualSelect 类从TextAsFrom重命名为更正确地适应其作为 SELECT 导向对象而不是 FROM 子句的角色。

另请参阅

text()

TextClause.columns() - 主要创建接口。

成员

add_cte(), alias(), 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)

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 构造的精确放置的控制，这些 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 alias(name: str | None = None, flat: bool = False) → Subquery

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

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

对于 SelectBase（与 FromClause 相对），这将返回一个大部分与与 FromClause 使用的 Alias 对象相同的 Subquery 对象。

自版本 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 compare(other: ClauseElement, **kw: Any) → bool

继承自 ClauseElement.compare() 方法的 ClauseElement

将这个 ClauseElement 与给定的 ClauseElement 进行比较。

子类应该重写默认行为，即直接的标识比较。

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

method compile(bind: _HasDialect | None = None, dialect: Dialect | None = None, **kw: Any) → Compiled

继承自 CompilerElement.compile() 方法的 CompilerElement

编译这个 SQL 表达式。

返回值是一个 Compiled 对象。在返回值上调用 str() 或 unicode() 将产生结果的字符串表示。Compiled 对象还可以使用 params 访问器返回绑定参数名称和值的字典。

参数：

bind – 可以提供 Dialect 以生成 Compiled 对象的 Connection 或 Engine。如果 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 表达式呈现为字符串，可能包含内联的绑定参数？

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

继承自 Selectable.corresponding_column() 方法，属于 Selectable

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

参数：

column – 要匹配的目标 ColumnElement。
require_embedded – 仅在给定 ColumnElement 的情况下返回对应列，如果给定的 ColumnElement 实际上存在于此 Selectable 的子元素中。通常，如果该列仅与此 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 语句可以借助以前已选择的行集。

CTEs 也可应用于某些数据库上的 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 进行 upsert，带有 CTEs：

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

可以使用 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 个 UNIONs。

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.execution_options 参数上的 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 以及像 Session.execute() 这样的 ORM 结构所接受。

另请参阅

Connection.execution_options()

Connection.execute.execution_options

Session.execute.execution_options

ORM Execution Options - documentation on all ORM-specific execution options

method exists() → Exists

inherited from the SelectBase.exists() method of SelectBase

Return an Exists representation of this selectable, which can be used as a column expression.

The returned object is an instance of Exists.

标签样式常量

与 GenerativeSelect.set_label_style() 方法一起使用的常量。

对象名称	描述
SelectLabelStyle	可传递给 `Select.set_label_style()` 方法的标签样式常量。

class sqlalchemy.sql.expression.SelectLabelStyle

可传递给 Select.set_label_style() 方法的标签样式常量。

成员

LABEL_STYLE_DEFAULT，LABEL_STYLE_DISAMBIGUATE_ONLY，LABEL_STYLE_NONE，LABEL_STYLE_TABLENAME_PLUS_COL

类签名

sqlalchemy.sql.expression.SelectLabelStyle 类 (enum.Enum)

attribute LABEL_STYLE_DEFAULT = 2

默认标签样式，指的是 LABEL_STYLE_DISAMBIGUATE_ONLY。

自 1.4 版本新增。

attribute LABEL_STYLE_DISAMBIGUATE_ONLY = 2

标签样式指示，当生成 SELECT 语句的列子句时，具有与现有名称冲突的名称的列应使用半匿名标签进行标记。

下面，大多数列名保持不变，除了第二次出现的 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 是所有 SELECT 语句的默认标签样式，适用于 1.x 风格 ORM 查询之外。

自 1.4 版本新增。

attribute LABEL_STYLE_NONE = 0

标签样式指示不应将任何自动标签应用于 SELECT 语句的列子句。

下面，名为 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 版本新增。

attribute LABEL_STYLE_TABLENAME_PLUS_COL = 1

标签样式指示当生成 SELECT 语句的列子句时，所有列都应标记为 _，以区分来自不同表、别名或子查询的同名列。

下面，所有列名都被赋予标签，以便将两个同名列 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()

可选的基础构造器

顶层“FROM 子句”和“SELECT”构造器。

对象名称	描述
除去(*selects)	返回多个可选择的`EXCEPT`。
除去全部(*selects)	返回多个可选择的`EXCEPT ALL`。
存在([__argument])	构造一个新的`Exists`构造。
交集(*selects)	返回多个可选择的`INTERSECT`。
全交集(*selects)	返回多个可选择的`INTERSECT ALL`。
选择(entities, *__kw)	构造一个新的`Select`。
表(name, columns, *kw)	生成一个新的`TableClause`。
联合(*selects)	返回多个可选择的`UNION`。
全联合(*selects)	返回多个可选择的`UNION ALL`。
数值(*columns, [name, literal_binds])	构造一个`Values`构造。

function sqlalchemy.sql.expression.except_(*selects: _SelectStatementForCompoundArgument) → CompoundSelect

返回多个可选择的EXCEPT。

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

参数：

*selects – 一个Select实例的列表。

function sqlalchemy.sql.expression.except_all(*selects: _SelectStatementForCompoundArgument) → CompoundSelect

返回多个可选择的EXCEPT ALL。

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

参数：

*selects – 一个Select实例的列表。

function sqlalchemy.sql.expression.exists(__argument: _ColumnsClauseArgument[Any] | SelectBase | ScalarSelect[Any] | None = None) → Exists

构造一个新的Exists构造。

exists()可以单独调用以生成一个Exists构造，它将接受简单的 WHERE 条件：

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

但是，为了在构建 SELECT 语句时更灵活，可以将现有的Select构造转换为Exists，最方便的方法是利用SelectBase.exists()方法：

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

EXISTS 条件然后用于封闭 SELECT 中：

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子句的方法。

function sqlalchemy.sql.expression.intersect(*selects: _SelectStatementForCompoundArgument) → CompoundSelect

返回多个可选项的INTERSECT。

返回的对象是CompoundSelect的实例。

参数：

*selects – 一个Select实例列表。

function sqlalchemy.sql.expression.intersect_all(*selects: _SelectStatementForCompoundArgument) → CompoundSelect

返回多个可选项的INTERSECT ALL。

返回的对象是CompoundSelect的实例。

参数：

*selects – 一个Select实例列表。

function sqlalchemy.sql.expression.select(*entities: _ColumnsClauseArgument[Any], **__kw: Any) → Select[Any]

构建一个新的Select。

1.4 版新功能： - select()函数现在接受位置参数列。顶级select()函数将根据传入的参数自动使用 1.x 或 2.x 样式的 API；使用sqlalchemy.future模块中的select()将强制使用只使用 2.x 样式构造函数。

任何FromClause上的FromClause.select()方法也提供了类似的功能。

另请参见

使用 SELECT 语句 - 在 SQLAlchemy 统一教程中。

参数：

*entities –

要从中选择的实体。对于 Core 使用，这通常是一系列 ColumnElement 和/或 FromClause 对象，它们将形成生成语句的列子句。对于那些是 FromClause 实例的对象（通常是 Table 或 Alias 对象），FromClause.c 集合被提取以形成 ColumnElement 对象的集合。

此参数还将接受给定的 TextClause 构造，以及 ORM 映射的类。

function sqlalchemy.sql.expression.table(name: str, *columns: ColumnClause[Any], **kw: Any) → TableClause

生成一个新的 TableClause。

返回的对象是 TableClause 的一个实例，它表示模式级别的 “语法” 部分 Table 对象。它可以用于构建轻量级表构造。

参数：

name – 表的名称。
columns – 一组 column() 构造。
schema –
此表的模式名称。
在 1.3.18 版中新增：table() 现在可以接受 schema 参数。

function sqlalchemy.sql.expression.union(*selects: _SelectStatementForCompoundArgument) → CompoundSelect

返回多个可选择的 UNION。

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

所有 FromClause 子类上都有类似的 union() 方法可用。

参数：

*selects – Select 实例的列表。
**kwargs – 可用的关键字参数与 select() 的相同。

function sqlalchemy.sql.expression.union_all(*selects: _SelectStatementForCompoundArgument) → CompoundSelect

返回多个可选择的 UNION ALL。

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

所有FromClause子类上都有一个类似的union_all()方法可用。

参数：

*selects – 一个Select实例的列表。

function sqlalchemy.sql.expression.values(*columns: ColumnClause[Any], name: str | None = None, literal_binds: bool = False) → Values

构造一个Values构造。

列表达式和Values的实际数据是在两个独立的步骤中给出的。构造函数通常接收列表达式，如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 输出中将数据值直接呈现为内联形式，而不是使用绑定参数。

可选修饰符构造函数

此处列出的函数更常见地作为FromClause和Selectable元素的方法，例如，alias()函数通常通过FromClause.alias()方法调用。

对象名称	描述
alias(selectable[, name, flat])	返回给定`FromClause`的命名别名。
cte(selectable[, name, recursive])	返回一个新的`CTE`，或公共表达式实例。
join(left, right[, onclause, isouter, …])	根据两个`FromClause`表达式生成一个`Join`对象。
lateral(selectable[, name])	返回一个`Lateral`对象。
outerjoin(left, right[, onclause, full])	返回一个`OUTER JOIN`子句元素。
tablesample(selectable, sampling[, name, seed])	返回一个`TableSample`对象。

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

返回给定FromClause的命名别名。

对于Table和Join对象，返回类型是Alias对象。其他类型的NamedFromClause对象可能会返回其他类型的FromClause对象。

命名别名代表具有 SQL 中分配的替代名称的任何FromClause，通常在生成时使用AS子句，例如SELECT * FROM table AS aliasname。

可通过所有FromClause对象上可用的FromClause.alias()方法获得等效功能。

参数：

selectable – 任何FromClause子类，例如表、选择语句等。
name – 要分配为别名的字符串名称。如果为None，则会在编译时确定性地生成名称。确定性意味着该名称确保与同一语句中使用的其他结构相对于其他结构的唯一性，并且对同一语句对象的每次后续编译也将是相同的名称。
flat – 如果给定的可选择对象是Join的实例，则将传递给 - 有关详细信息，请参阅Join.alias()。

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

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

有关 CTE 用法的详细信息，请参阅HasCTE.cte()。

function sqlalchemy.sql.expression.join(left: _FromClauseArgument, right: _FromClauseArgument, onclause: _OnClauseArgument | None = None, isouter: bool = False, full: bool = False) → Join

给定两个FromClause表达式生成一个Join对象。

例如：

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对象（例如Table）都可以使用FromClause.join()方法提供类似的功能。

参数：

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

另请参阅

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

Join - 生成的对象类型。

function sqlalchemy.sql.expression.lateral(selectable: SelectBase | _FromClauseArgument, name: str | None = None) → LateralFromClause

返回一个Lateral对象。

Lateral是一个带有 LATERAL 关键字的子查询的Alias子类。

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

另请参阅

LATERAL 相关性 - 用法概述。

function sqlalchemy.sql.expression.outerjoin(left: _FromClauseArgument, right: _FromClauseArgument, onclause: _OnClauseArgument | None = None, full: bool = False) → Join

返回一个OUTER JOIN子句元素。

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

任何FromClause对象上也可以通过FromClause.outerjoin()方法提供类似的功能。

参数：

left – 连接的左侧。
right – 连接的右侧。
onclause – 可选的ON子句条件，如果没有指定，则从左侧和右侧之间建立的外键关系中派生。

要将连接链接在一起，请使用所得到的 Join 对象上的 FromClause.join() 或 FromClause.outerjoin() 方法。

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

返回一个 TableSample 对象。

TableSample 是一个Alias 的子类，表示应用了 TABLESAMPLE 子句的表。tablesample() 还可以通过 FromClause.tablesample() 方法从 FromClause 类中获得。

TABLESAMPLE 子句允许从表中随机选择近似百分比的行。它支持多种抽样方法，最常见的是 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 之间的float百分比，或 Function。
name – 可选的别名
seed – 任何实值 SQL 表达式。当指定时，也会呈现 REPEATABLE 子句。

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

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

标签样式常量

可选的基础构造器

可选修饰符构造函数

热门文章

最新文章

相关电子书