SqlAlchemy 2.0 中文文档（三十四）（1）

原文：docs.sqlalchemy.org/en/20/contents.html

SQLAlchemy 核心

原文：docs.sqlalchemy.org/en/20/core/index.html

SQLAlchemy 的 SQL 渲染引擎、DBAPI 集成、事务集成以及模式描述服务在这里有所记录。与 ORM 的面向领域的使用方式相反，SQL 表达语言提供了一种以模式为中心的使用范式。

• SQL 语句和表达式 API

• 列元素和表达式
  
• 操作符参考
  
• SELECT 及相关结构
  
• 插入、更新、删除
  
• SQL 和通用函数
  
• 自定义 SQL 构造和编译扩展
  
• 表达式序列化扩展
  
• SQL 表达语言基础构造
  
• 访问者和遍历工具
  

• 模式定义语言

• 用 MetaData 描述数据库
  
• 反映数据库对象
  
• 列 INSERT/UPDATE 默认值
  
• 定义约束和索引
  
• 自定义 DDL
  

• SQL 数据类型对象

• 类型层次结构
  
• 自定义类型
  
• 基本类型 API
  

• 引擎和连接的使用

• 引擎配置
  
• 与引擎和连接工作
  
• 连接池
  
• 核心事件
  

• 核心 API 基础知识

• 事件
  
• 运行时检查 API
  
• 核心异常
  
• 核心内部机制
  

SQL 语句和表达式 API

原文：docs.sqlalchemy.org/en/20/core/expression_api.html

本节介绍了 SQL 表达式语言的 API 参考。要了解简介，请从 SQLAlchemy 统一教程中的数据操作开始。

• 列元素和表达式

• 列元素基础构造函数

• and_()
  
• bindparam()
  
• bitwise_not()
  
• case()
  
• cast()
  
• column()
  
• custom_op
  
• distinct()
  
• extract()
  
• false()
  
• func
  
• lambda_stmt()
  
• literal()
  
• literal_column()
  
• not_()
  
• null()
  
• or_()
  
• outparam()
  
• text()
  
• true()
  
• try_cast()
  
• tuple_()
  
• type_coerce()
  
• quoted_name
  

• 列元素修饰符构造函数

• all_()
  
• any_()
  
• asc()
  
• between()
  
• collate()
  
• desc()
  
• funcfilter()
  
• label()
  
• nulls_first()
  
• nullsfirst()
  
• nulls_last()
  
• nullslast()
  
• over()
  
• within_group()
  

• 列元素类文档

• BinaryExpression
  
• BindParameter
  
• Case
  
• Cast
  
• ClauseList
  
• ColumnClause
  
• ColumnCollection
  
• ColumnElement
  
• ColumnExpressionArgument
  
• ColumnOperators
  
• Extract
  
• False_
  
• FunctionFilter
  
• Label
  
• Null
  
• Operators
  
• Over
  
• SQLColumnExpression
  
• TextClause
  
• TryCast
  
• Tuple
  
• WithinGroup
  
• WrapsColumnExpression
  
• True_
  
• TypeCoerce
  
• UnaryExpression
  

• 列元素类型工具

• NotNullable()
  
• Nullable()
  

• 运算符参考

• 比较运算符
  
• IN 比较

• IN 对值列表的比较
  
• 空 IN 表达式
  
• NOT IN
  
• 元组 IN 表达式
  
• 子查询 IN
  

• 身份比较
  
• 字符串比较
  
• 字符串包含
  
• 字符串匹配
  
• 字符串修改
  
• 算术运算符
  
• 位运算操作符
  
• 使用连接词和否定词
  
• 连接操作符
  

• SELECT 和相关构造

• 可选择的基础构造函数

• except_()
  
• except_all()
  
• exists()
  
• intersect()
  
• intersect_all()
  
• select()
  
• table()
  
• union()
  
• union_all()
  
• values()
  

• 可选择的修改构造函数

• alias()
  
• cte()
  
• join()
  
• lateral()
  
• outerjoin()
  
• tablesample()
  

• 可选择类文档

• Alias
  
• AliasedReturnsRows
  
• CompoundSelect
  
• CTE
  
• Executable
  
• Exists
  
• FromClause
  
• GenerativeSelect
  
• HasCTE
  
• HasPrefixes
  
• HasSuffixes
  
• Join
  
• Lateral
  
• ReturnsRows
  
• ScalarSelect
  
• Select
  
• Selectable
  
• SelectBase
  
• Subquery
  
• TableClause
  
• TableSample
  
• TableValuedAlias
  
• TextualSelect
  
• Values
  
• ScalarValues
  

• 标签样式常量

• SelectLabelStyle

• 插入、更新、删除

• DML 基础构造函数

• delete()
  
• insert()
  
• update()
  

• DML 类文档构造函数

• Delete
  
• Insert
  
• Update
  
• UpdateBase
  
• ValuesBase
  

• SQL 和通用函数

• 函数 API

• AnsiFunction
  
• Function
  
• FunctionElement
  
• GenericFunction
  
• register_function()
  

• 已选中的“已知”函数

• aggregate_strings
  
• array_agg
  
• char_length
  
• coalesce
  
• concat
  
• count
  
• cube
  
• cume_dist
  
• current_date
  
• current_time
  
• current_timestamp
  
• current_user
  
• dense_rank
  
• grouping_sets
  
• localtime
  
• localtimestamp
  
• max
  
• min
  
• mode
  
• next_value
  
• now
  
• percent_rank
  
• percentile_cont
  
• percentile_disc
  
• random
  
• rank
  
• rollup
  
• session_user
  
• sum
  
• sysdate
  
• user
  

• 自定义 SQL 构造和编译扩展

• 简介
  
• 特定于方言的编译规则
  
• 编译自定义表达式构造的子元素

• SQL 和 DDL 编译器之间的交叉编译

• 更改现有构造的默认编译
  
• 更改类型的编译
  
• 子类化指南
  
• 为自定义构造启用缓存支持
  
• 更多示例

• “UTC 时间戳” 函数
  
• “GREATEST” 函数
  
• “false” 表达式
  

• compiles()
  
• deregister()
  

• 表达式序列化扩展

• Deserializer()
  
• Serializer()
  
• dumps()
  
• loads()
  

• SQL 表达式语言基础构造

• CacheKey

• CacheKey.bindparams
  
• CacheKey.key
  
• CacheKey.to_offline_string()
  

• ClauseElement

• ClauseElement.compare()
  
• ClauseElement.compile()
  
• ClauseElement.get_children()
  
• ClauseElement.inherit_cache
  
• ClauseElement.params()
  
• ClauseElement.self_group()
  
• ClauseElement.unique_params()
  

• DialectKWArgs

• DialectKWArgs.argument_for()
  
• DialectKWArgs.dialect_kwargs
  
• DialectKWArgs.dialect_options
  
• DialectKWArgs.kwargs
  

• HasCacheKey

• HasCacheKey.inherit_cache

• LambdaElement
  
• StatementLambdaElement

• StatementLambdaElement.add_criteria()
  
• StatementLambdaElement.is_delete
  
• StatementLambdaElement.is_dml
  
• StatementLambdaElement.is_insert
  
• StatementLambdaElement.is_select
  
• StatementLambdaElement.is_text
  
• StatementLambdaElement.is_update
  
• StatementLambdaElement.spoil()
  

• Visitor and Traversal Utilities

• ExternalTraversal

• ExternalTraversal.chain()
  
• ExternalTraversal.iterate()
  
• ExternalTraversal.traverse()
  
• ExternalTraversal.visitor_iterator
  

• InternalTraversal

• InternalTraversal.dp_annotations_key
  
• InternalTraversal.dp_anon_name
  
• InternalTraversal.dp_boolean
  
• InternalTraversal.dp_clauseelement
  
• InternalTraversal.dp_clauseelement_list
  
• InternalTraversal.dp_clauseelement_tuple
  
• InternalTraversal.dp_clauseelement_tuples
  
• InternalTraversal.dp_dialect_options
  
• InternalTraversal.dp_dml_multi_values
  
• InternalTraversal.dp_dml_ordered_values
  
• InternalTraversal.dp_dml_values
  
• InternalTraversal.dp_fromclause_canonical_column_collection
  
• InternalTraversal.dp_fromclause_ordered_set
  
• InternalTraversal.dp_has_cache_key
  
• InternalTraversal.dp_has_cache_key_list
  
• InternalTraversal.dp_has_cache_key_tuples
  
• InternalTraversal.dp_ignore
  
• InternalTraversal.dp_inspectable
  
• InternalTraversal.dp_inspectable_list
  
• InternalTraversal.dp_multi
  
• InternalTraversal.dp_multi_list
  
• InternalTraversal.dp_named_ddl_element
  
• InternalTraversal.dp_operator
  
• InternalTraversal.dp_plain_dict
  
• InternalTraversal.dp_plain_obj
  
• InternalTraversal.dp_prefix_sequence
  
• InternalTraversal.dp_propagate_attrs
  
• InternalTraversal.dp_statement_hint_list
  
• InternalTraversal.dp_string
  
• InternalTraversal.dp_string_clauseelement_dict
  
• InternalTraversal.dp_string_list
  
• InternalTraversal.dp_string_multi_dict
  
• InternalTraversal.dp_table_hint_list
  
• InternalTraversal.dp_type
  
• InternalTraversal.dp_unknown_structure
  

• Visitable
  
• anon_map
  
• cloned_traverse()
  
• iterate()
  
• replacement_traverse()
  
• traverse()
  
• traverse_using()
  

列元素和表达式

原文：docs.sqlalchemy.org/en/20/core/sqlelement.html

表达式 API 由一系列类组成，每个类代表 SQL 字符串中的特定词法元素。将它们组合成一个更大的结构，形成一个语句构造，可以编译成一个字符串表示，可以传递给数据库。这些类被组织成一个从最基本的ClauseElement类开始的层次结构。关键子类包括ColumnElement，它代表 SQL 语句中任何基于列的表达式的角色，例如在列子句、WHERE 子句和 ORDER BY 子句中，以及FromClause，它代表放置在 SELECT 语句的 FROM 子句中的令牌的角色。

列元素基础构造函数

从sqlalchemy命名空间导入的独立函数，用于构建 SQLAlchemy 表达语言构造时使用。

function sqlalchemy.sql.expression.and_(*clauses)

生成由AND连接的表达式的合取。

例如：

from sqlalchemy import and_
stmt = select(users_table).where(
                and_(
                    users_table.c.name == 'wendy',
                    users_table.c.enrolled == True
                )
            )

and_()合取也可使用 Python 的&运算符（但请注意，为了与 Python 运算符优先级行为配合使用，复合表达式需要加括号）：

stmt = select(users_table).where(
                (users_table.c.name == 'wendy') &
                (users_table.c.enrolled == True)
            )

and_()操作在某些情况下也是隐式的；例如，Select.where()方法可以对语句多次调用，每个子句都会使用and_()结合：

stmt = select(users_table).\
        where(users_table.c.name == 'wendy').\
        where(users_table.c.enrolled == True)

and_() 构造必须至少给定一个位置参数才能有效；没有参数的and_() 构造是模棱两可的。为了生成一个“空”或动态生成的and_() 表达式，从给定的表达式列表中，应指定一个“默认”元素true()（或只是True）：

from sqlalchemy import true
criteria = and_(true(), *expressions)

上述表达式将编译为 SQL 表达式true或1 = 1，取决于后端，如果没有其他表达式存在。如果存在表达式，则true()值将被忽略，因为它不影响具有其他元素的 AND 表达式的结果。

自版本 1.4 弃用：and_() 元素现在要求至少传递一个参数；创建没有参数的and_() 构造已被弃用，并将发出弃用警告，同时继续生成空白的 SQL 字符串。

另请参阅

or_()

function sqlalchemy.sql.expression.bindparam(key: str | None, value: Any = _NoArg.NO_ARG, type_: _TypeEngineArgument[_T] | None = None, unique: bool = False, required: bool | Literal[_NoArg.NO_ARG] = _NoArg.NO_ARG, quote: bool | None = None, callable_: Callable[[], Any] | None = None, expanding: bool = False, isoutparam: bool = False, literal_execute: bool = False) → BindParameter[_T]

生成一个“绑定表达式”。

返回值是BindParameter的一个实例；这是ColumnElement的子类，表示 SQL 表达式中的所谓“占位符”值，在执行语句时会根据数据库连接提供的值。

在 SQLAlchemy 中，bindparam() 构造具有携带最终在表达式时间使用的实际值的能力。通过这种方式，它不仅作为最终填充的“占位符”，还作为表示所谓“不安全”值的一种方式，这些值不应直接呈现在 SQL 语句中，而应作为需要正确转义和可能处理类型安全性的值传递给 DBAPI。

在显式使用bindparam()时，典型用例通常是传统参数的延迟；bindparam() 构造接受一个名称，然后可以在执行时引用：

from sqlalchemy import bindparam
stmt = select(users_table).where(
    users_table.c.name == bindparam("username")
)

上述语句在渲染时将生成类似于 SQL 的内容：

SELECT id, name FROM user WHERE name = :username

为了填充上面的:username的值，通常会在执行时将该值应用到Connection.execute()方法中：

result = connection.execute(stmt, {"username": "wendy"})

当产生要多次调用的 UPDATE 或 DELETE 语句时，明确使用bindparam()也很常见，其中语句的 WHERE 条件在每次调用时都会更改，例如：

stmt = (
    users_table.update()
    .where(user_table.c.name == bindparam("username"))
    .values(fullname=bindparam("fullname"))
)
connection.execute(
    stmt,
    [
        {"username": "wendy", "fullname": "Wendy Smith"},
        {"username": "jack", "fullname": "Jack Jones"},
    ],
)

SQLAlchemy 的核心表达式系统在隐式意义上广泛使用bindparam()。几乎所有 SQL 表达式函数传递给 Python 字面值都会被强制转换为固定的bindparam()构造。例如，给定一个比较操作，如下所示：

expr = users_table.c.name == 'Wendy'

上述表达式将生成一个BinaryExpression结构，其中左侧是代表name列的Column对象，右侧是代表字面值的BindParameter：

print(repr(expr.right))
BindParameter('%(4327771088 name)s', 'Wendy', type_=String())

上述表达式将渲染出如下的 SQL：

user.name = :name_1

:name_1参数名是匿名的。实际字符串Wendy不在渲染的字符串中，但在稍后在语句执行中使用时会一起传递。如果我们调用以下语句：

stmt = select(users_table).where(users_table.c.name == 'Wendy')
result = connection.execute(stmt)

我们会看到 SQL 日志输出如下：

SELECT "user".id, "user".name
FROM "user"
WHERE "user".name = %(name_1)s
{'name_1': 'Wendy'}

上面，我们看到Wendy作为参数传递给数据库，而占位符:name_1在适当形式下被渲染到目标数据库中，这里是 PostgreSQL 数据库。

类似地，当处理 CRUD 语句的“VALUES”部分时，bindparam()会在自动调用时进行处理。insert()构造生成一个INSERT表达式，在语句执行时，将根据传递的参数生成绑定占位符，如下所示：

stmt = users_table.insert()
result = connection.execute(stmt, {"name": "Wendy"})

上述操作将产生如下的 SQL 输出：

INSERT INTO "user" (name) VALUES (%(name)s)
{'name': 'Wendy'}

Insert构造在编译/执行时，根据我们传递给Connection.execute()方法的单个name参数，生成一个单个的bindparam()镜像列名name。

参数：

• key –
  此绑定参数的键（例如名称）。对于使用命名参数的方言，将在生成的 SQL 语句中使用此键。在编译操作的一部分时，如果存在具有相同键的其他 BindParameter 对象，或者如果其长度太长并且需要截断，则可能会修改此值。
  如果省略，则为绑定参数生成一个“匿名”名称；当给定一个要绑定的值时，最终结果相当于使用一个值来绑定调用 literal() 函数，特别是如果还提供了 bindparam.unique 参数。
  
• value – 此绑定参数的初始值。如果没有为此特定参数名称指示语句执行方法的其他值，则在语句执行时将用作传递给 DBAPI 的此参数的值。默认为 None。
  
• callable_ – 一个可调用函数，用于取代“value”。该函数将在语句执行时被调用，以确定最终值。用于无法在创建子句构造时确定实际绑定值，但仍希望使用嵌入式绑定值的情况。
  
• type_ –
  表示此 bindparam() 的可选数据类型的 TypeEngine 类或实例。如果未传递，则可以根据给定值自动确定绑定的类型；例如，trivial Python 类型，如 str、int、bool 可能会自动选择 String、Integer 或 Boolean 类型。
  bindparam() 的类型尤其重要，因为该类型将在将值传递到数据库之前对值进行预处理。例如，引用 datetime 值的 bindparam()，并且被指定为持有 DateTime 类型，可能会在将值传递到数据库之前对值进行所需的转换（例如在 SQLite 上进行字符串化）。
  
• unique – 如果为 True，则此 BindParameter 的键名将被修改，如果同名的另一个 BindParameter 已经存在于包含表达式中。这个标志通常由内部使用，当产生所谓的“匿名”绑定表达式时，它通常不适用于明确命名的 bindparam() 构造。
  
• required – 如果为True，则在执行时需要一个值。如果未传递，且既未传递 bindparam.value 也未传递 bindparam.callable，则默认为True。如果存在这些参数中的任何一个，则 bindparam.required 默认为False。
  
• quote – 如果此参数名需要引用，并且当前不被认为是 SQLAlchemy 保留字，则为 True；目前仅适用于 Oracle 后端，其中绑定名称有时必须被引用。
  
• isoutparam – 如果为 True，则应将参数视为存储过程的“OUT”参数。这适用于诸如 Oracle 之类支持 OUT 参数的后端。
  
• expanding –
  如果为 True，则此参数在执行时将被视为“扩展”参数；参数值应为序列，而不是标量值，并且字符串 SQL 语句将在每次执行时进行转换，以适应具有可变数量参数槽的序列传递给 DBAPI。这是为了允许语句缓存与 IN 子句一起使用。
  另请参阅
  ColumnOperators.in_()
  使用 IN 表达式 - 使用烘焙查询
  注意
  “扩展”功能不支持“executemany”式参数集。
  自版本 1.2 新增。
  自版本 1.3 更改：现在，“扩展”绑定参数功能支持空列表。
  
• literal_execute –
  如果为 True，则绑定参数将在编译阶段呈现为特殊的“POSTCOMPILE”令牌，并且 SQLAlchemy 编译器将在语句执行时将参数的最终值呈现为 SQL 语句，省略了传递给 DBAPI cursor.execute() 的参数字典/列表中的值。这产生了与使用 literal_binds 编译标志类似的效果，但是发生在将语句发送到 DBAPI cursor.execute() 方法时，而不是在语句编译时。此功能的主要用途是在数据库驱动程序无法在这些上下文中容纳绑定参数的情况下呈现 LIMIT/OFFSET 子句，同时允许 SQL 结构在编译级别可缓存。
  版本 1.4 中的新功能：添加了“编译后”绑定参数
  另请参阅
  Oracle、SQL Server 中用于 LIMIT/OFFSET 的新的“编译后”绑定参数。
  

另请参阅

发送参数 - 在 SQLAlchemy 统一教程 中

function sqlalchemy.sql.expression.bitwise_not(expr: _ColumnExpressionArgument[_T]) → UnaryExpression[_T]

生成一元位取反子句，通常通过 ~ 运算符实现。

不要与布尔取反 not_() 混淆。

版本 2.0.2 中的新功能。

另请参阅

位运算符

function sqlalchemy.sql.expression.case(*whens: typing_Tuple[_ColumnExpressionArgument[bool], Any] | Mapping[Any, Any], value: Any | None = None, else_: Any | None = None) → Case[Any]

生成一个 CASE 表达式。

SQL 中的 CASE 结构是一个条件对象，其作用类似于其他语言中的“if/then”结构。它返回一个 Case 的实例。

case() 通常形式下传递了一系列“when”构造，即一系列条件和结果的元组：

from sqlalchemy import case
stmt = select(users_table).\
            where(
                case(
                    (users_table.c.name == 'wendy', 'W'),
                    (users_table.c.name == 'jack', 'J'),
                    else_='E'
                )
            )

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

SELECT id, name FROM user
WHERE CASE
    WHEN (name = :name_1) THEN :param_1
    WHEN (name = :name_2) THEN :param_2
    ELSE :param_3
END

当需要针对单个父列的几个值进行简单等式表达式时，case() 也有一种“简写”格式，通过 case.value 参数传递，该参数传递了要比较的列表达式。在这种形式下，case.whens 参数作为包含要与键入结果表达式比较的表达式的字典传递。下面的语句与前面的语句等效：

stmt = select(users_table).\
            where(
                case(
                    {"wendy": "W", "jack": "J"},
                    value=users_table.c.name,
                    else_='E'
                )
            )

在 case.whens 中作为结果值接受的值以及与 case.else_ 相同的值从 Python 文字转换为 bindparam() 构造。 SQL 表达式，例如 ColumnElement 构造，也被接受。要将文字字符串表达式强制转换为内联渲染的常量表达式，请使用 literal_column() 构造，例如：

from sqlalchemy import case, literal_column
case(
    (
        orderline.c.qty > 100,
        literal_column("'greaterthan100'")
    ),
    (
        orderline.c.qty > 10,
        literal_column("'greaterthan10'")
    ),
    else_=literal_column("'lessthan10'")
)

以上将渲染给定的常量，而不是使用绑定参数作为结果值（但仍然适用于比较值），例如：

CASE
    WHEN (orderline.qty > :qty_1) THEN 'greaterthan100'
    WHEN (orderline.qty > :qty_2) THEN 'greaterthan10'
    ELSE 'lessthan10'
END

参数：

• *whens –
  要进行比较的条件，case.whens 接受两种不同形式，基于是否使用了 case.value。
  1.4 版更改：case() 函数现在按位置接受 WHEN 条件的系列。
  在第一种形式中，它接受多个以位置参数传递的 2 元组；每个 2 元组由 (, ) 组成，其中 SQL 表达式是布尔表达式，而“value”是一个结果值，例如：

case(
    (users_table.c.name == 'wendy', 'W'),
    (users_table.c.name == 'jack', 'J')
)

• 在第二种形式中，它接受一个将比较值映射到结果值的 Python 字典；此形式需要 case.value 存在，并且值将使用 == 运算符进行比较，例如：

case(
    {"wendy": "W", "jack": "J"},
    value=users_table.c.name
)

• value – 一个可选的 SQL 表达式，它将作为传递给 case.whens 的字典中的候选值的固定“比较点”。
  
• else_ – 一个可选的 SQL 表达式，如果 case.whens 中的所有表达式都为 false，则将其作为 CASE 构造的评估结果。如果省略，大多数数据库在所有“when”表达式均未评估为 true 时会产生 NULL 结果。
  

function sqlalchemy.sql.expression.cast(expression: _ColumnExpressionOrLiteralArgument[Any], type_: _TypeEngineArgument[_T]) → Cast[_T]

生成一个 CAST 表达式。

cast() 返回 Cast 的实例。

例如：

from sqlalchemy import cast, Numeric
stmt = select(cast(product_table.c.unit_price, Numeric(10, 4)))

上述语句将产生类似的 SQL：

SELECT CAST(unit_price AS NUMERIC(10, 4)) FROM product

当使用时，cast() 函数执行两个不同的功能。第一个是它在结果 SQL 字符串中呈现 CAST 表达式。第二个是它将给定类型（例如TypeEngine类或实例）与 Python 端的列表达式关联起来，这意味着表达式将采用与该类型关联的表达式运算符行为，以及该类型的绑定值处理和结果行处理行为。

cast()的替代方法是type_coerce()函数。该函数执行了将表达式与特定类型关联的第二个任务，但不会在 SQL 中呈现 CAST 表达式。

参数：

• expression – 一个 SQL 表达式，比如一个 ColumnElement 表达式或一个将被强制转换为绑定文字值的 Python 字符串。
  
• type_ – 一个指示 CAST 应用的类型的TypeEngine类或实例。
  

另请参阅

数据转换和类型强制

try_cast() - CAST 的一种替代方法，当转换失败时返回 NULL，而不是引发错误。仅受一些方言支持。

type_coerce() - CAST 的替代方法，仅在 Python 端强制转换类型，这通常足以生成正确的 SQL 和数据强制转换。

function sqlalchemy.sql.expression.column(text: str, type_: _TypeEngineArgument[_T] | None = None, is_literal: bool = False, _selectable: FromClause | None = None) → ColumnClause[_T]

生成一个 ColumnClause 对象。

ColumnClause 是 Column 类的轻量级模拟。column() 函数可以仅使用名称调用，如下所示：

from sqlalchemy import column
id, name = column("id"), column("name")
stmt = select(id, name).select_from("user")

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

SELECT id, name FROM user

构造完毕后，column() 可以像其他 SQL 表达式元素一样使用，比如在 select() 构造中：

from sqlalchemy.sql import column
id, name = column("id"), column("name")
stmt = select(id, name).select_from("user")

由 column() 处理的文本被假定处理为数据库列的名称；如果字符串包含混合大小写、特殊字符，或与目标后端的已知保留字匹配，则列表达式将使用由后端确定的引用行为渲染。若要生成一个确切的文本 SQL 表达式而不应用任何引用，请改用 literal_column()，或将 column.is_literal 的值传递为 True。此外，完整的 SQL 语句最好使用 text() 构造处理。

column() 可以通过与 table() 函数组合（它是 Table 的轻量级类比）以表格方式使用，以产生一个带有最小样板的可用表构造：

from sqlalchemy import table, column, select
user = table("user",
        column("id"),
        column("name"),
        column("description"),
)
stmt = select(user.c.description).where(user.c.name == 'wendy')

像上面示例的 column() / table() 构造可以以临时方式创建，并且与任何 MetaData、DDL 或事件无关，不像它的 Table 对应物。

参数：

• text – 元素的文本。
  
• type – TypeEngine 对象，可以将此 ColumnClause 与类型关联。
  
• is_literal – 如果为 True，则假定 ColumnClause 是一个精确的表达式，将以不考虑大小写设置的情况下，无论如何都不会应用任何引用规则传递到输出。 literal_column() 函数本质上调用 column()，同时传递 is_literal=True。
  

另请参阅

Column

literal_column()

table()

text()

使用文本列表达式进行选择

class sqlalchemy.sql.expression.custom_op

表示“自定义”运算符。

当使用Operators.op()或Operators.bool_op()方法创建自定义运算符可调用时，通常会实例化custom_op。该类也可以直接在编程构建表达式时使用。例如，表示“阶乘”操作：

from sqlalchemy.sql import UnaryExpression
from sqlalchemy.sql import operators
from sqlalchemy import Numeric
unary = UnaryExpression(table.c.somecolumn,
        modifier=operators.custom_op("!"),
        type_=Numeric)

另请参阅

Operators.op()

Operators.bool_op()

类签名

类sqlalchemy.sql.expression.custom_op（sqlalchemy.sql.expression.OperatorType，typing.Generic）

function sqlalchemy.sql.expression.distinct(expr: _ColumnExpressionArgument[_T]) → UnaryExpression[_T]

生成一个列表达式级别的一元DISTINCT子句。

这将在单独的列表达式上应用DISTINCT关键字（例如，不是整个语句），并特定地在该列位置呈现；这用于在聚合函数内部进行包含，如：

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

上述将产生类似于以下语句：

SELECT user.id, count(DISTINCT user.name) FROM user

提示

distinct()函数不会将 DISTINCT 应用于完整的 SELECT 语句，而是将 DISTINCT 修饰符应用于单独的列表达式。要获得一般的SELECT DISTINCT支持，请在Select上使用Select.distinct()方法。

distinct()函数也可作为列级方法使用，例如ColumnElement.distinct()，如下所示：

stmt = select(func.count(users_table.c.name.distinct()))

distinct()运算符与Select.distinct()方法不同，后者会在整个结果集上应用DISTINCT，例如SELECT DISTINCT表达式。有关更多信息，请参阅该方法。

另请参阅

ColumnElement.distinct()

Select.distinct()

func

function sqlalchemy.sql.expression.extract(field: str, expr: _ColumnExpressionArgument[Any]) → Extract

返回一个 Extract 结构。

通常可从 func 命名空间中的 extract() 或 func.extract 中获得此功能。

参数：

• field – 要提取的字段。
  
• expr – 作为 EXTRACT 表达式右侧的列或 Python 标量表达式。
  

例如：

from sqlalchemy import extract
from sqlalchemy import table, column
logged_table = table("user",
        column("id"),
        column("date_created"),
)
stmt = select(logged_table.c.id).where(
    extract("YEAR", logged_table.c.date_created) == 2021
)

在上面的示例中，该语句用于从数据库中选择 YEAR 组件与特定值匹配的 id。

同样，也可以选择提取的组件：

stmt = select(
    extract("YEAR", logged_table.c.date_created)
).where(logged_table.c.id == 1)

EXTRACT 的实现可能因数据库后端而异。提醒用户查阅其数据库文档。

function sqlalchemy.sql.expression.false() → False_

返回一个 False_ 结构。

例如：

>>> from sqlalchemy import false
>>> print(select(t.c.x).where(false()))
SELECT  x  FROM  t  WHERE  false 

如果后端不支持真/假常量，将呈现为针对 1 或 0 的表达式：

>>> print(select(t.c.x).where(false()))
SELECT  x  FROM  t  WHERE  0  =  1 

true() 和 false() 常量也在 and_() 或 or_() 连接中具有“短路”操作：

>>> print(select(t.c.x).where(or_(t.c.x > 5, true())))
SELECT  x  FROM  t  WHERE  true
>>> print(select(t.c.x).where(and_(t.c.x > 5, false())))
SELECT  x  FROM  t  WHERE  false 

另请参阅

true()

sqlalchemy.sql.expression.func = <sqlalchemy.sql.functions._FunctionGenerator object>

生成 SQL 函数表达式。

func 是一个特殊的对象实例，根据基于名称的属性生成 SQL 函数，例如：

>>> print(func.count(1))
count(:param_1) 

返回的对象是 Function 的实例，并且是一个面向列的 SQL 元素，可以以这种方式使用：

>>> print(select(func.count(table.c.id)))
SELECT  count(sometable.id)  FROM  sometable 

func 可以指定任何名称。如果 SQLAlchemy 不认识函数名称，则会按原样呈现。对于 SQLAlchemy 认识的常见 SQL 函数，名称可能被解释为通用函数，将根据目标数据库适当编译：

>>> print(func.current_timestamp())
CURRENT_TIMESTAMP 

要调用点分包中存在的函数，以相同的方式指定它们：

>>> print(func.stats.yield_curve(5, 10))
stats.yield_curve(:yield_curve_1,  :yield_curve_2) 

SQLAlchemy 可以了解函数的返回类型，以启用特定类型的词法和基于结果的行为。例如，要确保基于字符串的函数返回 Unicode 值，并且在表达式中类似地对待为字符串，请将 Unicode 指定为类型：

>>> print(func.my_string(u'hi', type_=Unicode) + ' ' +
...       func.my_string(u'there', type_=Unicode))
my_string(:my_string_1)  ||  :my_string_2  ||  my_string(:my_string_3) 

通过 func 调用返回的对象通常是 Function 的实例。该对象符合“列”接口，包括比较和标记函数。该对象也可以传递给 Connection 或 Engine 的 Connectable.execute() 方法，它首先将被包装在 SELECT 语句中：

print(connection.execute(func.current_timestamp()).scalar())

在一些例外情况下，func 访问器将名称重定向到内置表达式，如 cast() 或 extract() ，因为这些名称具有众所周知的含义，但从 SQLAlchemy 的角度来看并不完全相同于“函数”。

被解释为“通用”函数的函数知道如何自动计算它们的返回类型。有关已知通用函数的列表，请参阅 SQL 和通用函数。

注意

func 结构对于调用独立的“存储过程”仅有有限的支持，特别是那些具有特殊参数化关注的情况。

有关如何使用 DBAPI 级别的 callproc() 方法来完全传统的存储过程的详细信息，请参阅 调用存储过程和用户定义的函数 部分。

另请参阅

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

Function

function sqlalchemy.sql.expression.lambda_stmt(lmb: Callable[[], Any], enable_tracking: bool = True, track_closure_variables: bool = True, track_on: object | None = None, global_track_bound_values: bool = True, track_bound_values: bool = True, lambda_cache: MutableMapping[Tuple[Any, ...], NonAnalyzedFunction | AnalyzedFunction] | None = None) → StatementLambdaElement

将一个 SQL 语句制作成一个缓存为 lambda。

lambda 中的 Python 代码对象会被扫描，其中既包括将变为绑定参数的 Python 字面量，也包括引用可能不同的 Core 或 ORM 构造的闭包变量。 lambda 本身仅在检测到特定一组构造时才会被调用一次。

例如：

from sqlalchemy import lambda_stmt
stmt = lambda_stmt(lambda: table.select())
stmt += lambda s: s.where(table.c.id == 5)
result = connection.execute(stmt)

返回的对象是 StatementLambdaElement 的实例。

在版本 1.4 中新增。

参数：

• lmb – 一个 Python 函数，通常是一个 lambda，不接受任何参数并返回一个 SQL 表达式构造
  
• enable_tracking – 当为 False 时，所有对给定 lambda 的扫描，以检测闭包变量或绑定参数的更改都将被禁用。对于在所有情况下都产生相同结果且没有参数化的 lambda 使用。
  
• track_closure_variables – 当为 False 时，将不会扫描 lambda 中闭包变量的更改。用于闭包变量的状态永远不会改变 lambda 返回的 SQL 结构的 lambda。
  
• track_bound_values – 当为 False 时，将禁用给定 lambda 的绑定参数跟踪。用于不生成任何绑定值的 lambda，或者初始绑定值永远不会更改的 lambda。
  
• global_track_bound_values – 当为 False 时，整个语句的绑定参数跟踪将被禁用，包括通过StatementLambdaElement.add_criteria()方法添加的其他链接。
  
• lambda_cache – 一个字典或其他类似映射的对象，其中将存储有关 lambda 的 Python 代码以及 lambda 本身中跟踪的闭包变量的信息。默认为全局 LRU 缓存。此缓存独立于 Connection 对象使用的“compiled_cache”。
  

另请参阅

使用 Lambdas 为语句生成添加显著的速度增益

function sqlalchemy.sql.expression.literal(value: Any, type_: _TypeEngineArgument[Any] | None = None, literal_execute: bool = False) → BindParameter[Any]

返回一个文字子句，绑定到一个绑定参数。

当使用非ClauseElement对象（例如字符串、整数、日期等）与ColumnElement子类（如 Column 对象）进行比较操作时，会自动创建文字子句。使用此函数强制生成文字子句，它将作为具有绑定值的 BindParameter 创建。

参数：

• value – 要绑定的值。可以是底层 DB-API 支持的任何 Python 对象，或者可以通过给定的类型参数进行翻译。
  
• type_ – 一个可选的TypeEngine，它将为此文字提供绑定参数翻译。
  
• literal_execute –
  可选布尔值，当为 True 时，SQL 引擎将尝试在执行时直接在 SQL 语句中渲染绑定值，而不是提供作为参数值。
  新版本 2.0 中新增。
  

function sqlalchemy.sql.expression.literal_column(text: str, type_: _TypeEngineArgument[_T] | None = None) → ColumnClause[_T]

生成一个具有 column.is_literal 标志设置为 True 的 ColumnClause 对象。

literal_column() 类似于 column()，但更常用作“独立的”列表达式，其呈现方式与所述完全相同；而 column() 存储一个假设为表的一部分并可能被引用为此类的字符串名称， literal_column() 可以是那个，或任何其他任意的面向列的表达式。

参数：

• text – 表达式的文本；可以是任何 SQL 表达式。引号规则不会应用。要指定应受引号规则约束的列名表达式，请使用 column() 函数。
  
• type_ – 一个可选的 TypeEngine 对象，将为该列提供结果集转换和附加表达语义。如果保持为 None，类型将是 NullType。
  

另请参阅

column()

text()

使用文本列表达式进行选择

function sqlalchemy.sql.expression.not_(clause: _ColumnExpressionArgument[_T]) → ColumnElement[_T]

返回给定子句的否定，即 NOT(clause)。

~ 操作符也对所有 ColumnElement 子类进行了重载，以产生相同的结果。

function sqlalchemy.sql.expression.null() → Null

返回一个常量 Null 结构。

function sqlalchemy.sql.expression.or_(*clauses)

生成由 OR 连接的表达式。

例如：

from sqlalchemy import or_
stmt = select(users_table).where(
                or_(
                    users_table.c.name == 'wendy',
                    users_table.c.name == 'jack'
                )
            )

or_() 连接词也可使用 Python 的 | 操作符（但请注意，复合表达式需要用括号括起来以与 Python 运算符优先级行为一起使用）：

stmt = select(users_table).where(
                (users_table.c.name == 'wendy') |
                (users_table.c.name == 'jack')
            )

or_() 结构必须至少给定一个位置参数才能有效；没有参数的 or_() 结构是模棱两可的。为了生成一个“空”的或动态生成的 or_() 表达式，从给定的表达式列表中，应指定一个“默认”元素 false() （或只是 False）：

from sqlalchemy import false
or_criteria = or_(false(), *expressions)

如果没有其他表达式存在，则上述表达式将编译为 SQL 表达式false或0 = 1，取决于后端。 如果存在表达式，则false()值将被忽略，因为它不影响具有其他元素的 OR 表达式的结果。

自版本 1.4 起弃用：or_()元素现在要求至少传递一个参数；创建没有参数的or_()结构已被弃用，并将发出弃用警告，同时继续生成空白 SQL 字符串。

另请参阅

and_()

function sqlalchemy.sql.expression.outparam(key: str, type_: TypeEngine[_T] | None = None) → BindParameter[_T]

为在支持它们的数据库中使用的函数（存储过程）创建一个“OUT”参数。

outparam可以像常规函数参数一样使用。 “输出”值将通过其out_parameters属性从CursorResult对象中获取，该属性返回一个包含值的字典。

function sqlalchemy.sql.expression.text(text: str) → TextClause

构建一个新的TextClause子句，直接表示文本 SQL 字符串。

例如：

from sqlalchemy import text
t = text("SELECT * FROM users")
result = connection.execute(t)

text()相对于普通字符串提供的优势是，后端中立地支持绑定参数，每个语句的执行选项，以及绑定参数和结果列类型行为，允许 SQLAlchemy 类型构造在执行字面上指定的语句时发挥作用。该构造还可以提供一个.c列元素集合，允许将其嵌入到其他 SQL 表达式构造中作为子查询。

通过名称指定绑定参数，使用格式:name。 例如：

t = text("SELECT * FROM users WHERE id=:user_id")
result = connection.execute(t, {"user_id": 12})

对于需要直接使用冒号的 SQL 语句，如在内联字符串中，使用反斜杠进行转义：

t = text(r"SELECT * FROM users WHERE name='\:username'")

TextClause构造包括可以提供有关绑定参数的信息以及从文本语句返回的列值的方法，假设它是可执行的 SELECT 类型语句。 TextClause.bindparams()方法用于提供绑定参数详细信息，TextClause.columns()方法允许指定返回列，包括名称和类型：

t = text("SELECT * FROM users WHERE id=:user_id").\
        bindparams(user_id=7).\
        columns(id=Integer, name=String)
for id, name in connection.execute(t):
    print(id, name)

在指定较大查询的一部分（例如 SELECT 语句的 WHERE 子句）时，使用text()构造表示文本字符串 SQL 片段的情况：

s = select(users.c.id, users.c.name).where(text("id=:user_id"))
result = connection.execute(s, {"user_id": 12})

text()还用于构建完整的、独立的文本语句。因此，SQLAlchemy 将其称为Executable对象，并且可以像传递给.execute()方法的任何其他语句一样使用。

参数：

text –

要创建的 SQL 语句的文本。使用:指定绑定参数；它们将被编译为特定于引擎的格式。

警告

text()函数的text.text参数可以作为 Python 字符串参数传递，它将被视为受信任的 SQL 文本并按照给定的方式呈现。不要将不受信任的输入传递给此参数。

亦可参见

使用文本列表达式进行选择

function sqlalchemy.sql.expression.true() → True_

返回一个常量True_构造。

例如：

>>> from sqlalchemy import true
>>> print(select(t.c.x).where(true()))
SELECT  x  FROM  t  WHERE  true 

不支持 true/false 常量的后端将呈现为针对 1 或 0 的表达式：

>>> print(select(t.c.x).where(true()))
SELECT  x  FROM  t  WHERE  1  =  1 

true()和false()常量在and_()或or_()连接中也具有“短路”操作：

>>> print(select(t.c.x).where(or_(t.c.x > 5, true())))
SELECT  x  FROM  t  WHERE  true
>>> print(select(t.c.x).where(and_(t.c.x > 5, false())))
SELECT  x  FROM  t  WHERE  false 

亦可参见

false()

function sqlalchemy.sql.expression.try_cast(expression: _ColumnExpressionOrLiteralArgument[Any], type_: _TypeEngineArgument[_T]) → TryCast[_T]

为支持它的后端生成一个TRY_CAST表达式；这是一个返回不可转换的转换为 NULL 的CAST。

在 SQLAlchemy 中，这种构造仅由 SQL Server 方言支持，如果在其他包含的后端使用将引发CompileError。但是，第三方后端也可能支持此构造。

提示

由于try_cast()源自 SQL Server 方言，因此可以从sqlalchemy.以及sqlalchemy.dialects.mssql导入它。

try_cast() 返回 TryCast 的实例，并且通常行为类似于 Cast 构造；在 SQL 级别上，CAST 和 TRY_CAST 之间的区别是 TRY_CAST 对于无法转换的表达式（例如尝试将字符串"hi"转换为整数值）返回 NULL。

例如：

from sqlalchemy import select, try_cast, Numeric
stmt = select(
    try_cast(product_table.c.unit_price, Numeric(10, 4))
)

在 Microsoft SQL Server 上，上述内容将呈现为：

SELECT TRY_CAST (product_table.unit_price AS NUMERIC(10, 4))
FROM product_table

从版本 2.0.14 开始：try_cast() 已从 SQL Server 方言泛化为一个通用构造，可能会受到其他方言的支持。

function sqlalchemy.sql.expression.tuple_(*clauses: _ColumnExpressionArgument[Any], types: Sequence[_TypeEngineArgument[Any]] | None = None) → Tuple

返回一个 Tuple。

主要用途是使用ColumnOperators.in_()生成复合的 IN 构造。

from sqlalchemy import tuple_
tuple_(table.c.col1, table.c.col2).in_(
    [(1, 2), (5, 12), (10, 19)]
)

在版本 1.3.6 中更改：添加对 SQLite IN 元组的支持。

警告

不是所有后端都支持复合的 IN 构造，目前已知的仅支持 PostgreSQL、MySQL 和 SQLite。当调用这样的表达式时，不支持的后端将引发 DBAPIError 的子类。

function sqlalchemy.sql.expression.type_coerce(expression: _ColumnExpressionOrLiteralArgument[Any], type_: _TypeEngineArgument[_T]) → TypeCoerce[_T]

将 SQL 表达式与特定类型关联，而不会渲染CAST。

例如：

from sqlalchemy import type_coerce
stmt = select(type_coerce(log_table.date_string, StringDateTime()))

上述构造将生成一个 TypeCoerce 对象，在 SQL 方面不会以任何方式修改呈现，可能的例外情况是在列子句上下文中使用时生成的标签：

SELECT  date_string  AS  date_string  FROM  log

当提取结果行时，StringDateTime 类型处理器将代表date_string列应用于结果行。

注意

type_coerce() 构造不会渲染任何自己的 SQL 语法，包括不会暗示添加括号。如果需要显式添加括号，请使用 TypeCoerce.self_group()。

为了为表达式提供一个命名标签，请使用 ColumnElement.label()：

stmt = select(
    type_coerce(log_table.date_string, StringDateTime()).label('date')
)

具有绑定值处理功能的类型在将文字值或bindparam()构造传递给type_coerce()作为目标时也会产生该行为。例如，如果一个类型实现了TypeEngine.bind_expression()方法或TypeEngine.bind_processor()方法或等效方法，这些函数将在语句编译/执行时生效，当传递文字值时，如：

# bound-value handling of MyStringType will be applied to the
# literal value "some string"
stmt = select(type_coerce("some string", MyStringType))

在使用type_coerce()与组合表达式时，请注意不要应用括号。如果在需要 CAST 中通常存在的括号的运算符上下文中使用type_coerce()，请使用TypeCoerce.self_group()方法：

>>> some_integer = column("someint", Integer)
>>> some_string = column("somestr", String)
>>> expr = type_coerce(some_integer + 5, String) + some_string
>>> print(expr)
someint  +  :someint_1  ||  somestr
>>> expr = type_coerce(some_integer + 5, String).self_group() + some_string
>>> print(expr)
(someint  +  :someint_1)  ||  somestr 

参数：

• expression – 一个 SQL 表达式，例如一个ColumnElement表达式或一个将被强制转换为绑定文字值的 Python 字符串。
  
• type_ – 一个指示表达式被强制转换为的类型的TypeEngine类或实例。
  

另请参阅

数据转换和类型强制转换

cast()

class sqlalchemy.sql.expression.quoted_name

表示与引号偏好结合的 SQL 标识符。

quoted_name是一个表示特定标识符名称的 Python unicode/str 子类，以及一个quote标志。当将此quote标志设置为True或False时，将覆盖此标识符的自动引号行为，以便无条件引用或不引用名称。如果保持默认值None，则引号行为将根据对标记本身的检查在每个后端基础上应用于标识符。

当 quoted_name 对象的 quote=True  时，还会防止出现所谓的“名称规范化”选项。某些数据库后端（如 Oracle、Firebird 和  DB2）将不区分大小写的名称规范化为大写。这些后端的 SQLAlchemy 方言将从 SQLAlchemy  的小写表示不敏感约定转换为这些后端的大写表示不敏感约定。在此处的 quote=True 标志将阻止此转换发生，以支持针对此类后端引用的标识符为全部小写。

quoted_name 对象通常在指定键架构构造的名称时自动生成，如 Table、Column 等。该类也可以显式地作为任何接收可引用名称的函数的名称传递。例如，要在未经条件引用的名称上使用 Engine.has_table() 方法：

from sqlalchemy import create_engine
from sqlalchemy import inspect
from sqlalchemy.sql import quoted_name
engine = create_engine("oracle+cx_oracle://some_dsn")
print(inspect(engine).has_table(quoted_name("some_table", True)))

上述逻辑将针对 Oracle 后端运行“has table”逻辑，将名称传递为 "some_table"，而不会转换为大写。

从版本 1.2 开始更改：quoted_name 构造现在可以从 sqlalchemy.sql 导入，而不仅仅是以前的位置 sqlalchemy.sql.elements。

成员

quote

类签名

类 sqlalchemy.sql.expression.quoted_name (sqlalchemy.util.langhelpers.MemoizedSlots, builtins.str)

attribute quote

字符串是否应该被无条件引用 ## Column Element Modifier Constructors

此处列出的函数通常作为任何 ColumnElement 构造的方法更常见。例如，label() 函数通常通过 ColumnElement.label() 方法调用。

function sqlalchemy.sql.expression.all_(expr: _ColumnExpressionArgument[_T]) → CollectionAggregate[bool]

生成一个 ALL 表达式。

对于像 PostgreSQL 的方言，这个运算符适用于 ARRAY 数据类型的用法，对于 MySQL，它可能适用于子查询。例如：

# renders on PostgreSQL:
# '5 = ALL (somearray)'
expr = 5 == all_(mytable.c.somearray)
# renders on MySQL:
# '5 = ALL (SELECT value FROM table)'
expr = 5 == all_(select(table.c.value))

与 NULL 的比较可以使用 None：

None == all_(mytable.c.somearray)

any_() / all_() 运算符还具有特殊的“操作数翻转”行为，即如果 any_() / all_() 用于比较的左侧是独立运算符，如 ==、!= 等（不包括操作符方法，比如 ColumnOperators.is_()），则渲染的表达式会被翻转：

# would render '5 = ALL (column)`
all_(mytable.c.column) == 5

或者使用 None，需要注意的是，通常情况下不会像对待 NULL 一样渲染 “IS”：

# would render 'NULL = ALL(somearray)'
all_(mytable.c.somearray) == None

从版本 1.4.26 开始更改：修复了 any_() / all_() 将 NULL 与右侧比较时翻转为左侧的问题。

列级别的 ColumnElement.all_() 方法（不要与 ARRAY 级别的 Comparator.all() 混淆）是 all_(col) 的速记形式：

5 == mytable.c.somearray.all_()

参见

ColumnOperators.all_()

any_()

function sqlalchemy.sql.expression.any_(expr: _ColumnExpressionArgument[_T]) → CollectionAggregate[bool]

生成一个 ANY 表达式。

对于像 PostgreSQL 这样的方言，此运算符适用于 ARRAY 数据类型的使用，对于 MySQL，它可能适用于子查询。例如：

# renders on PostgreSQL:
# '5 = ANY (somearray)'
expr = 5 == any_(mytable.c.somearray)
# renders on MySQL:
# '5 = ANY (SELECT value FROM table)'
expr = 5 == any_(select(table.c.value))

使用 None 或 null() 可能会与 NULL 进行比较：

None == any_(mytable.c.somearray)

any_() / all_() 运算符还具有特殊的“操作数翻转”行为，即如果 any_() / all_() 用于比较的左侧，使用独立运算符如 ==、!= 等（不包括操作符方法如 ColumnOperators.is_()）则渲染的表达式会被翻转：

# would render '5 = ANY (column)`
any_(mytable.c.column) == 5

或者使用 None，这个注释不会执行通常用于 NULL 的“IS”渲染步骤：

# would render 'NULL = ANY(somearray)'
any_(mytable.c.somearray) == None

在版本 1.4.26 中更改：修复了 any_() / all_() 与右侧 NULL 进行比较时翻转到左侧的问题。

列级别的 ColumnElement.any_() 方法（不要与 ARRAY 级别的 Comparator.any() 混淆）是 any_(col) 的简写：

5 = mytable.c.somearray.any_()

另请参见

ColumnOperators.any_()

all_()

function sqlalchemy.sql.expression.asc(column: _ColumnExpressionOrStrLabelArgument[_T]) → UnaryExpression[_T

生成一个升序的 ORDER BY 子句元素。

例如：

from sqlalchemy import asc
stmt = select(users_table).order_by(asc(users_table.c.name))

将产生 SQL 如下：

SELECT id, name FROM user ORDER BY name ASC

asc() 函数是所有 SQL 表达式上可用的 ColumnElement.asc() 方法的独立版本，例如：

stmt = select(users_table).order_by(users_table.c.name.asc())

参数：

column – 一个 ColumnElement（例如标量 SQL 表达式），用于应用 asc() 操作。

另请参见

desc()

nulls_first()

nulls_last()

Select.order_by()

function sqlalchemy.sql.expression.between(expr: _ColumnExpressionOrLiteralArgument[_T], lower_bound: Any, upper_bound: Any, symmetric: bool = False) → BinaryExpression[bool]

生成一个 BETWEEN 谓词子句。

例如：

from sqlalchemy import between
stmt = select(users_table).where(between(users_table.c.id, 5, 7))

会产生类似的 SQL：

SELECT id, name FROM user WHERE id BETWEEN :id_1 AND :id_2

between()函数是所有 SQL 表达式上都可用的ColumnElement.between()方法的独立版本，如下所示：

stmt = select(users_table).where(users_table.c.id.between(5, 7))

所有传递给between()的参数，包括左侧列表达式，如果值不是ColumnElement子类，则从 Python 标量值转换。例如，可以像这样比较三个固定值：

print(between(5, 3, 7))

这将产生：

:param_1 BETWEEN :param_2 AND :param_3

参数：

• expr – 一个列表达式，通常是一个ColumnElement实例，或者作为要强制转换为列表达式的 Python 标量表达式，用作BETWEEN表达式的左侧。
  
• lower_bound – 作为BETWEEN表达式右侧下限的列或 Python 标量表达式。
  
• upper_bound – 作为BETWEEN表达式右侧上限的列或 Python 标量表达式。
  
• symmetric – 如果为 True，则渲染“ BETWEEN SYMMETRIC ”。请注意，并非所有数据库都支持此语法。
  

另请参阅

ColumnElement.between()

function sqlalchemy.sql.expression.collate(expression: _ColumnExpressionArgument[str], collation: str) → BinaryExpression[str]

返回子句expression COLLATE collation。

例如：

collate(mycolumn, 'utf8_bin')

产生：

mycolumn COLLATE utf8_bin

如果排序表达式是大小写敏感的标识符，例如包含大写字符，则排序表达式也会被引用。

从版本 1.2 开始更改：如果 COLLATE 表达式是大小写敏感的，则会自动应用引用。

function sqlalchemy.sql.expression.desc(column: _ColumnExpressionOrStrLabelArgument[_T]) → UnaryExpression[_T]

产生一个降序的ORDER BY子句元素。

例如：

from sqlalchemy import desc
stmt = select(users_table).order_by(desc(users_table.c.name))

将生成 SQL 如下：

SELECT id, name FROM user ORDER BY name DESC

desc()函数是所有 SQL 表达式上可用的ColumnElement.desc()方法的独立版本，例如：

stmt = select(users_table).order_by(users_table.c.name.desc())

参数：

column – 一个ColumnElement（例如标量 SQL 表达式），用于应用desc()操作。

另请参阅

asc()

nulls_first()

nulls_last()

Select.order_by()

function sqlalchemy.sql.expression.funcfilter(func: FunctionElement[_T], *criterion: _ColumnExpressionArgument[bool]) → FunctionFilter[_T]

对函数产生一个FunctionFilter对象。

对支持“FILTER”子句的数据库后端使用于聚合和窗口函数。

例如：

from sqlalchemy import funcfilter
funcfilter(func.count(1), MyClass.name == 'some name')

会产生“COUNT(1) FILTER (WHERE myclass.name = ‘some name’)”。

此函数也可通过func构造本身通过FunctionElement.filter()方法使用。

另请参见

组内特殊修改器，过滤器 - 在 SQLAlchemy 统一教程中

FunctionElement.filter()

function sqlalchemy.sql.expression.label(name: str, element: _ColumnExpressionArgument[_T], type_: _TypeEngineArgument[_T] | None = None) → Label[_T]

为给定的ColumnElement返回一个Label对象。

标签通过AS SQL 关键字通常在SELECT语句的列子句中更改元素的名称。

通过ColumnElement.label()方法更方便地使用ColumnElement。

参数：

• name – 标签名称
  
• obj – 一个ColumnElement。
  

function sqlalchemy.sql.expression.nulls_first(column: _ColumnExpressionArgument[_T]) → UnaryExpression[_T]

为ORDER BY表达式生成NULLS FIRST修饰符。

nulls_first()旨在修改由asc()或desc()产生的表达式，并指示在排序过程中遇到 NULL 值时应如何处理：

from sqlalchemy import desc, nulls_first
stmt = select(users_table).order_by(
    nulls_first(desc(users_table.c.name)))

上面的 SQL 表达式类似于：

SELECT id, name FROM user ORDER BY name DESC NULLS FIRST

类似于asc()和desc()，nulls_first()通常是从列表达式本身使用ColumnElement.nulls_first()调用的，而不是作为其独立的函数版本，如下所示：

stmt = select(users_table).order_by(
    users_table.c.name.desc().nulls_first())

从版本 1.4 开始更改：nulls_first()从以前的版本中的nullsfirst()重命名。以前的名称仍然可用于向后兼容性。

另请参见

asc()

desc()

nulls_last()

Select.order_by()

function sqlalchemy.sql.expression.nullsfirst()

nulls_first() 函数的同义词。

2.0.5 版本更改：恢复了丢失的遗留符号 nullsfirst()。

function sqlalchemy.sql.expression.nulls_last(column: _ColumnExpressionArgument[_T]) → UnaryExpression[_T]

生成 ORDER BY 表达式的 NULLS LAST 修饰符。

nulls_last() 旨在修改由 asc() 或 desc() 生成的表达式，并指示在排序过程中遇到 NULL 值时应如何处理：

from sqlalchemy import desc, nulls_last
stmt = select(users_table).order_by(
    nulls_last(desc(users_table.c.name)))

上述 SQL 表达式将类似于：

SELECT id, name FROM user ORDER BY name DESC NULLS LAST

像 asc() 和 desc() 一样，nulls_last() 通常是通过列表达式本身使用 ColumnElement.nulls_last() 而不是作为其独立函数版本调用的，如下所示：

stmt = select(users_table).order_by(
    users_table.c.name.desc().nulls_last())

1.4 版本更改：nulls_last() 在之前的版本中被重命名为 nullslast()。 以前的名称仍然可用于向后兼容。

另请参阅

asc()

desc()

nulls_first()

Select.order_by()

function sqlalchemy.sql.expression.nullslast()

nulls_last() 函数的旧词语同义词。

2.0.5 版本更改：恢复了丢失的遗留符号 nullslast()。

function sqlalchemy.sql.expression.over(element: FunctionElement[_T], partition_by: _ByArgument | None = None, order_by: _ByArgument | None = None, range_: typing_Tuple[int | None, int | None] | None = None, rows: typing_Tuple[int | None, int | None] | None = None) → Over[_T]

对函数生成一个 Over 对象。

用于针对聚合或所谓的“窗口”函数，在支持窗口函数的数据库后端使用。

over()通常使用FunctionElement.over()方法调用，例如：

func.row_number().over(order_by=mytable.c.some_column)

会产生：

ROW_NUMBER() OVER(ORDER BY some_column)

还可以使用over.range_和over.rows参数进行范围设置。这两个互斥参数各自接受一个二元组，其中包含整数和 None 的组合：

func.row_number().over(
    order_by=my_table.c.some_column, range_=(None, 0))

上述将产生：

ROW_NUMBER() OVER(ORDER BY some_column
RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)

None的值表示“无限制”，零的值表示“当前行”，负/正整数表示“前面”和“后面”：

• RANGE BETWEEN 5 PRECEDING AND 10 FOLLOWING:

func.row_number().over(order_by='x', range_=(-5, 10))

• ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW:

func.row_number().over(order_by='x', rows=(None, 0))

• RANGE BETWEEN 2 PRECEDING AND UNBOUNDED FOLLOWING:

func.row_number().over(order_by='x', range_=(-2, None))

• RANGE BETWEEN 1 FOLLOWING AND 3 FOLLOWING:

func.row_number().over(order_by='x', range_=(1, 3))

参数：

• element – 一个FunctionElement、WithinGroup或其他兼容的构造。
  
• partition_by – 作为 OVER 构造的 PARTITION BY 子句使用的列元素或字符串，或这些列元素或字符串的列表。
  
• order_by – 作为 OVER 构造的 ORDER BY 子句使用的列元素或字符串，或这些列元素或字符串的列表。
  
• range_ – 窗口的可选范围子句。这是一个元组值，可以包含整数值或None，并将呈现为一个 RANGE BETWEEN PRECEDING / FOLLOWING 子句。
  
• rows – 窗口的可选行子句。这是一个元组值，可以包含整数值或 None，并将呈现为一个 ROWS BETWEEN PRECEDING / FOLLOWING 子句。
  

此函数也可以通过func构造本身使用FunctionElement.over()方法。

另见

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

func

within_group()

function sqlalchemy.sql.expression.within_group(element: FunctionElement[_T], *order_by: _ColumnExpressionArgument[Any]) → WithinGroup[_T]

产生一个WithinGroup对象与一个函数。

用于所谓的“有序集聚合”和“假设集聚合”函数，包括 percentile_cont、rank、dense_rank 等。

within_group() 通常使用 FunctionElement.within_group() 方法来调用，例如：

from sqlalchemy import within_group
stmt = select(
    department.c.id,
    func.percentile_cont(0.5).within_group(
        department.c.salary.desc()
    )
)

上述语句将产生类似于 SELECT department.id, percentile_cont(0.5) WITHIN GROUP (ORDER BY department.salary DESC) 的 SQL。

参数:

• element – 一个 FunctionElement 结构，通常由 func 生成。
  
• *order_by – 一个或多个列元素，将用作 WITHIN GROUP 构造的 ORDER BY 子句。
  

另请参阅

特殊修饰符 WITHIN GROUP, FILTER - 在 SQLAlchemy 统一教程 中

func

over()

SqlAlchemy 2.0 中文文档（三十四）（2）https://developer.aliyun.com/article/1562818