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

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

列元素基础构造函数

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

使用 Python & 运算符也可以获得 and_() 合取（注意，复合表达式需要用括号括起来，以便与 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"})

明确使用bindparam()在多次调用的情况下生成 UPDATE 或 DELETE 语句时也很常见，其中语句的 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 结构会生成一个 bindparam()，镜像了列名 name，这是由于我们传递给 Connection.execute() 方法的单个 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，则在执行时需要一个值。如果未传递，则默认为 True，如果没有传递 bindparam.value 或 bindparam.callable，则为 True。如果这些参数中的任何一个存在，则 bindparam.required 默认为 False。
  
• quote – 如果此参数名需要引号，并且当前不被认为是 SQLAlchemy 的保留字，则为 True；目前仅适用于 Oracle 后端，在那里绑定的名称有时必须用引号括起来。
  
• isoutparam – 如果为 True，则应该将该参数视为存储过程的“OUT”参数。这适用于支持 OUT 参数的后端，如 Oracle。
  
• 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'
                )
            )

上述语句将产生类似于：

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 表达式是布尔表达式，“值”是一个结果值，例如：

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_ – 如果case.whens中的所有表达式求值结果都为 false，则将是CASE构造中的可选 SQL 表达式的评估结果。如果省略，则大多数数据库将在“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)))

上述语句将生成类似于：

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_ – 一个TypeEngine类或实例，指示CAST应用的类型。
  

另请参阅

数据转换和类型强制转换

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。此外，最好使用 text() 构造来处理完整的 SQL 语句。

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.distinct() 上使用方法 Select。

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 构造。

这通常也可以通过 extract() 或 func.extract 从 func 命名空间中获取。

参数：

• 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 组件与特定值匹配的 ids。

类似地，也可以选择提取的组件：

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

生成一个作为 lambda 缓存的 SQL 语句。

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，其闭包变量的状态永远不会改变 lambda 返回的 SQL 结构。
  
• 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 对象，它将为此列提供结果集转换和其他表达式语义。如果留空，类型将是 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 子句中指定了文字字符串 SQL 片段时，使用 text() 结构：

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 参数可以作为 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对于无法转换的表达式返回 NULL，例如尝试将字符串"hi"转换为整数值。

例如：

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() 时，请注意不会应用括号。如果 type_coerce() 被用在一个操作符上下文中，通常来自 CAST 的括号是必要的，那么可以使用 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，则引用行为将根据标记本身的检查在每个后端基础上应用到标识符上。

具有quote=True的quoted_name对象也在所谓的“名称规范化”选项的情况下被阻止修改。某些数据库后端，如  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

字符串是否应该被无条件引用

列元素修饰符构造函数

此处列出的函数通常作为任何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()方法获得。

另请参阅

特殊修饰符 WITHIN GROUP, 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参数也可以实现范围。这些互斥参数每个都接受一个 2 元组，其中包含整数和 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 中文文档（三十四）（5）https://developer.aliyun.com/article/1562885