列元素和表达式

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

列元素基础构造函数

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

对象名称	描述
and_(*clauses)	生成由 AND 连接的表达式的合取。
bindparam(key[, value, type_, unique, ...])	生成一个“绑定表达式”。
bitwise_not(expr)	生成一个一元按位 NOT 子句，通常通过 ~ 运算符实现。
case(*whens, [value, else_])	生成一个 CASE 表达式。
cast(expression, type_)	生成一个 CAST 表达式。
column(text[, type_, is_literal, _selectable])	生成一个 ColumnClause 对象。
custom_op	表示一个“自定义”运算符。
distinct(expr)	生成一个列表达式级的 unary DISTINCT 子句。
extract(field, expr)	返回一个 Extract 构造。
false()	返回一个 False_ 构造。
func	生成 SQL 函数表达式。
lambda_stmt(lmb[, enable_tracking, track_closure_variables, track_on, ...])	生成一个作为 lambda 缓存的 SQL 语句。
literal(value[, type_, literal_execute])	返回一个绑定到绑定参数的文字子句。
literal_column(text[, type_])	生成一个 ColumnClause 对象，该对象将 column.is_literal 标志设置为 True。
not_(clause)	返回给定子句的否定，即 NOT(clause)。
null()	返回一个常量 Null 构造。
or_(*clauses)	生成由 OR 连接的表达式的连接。
outparam(key[, type_])	为支持它们的数据库创建用于函数（存储过程）的“OUT”参数。
quoted_name	表示与引用首选项相结合的 SQL 标识符。
text(text)	构造一个新的 TextClause 子句，直接表示文本 SQL 字符串。
true()	返回一个常量 True_ 构造。
try_cast(expression, type_)	为支持它的后端生成 TRY_CAST 表达式；这是一种 CAST，对于不可转换的转换返回 NULL。
tuple_(*clauses, [types])	返回一个 Tuple.
type_coerce(expression, type_)	将 SQL 表达式与特定类型关联，但不呈现 CAST。

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"})

显式使用 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 的 Core 表达式系统广泛地隐式使用了 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 语句时，bindparam() 会在“VALUES”部分被自动调用。 insert() 构造会生成一个 INSERT 表达式，该表达式将在语句执行时根据传递的参数生成绑定的占位符，例如

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

上面的语句将产生类似于以下的 SQL 输出

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

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

参数：

• key –

  此绑定参数的键（例如名称）。将用于为使用命名参数的方言生成的 SQL 语句。当作为编译操作的一部分时，此值可能会被修改，如果其他 BindParameter 对象具有相同的键，或者如果它的长度过长并且需要截断。

  如果省略，将为绑定参数生成一个“匿名”名称；当给定要绑定的值时，最终结果等效于使用要绑定的值调用 literal() 函数，特别是当 bindparam.unique 参数也提供时。

• value – 此绑定参数的初始值。如果语句执行方法没有为这个特定参数名称指示其他值，则将在语句执行时用作传递给 DBAPI 的此参数的值。默认为 None。

• callable_ – 代替“value”的可调用函数。该函数将在语句执行时被调用以确定最终值。用于在创建子句结构时无法确定实际绑定值的场景，但仍然需要嵌入绑定值。

• type_ –

  一个 TypeEngine 类或实例，表示此 bindparam() 的可选数据类型。如果未传递，则可能会根据给定值自动确定绑定的类型；例如，简单的 Python 类型，如 str、int、bool 可能会导致自动选择 String、Integer 或 Boolean 类型。

  bindparam() 的类型很重要，因为该类型将在将值传递给数据库之前对该值进行预处理。例如，一个引用日期时间值的 bindparam()，并被指定为持有 DateTime 类型，可能会在将值传递给数据库之前对该值进行必要的转换（例如在 SQLite 上进行字符串化）。

• unique – 如果为 True，如果另一个具有相同名称的 BindParameter 已经位于包含的表达式中，则将修改此 BindParameter 的键名称。此标志通常由内部机制在生成所谓的“匿名”绑定表达式时使用，它通常不适用于显式命名的 bindparam() 结构。

• required – 如果为 True，则在执行时需要一个值。如果没有传递，如果既没有传递 bindparam.value 也没有传递 bindparam.callable，则默认为 True。如果这两个参数中的任何一个存在，则 bindparam.required 默认为 False。

• quote – 如果此参数名需要引号，并且当前不被视为 SQLAlchemy 保留字；这目前仅适用于 Oracle 后端，在 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 中的新增内容： 添加了“post compile”绑定参数

  另请参阅

  用于 Oracle、SQL Server 中 LIMIT/OFFSET 的新“post compile”绑定参数.

另请参阅

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

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

生成一个一元按位 NOT 子句，通常通过 ~ 运算符实现。

不要与布尔否定 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 expression>, <value>) 组成，其中 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 中的所有表达式都计算为假，它将是 CASE 结构的计算结果。省略时，大多数数据库会在没有“when”表达式计算为真的情况下生成 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_ – 一个 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() 而不是，或者将 True 作为 column.is_literal 的值。 此外，最好使用 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() 结构可以以临时的方式创建，并且不像其 Table 对等体那样不与任何 MetaData、DDL 或事件关联。

参数：

• text – 元素的文本。

• type – TypeEngine 对象，可以将此 ColumnClause 与类型关联。

• is_literal – 如果为 True，则假定 ColumnClause 是一个精确表达式，无论大小写敏感设置如何，它都将传递到输出而不应用任何引用规则。 literal_column() 函数本质上是在传递 is_literal=True 的情况下调用 column()。

另请参阅

列

literal_column()

table()

text()

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

class sqlalchemy.sql.expression.custom_op

表示一个“自定义”运算符。

custom_op 通常在使用 Operators.op() 或 Operators.bool_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()

类签名

class sqlalchemy.sql.expression.custom_op (sqlalchemy.sql.expression.OperatorType, typing.Generic)

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

生成一个列表达式级的 unary 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() 方法 Select，它会生成一个 SELECT 语句，其中 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 –

  要提取的字段。

  警告

  此字段用作文字 SQL 字符串。 请勿将不可信的输入传递给此字符串。

• 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

不支持 true/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 返回的 SQL 结构的 lambda 使用。

• track_bound_values – 当为 False 时，将为给定 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 –

  可选的 bool，当为 True 时，SQL 引擎将尝试在执行时直接在 SQL 语句中呈现绑定值，而不是作为参数值提供。

  2.0 版中的新功能。

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

生成一个 ColumnClause 对象，该对象将 column.is_literal 标志设置为 True。

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 可以像普通函数参数一样使用。“输出”值将从 CursorResult 对象的 out_parameters 属性中获得，该属性返回一个包含值的字典。

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)

text() 结构用于在将文字字符串 SQL 片段指定为较大查询的一部分时（例如 SELECT 语句的 WHERE 子句），例如。

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 语句的文本。使用 :<param> 指定绑定参数；它们将编译成其特定于引擎的格式。

警告

传递给 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 表达式；这是一种 CAST，对于不可转换的转换返回 NULL。

在 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

New in version 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)]
)

Changed in version 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 语法，包括它不暗示括号。如果在 CAST 通常存在的括号在运算符上下文中必需的地方使用 type_coerce()，请使用 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 标志将阻止此转换发生，以支持针对此类后端的以全小写形式引用的标识符。

通常，在为关键模式结构（如 Table、Column 等）指定名称时，会自动创建 quoted_name 对象。该类也可以显式地作为名称传递给任何接收可以引用的名称的函数。例如，使用 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 后端运行“是否有表”逻辑，将名称完全作为 "some_table" 传递，而不会转换为大写。

更改于版本 1.2: 现在可以从 sqlalchemy.sql 导入 quoted_name 结构，除了之前位于 sqlalchemy.sql.elements 的位置。

成员

quote

类签名

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

attribute sqlalchemy.sql.expression.quoted_name.quote

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

列元素修饰符构造函数

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

对象名称	描述
all_(expr)	生成一个 ALL 表达式。
any_(expr)	生成一个 ANY 表达式。
asc(column)	生成一个升序的 ORDER BY 子句元素。
between(expr, lower_bound, upper_bound[, symmetric])	生成一个 BETWEEN 谓词子句。
collate(expression, collation)	返回子句 expression COLLATE collation。
desc(column)	生成一个降序的 ORDER BY 子句元素。
funcfilter(func, *criterion)	针对一个函数生成一个 FunctionFilter 对象。
label(name, element[, type_])	为给定的 ColumnElement 返回一个 Label 对象。
nulls_first(column)	为一个 ORDER BY 表达式生成 NULLS FIRST 修饰符。
nulls_last(column)	为一个 ORDER BY 表达式生成 NULLS LAST 修饰符。
nullsfirst	nulls_first() 函数的同义词。
nullslast	nulls_last() 函数的旧版同义词。
over(element[, partition_by, order_by, range_, ...])	针对一个函数生成一个 Over 对象。
within_group(element, *order_by)	针对一个函数生成一个 WithinGroup 对象。

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

使用 None 比较 NULL 可能有效

None == all_(mytable.c.somearray)

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

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

或者使用 None，请注意，这不会执行通常情况下将“IS”渲染为 NULL 的步骤

# 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，请注意，这不会执行通常情况下将“IS”渲染为 NULL 的步骤

# 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

The asc() 函数是 ColumnElement.asc() 方法的独立版本，该方法适用于所有 SQL 表达式，例如

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

The between() 函数是 ColumnElement.between() 方法的独立版本，该方法适用于所有 SQL 表达式，例如

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 – 一个列或 Python 标量表达式，作为 BETWEEN 表达式右侧的下限。

• upper_bound – 一个列或 Python 标量表达式，作为 BETWEEN 表达式右侧的上限。

• 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

如果排序规则是区分大小写的标识符（例如，包含大写字符），它也会被引用。

Changed in version 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

The desc() 函数是 ColumnElement.desc() 方法的独立版本，该方法适用于所有 SQL 表达式，例如

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 对象。

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

此功能可以通过 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()

列元素类文档

这里的类使用在 列元素基础构造函数 和 列元素修改器构造函数 中列出的构造函数生成。

对象名称	描述
BinaryExpression	表示一个 LEFT <operator> RIGHT 的表达式。
BindParameter	表示一个“绑定表达式”。
Case	表示一个 CASE 表达式。
Cast	表示一个 CAST 表达式。
ClauseList	描述一个由运算符分隔的子句列表。
ColumnClause	表示来自任何文本字符串的列表达式。
ColumnCollection	一个 ColumnElement 实例的集合，通常用于 FromClause 对象。
ColumnElement	表示一个适合在语句的“columns”子句、WHERE 子句等中使用的面向列的 SQL 表达式。
ColumnExpressionArgument	通用“列表达式”参数。
ColumnOperators	为 ColumnElement 表达式定义布尔值、比较和其他运算符。
Extract	表示一个 SQL EXTRACT 子句，extract(field FROM expr)。
False_	表示 SQL 语句中的 false 关键字，或等效项。
FunctionFilter	表示一个函数 FILTER 子句。
Label	表示一个列标签 (AS)。
Null	表示 SQL 语句中的 NULL 关键字。
Operators	比较和逻辑运算符的基础。
Over	表示一个 OVER 子句。
SQLColumnExpression	一个类型，可用于指示任何 SQL 列元素或充当其替代的对象。
TextClause	表示一个文字 SQL 文本片段。
True_	表示 SQL 语句中的 true 关键字，或等效项。
TryCast	表示一个 TRY_CAST 表达式。
Tuple	表示一个 SQL 元组。
TypeCoerce	表示一个 Python 端类型强制转换包装器。
UnaryExpression	定义一个“一元”表达式。
WithinGroup	表示一个 WITHIN GROUP (ORDER BY) 子句。
WrapsColumnExpression	混合类，将一个 ColumnElement 定义为一个包装器，对已有名稱的表达式具有特殊的标签行为。

class sqlalchemy.sql.expression.BinaryExpression

表示一个 LEFT <operator> RIGHT 的表达式。

一个 BinaryExpression 只要两个列表达式在 Python 二元表达式中使用就会自动生成

>>> from sqlalchemy.sql import column
>>> column('a') + column('b')
<sqlalchemy.sql.expression.BinaryExpression object at 0x101029dd0>
>>> print(column('a') + column('b'))
a + b

类签名

class sqlalchemy.sql.expression.BinaryExpression (sqlalchemy.sql.expression.OperatorExpression)

class sqlalchemy.sql.expression.BindParameter

表示一个“绑定表达式”。

BindParameter 使用 bindparam() 函数显式调用，如

from sqlalchemy import bindparam

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

有关 BindParameter 的详细讨论请参见 bindparam()。

另请参阅

bindparam()

成员

effective_value，inherit_cache，render_literal_execute()

类签名

class sqlalchemy.sql.expression.BindParameter (sqlalchemy.sql.roles.InElementRole, sqlalchemy.sql.expression.KeyedColumnElement)

attribute sqlalchemy.sql.expression.BindParameter.effective_value

返回此绑定参数的值，考虑是否设置了 callable 参数。

如果存在，将评估并返回 callable 值，否则返回 value。

attribute sqlalchemy.sql.expression.BindParameter.inherit_cache: bool | None = True

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

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

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

另请参阅

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

方法 sqlalchemy.sql.expression.BindParameter.render_literal_execute() → BindParameter[_T]

生成此绑定参数的副本，该副本将启用 BindParameter.literal_execute 标志。

BindParameter.literal_execute 标志将使参数在使用 [POSTCOMPILE] 形式的编译 SQL 字符串中呈现，这是一种特殊形式，在 SQL 执行时将转换为参数的文字值的呈现。基本原理是支持缓存可以在最终传递给 DBAPI 的 SQL 字符串中嵌入每条语句文字值的 SQL 语句字符串，例如 LIMIT 和 OFFSET 参数。特别是，方言可能希望在自定义编译方案中使用此方法。

版本 1.4.5 中新增。

另请参阅

第三方方言的缓存

类 sqlalchemy.sql.expression.Case

表示一个 CASE 表达式。

Case 是使用 case() 工厂函数生成的，例如

from sqlalchemy import case

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

Case 用法的详细信息在 case() 中。

另请参阅

case()

类签名

class sqlalchemy.sql.expression.Case (sqlalchemy.sql.expression.ColumnElement)

类 sqlalchemy.sql.expression.Cast

表示一个 CAST 表达式。

Cast 是使用 cast() 工厂函数生成的，例如

from sqlalchemy import cast, Numeric

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

Cast 用法的详细信息在 cast() 中。

另请参阅

数据转换和类型强制

cast()

try_cast()

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

类签名

class sqlalchemy.sql.expression.Cast (sqlalchemy.sql.expression.WrapsColumnExpression)

类 sqlalchemy.sql.expression.ClauseList

描述一个由运算符分隔的子句列表。

默认情况下，是逗号分隔的，例如列列表。

成员

self_group()

类签名

class sqlalchemy.sql.expression.ClauseList (sqlalchemy.sql.roles.InElementRole, sqlalchemy.sql.roles.OrderByRole, sqlalchemy.sql.roles.ColumnsClauseRole, sqlalchemy.sql.roles.DMLColumnRole, sqlalchemy.sql.expression.DQLDMLClauseElement)

方法 sqlalchemy.sql.expression.ClauseList.self_group(against: OperatorType | None = None) → Self | Grouping[Any]

对这个 ClauseElement 应用“分组”。

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

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

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

类 sqlalchemy.sql.expression.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

ColumnClause 是特定于模式的 Column 对象的直接父类。虽然 Column 类具有与 ColumnClause 相同的所有功能，但 ColumnClause 类本身可以在行为需求仅限于简单 SQL 表达式生成的情况下使用。该对象没有与 Column 相似的模式级别元数据或运行时行为关联，因此从某种意义上来说是 Column 的“轻量级”版本。

有关 ColumnClause 用法的完整细节请参见 column()。

另请参阅

column()

列

成员

get_children()

类签名

class sqlalchemy.sql.expression.ColumnClause (sqlalchemy.sql.roles.DDLReferredColumnRole, sqlalchemy.sql.roles.LabeledColumnExprRole, sqlalchemy.sql.roles.StrAsPlainColumnRole, sqlalchemy.sql.expression.Immutable, sqlalchemy.sql.expression.NamedColumn)

method sqlalchemy.sql.expression.ColumnClause.get_children(*, column_tables=False, **kw)

返回此 HasTraverseInternals 的直接子 HasTraverseInternals 元素。

这用于访问遍历。

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

class sqlalchemy.sql.expression.ColumnCollection

一个 ColumnElement 实例的集合，通常用于 FromClause 对象。

ColumnCollection 对象最常作为 Table.c 或 Table.columns 集合在 Table 对象上，在 访问表和列 中介绍。

ColumnCollection 同时具有映射和序列的行为。 ColumnCollection 通常存储 Column 对象，然后可以通过映射风格访问和属性访问风格来访问它们。

要使用普通属性风格访问来访问 Column 对象，请指定名称，就像任何其他对象属性一样，例如在名为 employee_name 的列下方访问

>>> employee_table.c.employee_name

要访问具有特殊字符或空格的名称的列，请使用索引风格访问，例如以下示例说明了如何访问名为 employee ' payment 的列

>>> employee_table.c["employee ' payment"]

由于 ColumnCollection 对象提供 Python 字典接口，因此可使用常见的字典方法名称，如 ColumnCollection.keys()、ColumnCollection.values() 和 ColumnCollection.items()，这意味着在这些名称下键入的数据库列也需要使用索引访问

>>> employee_table.c["values"]

Column 所在的名称通常是 Column.key 参数的名称。在某些上下文中，例如使用 Select.set_label_style() 方法使用标签样式设置的 Select 对象，具有特定键的列可能以特定标签名称（例如 tablename_columnname）表示

>>> from sqlalchemy import select, column, table
>>> from sqlalchemy import LABEL_STYLE_TABLENAME_PLUS_COL
>>> t = table("t", column("c"))
>>> stmt = select(t).set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
>>> subq = stmt.subquery()
>>> subq.c.t_c
<sqlalchemy.sql.elements.ColumnClause at 0x7f59dcf04fa0; t_c>

ColumnCollection 还按顺序索引列，并允许通过它们的整数位置访问它们

>>> cc[0]
Column('x', Integer(), table=None)
>>> cc[1]
Column('y', Integer(), table=None)

版本 1.4 中新增： ColumnCollection 允许对集合进行基于整数的索引访问。

迭代集合按顺序生成列表达式

>>> list(cc)
[Column('x', Integer(), table=None),
 Column('y', Integer(), table=None)]

基本 ColumnCollection 对象可以存储重复项，这意味着两个具有相同键的列，在这种情况下，通过键访问返回的列是 **任意的**

>>> x1, x2 = Column('x', Integer), Column('x', Integer)
>>> cc = ColumnCollection(columns=[(x1.name, x1), (x2.name, x2)])
>>> list(cc)
[Column('x', Integer(), table=None),
 Column('x', Integer(), table=None)]
>>> cc['x'] is x1
False
>>> cc['x'] is x2
True

或者它也可以意味着同一列多次出现。这些情况受到支持，因为 ColumnCollection 用于表示 SELECT 语句中的列，该语句可能包含重复项。

一个特殊的子类 DedupeColumnCollection 存在，它保留 SQLAlchemy 的旧行为，不允许重复；此集合用于模式级对象，如 Table 和 PrimaryKeyConstraint，在这些情况下，这种去重是有帮助的。 DedupeColumnCollection 类还具有额外的变异方法，因为模式结构具有更多需要移除和替换列的用例。

版本 1.4 中的变更： ColumnCollection 现在存储重复的列键以及同一个列的多个位置。 DedupeColumnCollection 类被添加以在那些需要去重以及额外的替换/移除操作的情况下保留以前的行為。

成员

add()、as_readonly()、clear()、compare()、contains_column()、corresponding_column()、get()、items()、keys()、update()、values()

类签名

类 sqlalchemy.sql.expression.ColumnCollection (typing.Generic)

方法 sqlalchemy.sql.expression.ColumnCollection.add(column: ColumnElement[Any], key: _COLKEY | None = None) → None

向此 ColumnCollection 添加一列。

注意

此方法通常不会被面向用户的代码使用，因为ColumnCollection 通常是现有对象的一部分，例如 Table。要将 Column 添加到现有的 Table 对象，请使用 Table.append_column() 方法。

方法 sqlalchemy.sql.expression.ColumnCollection.as_readonly() → ReadOnlyColumnCollection[_COLKEY, _COL_co]

返回此 ColumnCollection 的“只读”形式。

方法 sqlalchemy.sql.expression.ColumnCollection.clear() → NoReturn

字典 clear() 对于 ColumnCollection 未实现。

方法 sqlalchemy.sql.expression.ColumnCollection.compare(other: ColumnCollection[Any, Any]) → bool

根据键的名称比较此 ColumnCollection 与另一个。

方法 sqlalchemy.sql.expression.ColumnCollection.contains_column(col: ColumnElement[Any]) → bool

检查此集合中是否存在列对象。

方法 sqlalchemy.sql.expression.ColumnCollection.corresponding_column(column: _COL, require_embedded: bool = False) → _COL | _COL_co | None

给定一个 ColumnElement，从此 ColumnCollection 返回导出 ColumnElement 对象，该对象通过公共祖先列对应于该原始 ColumnElement。

参数：

• column – 要匹配的目标 ColumnElement。

• require_embedded – 仅返回给定 ColumnElement 的对应列，如果给定 ColumnElement 实际上存在于此 Selectable 的子元素中。通常，如果该列仅与此 Selectable 的一个导出列共享公共祖先，则该列将匹配。

另请参阅

Selectable.corresponding_column() - 对 Selectable.exported_columns 返回的集合调用此方法。

在版本 1.4 中更改: corresponding_column 的实现被移到了 ColumnCollection 本身。

方法 sqlalchemy.sql.expression.ColumnCollection.get(key: str, default: _COL | None = None) → _COL | _COL_co | None

从该 ColumnCollection 中根据字符串键名获取一个 ColumnClause 或 Column 对象。

method sqlalchemy.sql.expression.ColumnCollection.items() → List[Tuple[_COLKEY, _COL_co]]

返回该集合中所有列的 (键，列) 元组序列，每个元组包含一个字符串键名和一个 ColumnClause 或 Column 对象。

method sqlalchemy.sql.expression.ColumnCollection.keys() → List[_COLKEY]

返回该集合中所有列的字符串键名序列。

method sqlalchemy.sql.expression.ColumnCollection.update(iter_: Any) → NoReturn

字典 update() 方法对于 ColumnCollection 未实现。

method sqlalchemy.sql.expression.ColumnCollection.values() → List[_COL_co]

返回该集合中所有列的 ColumnClause 或 Column 对象序列。

class sqlalchemy.sql.expression.ColumnElement

表示一个适合在语句的“columns”子句、WHERE 子句等中使用的面向列的 SQL 表达式。

虽然最常见的 ColumnElement 是 Column 对象，但 ColumnElement 是任何可能出现在 SQL 表达式中的单元的基础，包括表达式本身、SQL 函数、绑定参数、文字表达式、如 NULL 这样的关键字等等。 ColumnElement 是所有这些元素的最终基类。

许多 SQLAlchemy Core 函数在 SQL 表达式级别工作，旨在接受 ColumnElement 实例作为参数。这些函数通常会记录它们接受“SQL 表达式”作为参数。在 SQLAlchemy 中，这意味着输入通常已经是 ColumnElement 对象，或者可以**强制转换**为 ColumnElement 对象的值。大多数（但并非全部）SQLAlchemy Core 函数在 SQL 表达式方面的强制转换规则如下。

• 文字 Python 值，例如字符串、整数或浮点数、布尔值、日期时间、Decimal 对象，或者几乎任何其他 Python 对象，将被强制转换为“文字绑定值”。这通常意味着会生成一个包含给定值的 bindparam()；生成的 BindParameter 对象是 ColumnElement 的实例。最终，Python 值将在执行时作为参数化参数发送到 DBAPI，以便在 execute() 或 executemany() 方法中使用，并应用 SQLAlchemy 类型特定的转换器（例如，任何关联的 TypeEngine 对象提供的转换器）到该值。

• 任何特殊对象值，通常是 ORM 级的构造，具有名为 __clause_element__() 的访问器。当将未知类型对象传递给希望将参数强制转换为 ColumnElement（有时还强制转换为 SelectBase 表达式）的函数时，Core 表达式系统会查找该方法。它在 ORM 中用于将 ORM 特定的对象（如映射的类和映射的属性）转换为 Core 表达式对象。

• Python None 值通常被解释为 NULL，在 SQLAlchemy Core 中会生成 null() 的实例。

ColumnElement 提供了使用 Python 表达式生成新的 ColumnElement 对象的能力。这意味着 Python 运算符（如 ==、!= 和 <）被重载以模拟 SQL 操作，并允许实例化由其他更基本的 ColumnElement 对象组成的进一步的 ColumnElement 实例。例如，两个 ColumnClause 对象可以使用加法运算符 + 相加，以生成一个 BinaryExpression。 ColumnClause 和 BinaryExpression 都是 ColumnElement 的子类。

>>> from sqlalchemy.sql import column
>>> column('a') + column('b')
<sqlalchemy.sql.expression.BinaryExpression object at 0x101029dd0>
>>> print(column('a') + column('b'))
a + b

另请参阅

列

column()

成员

__eq__()，__le__()，__lt__()，__ne__()，all_()，allows_lambda，anon_key_label，anon_label，any_()，asc()，base_columns，between()，bitwise_and()，bitwise_lshift()，bitwise_not()，bitwise_or()，bitwise_rshift()，bitwise_xor()，bool_op()，cast()，collate()，comparator，compare()，compile()，concat()，contains()，desc()，description，distinct()，endswith()，entity_namespace，expression，foreign_keys，get_children()，icontains()，iendswith()，ilike()，in_()，inherit_cache，is_()，is_clause_element，is_distinct_from()，is_dml，is_not()，is_not_distinct_from()，is_selectable，isnot()，isnot_distinct_from()，istartswith()，key，label()，like()，match()，negation_clause，not_ilike()，not_in()，not_like()，notilike()，notin_()，notlike()，nulls_first()，nulls_last()，nullsfirst()，nullslast()，op()，operate()，params()，primary_key，proxy_set，regexp_match()，regexp_replace()，reverse_operate()，self_group()，shares_lineage()，startswith()，stringify_dialect，supports_execution，timetuple，type，unique_params()，uses_inspection

类签名

class sqlalchemy.sql.expression.ColumnElement (sqlalchemy.sql.roles.ColumnArgumentOrKeyRole, sqlalchemy.sql.roles.StatementOptionRole, sqlalchemy.sql.roles.WhereHavingRole, sqlalchemy.sql.roles.BinaryElementRole, sqlalchemy.sql.roles.OrderByRole, sqlalchemy.sql.roles.ColumnsClauseRole, sqlalchemy.sql.roles.LimitOffsetRole, sqlalchemy.sql.roles.DMLColumnRole, sqlalchemy.sql.roles.DDLConstraintColumnRole, sqlalchemy.sql.roles.DDLExpressionRole, sqlalchemy.sql.expression.SQLColumnExpression, sqlalchemy.sql.expression.DQLDMLClauseElement)

method sqlalchemy.sql.expression.ColumnElement.__eq__(other: Any) → ColumnOperators

从 sqlalchemy.sql.expression.ColumnOperators.__eq__ 方法继承，该方法属于 ColumnOperators

实现 == 运算符。

在列上下文中，生成 a = b 子句。如果目标是 None，则生成 a IS NULL。

method sqlalchemy.sql.expression.ColumnElement.__le__(other: Any) → ColumnOperators

从 sqlalchemy.sql.expression.ColumnOperators.__le__ 方法继承，该方法属于 ColumnOperators

实现 <= 运算符。

在列上下文中，生成子句 a <= b。

method sqlalchemy.sql.expression.ColumnElement.__lt__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__lt__ 方法，属于 ColumnOperators

实现 < 运算符。

在列上下文中，生成子句 a < b。

method sqlalchemy.sql.expression.ColumnElement.__ne__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__ne__ 方法，属于 ColumnOperators

实现 != 运算符。

在列上下文中，生成子句 a != b。如果目标是 None，则生成 a IS NOT NULL。

method sqlalchemy.sql.expression.ColumnElement.all_() → ColumnOperators

继承自 ColumnOperators.all_() 方法，属于 ColumnOperators

针对父对象生成一个 all_() 子句。

有关示例，请参阅 all_() 的文档。

注意

确保不要将较新的 ColumnOperators.all_() 方法与该方法的旧版混淆，即专门用于 ARRAY 的 Comparator.all() 方法，它使用不同的调用方式。

attribute sqlalchemy.sql.expression.ColumnElement.allows_lambda = True

attribute sqlalchemy.sql.expression.ColumnElement.anon_key_label

自版本 1.4 起已弃用: ColumnElement.anon_key_label 属性现在是私有的，公开访问器已弃用。

attribute sqlalchemy.sql.expression.ColumnElement.anon_label

自版本 1.4 起已弃用: ColumnElement.anon_label 属性现在是私有的，公开访问器已弃用。

method sqlalchemy.sql.expression.ColumnElement.any_() → ColumnOperators

继承自 ColumnOperators.any_() 方法，属于 ColumnOperators

针对父对象生成一个 any_() 子句。

有关示例，请参阅 any_() 的文档。

注意

确保不要将较新的 ColumnOperators.any_() 方法与该方法的旧版混淆，即专门用于 ARRAY 的 Comparator.any() 方法，它使用不同的调用方式。

method sqlalchemy.sql.expression.ColumnElement.asc() → ColumnOperators

继承自 ColumnOperators.asc() 方法，属于 ColumnOperators

针对父对象生成一个 asc() 子句。

attribute sqlalchemy.sql.expression.ColumnElement.base_columns

method sqlalchemy.sql.expression.ColumnElement.between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators

继承自 ColumnOperators.between() 方法，属于 ColumnOperators

针对父对象生成一个 between() 子句，给定上下限范围。

method sqlalchemy.sql.expression.ColumnElement.bitwise_and(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_and() 方法 ColumnOperators

生成一个按位 AND 操作，通常通过 & 运算符。

版本 2.0.2 中的新增内容。

另请参阅

位运算符

method sqlalchemy.sql.expression.ColumnElement.bitwise_lshift(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_lshift() 方法 ColumnOperators

生成一个按位左移操作，通常通过 << 运算符。

版本 2.0.2 中的新增内容。

另请参阅

位运算符

method sqlalchemy.sql.expression.ColumnElement.bitwise_not() → ColumnOperators

继承自 ColumnOperators.bitwise_not() 方法 ColumnOperators

生成一个按位取反操作，通常通过 ~ 运算符。

版本 2.0.2 中的新增内容。

另请参阅

位运算符

method sqlalchemy.sql.expression.ColumnElement.bitwise_or(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_or() 方法 ColumnOperators

生成一个按位 OR 操作，通常通过 | 运算符。

版本 2.0.2 中的新增内容。

另请参阅

位运算符

method sqlalchemy.sql.expression.ColumnElement.bitwise_rshift(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_rshift() 方法 ColumnOperators

生成一个按位右移操作，通常通过 >> 运算符。

版本 2.0.2 中的新增内容。

另请参阅

位运算符

method sqlalchemy.sql.expression.ColumnElement.bitwise_xor(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_xor() 方法 ColumnOperators

生成一个按位异或操作，通常通过 ^ 运算符，或者 # 用于 PostgreSQL。

版本 2.0.2 中的新增内容。

另请参阅

位运算符

method sqlalchemy.sql.expression.ColumnElement.bool_op(opstring: str, precedence: int = 0, python_impl: Callable[[...], Any] | None = None) → Callable[[Any], Operators]

继承自 Operators.bool_op() 方法 Operators

返回一个自定义布尔运算符。

此方法是调用 Operators.op() 并传递 Operators.op.is_comparison 标记为 True 的简写。使用 Operators.bool_op() 的主要优势是，当使用列构造时，返回表达式的“布尔”性质将存在于 PEP 484 目的。

另请参阅

Operators.op()

method sqlalchemy.sql.expression.ColumnElement.cast(type_: _TypeEngineArgument[_OPT]) → Cast[_OPT]

生成一个类型转换，即 CAST(<expression> AS <type>)。

这是 cast() 函数的快捷方式。

另请参阅

数据转换和类型强制

cast()

type_coerce()

method sqlalchemy.sql.expression.ColumnElement.collate(collation: str) → ColumnOperators

继承自 ColumnOperators.collate() 方法的 ColumnOperators

使用给定的排序规则字符串，针对父对象生成 collate() 子句。

另请参阅

collate()

属性 sqlalchemy.sql.expression.ColumnElement.comparator

方法 sqlalchemy.sql.expression.ColumnElement.compare(other: ClauseElement, **kw: Any) → bool

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

将此 ClauseElement 与给定的 ClauseElement 进行比较。

子类应该覆盖默认行为，该行为是直接身份比较。

**kw 是子类 compare() 方法使用的参数，可用于修改比较标准（参见 ColumnElement）。

方法 sqlalchemy.sql.expression.ColumnElement.compile(bind: _HasDialect | None = None, dialect: Dialect | None = None, **kw: Any) → Compiled

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

编译此 SQL 表达式。

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

参数：

• bind – 一个 Connection 或 Engine，它可以提供一个 Dialect 以生成一个 Compiled 对象。如果 bind 和 dialect 参数都省略，则使用默认的 SQL 编译器。

• column_keys – 用于 INSERT 和 UPDATE 语句，一个包含应出现在已编译语句的 VALUES 子句中的列名称的列表。如果为 None，则呈现目标表对象中的所有列。

• dialect – 一个 Dialect 实例，它可以生成一个 Compiled 对象。此参数优先于 bind 参数。

• compile_kwargs –

  可选的字典，其中包含将通过所有“visit”方法传递给编译器的其他参数。这允许将任何自定义标志传递给自定义编译构造，例如。它也用于传递 literal_binds 标志的情况

  from sqlalchemy.sql import table, column, select
  
  t = table('t', column('x'))
  
  s = select(t).where(t.c.x == 5)
  
  print(s.compile(compile_kwargs={"literal_binds": True}))

另请参阅

如何将 SQL 表达式呈现为字符串，可能包含内联的绑定参数？

方法 sqlalchemy.sql.expression.ColumnElement.concat(other: Any) → ColumnOperators

继承自 ColumnOperators.concat() 方法的 ColumnOperators

实现“concat”运算符。

在列上下文中，生成子句 a || b，或在 MySQL 上使用 concat() 运算符。

方法 sqlalchemy.sql.expression.ColumnElement.contains(other: Any, **kw: Any) → ColumnOperators

继承自 ColumnOperators.contains() 方法的 ColumnOperators

实现“contains”运算符。

生成一个 LIKE 表达式，它测试字符串值的中间部分的匹配项

column LIKE '%' || <other> || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.contains("foobar"))

由于操作符使用 LIKE，因此在 <&other> 表达式中存在的通配符字符 "%" 和 "_" 也将表现为通配符。对于字面字符串值，ColumnOperators.contains.autoescape 标志可以设置为 True，以便对字符串值中这些字符的出现应用转义，使它们匹配自身，而不是作为通配符字符。或者，ColumnOperators.contains.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是字面字符串时非常有用。

参数：

• other – 要比较的表达式。这通常是一个普通字符串值，但也可以是任意 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.contains.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中 "%"、"_" 和转义字符本身的所有出现，假设该值是一个字面字符串，而不是 SQL 表达式。

  例如，表达式

  somecolumn.contains("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE '%' || :param || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时将使用 ESCAPE 关键字渲染，以建立该字符作为转义字符。然后，该字符可以放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符字符。

  例如，表达式

  somecolumn.contains("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE '%' || :param || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.contains.autoescape 组合使用

  somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的字面参数将在传递给数据库之前被转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.startswith()

ColumnOperators.endswith()

ColumnOperators.like()

method sqlalchemy.sql.expression.ColumnElement.desc() → ColumnOperators

从 ColumnOperators.desc() 方法继承 ColumnOperators

针对父对象生成 desc() 子句。

attribute sqlalchemy.sql.expression.ColumnElement.description

从 ClauseElement.description 属性继承 ClauseElement

method sqlalchemy.sql.expression.ColumnElement.distinct() → ColumnOperators

从 ColumnOperators.distinct() 方法继承 ColumnOperators

针对父对象生成 distinct() 子句。

method sqlalchemy.sql.expression.ColumnElement.endswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

从 ColumnOperators.endswith() 方法继承 ColumnOperators

实现 'endswith' 操作符。

生成一个 LIKE 表达式，用于测试字符串值结尾的匹配情况

column LIKE '%' || <other>

例如：

stmt = select(sometable).\
    where(sometable.c.column.endswith("foobar"))

由于操作符使用 LIKE，因此在 <&other> 表达式中存在的通配符字符 "%" 和 "_" 也将表现为通配符。对于字面字符串值，ColumnOperators.endswith.autoescape 标志可以设置为 True，以便对字符串值中这些字符的出现应用转义，使它们匹配自身，而不是作为通配符字符。或者，ColumnOperators.endswith.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是字面字符串时非常有用。

参数：

• other – 要比较的表达式。这通常是一个普通字符串值，但也可以是任意 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.endswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中 "%"、"_" 和转义字符本身的所有出现，假设该值是一个字面字符串，而不是 SQL 表达式。

  例如，表达式

  somecolumn.endswith("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE '%' || :param ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时将使用 ESCAPE 关键字渲染，以建立该字符作为转义字符。然后，该字符可以放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符字符。

  例如，表达式

  somecolumn.endswith("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE '%' || :param ESCAPE '^'

  该参数也可以与 ColumnOperators.endswith.autoescape 组合使用

  somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的字面参数将在传递给数据库之前被转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.startswith()

ColumnOperators.contains()

ColumnOperators.like()

attribute sqlalchemy.sql.expression.ColumnElement.entity_namespace

从 ClauseElement.entity_namespace 属性继承 ClauseElement

attribute sqlalchemy.sql.expression.ColumnElement.expression

返回一个列表达式。

检查接口的一部分；返回自身。

attribute sqlalchemy.sql.expression.ColumnElement.foreign_keys: AbstractSet[ForeignKey] = frozenset({})

方法 sqlalchemy.sql.expression.ColumnElement.get_children(*, omit_attrs: Tuple[str, ...] = (), **kw: Any) → Iterable[HasTraverseInternals]

继承自 HasTraverseInternals.get_children() 方法 HasTraverseInternals

返回此 HasTraverseInternals 的直接子 HasTraverseInternals 元素。

这用于访问遍历。

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

方法 sqlalchemy.sql.expression.ColumnElement.icontains(other: Any, **kw: Any) → ColumnOperators

继承自 ColumnOperators.icontains() 方法 ColumnOperators

实现 icontains 运算符，例如 ColumnOperators.contains() 的不区分大小写版本。

生成一个 LIKE 表达式，用于测试字符串值中间的不区分大小写匹配。

lower(column) LIKE '%' || lower(<other>) || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.icontains("foobar"))

由于运算符使用 LIKE，因此 <other> 表达式中存在的通配符 "%" 和 "_" 也将像通配符一样起作用。对于文字字符串值，ColumnOperators.icontains.autoescape 标志可以设置为 True 以对字符串值中这些字符的出现进行转义，以便它们以自身形式匹配，而不是作为通配符。或者，ColumnOperators.icontains.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是文字字符串时很有用。

参数：

• other – 要比较的表达式。这通常是一个普通的字符串值，但也可能是任意 SQL 表达式。LIKE 通配符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.icontains.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中 "%"、"_" 和转义字符本身的所有出现，假设该值是一个字面字符串，而不是 SQL 表达式。

  例如，表达式

  somecolumn.icontains("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时将使用 ESCAPE 关键字渲染，以建立该字符作为转义字符。然后，该字符可以放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符字符。

  例如，表达式

  somecolumn.icontains("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.contains.autoescape 组合使用

  somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的字面参数将在传递给数据库之前被转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.contains()

方法 sqlalchemy.sql.expression.ColumnElement.iendswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.iendswith() 方法 ColumnOperators

实现 iendswith 运算符，例如 ColumnOperators.endswith() 的不区分大小写版本。

生成一个 LIKE 表达式，用于测试字符串值末尾的不区分大小写匹配。

lower(column) LIKE '%' || lower(<other>)

例如：

stmt = select(sometable).\
    where(sometable.c.column.iendswith("foobar"))

由于运算符使用 LIKE，因此 <other> 表达式中存在的通配符 "%" 和 "_" 也将像通配符一样起作用。对于文字字符串值，ColumnOperators.iendswith.autoescape 标志可以设置为 True 以对字符串值中这些字符的出现进行转义，以便它们以自身形式匹配，而不是作为通配符。或者，ColumnOperators.iendswith.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是文字字符串时很有用。

参数：

• other – 要比较的表达式。这通常是一个普通的字符串值，但也可能是任意 SQL 表达式。LIKE 通配符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.iendswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中 "%"、"_" 和转义字符本身的所有出现，假设该值是一个字面字符串，而不是 SQL 表达式。

  例如，表达式

  somecolumn.iendswith("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时将使用 ESCAPE 关键字渲染，以建立该字符作为转义字符。然后，该字符可以放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符字符。

  例如，表达式

  somecolumn.iendswith("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'

  参数也可以与 ColumnOperators.iendswith.autoescape 组合使用

  somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的字面参数将在传递给数据库之前被转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.endswith()

方法 sqlalchemy.sql.expression.ColumnElement.ilike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.ilike() 方法 ColumnOperators

实现 ilike 运算符，例如不区分大小写的 LIKE。

在列上下文中，生成一个表达式，其形式为

lower(a) LIKE lower(other)

或者在支持 ILIKE 运算符的后端上

a ILIKE other

例如：

stmt = select(sometable).\
    where(sometable.c.column.ilike("%foobar%"))

参数：

• other – 要比较的表达式

• escape –

  可选的转义字符，渲染 ESCAPE 关键字，例如

  somecolumn.ilike("foo/%bar", escape="/")

另请参阅

ColumnOperators.like()

method sqlalchemy.sql.expression.ColumnElement.in_(other: Any) → ColumnOperators

继承自 ColumnOperators.in_() 方法 ColumnOperators

实现 in 运算符。

在列上下文中，生成子句 column IN <other>。

给定的参数 other 可以是

• 文字值的列表，例如

  stmt.where(column.in_([1, 2, 3]))

  在这种调用形式中，项目列表被转换为与给定列表长度相同的绑定参数集。

  WHERE COL IN (?, ?, ?)

• 如果比较是对包含多个表达式的 tuple_()，则可以提供元组列表。

  from sqlalchemy import tuple_
  stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))

• 空列表，例如

  stmt.where(column.in_([]))

  在这种调用形式中，表达式呈现“空集”表达式。这些表达式针对各个后端定制，通常试图获取一个空 SELECT 语句作为子查询。例如在 SQLite 上，表达式是

  WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

  在版本 1.4 中更改: 空 IN 表达式现在在所有情况下都使用运行时生成的 SELECT 子查询。

• 绑定参数，例如 bindparam()，如果它包含 bindparam.expanding 标志，则可以使用。

  stmt.where(column.in_(bindparam('value', expanding=True)))

  在这种调用形式中，表达式呈现一个特殊的非 SQL 占位符表达式，看起来像

  WHERE COL IN ([EXPANDING_value])

  此占位符表达式在语句执行时被拦截，转换为前面说明的可变数量绑定参数形式。如果语句被执行为

  connection.execute(stmt, {"value": [1, 2, 3]})

  数据库将为每个值传递一个绑定参数。

  WHERE COL IN (?, ?, ?)

  在版本 1.2 中添加: 添加了“扩展”绑定参数。

  如果传递空列表，将渲染一个特殊的“空列表”表达式，该表达式特定于使用的数据库。在 SQLite 上，这将是

  WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

  在版本 1.3 中添加: “扩展”绑定参数现在支持空列表。

• 一个 select() 结构，通常是相关标量选择

  stmt.where(
      column.in_(
          select(othertable.c.y).
          where(table.c.x == othertable.c.x)
      )
  )

  在这种调用形式中，ColumnOperators.in_() 按给定方式呈现。

  WHERE COL IN (SELECT othertable.y
  FROM othertable WHERE othertable.x = table.x)

参数：

other – 文字列表、select() 结构或包含 bindparam.expanding 标志设置为 True 的 bindparam() 结构。

attribute sqlalchemy.sql.expression.ColumnElement.inherit_cache: bool | None = None

继承自 HasCacheKey.inherit_cache 属性 HasCacheKey

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

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

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

另请参阅

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

method sqlalchemy.sql.expression.ColumnElement.is_(other: Any) → ColumnOperators

继承自 ColumnOperators.is_() 方法 ColumnOperators

实现 IS 运算符。

通常，IS 在与 None 的值进行比较时会自动生成，该值解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则显式使用 IS 可能需要。

另请参阅

ColumnOperators.is_not()

attribute sqlalchemy.sql.expression.ColumnElement.is_clause_element = True

method sqlalchemy.sql.expression.ColumnElement.is_distinct_from(other: Any) → ColumnOperators

继承自 ColumnOperators.is_distinct_from() 方法 ColumnOperators

实现 IS DISTINCT FROM 运算符。

在大多数平台上呈现“a IS DISTINCT FROM b”；在某些平台上（如 SQLite）可能呈现“a IS NOT b”。

attribute sqlalchemy.sql.expression.ColumnElement.is_dml = False

method sqlalchemy.sql.expression.ColumnElement.is_not(other: Any) → ColumnOperators

继承自 ColumnOperators.is_not() 方法 ColumnOperators

实现 IS NOT 运算符。

通常，IS NOT 在与 None 的值进行比较时会自动生成，该值解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则显式使用 IS NOT 可能需要。

版本 1.4 中的变更: 操作符 is_not() 在以前版本中更名为 isnot()。为了向后兼容，以前的名字仍然可以使用。

另请参阅

ColumnOperators.is_()

方法 sqlalchemy.sql.expression.ColumnElement.is_not_distinct_from(other: Any) → ColumnOperators

从以下继承 ColumnOperators.is_not_distinct_from() 方法 ColumnOperators

实现 IS NOT DISTINCT FROM 操作符。

在大多数平台上呈现“a IS NOT DISTINCT FROM b”；在 SQLite 等一些平台上可能呈现“a IS b”。

版本 1.4 中的变更: 操作符 is_not_distinct_from() 在以前版本中更名为 isnot_distinct_from()。为了向后兼容，以前的名字仍然可以使用。

属性 sqlalchemy.sql.expression.ColumnElement.is_selectable = False

方法 sqlalchemy.sql.expression.ColumnElement.isnot(other: Any) → ColumnOperators

从以下继承 ColumnOperators.isnot() 方法 ColumnOperators

实现 IS NOT 运算符。

通常，IS NOT 在与 None 的值进行比较时会自动生成，该值解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则显式使用 IS NOT 可能需要。

版本 1.4 中的变更: 操作符 is_not() 在以前版本中更名为 isnot()。为了向后兼容，以前的名字仍然可以使用。

另请参阅

ColumnOperators.is_()

方法 sqlalchemy.sql.expression.ColumnElement.isnot_distinct_from(other: Any) → ColumnOperators

从以下继承 ColumnOperators.isnot_distinct_from() 方法 ColumnOperators

实现 IS NOT DISTINCT FROM 操作符。

在大多数平台上呈现“a IS NOT DISTINCT FROM b”；在 SQLite 等一些平台上可能呈现“a IS b”。

版本 1.4 中的变更: 操作符 is_not_distinct_from() 在以前版本中更名为 isnot_distinct_from()。为了向后兼容，以前的名字仍然可以使用。

方法 sqlalchemy.sql.expression.ColumnElement.istartswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

从以下继承 ColumnOperators.istartswith() 方法 ColumnOperators

实现 istartswith 操作符，例如，ColumnOperators.startswith() 的不区分大小写的版本。

生成一个 LIKE 表达式，用于测试字符串值开头的非敏感匹配

lower(column) LIKE lower(<other>) || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.istartswith("foobar"))

由于该操作符使用 LIKE，因此 <other> 表达式中存在的通配符 "%" 和 "_" 也将像通配符一样工作。对于文字字符串值，ColumnOperators.istartswith.autoescape 标志可以设置为 True，将这些字符在字符串值中的出现进行转义，以便它们匹配自身而不是通配符。或者，ColumnOperators.istartswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是文字字符串时，这很有用。

参数：

• other – 要比较的表达式。这通常是一个普通字符串值，但也可以是任意 SQL 表达式。 LIKE 通配符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.istartswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中 "%"、"_" 和转义字符本身的所有出现，假设该值是一个字面字符串，而不是 SQL 表达式。

  例如，表达式

  somecolumn.istartswith("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时将使用 ESCAPE 关键字渲染，以建立该字符作为转义字符。然后，该字符可以放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符字符。

  例如，表达式

  somecolumn.istartswith("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.istartswith.autoescape 结合使用

  somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的字面参数将在传递给数据库之前被转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.startswith()

属性 sqlalchemy.sql.expression.ColumnElement.key: str | None = None

在某些情况下，引用 Python 命名空间中的此对象的“键”。

这通常指的是列在可选择对象的 .c 集合中的“键”，例如 sometable.c["somekey"] 将返回一个 Column，其 .key 为“somekey”。

method sqlalchemy.sql.expression.ColumnElement.label(name: str | None) → Label[_T]

生成一个列标签，例如 <columnname> AS <name>。

这是对 label() 函数的快捷方式。

如果 ‘name’ 为 None，则会生成一个匿名标签名称。

method sqlalchemy.sql.expression.ColumnElement.like(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.like() 方法的 ColumnOperators

实现 like 运算符。

在列上下文中，产生表达式

a LIKE other

例如：

stmt = select(sometable).\
    where(sometable.c.column.like("%foobar%"))

参数：

• other – 要比较的表达式

• escape –

  可选的转义字符，渲染 ESCAPE 关键字，例如

  somecolumn.like("foo/%bar", escape="/")

另请参阅

ColumnOperators.ilike()

method sqlalchemy.sql.expression.ColumnElement.match(other: Any, **kwargs: Any) → ColumnOperators

继承自 ColumnOperators.match() 方法的 ColumnOperators

实现数据库特有的 'match' 运算符。

ColumnOperators.match() 尝试解析为后端提供的 MATCH 类函数或运算符。例如：

• PostgreSQL - 呈现 x @@ plainto_tsquery(y)

  在版本 2.0 中更改： plainto_tsquery() 现在用作 PostgreSQL 的 to_tsquery() 的替代；有关其他形式的兼容性，请参阅 全文搜索.

• MySQL - 呈现 MATCH (x) AGAINST (y IN BOOLEAN MODE)

  另请参阅

  match - MySQL 特定结构，具有更多功能。

• Oracle - 呈现 CONTAINS(x, y)

• 其他后端可能提供特殊的实现。

• 没有特殊实现的后端会将运算符输出为 “MATCH”。例如，这与 SQLite 兼容。

attribute sqlalchemy.sql.expression.ColumnElement.negation_clause: ColumnElement[bool]

method sqlalchemy.sql.expression.ColumnElement.not_ilike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.not_ilike() 方法的 ColumnOperators

实现 NOT ILIKE 运算符。

这等效于使用否定运算符和 ColumnOperators.ilike()，即 ~x.ilike(y)。

在版本 1.4 中更改： not_ilike() 运算符在之前的版本中被重命名为 notilike()。为了向后兼容，之前的名称仍然可用。

另请参阅

ColumnOperators.ilike()

method sqlalchemy.sql.expression.ColumnElement.not_in(other: Any) → ColumnOperators

继承自 ColumnOperators.not_in() 方法的 ColumnOperators

实现 NOT IN 运算符。

这等效于使用否定运算符和 ColumnOperators.in_()，即 ~x.in_(y)。

如果 other 是一个空序列，编译器将产生一个 “空不在” 表达式。默认情况下，此表达式为 “1 = 1”，在所有情况下都产生真值。 create_engine.empty_in_strategy 可以用来改变这种行为。

在版本 1.4 中更改： not_in() 运算符在之前的版本中被重命名为 notin_()。为了向后兼容，之前的名称仍然可用。

版本 1.2 中变更: ColumnOperators.in_() 和 ColumnOperators.not_in() 运算符现在默认情况下会为一个空的 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

method sqlalchemy.sql.expression.ColumnElement.not_like(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.not_like() 方法 ColumnOperators

实现 NOT LIKE 运算符。

这等同于使用否定运算符与 ColumnOperators.like()，即 ~x.like(y)。

版本 1.4 中变更: not_like() 运算符从之前版本中的 notlike() 重命名。旧的名称仍然可用以确保向后兼容性。

另请参阅

ColumnOperators.like()

method sqlalchemy.sql.expression.ColumnElement.notilike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.notilike() 方法 ColumnOperators

实现 NOT ILIKE 运算符。

这等效于使用否定运算符和 ColumnOperators.ilike()，即 ~x.ilike(y)。

在版本 1.4 中更改： not_ilike() 运算符在之前的版本中被重命名为 notilike()。为了向后兼容，之前的名称仍然可用。

另请参阅

ColumnOperators.ilike()

method sqlalchemy.sql.expression.ColumnElement.notin_(other: Any) → ColumnOperators

继承自 ColumnOperators.notin_() 方法 ColumnOperators

实现 NOT IN 运算符。

这等效于使用否定运算符和 ColumnOperators.in_()，即 ~x.in_(y)。

如果 other 是一个空序列，编译器将产生一个 “空不在” 表达式。默认情况下，此表达式为 “1 = 1”，在所有情况下都产生真值。 create_engine.empty_in_strategy 可以用来改变这种行为。

在版本 1.4 中更改： not_in() 运算符在之前的版本中被重命名为 notin_()。为了向后兼容，之前的名称仍然可用。

版本 1.2 中变更: ColumnOperators.in_() 和 ColumnOperators.not_in() 运算符现在默认情况下会为一个空的 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

method sqlalchemy.sql.expression.ColumnElement.notlike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.notlike() 方法 ColumnOperators

实现 NOT LIKE 运算符。

这等同于使用否定运算符与 ColumnOperators.like()，即 ~x.like(y)。

版本 1.4 中变更: not_like() 运算符从之前版本中的 notlike() 重命名。旧的名称仍然可用以确保向后兼容性。

另请参阅

ColumnOperators.like()

method sqlalchemy.sql.expression.ColumnElement.nulls_first() → ColumnOperators

继承自 ColumnOperators.nulls_first() 方法 ColumnOperators

针对父对象生成一个 nulls_first() 子句。

版本 1.4 中变更: nulls_first() 运算符从之前版本中的 nullsfirst() 重命名。旧的名称仍然可用以确保向后兼容性。

method sqlalchemy.sql.expression.ColumnElement.nulls_last() → ColumnOperators

继承自 ColumnOperators.nulls_last() 方法 ColumnOperators

针对父对象生成一个 nulls_last() 子句。

版本 1.4 中变更: nulls_last() 运算符从之前版本中的 nullslast() 重命名。旧的名称仍然可用以确保向后兼容性。

method sqlalchemy.sql.expression.ColumnElement.nullsfirst() → ColumnOperators

继承自 ColumnOperators.nullsfirst() 方法 ColumnOperators

针对父对象生成一个 nulls_first() 子句。

版本 1.4 中变更: nulls_first() 运算符从之前版本中的 nullsfirst() 重命名。旧的名称仍然可用以确保向后兼容性。

方法 sqlalchemy.sql.expression.ColumnElement.nullslast() → ColumnOperators

继承自 ColumnOperators.nullslast() 方法 ColumnOperators

针对父对象生成一个 nulls_last() 子句。

版本 1.4 中变更: nulls_last() 运算符从之前版本中的 nullslast() 重命名。旧的名称仍然可用以确保向后兼容性。

方法 sqlalchemy.sql.expression.ColumnElement.op(opstring: str, precedence: int = 0, is_comparison: bool = False, return_type: Type[TypeEngine[Any]] | TypeEngine[Any] | None = None, python_impl: Callable[..., Any] | None = None) → Callable[[Any], Operators]

继承自 Operators.op() 方法 Operators

生成一个通用的操作符函数。

例如

somecolumn.op("*")(5)

生成

somecolumn * 5

此函数还可用于明确地创建位运算符。例如

somecolumn.op('&')(0xff)

是 somecolumn 中值的按位与。

参数：

• opstring – 一个字符串，它将作为此元素与传递给生成的函数的表达式之间的中缀运算符输出。

• precedence –

  数据库在 SQL 表达式中预计应用于该运算符的优先级。此整数值充当 SQL 编译器的一个提示，让它知道何时应在特定操作周围渲染显式括号。较小的数字将导致表达式在应用于另一个优先级较高的运算符时被加括号。默认值 0 低于除逗号 (,) 和 AS 运算符之外的所有运算符。值为 100 将高于或等于所有运算符，而 -100 将低于或等于所有运算符。

  另请参阅

  我正在使用 op() 生成自定义运算符，但我的括号显示不正确 - 有关 SQLAlchemy SQL 编译器如何渲染括号的详细说明

• is_comparison –

  旧版；如果为 True，则运算符将被视为“比较”运算符，即评估为布尔值 true/false 的运算符，如 ==、> 等。提供此标志是为了让 ORM 关系能够在使用自定义联接条件时确定运算符是比较运算符。

  使用 is_comparison 参数被使用 Operators.bool_op() 方法代替；此更简洁的运算符会自动设置此参数，但也提供正确的 PEP 484 类型支持，因为返回的对象将表示“布尔”数据类型，即 BinaryExpression[bool]。

• return_type – 一个 TypeEngine 类或对象，它将强制由此运算符生成的表达式的返回类型为该类型。默认情况下，指定了 Operators.op.is_comparison 的运算符将解析为 Boolean，而未指定的运算符将与左侧操作数类型相同。

• python_impl –

  一个可选的 Python 函数，它可以评估两个 Python 值，与在数据库服务器上运行时此运算符的工作方式相同。这对 Python 中的 SQL 表达式评估函数很有用，例如 ORM 混合属性和 ORM“评估器”，用于在多行更新或删除后匹配会话中的对象。

  例如

  >>> expr = column('x').op('+', python_impl=lambda a, b: a + b)('y')

  上述表达式的运算符也适用于非 SQL 左边和右边对象

  >>> expr.operator(5, 10)
  15

  2.0 版中的新功能。

另请参阅

Operators.bool_op()

重新定义和创建新运算符

在联接条件中使用自定义运算符

方法 sqlalchemy.sql.expression.ColumnElement.operate(op: OperatorType, *other: Any, **kwargs: Any) → ColumnElement[Any]

对一个参数进行操作。

这是最低级别的操作，默认情况下会引发 NotImplementedError。

在子类上覆盖它可以允许将通用行为应用于所有操作。例如，覆盖 ColumnOperators 以将 func.lower() 应用于左右两边

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 运算符可调用对象。

• *other – 操作的“另一方”。对于大多数操作，它将是一个标量值。

• **kwargs – 修饰符。这些可能由特殊运算符传递，例如 ColumnOperators.contains()。

方法 sqlalchemy.sql.expression.ColumnElement.params(_ClauseElement__optionaldict: Mapping[str, Any] | None = None, **kwargs: Any) → Self

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

返回一个用 bindparam() 元素替换后的副本。

返回此 ClauseElement 的副本，其中 bindparam() 元素被替换为从给定字典中获取的值。

>>> clause = column('x') + bindparam('foo')
>>> print(clause.compile().params)
{'foo':None}
>>> print(clause.params({'foo':7}).compile().params)
{'foo':7}

属性 sqlalchemy.sql.expression.ColumnElement.primary_key: bool = False

属性 sqlalchemy.sql.expression.ColumnElement.proxy_set: util.generic_fn_descriptor[FrozenSet[Any]]

我们代理的所有列的集合

从 2.0 版本开始，这明确地是取消注释的列。以前它实际上是取消注释的列，但没有强制执行。如果可能的话，注释列基本上不应该进入集合，因为它们的哈希行为非常低效。

方法 sqlalchemy.sql.expression.ColumnElement.regexp_match(pattern: Any, flags: str | None = None) → ColumnOperators

继承自 ColumnOperators.regexp_match() 方法的 ColumnOperators

实现特定于数据库的“正则表达式匹配”运算符。

例如：

stmt = select(table.c.some_column).where(
    table.c.some_column.regexp_match('^(b|c)')
)

ColumnOperators.regexp_match() 尝试解析为后端提供的类似 REGEXP 的函数或运算符，但是可用的特定正则表达式语法和标志是 **不是后端无关的**。

示例包括

• PostgreSQL - 渲染 x ~ y 或 x !~ y 当否定时。

• Oracle - 渲染 REGEXP_LIKE(x, y)

• SQLite - 使用 SQLite 的 REGEXP 占位符运算符，并调用 Python re.match() 内置函数。

• 其他后端可能提供特殊的实现。

• 没有特殊实现的后端将发出运算符为“REGEXP”或“NOT REGEXP”。例如，这与 SQLite 和 MySQL 兼容。

正则表达式支持目前已在 Oracle、PostgreSQL、MySQL 和 MariaDB 中实现。SQLite 提供部分支持。第三方方言之间的支持可能会有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。

• flags – 要应用的任何正则表达式字符串标志，以纯 Python 字符串形式传递。这些标志是特定于后端的。某些后端（如 PostgreSQL 和 MariaDB）可以选择将标志指定为模式的一部分。在 PostgreSQL 中使用忽略大小写标志“i”时，将使用忽略大小写正则表达式匹配运算符 ~* 或 !~*。

1.4 版中的新功能。

在版本 1.4.48 中更改,: 2.0.18 请注意，由于实现错误，以前“flags”参数除了纯 Python 字符串外，还接受 SQL 表达式对象，例如列表达式。此实现无法与缓存正确配合，因此已删除；对于“flags”参数，应仅传递字符串，因为这些标志在 SQL 表达式中以文字内联值的

另请参阅

ColumnOperators.regexp_replace()

方法 sqlalchemy.sql.expression.ColumnElement.regexp_replace(pattern: Any, replacement: Any, flags: str | None = None) → ColumnOperators

继承自 ColumnOperators.regexp_replace() 方法的 ColumnOperators

实现特定于数据库的“正则表达式替换”运算符。

例如：

stmt = select(
    table.c.some_column.regexp_replace(
        'b(..)',
        'X
Y',
        flags='g'
    )
)

ColumnOperators.regexp_replace() 尝试解析为后端提供的类似 REGEXP_REPLACE 的函数，该函数通常会发出函数 REGEXP_REPLACE()。但是，可用的特定正则表达式语法和标志是 **不是后端无关的**。

正则表达式替换支持目前已在 Oracle、PostgreSQL、MySQL 8 或更高版本以及 MariaDB 中实现。第三方方言之间的支持可能会有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。

• pattern – 替换字符串或列子句。

• flags – 要应用的任何正则表达式字符串标志，以纯 Python 字符串形式传递。这些标志是特定于后端的。某些后端（如 PostgreSQL 和 MariaDB）可以选择将标志指定为模式的一部分。

1.4 版中的新功能。

在版本 1.4.48 中更改,: 2.0.18 请注意，由于实现错误，以前“flags”参数除了纯 Python 字符串外，还接受 SQL 表达式对象，例如列表达式。此实现无法与缓存正确配合，因此已删除；对于“flags”参数，应仅传递字符串，因为这些标志在 SQL 表达式中以文字内联值的

另请参阅

ColumnOperators.regexp_match()

方法 sqlalchemy.sql.expression.ColumnElement.reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → ColumnElement[Any]

对参数进行反向操作。

使用方法与 operate() 相同。

方法 sqlalchemy.sql.expression.ColumnElement.self_group(against: OperatorType | None = None) → ColumnElement[Any]

对这个 ClauseElement 应用“分组”。

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

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

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

方法 sqlalchemy.sql.expression.ColumnElement.shares_lineage(othercolumn: ColumnElement[Any]) → bool

如果给定的 ColumnElement 与该 ColumnElement 具有共同的祖先，则返回 True。

方法 sqlalchemy.sql.expression.ColumnElement.startswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

从 ColumnOperators.startswith() 方法继承 ColumnOperators

实现 startswith 运算符。

生成一个 LIKE 表达式，它测试与字符串值开头的匹配。

column LIKE <other> || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.startswith("foobar"))

由于该运算符使用 LIKE，因此在 <other> 表达式中出现的通配符字符 "%" 和 "_" 也将像通配符一样工作。对于文字字符串值，ColumnOperators.startswith.autoescape 标志可以设置为 True，以对字符串值内的这些字符的出现进行转义，以便它们本身匹配，而不是作为通配符字符。或者，ColumnOperators.startswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是文字字符串时，这将很有用。

参数：

• other – 要比较的表达式。这通常是一个普通的字符串值，但也可以是任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.startswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中 "%"、"_" 和转义字符本身的所有出现，假设该值是一个字面字符串，而不是 SQL 表达式。

  例如，表达式

  somecolumn.startswith("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE :param || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时将使用 ESCAPE 关键字渲染，以建立该字符作为转义字符。然后，该字符可以放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符字符。

  例如，表达式

  somecolumn.startswith("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE :param || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.startswith.autoescape 组合使用

  somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的字面参数将在传递给数据库之前被转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.endswith()

ColumnOperators.contains()

ColumnOperators.like()

属性 sqlalchemy.sql.expression.ColumnElement.stringify_dialect = 'default'

属性 sqlalchemy.sql.expression.ColumnElement.supports_execution = False

属性 sqlalchemy.sql.expression.ColumnElement.timetuple: Literal[None] = None

从 ColumnOperators.timetuple 属性继承 ColumnOperators

Hack，允许 datetime 对象在 LHS 上进行比较。

属性 sqlalchemy.sql.expression.ColumnElement.type: TypeEngine[_T]

方法 sqlalchemy.sql.expression.ColumnElement.unique_params(_ClauseElement__optionaldict: Dict[str, Any] | None = None, **kwargs: Any) → Self

从 ClauseElement.unique_params() 方法继承 ClauseElement

返回一个用 bindparam() 元素替换后的副本。

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

属性 sqlalchemy.sql.expression.ColumnElement.uses_inspection = True

sqlalchemy.sql.expression.ColumnExpressionArgument

通用“列表达式”参数。

新版本 2.0.13。

此类型用于通常代表单个 SQL 列表达式的“列”类型的表达式，包括 ColumnElement，以及将具有 __clause_element__() 方法的 ORM 映射属性。

class sqlalchemy.sql.expression.ColumnOperators

为 ColumnElement 表达式定义布尔值、比较和其他运算符。

默认情况下，所有方法都会调用 operate() 或 reverse_operate()，并将 Python 内置 operator 模块中的相应操作符函数或 sqlalchemy.expression.operators 中的 SQLAlchemy 特定操作符函数传递进去。例如，__eq__ 函数

def __eq__(self, other):
    return self.operate(operators.eq, other)

其中 operators.eq 本质上是

def eq(a, b):
    return a == b

核心列表达式单元 ColumnElement 覆盖了 Operators.operate() 等方法，以返回更多 ColumnElement 结构，因此上面的 == 操作被替换为子句结构。

另请参阅

重新定义和创建新运算符

TypeEngine.comparator_factory

ColumnOperators

PropComparator

成员

__add__(), __and__(), __eq__(), __floordiv__(), __ge__(), __getitem__(), __gt__(), __hash__(), __invert__(), __le__(), __lshift__(), __lt__(), __mod__(), __mul__(), __ne__(), __neg__(), __or__(), __radd__(), __rfloordiv__(), __rmod__(), __rmul__(), __rshift__(), __rsub__(), __rtruediv__(), __sa_operate__(), __sub__(), __truediv__(), all_(), any_(), asc(), between(), bitwise_and(), bitwise_lshift(), bitwise_not(), bitwise_or(), bitwise_rshift(), bitwise_xor(), bool_op(), collate(), concat(), contains(), desc(), distinct(), endswith(), icontains(), iendswith(), ilike(), in_(), is_(), is_distinct_from(), is_not(), is_not_distinct_from(), isnot(), isnot_distinct_from(), istartswith(), like(), match(), not_ilike(), not_in(), not_like(), notilike(), notin_(), notlike(), nulls_first(), nulls_last(), nullsfirst(), nullslast(), op(), operate(), regexp_match(), regexp_replace(), reverse_operate(), startswith(), timetuple

类签名

class sqlalchemy.sql.expression.ColumnOperators (sqlalchemy.sql.expression.Operators)

method sqlalchemy.sql.expression.ColumnOperators.__add__(other: Any) → ColumnOperators

实现 + 操作符。

在列上下文中，如果父对象没有字符串亲和性，则生成子句 a + b。如果父对象具有字符串亲和性，则生成连接操作符 a || b - 请参见 ColumnOperators.concat()。

method sqlalchemy.sql.expression.ColumnOperators.__and__(other: Any) → Operators

继承自 sqlalchemy.sql.expression.Operators.__and__ 方法 Operators

实现 & 操作符。

在与 SQL 表达式一起使用时，会导致 AND 操作，等效于 and_()，即

a & b

等效于

from sqlalchemy import and_
and_(a, b)

在使用 & 时，应注意运算符优先级；& 运算符具有最高优先级。如果操作数包含进一步的子表达式，则应将它们括在括号中。

(a == 2) & (b == 4)

method sqlalchemy.sql.expression.ColumnOperators.__eq__(other: Any) → ColumnOperators

实现 == 运算符。

在列上下文中，生成 a = b 子句。如果目标是 None，则生成 a IS NULL。

method sqlalchemy.sql.expression.ColumnOperators.__floordiv__(other: Any) → ColumnOperators

实现 // 运算符。

在列上下文中，生成子句 a / b，它与“truediv”相同，但将结果类型视为整数。

2.0 版中的新功能。

method sqlalchemy.sql.expression.ColumnOperators.__ge__(other: Any) → ColumnOperators

实现 >= 运算符。

在列上下文中，生成子句 a >= b。

method sqlalchemy.sql.expression.ColumnOperators.__getitem__(index: Any) → ColumnOperators

实现 [] 运算符。

这可以被一些数据库特定的类型使用，例如 PostgreSQL ARRAY 和 HSTORE。

method sqlalchemy.sql.expression.ColumnOperators.__gt__(other: Any) → ColumnOperators

实现 > 运算符。

在列上下文中，生成子句 a > b。

method sqlalchemy.sql.expression.ColumnOperators.__hash__()

返回 hash(self)。

method sqlalchemy.sql.expression.ColumnOperators.__invert__() → Operators

继承自 sqlalchemy.sql.expression.Operators.__invert__ 方法 Operators

实现 ~ 运算符。

在与 SQL 表达式一起使用时，会导致 NOT 操作，等效于 not_()，即

~a

等效于

from sqlalchemy import not_
not_(a)

method sqlalchemy.sql.expression.ColumnOperators.__le__(other: Any) → ColumnOperators

实现 <= 运算符。

在列上下文中，生成子句 a <= b。

method sqlalchemy.sql.expression.ColumnOperators.__lshift__(other: Any) → ColumnOperators

实现 << 运算符。

SQLAlchemy 核心未使用，这是为希望使用 << 作为扩展点的自定义运算符系统提供的。

method sqlalchemy.sql.expression.ColumnOperators.__lt__(other: Any) → ColumnOperators

实现 < 运算符。

在列上下文中，生成子句 a < b。

method sqlalchemy.sql.expression.ColumnOperators.__mod__(other: Any) → ColumnOperators

实现 % 运算符。

在列上下文中，生成子句 a % b。

method sqlalchemy.sql.expression.ColumnOperators.__mul__(other: Any) → ColumnOperators

实现 * 运算符。

在列上下文中，生成子句 a * b。

method sqlalchemy.sql.expression.ColumnOperators.__ne__(other: Any) → ColumnOperators

实现 != 运算符。

在列上下文中，生成子句 a != b。如果目标是 None，则生成 a IS NOT NULL。

method sqlalchemy.sql.expression.ColumnOperators.__neg__() → ColumnOperators

实现 - 运算符。

在列上下文中，生成子句 -a。

method sqlalchemy.sql.expression.ColumnOperators.__or__(other: Any) → Operators

继承自 sqlalchemy.sql.expression.Operators.__or__ 方法的 Operators

实现 | 运算符。

当与 SQL 表达式一起使用时，会产生一个 OR 操作，等效于 or_()，即

a | b

等效于

from sqlalchemy import or_
or_(a, b)

在使用 | 时应注意运算符优先级；| 运算符具有最高优先级。如果操作数包含进一步的子表达式，则应将其括在括号中。

(a == 2) | (b == 4)

method sqlalchemy.sql.expression.ColumnOperators.__radd__(other: Any) → ColumnOperators

反向实现 + 运算符。

参见 ColumnOperators.__add__().

method sqlalchemy.sql.expression.ColumnOperators.__rfloordiv__(other: Any) → ColumnOperators

反向实现 // 运算符。

参见 ColumnOperators.__floordiv__().

method sqlalchemy.sql.expression.ColumnOperators.__rmod__(other: Any) → ColumnOperators

反向实现 % 运算符。

参见 ColumnOperators.__mod__().

method sqlalchemy.sql.expression.ColumnOperators.__rmul__(other: Any) → ColumnOperators

反向实现 * 运算符。

参见 ColumnOperators.__mul__().

method sqlalchemy.sql.expression.ColumnOperators.__rshift__(other: Any) → ColumnOperators

实现 >> 运算符。

SQLAlchemy 核心不使用它，它用于想要将 >> 用作扩展点的自定义运算符系统。

method sqlalchemy.sql.expression.ColumnOperators.__rsub__(other: Any) → ColumnOperators

反向实现 - 运算符。

参见 ColumnOperators.__sub__().

method sqlalchemy.sql.expression.ColumnOperators.__rtruediv__(other: Any) → ColumnOperators

反向实现 / 运算符。

参见 ColumnOperators.__truediv__().

method sqlalchemy.sql.expression.ColumnOperators.__sa_operate__(op: OperatorType, *other: Any, **kwargs: Any) → Operators

继承自 sqlalchemy.sql.expression.Operators.__sa_operate__ 方法的 Operators

对一个参数进行操作。

这是最低级别的操作，默认情况下会引发 NotImplementedError。

在子类上覆盖它可以允许将通用行为应用于所有操作。例如，覆盖 ColumnOperators 以将 func.lower() 应用于左右两边

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 运算符可调用对象。

• *other – 操作的“另一边”。对于大多数操作来说，它将是一个标量。

• **kwargs – 修饰符。这些可能由特殊运算符传递，例如 ColumnOperators.contains().

method sqlalchemy.sql.expression.ColumnOperators.__sub__(other: Any) → ColumnOperators

实现 - 运算符。

在列上下文中，产生子句 a - b。

method sqlalchemy.sql.expression.ColumnOperators.__truediv__(other: Any) → ColumnOperators

实现 / 运算符。

在列上下文中，产生子句 a / b，并将结果类型视为数字。

在版本 2.0 中更改: 两个整数之间的 truediv 运算符现在被认为返回一个数值。特定后端上的行为可能有所不同。

method sqlalchemy.sql.expression.ColumnOperators.all_() → ColumnOperators

针对父对象生成一个 all_() 子句。

有关示例，请参阅 all_() 的文档。

注意

确保不要将较新的 ColumnOperators.all_() 方法与该方法的旧版混淆，即专门用于 ARRAY 的 Comparator.all() 方法，它使用不同的调用方式。

方法 sqlalchemy.sql.expression.ColumnOperators.any_() → ColumnOperators

针对父对象生成一个 any_() 子句。

有关示例，请参阅 any_() 的文档。

注意

确保不要将较新的 ColumnOperators.any_() 方法与该方法的旧版混淆，即专门用于 ARRAY 的 Comparator.any() 方法，它使用不同的调用方式。

方法 sqlalchemy.sql.expression.ColumnOperators.asc() → ColumnOperators

针对父对象生成一个 asc() 子句。

方法 sqlalchemy.sql.expression.ColumnOperators.between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators

针对父对象生成一个 between() 子句，给定上下限范围。

方法 sqlalchemy.sql.expression.ColumnOperators.bitwise_and(other: Any) → ColumnOperators

生成一个按位 AND 操作，通常通过 & 运算符。

版本 2.0.2 中的新增内容。

另请参阅

位运算符

方法 sqlalchemy.sql.expression.ColumnOperators.bitwise_lshift(other: Any) → ColumnOperators

生成一个按位左移操作，通常通过 << 运算符。

版本 2.0.2 中的新增内容。

另请参阅

位运算符

方法 sqlalchemy.sql.expression.ColumnOperators.bitwise_not() → ColumnOperators

生成一个按位取反操作，通常通过 ~ 运算符。

版本 2.0.2 中的新增内容。

另请参阅

位运算符

方法 sqlalchemy.sql.expression.ColumnOperators.bitwise_or(other: Any) → ColumnOperators

生成一个按位 OR 操作，通常通过 | 运算符。

版本 2.0.2 中的新增内容。

另请参阅

位运算符

方法 sqlalchemy.sql.expression.ColumnOperators.bitwise_rshift(other: Any) → ColumnOperators

生成一个按位右移操作，通常通过 >> 运算符。

版本 2.0.2 中的新增内容。

另请参阅

位运算符

方法 sqlalchemy.sql.expression.ColumnOperators.bitwise_xor(other: Any) → ColumnOperators

生成一个按位异或操作，通常通过 ^ 运算符，或者 # 用于 PostgreSQL。

版本 2.0.2 中的新增内容。

另请参阅

位运算符

方法 sqlalchemy.sql.expression.ColumnOperators.bool_op(opstring: str, precedence: int = 0, python_impl: Callable[[...], Any] | None = None) → Callable[[Any], Operators]

继承自 Operators.bool_op() 方法 Operators

返回一个自定义布尔运算符。

此方法是调用 Operators.op() 并将 Operators.op.is_comparison 标记设置为 True 的简写。使用 Operators.bool_op() 的主要优点是，在使用列构造时，返回表达式的“布尔”性质将可用于 PEP 484 目的。

另请参阅

Operators.op()

方法 sqlalchemy.sql.expression.ColumnOperators.collate(collation: str) → ColumnOperators

使用给定的排序规则字符串，针对父对象生成 collate() 子句。

另请参阅

collate()

方法 sqlalchemy.sql.expression.ColumnOperators.concat(other: Any) → ColumnOperators

实现“concat”运算符。

在列上下文中，生成子句 a || b，或在 MySQL 上使用 concat() 运算符。

方法 sqlalchemy.sql.expression.ColumnOperators.contains(other: Any, **kw: Any) → ColumnOperators

实现“contains”运算符。

生成一个 LIKE 表达式，它测试字符串值的中间部分的匹配项

column LIKE '%' || <other> || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.contains("foobar"))

由于操作符使用 LIKE，因此在 <&other> 表达式中存在的通配符字符 "%" 和 "_" 也将表现为通配符。对于字面字符串值，ColumnOperators.contains.autoescape 标志可以设置为 True，以便对字符串值中这些字符的出现应用转义，使它们匹配自身，而不是作为通配符字符。或者，ColumnOperators.contains.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是字面字符串时非常有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.contains.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中 "%"、"_" 和转义字符本身的所有出现，假设该值是一个字面字符串，而不是 SQL 表达式。

  例如，表达式

  somecolumn.contains("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE '%' || :param || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时将使用 ESCAPE 关键字渲染，以建立该字符作为转义字符。然后，该字符可以放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符字符。

  例如，表达式

  somecolumn.contains("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE '%' || :param || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.contains.autoescape 组合使用

  somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的字面参数将在传递给数据库之前被转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.startswith()

ColumnOperators.endswith()

ColumnOperators.like()

method sqlalchemy.sql.expression.ColumnOperators.desc() → ColumnOperators

针对父对象生成 desc() 子句。

method sqlalchemy.sql.expression.ColumnOperators.distinct() → ColumnOperators

针对父对象生成 distinct() 子句。

method sqlalchemy.sql.expression.ColumnOperators.endswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

实现 'endswith' 操作符。

生成一个 LIKE 表达式，用于测试字符串值结尾的匹配情况

column LIKE '%' || <other>

例如：

stmt = select(sometable).\
    where(sometable.c.column.endswith("foobar"))

由于操作符使用 LIKE，因此在 <&other> 表达式中存在的通配符字符 "%" 和 "_" 也将表现为通配符。对于字面字符串值，ColumnOperators.endswith.autoescape 标志可以设置为 True，以便对字符串值中这些字符的出现应用转义，使它们匹配自身，而不是作为通配符字符。或者，ColumnOperators.endswith.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是字面字符串时非常有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.endswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中 "%"、"_" 和转义字符本身的所有出现，假设该值是一个字面字符串，而不是 SQL 表达式。

  例如，表达式

  somecolumn.endswith("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE '%' || :param ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时将使用 ESCAPE 关键字渲染，以建立该字符作为转义字符。然后，该字符可以放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符字符。

  例如，表达式

  somecolumn.endswith("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE '%' || :param ESCAPE '^'

  该参数也可以与 ColumnOperators.endswith.autoescape 组合使用

  somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的字面参数将在传递给数据库之前被转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.startswith()

ColumnOperators.contains()

ColumnOperators.like()

method sqlalchemy.sql.expression.ColumnOperators.icontains(other: Any, **kw: Any) → ColumnOperators

实现 icontains 运算符，例如 ColumnOperators.contains() 的不区分大小写版本。

生成一个 LIKE 表达式，用于测试字符串值中间的不区分大小写匹配。

lower(column) LIKE '%' || lower(<other>) || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.icontains("foobar"))

由于运算符使用 LIKE，因此 <other> 表达式中存在的通配符 "%" 和 "_" 也将像通配符一样起作用。对于文字字符串值，ColumnOperators.icontains.autoescape 标志可以设置为 True 以对字符串值中这些字符的出现进行转义，以便它们以自身形式匹配，而不是作为通配符。或者，ColumnOperators.icontains.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是文字字符串时很有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.icontains.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中 "%"、"_" 和转义字符本身的所有出现，假设该值是一个字面字符串，而不是 SQL 表达式。

  例如，表达式

  somecolumn.icontains("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时将使用 ESCAPE 关键字渲染，以建立该字符作为转义字符。然后，该字符可以放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符字符。

  例如，表达式

  somecolumn.icontains("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.contains.autoescape 组合使用

  somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的字面参数将在传递给数据库之前被转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.contains()

method sqlalchemy.sql.expression.ColumnOperators.iendswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

实现 iendswith 运算符，例如 ColumnOperators.endswith() 的不区分大小写版本。

生成一个 LIKE 表达式，用于测试字符串值末尾的不区分大小写匹配。

lower(column) LIKE '%' || lower(<other>)

例如：

stmt = select(sometable).\
    where(sometable.c.column.iendswith("foobar"))

由于运算符使用 LIKE，因此 <other> 表达式中存在的通配符 "%" 和 "_" 也将像通配符一样起作用。对于文字字符串值，ColumnOperators.iendswith.autoescape 标志可以设置为 True 以对字符串值中这些字符的出现进行转义，以便它们以自身形式匹配，而不是作为通配符。或者，ColumnOperators.iendswith.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是文字字符串时很有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.iendswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中 "%"、"_" 和转义字符本身的所有出现，假设该值是一个字面字符串，而不是 SQL 表达式。

  例如，表达式

  somecolumn.iendswith("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时将使用 ESCAPE 关键字渲染，以建立该字符作为转义字符。然后，该字符可以放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符字符。

  例如，表达式

  somecolumn.iendswith("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'

  参数也可以与 ColumnOperators.iendswith.autoescape 组合使用

  somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的字面参数将在传递给数据库之前被转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.endswith()

method sqlalchemy.sql.expression.ColumnOperators.ilike(other: Any, escape: str | None = None) → ColumnOperators

实现 ilike 运算符，例如不区分大小写的 LIKE。

在列上下文中，生成一个表达式，其形式为

lower(a) LIKE lower(other)

或者在支持 ILIKE 运算符的后端上

a ILIKE other

例如：

stmt = select(sometable).\
    where(sometable.c.column.ilike("%foobar%"))

参数：

• other – 要比较的表达式

• escape –

  可选的转义字符，渲染 ESCAPE 关键字，例如

  somecolumn.ilike("foo/%bar", escape="/")

另请参阅

ColumnOperators.like()

method sqlalchemy.sql.expression.ColumnOperators.in_(other: Any) → ColumnOperators

实现 in 运算符。

在列上下文中，生成子句 column IN <other>。

给定的参数 other 可以是

• 文字值的列表，例如

  stmt.where(column.in_([1, 2, 3]))

  在这种调用形式中，项目列表被转换为与给定列表长度相同的绑定参数集。

  WHERE COL IN (?, ?, ?)

• 如果比较是对包含多个表达式的 tuple_()，则可以提供元组列表。

  from sqlalchemy import tuple_
  stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))

• 空列表，例如

  stmt.where(column.in_([]))

  在这种调用形式中，表达式呈现“空集”表达式。这些表达式针对各个后端定制，通常试图获取一个空 SELECT 语句作为子查询。例如在 SQLite 上，表达式是

  WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

  在版本 1.4 中更改: 空 IN 表达式现在在所有情况下都使用运行时生成的 SELECT 子查询。

• 绑定参数，例如 bindparam()，如果它包含 bindparam.expanding 标志，则可以使用。

  stmt.where(column.in_(bindparam('value', expanding=True)))

  在这种调用形式中，表达式呈现一个特殊的非 SQL 占位符表达式，看起来像

  WHERE COL IN ([EXPANDING_value])

  此占位符表达式在语句执行时被拦截，转换为前面说明的可变数量绑定参数形式。如果语句被执行为

  connection.execute(stmt, {"value": [1, 2, 3]})

  数据库将为每个值传递一个绑定参数。

  WHERE COL IN (?, ?, ?)

  在版本 1.2 中添加: 添加了“扩展”绑定参数。

  如果传递空列表，将渲染一个特殊的“空列表”表达式，该表达式特定于使用的数据库。在 SQLite 上，这将是

  WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

  在版本 1.3 中添加: “扩展”绑定参数现在支持空列表。

• 一个 select() 结构，通常是相关标量选择

  stmt.where(
      column.in_(
          select(othertable.c.y).
          where(table.c.x == othertable.c.x)
      )
  )

  在这种调用形式中，ColumnOperators.in_() 按给定方式呈现。

  WHERE COL IN (SELECT othertable.y
  FROM othertable WHERE othertable.x = table.x)

参数：

other – 字面量列表、select() 结构或包含 bindparam() 结构的 bindparam.expanding 标志设置为 True。

method sqlalchemy.sql.expression.ColumnOperators.is_(other: Any) → ColumnOperators

实现 IS 运算符。

通常，IS 在与 None 的值进行比较时会自动生成，该值解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则显式使用 IS 可能需要。

另请参阅

ColumnOperators.is_not()

method sqlalchemy.sql.expression.ColumnOperators.is_distinct_from(other: Any) → ColumnOperators

实现 IS DISTINCT FROM 运算符。

在大多数平台上呈现“a IS DISTINCT FROM b”；在某些平台上（如 SQLite）可能呈现“a IS NOT b”。

method sqlalchemy.sql.expression.ColumnOperators.is_not(other: Any) → ColumnOperators

实现 IS NOT 运算符。

通常，IS NOT 在与 None 的值进行比较时会自动生成，该值解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则显式使用 IS NOT 可能需要。

版本 1.4 中的变更: 操作符 is_not() 在以前版本中更名为 isnot()。为了向后兼容，以前的名字仍然可以使用。

另请参阅

ColumnOperators.is_()

method sqlalchemy.sql.expression.ColumnOperators.is_not_distinct_from(other: Any) → ColumnOperators

实现 IS NOT DISTINCT FROM 操作符。

在大多数平台上呈现“a IS NOT DISTINCT FROM b”；在 SQLite 等一些平台上可能呈现“a IS b”。

版本 1.4 中的变更: 操作符 is_not_distinct_from() 在以前版本中更名为 isnot_distinct_from()。为了向后兼容，以前的名字仍然可以使用。

method sqlalchemy.sql.expression.ColumnOperators.isnot(other: Any) → ColumnOperators

实现 IS NOT 运算符。

通常，IS NOT 在与 None 的值进行比较时会自动生成，该值解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则显式使用 IS NOT 可能需要。

版本 1.4 中的变更: 操作符 is_not() 在以前版本中更名为 isnot()。为了向后兼容，以前的名字仍然可以使用。

另请参阅

ColumnOperators.is_()

method sqlalchemy.sql.expression.ColumnOperators.isnot_distinct_from(other: Any) → ColumnOperators

实现 IS NOT DISTINCT FROM 操作符。

在大多数平台上呈现“a IS NOT DISTINCT FROM b”；在 SQLite 等一些平台上可能呈现“a IS b”。

版本 1.4 中的变更: 操作符 is_not_distinct_from() 在以前版本中更名为 isnot_distinct_from()。为了向后兼容，以前的名字仍然可以使用。

method sqlalchemy.sql.expression.ColumnOperators.istartswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

实现 istartswith 操作符，例如，ColumnOperators.startswith() 的不区分大小写的版本。

生成一个 LIKE 表达式，用于测试字符串值开头的非敏感匹配

lower(column) LIKE lower(<other>) || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.istartswith("foobar"))

由于该操作符使用 LIKE，因此 <other> 表达式中存在的通配符 "%" 和 "_" 也将像通配符一样工作。对于文字字符串值，ColumnOperators.istartswith.autoescape 标志可以设置为 True，将这些字符在字符串值中的出现进行转义，以便它们匹配自身而不是通配符。或者，ColumnOperators.istartswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是文字字符串时，这很有用。

参数：

• other – 要比较的表达式。这通常是普通字符串值，但也可以是任意 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.istartswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中 "%"、"_" 和转义字符本身的所有出现，假设该值是一个字面字符串，而不是 SQL 表达式。

  例如，表达式

  somecolumn.istartswith("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时将使用 ESCAPE 关键字渲染，以建立该字符作为转义字符。然后，该字符可以放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符字符。

  例如，表达式

  somecolumn.istartswith("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.istartswith.autoescape 结合使用

  somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的字面参数将在传递给数据库之前被转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.startswith()

method sqlalchemy.sql.expression.ColumnOperators.like(other: Any, escape: str | None = None) → ColumnOperators

实现 like 运算符。

在列上下文中，产生表达式

a LIKE other

例如：

stmt = select(sometable).\
    where(sometable.c.column.like("%foobar%"))

参数：

• other – 要比较的表达式

• escape –

  可选的转义字符，渲染 ESCAPE 关键字，例如

  somecolumn.like("foo/%bar", escape="/")

另请参阅

ColumnOperators.ilike()

method sqlalchemy.sql.expression.ColumnOperators.match(other: Any, **kwargs: Any) → ColumnOperators

实现数据库特有的 'match' 运算符。

ColumnOperators.match() 尝试解析为后端提供的 MATCH 类函数或运算符。例如：

• PostgreSQL - 呈现 x @@ plainto_tsquery(y)

  在版本 2.0 中更改： plainto_tsquery() 现在用作 PostgreSQL 的 to_tsquery() 的替代；有关其他形式的兼容性，请参阅 全文搜索.

• MySQL - 呈现 MATCH (x) AGAINST (y IN BOOLEAN MODE)

  另请参阅

  match - MySQL 特定结构，具有更多功能。

• Oracle - 呈现 CONTAINS(x, y)

• 其他后端可能提供特殊的实现。

• 没有特殊实现的后端会将运算符输出为 “MATCH”。例如，这与 SQLite 兼容。

method sqlalchemy.sql.expression.ColumnOperators.not_ilike(other: Any, escape: str | None = None) → ColumnOperators

实现 NOT ILIKE 运算符。

这等效于使用否定运算符和 ColumnOperators.ilike()，即 ~x.ilike(y)。

在版本 1.4 中更改： not_ilike() 运算符在之前的版本中被重命名为 notilike()。为了向后兼容，之前的名称仍然可用。

另请参阅

ColumnOperators.ilike()

method sqlalchemy.sql.expression.ColumnOperators.not_in(other: Any) → ColumnOperators

实现 NOT IN 运算符。

这等效于使用否定运算符和 ColumnOperators.in_()，即 ~x.in_(y)。

如果 other 是一个空序列，编译器将产生一个 “空不在” 表达式。默认情况下，此表达式为 “1 = 1”，在所有情况下都产生真值。 create_engine.empty_in_strategy 可以用来改变这种行为。

在版本 1.4 中更改： not_in() 运算符在之前的版本中被重命名为 notin_()。为了向后兼容，之前的名称仍然可用。

版本 1.2 中变更: ColumnOperators.in_() 和 ColumnOperators.not_in() 运算符现在默认情况下会为一个空的 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

method sqlalchemy.sql.expression.ColumnOperators.not_like(other: Any, escape: str | None = None) → ColumnOperators

实现 NOT LIKE 运算符。

这等同于使用否定运算符与 ColumnOperators.like()，即 ~x.like(y)。

版本 1.4 中变更: not_like() 运算符从之前版本中的 notlike() 重命名。旧的名称仍然可用以确保向后兼容性。

另请参阅

ColumnOperators.like()

方法 sqlalchemy.sql.expression.ColumnOperators.notilike(other: Any, escape: str | None = None) → ColumnOperators

实现 NOT ILIKE 运算符。

这等效于使用否定运算符和 ColumnOperators.ilike()，即 ~x.ilike(y)。

在版本 1.4 中更改： not_ilike() 运算符在之前的版本中被重命名为 notilike()。为了向后兼容，之前的名称仍然可用。

另请参阅

ColumnOperators.ilike()

方法 sqlalchemy.sql.expression.ColumnOperators.notin_(other: Any) → ColumnOperators

实现 NOT IN 运算符。

这等效于使用否定运算符和 ColumnOperators.in_()，即 ~x.in_(y)。

如果 other 是一个空序列，编译器将产生一个 “空不在” 表达式。默认情况下，此表达式为 “1 = 1”，在所有情况下都产生真值。 create_engine.empty_in_strategy 可以用来改变这种行为。

在版本 1.4 中更改： not_in() 运算符在之前的版本中被重命名为 notin_()。为了向后兼容，之前的名称仍然可用。

版本 1.2 中变更: ColumnOperators.in_() 和 ColumnOperators.not_in() 运算符现在默认情况下会为一个空的 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

方法 sqlalchemy.sql.expression.ColumnOperators.notlike(other: Any, escape: str | None = None) → ColumnOperators

实现 NOT LIKE 运算符。

这等同于使用否定运算符与 ColumnOperators.like()，即 ~x.like(y)。

版本 1.4 中变更: not_like() 运算符从之前版本中的 notlike() 重命名。旧的名称仍然可用以确保向后兼容性。

另请参阅

ColumnOperators.like()

方法 sqlalchemy.sql.expression.ColumnOperators.nulls_first() → ColumnOperators

针对父对象生成一个 nulls_first() 子句。

版本 1.4 中变更: nulls_first() 运算符从之前版本中的 nullsfirst() 重命名。旧的名称仍然可用以确保向后兼容性。

方法 sqlalchemy.sql.expression.ColumnOperators.nulls_last() → ColumnOperators

针对父对象生成一个 nulls_last() 子句。

版本 1.4 中变更: nulls_last() 运算符从之前版本中的 nullslast() 重命名。旧的名称仍然可用以确保向后兼容性。

方法 sqlalchemy.sql.expression.ColumnOperators.nullsfirst() → ColumnOperators

针对父对象生成一个 nulls_first() 子句。

版本 1.4 中变更: nulls_first() 运算符从之前版本中的 nullsfirst() 重命名。旧的名称仍然可用以确保向后兼容性。

方法 sqlalchemy.sql.expression.ColumnOperators.nullslast() → ColumnOperators

针对父对象生成一个 nulls_last() 子句。

版本 1.4 中变更: nulls_last() 运算符从之前版本中的 nullslast() 重命名。旧的名称仍然可用以确保向后兼容性。

方法 sqlalchemy.sql.expression.ColumnOperators.op(opstring: str, precedence: int = 0, is_comparison: bool = False, return_type: Type[TypeEngine[Any]] | TypeEngine[Any] | None = None, python_impl: Callable[..., Any] | None = None) → Callable[[Any], Operators]

继承自 Operators.op() 方法 Operators

生成一个通用的操作符函数。

例如

somecolumn.op("*")(5)

生成

somecolumn * 5

此函数还可用于明确地创建位运算符。例如

somecolumn.op('&')(0xff)

是 somecolumn 中值的按位与。

参数：

• opstring – 将作为此元素和传递给生成函数的表达式之间的中缀运算符输出的字符串。

• precedence –

  数据库在 SQL 表达式中预计应用于该运算符的优先级。此整数值充当 SQL 编译器的一个提示，让它知道何时应在特定操作周围渲染显式括号。较小的数字将导致表达式在应用于另一个优先级较高的运算符时被加括号。默认值 0 低于除逗号 (,) 和 AS 运算符之外的所有运算符。值为 100 将高于或等于所有运算符，而 -100 将低于或等于所有运算符。

  另请参阅

  我正在使用 op() 生成自定义运算符，但我的括号显示不正确 - 有关 SQLAlchemy SQL 编译器如何渲染括号的详细说明

• is_comparison –

  旧版；如果为 True，则运算符将被视为“比较”运算符，即评估为布尔值 true/false 的运算符，如 ==、> 等。提供此标志是为了让 ORM 关系能够在使用自定义联接条件时确定运算符是比较运算符。

  使用 is_comparison 参数已被使用 Operators.bool_op() 方法取代；这个更简洁的运算符会自动设置该参数，但也会提供正确的 PEP 484 类型提示支持，因为返回的对象将表示一个“布尔”数据类型，即 BinaryExpression[bool]。

• return_type – 一个 TypeEngine 类或对象，它将强制该运算符生成的表达式的返回类型为该类型。默认情况下，指定了 Operators.op.is_comparison 的运算符将解析为 Boolean，而那些没有指定该参数的运算符将与左侧操作数的类型相同。

• python_impl –

  一个可选的 Python 函数，它可以评估两个 Python 值，与在数据库服务器上运行时此运算符的工作方式相同。这对 Python 中的 SQL 表达式评估函数很有用，例如 ORM 混合属性和 ORM“评估器”，用于在多行更新或删除后匹配会话中的对象。

  例如

  >>> expr = column('x').op('+', python_impl=lambda a, b: a + b)('y')

  上述表达式的运算符也适用于非 SQL 左边和右边对象

  >>> expr.operator(5, 10)
  15

  2.0 版中的新功能。

另请参阅

Operators.bool_op()

重新定义和创建新运算符

在联接条件中使用自定义运算符

方法 sqlalchemy.sql.expression.ColumnOperators.operate(op: OperatorType, *other: Any, **kwargs: Any) → Operators

继承自 Operators.operate() 方法 Operators

对一个参数进行操作。

这是最低级别的操作，默认情况下会引发 NotImplementedError。

在子类上覆盖它可以允许将通用行为应用于所有操作。例如，覆盖 ColumnOperators 以将 func.lower() 应用于左右两边

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 运算符可调用对象。

• *other – 运算的“另一方”。对于大多数运算来说将是一个单独的标量。

• **kwargs – 修饰符。这些可以由特殊运算符传递，例如 ColumnOperators.contains()。

method sqlalchemy.sql.expression.ColumnOperators.regexp_match(pattern: Any, flags: str | None = None) → ColumnOperators

实现特定于数据库的“正则表达式匹配”运算符。

例如：

stmt = select(table.c.some_column).where(
    table.c.some_column.regexp_match('^(b|c)')
)

ColumnOperators.regexp_match() 尝试解析为后端提供的类似 REGEXP 的函数或运算符，但是可用的特定正则表达式语法和标志是 **不是后端无关的**。

示例包括

• PostgreSQL - 渲染 x ~ y 或 x !~ y 当否定时。

• Oracle - 渲染 REGEXP_LIKE(x, y)

• SQLite - 使用 SQLite 的 REGEXP 占位符运算符，并调用 Python re.match() 内置函数。

• 其他后端可能提供特殊的实现。

• 没有特殊实现的后端将发出运算符为“REGEXP”或“NOT REGEXP”。例如，这与 SQLite 和 MySQL 兼容。

正则表达式支持目前已在 Oracle、PostgreSQL、MySQL 和 MariaDB 中实现。SQLite 提供部分支持。第三方方言之间的支持可能会有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。

• flags – 要应用的任何正则表达式字符串标志，以纯 Python 字符串形式传递。这些标志是特定于后端的。某些后端，如 PostgreSQL 和 MariaDB，可以替代地将标志指定为模式的一部分。当在 PostgreSQL 中使用忽略大小写标志“i”时，将使用忽略大小写正则表达式匹配运算符 ~* 或 !~*。

1.4 版中的新功能。

在版本 1.4.48 中更改,: 2.0.18 请注意，由于实现错误，以前“flags”参数除了纯 Python 字符串外，还接受 SQL 表达式对象，例如列表达式。此实现无法与缓存正确配合，因此已删除；对于“flags”参数，应仅传递字符串，因为这些标志在 SQL 表达式中以文字内联值的

另请参阅

ColumnOperators.regexp_replace()

method sqlalchemy.sql.expression.ColumnOperators.regexp_replace(pattern: Any, replacement: Any, flags: str | None = None) → ColumnOperators

实现特定于数据库的“正则表达式替换”运算符。

例如：

stmt = select(
    table.c.some_column.regexp_replace(
        'b(..)',
        'X
Y',
        flags='g'
    )
)

ColumnOperators.regexp_replace() 尝试解析为后端提供的类似 REGEXP_REPLACE 的函数，该函数通常会发出函数 REGEXP_REPLACE()。但是，可用的特定正则表达式语法和标志是 **不是后端无关的**。

正则表达式替换支持目前已在 Oracle、PostgreSQL、MySQL 8 或更高版本以及 MariaDB 中实现。第三方方言之间的支持可能会有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。

• pattern – 替换字符串或列子句。

• flags – 要应用的任何正则表达式字符串标志，以纯 Python 字符串形式传递。这些标志是特定于后端的。某些后端，如 PostgreSQL 和 MariaDB，可以替代地将标志指定为模式的一部分。

1.4 版中的新功能。

在版本 1.4.48 中更改,: 2.0.18 请注意，由于实现错误，以前“flags”参数除了纯 Python 字符串外，还接受 SQL 表达式对象，例如列表达式。此实现无法与缓存正确配合，因此已删除；对于“flags”参数，应仅传递字符串，因为这些标志在 SQL 表达式中以文字内联值的

另请参阅

ColumnOperators.regexp_match()

method sqlalchemy.sql.expression.ColumnOperators.reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → Operators

inherited from the Operators.reverse_operate() method of Operators

对参数进行反向操作。

用法与 operate() 相同。

method sqlalchemy.sql.expression.ColumnOperators.startswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

实现 startswith 运算符。

生成一个 LIKE 表达式，它测试与字符串值开头的匹配。

column LIKE <other> || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.startswith("foobar"))

由于该运算符使用 LIKE，因此在 <other> 表达式中出现的通配符字符 "%" 和 "_" 也将像通配符一样工作。对于文字字符串值，ColumnOperators.startswith.autoescape 标志可以设置为 True，以对字符串值内的这些字符的出现进行转义，以便它们本身匹配，而不是作为通配符字符。或者，ColumnOperators.startswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是文字字符串时，这将很有用。

参数：

• other – 要比较的表达式。这通常是纯字符串值，但也可能是任意 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.startswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中 "%"、"_" 和转义字符本身的所有出现，假设该值是一个字面字符串，而不是 SQL 表达式。

  例如，表达式

  somecolumn.startswith("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE :param || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时将使用 ESCAPE 关键字渲染，以建立该字符作为转义字符。然后，该字符可以放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符字符。

  例如，表达式

  somecolumn.startswith("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE :param || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.startswith.autoescape 组合使用

  somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的字面参数将在传递给数据库之前被转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.endswith()

ColumnOperators.contains()

ColumnOperators.like()

attribute sqlalchemy.sql.expression.ColumnOperators.timetuple: Literal[None] = None

Hack，允许 datetime 对象在 LHS 上进行比较。

class sqlalchemy.sql.expression.Extract

表示一个 SQL EXTRACT 子句，extract(field FROM expr)。

类签名

class sqlalchemy.sql.expression.Extract (sqlalchemy.sql.expression.ColumnElement)

class sqlalchemy.sql.expression.False_

表示 SQL 语句中的 false 关键字，或等效项。

False_ 可通过 false() 函数作为常量访问。

类签名

class sqlalchemy.sql.expression.False_ (sqlalchemy.sql.expression.SingletonConstant, sqlalchemy.sql.roles.ConstExprRole, sqlalchemy.sql.expression.ColumnElement)

class sqlalchemy.sql.expression.FunctionFilter

表示一个函数 FILTER 子句。

这是一种针对聚合函数和窗口函数的特殊运算符，它控制传递给它的行。它仅受某些数据库后端支持。

调用 FunctionFilter 是通过 FunctionElement.filter() 进行的。

func.count(1).filter(True)

另请参阅

FunctionElement.filter()

成员

filter()、over()、self_group()、within_group()

类签名

类 sqlalchemy.sql.expression.FunctionFilter (sqlalchemy.sql.expression.Generative, sqlalchemy.sql.expression.ColumnElement)

方法 sqlalchemy.sql.expression.FunctionFilter.filter(*criterion: _ColumnExpressionArgument[bool]) → Self

对该函数生成额外的 FILTER。

此方法在 FunctionElement.filter() 设置的初始条件的基础上添加额外的条件。

多个条件在 SQL 渲染时通过 AND 连接在一起。

方法 sqlalchemy.sql.expression.FunctionFilter.over(partition_by: Iterable[_ColumnExpressionArgument[Any]] | _ColumnExpressionArgument[Any] | None = None, order_by: Iterable[_ColumnExpressionArgument[Any]] | _ColumnExpressionArgument[Any] | None = None, range_: typing_Tuple[int | None, int | None] | None = None, rows: typing_Tuple[int | None, int | None] | None = None) → Over[_T]

对这个已过滤函数生成一个 OVER 子句。

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

表达式

func.rank().filter(MyClass.y > 5).over(order_by='x')

是以下的简写

from sqlalchemy import over, funcfilter
over(funcfilter(func.rank(), MyClass.y > 5), order_by='x')

有关完整描述，请参见 over()。

方法 sqlalchemy.sql.expression.FunctionFilter.self_group(against: OperatorType | None = None) → Self | Grouping[_T]

对这个 ClauseElement 应用“分组”。

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

在表达式组合在一起时，self_group() 的应用是自动的 - 用户代码永远不需要直接使用此方法。请注意，SQLAlchemy 的子句构造会考虑运算符优先级 - 因此在类似 x OR (y AND z) 的表达式中可能不需要圆括号 - AND 的优先级高于 OR。

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

方法 sqlalchemy.sql.expression.FunctionFilter.within_group(*order_by: _ColumnExpressionArgument[Any]) → WithinGroup[_T]

对该函数生成一个 WITHIN GROUP (ORDER BY expr) 子句。

类 sqlalchemy.sql.expression.Label

表示一个列标签 (AS)。

表示一个标签，通常使用 AS sql 关键字应用于任何列级元素。

成员

foreign_keys、primary_key、self_group()

类签名

类 sqlalchemy.sql.expression.Label (sqlalchemy.sql.roles.LabeledColumnExprRole, sqlalchemy.sql.expression.NamedColumn)

属性 sqlalchemy.sql.expression.Label.foreign_keys: AbstractSet[ForeignKey]

属性 sqlalchemy.sql.expression.Label.primary_key: bool

方法 sqlalchemy.sql.expression.Label.self_group(against: OperatorType | None = None) → Label[_T]

对这个 ClauseElement 应用“分组”。

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

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

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

class sqlalchemy.sql.expression.Null

表示 SQL 语句中的 NULL 关键字。

Null 通过 null() 函数作为常量访问。

类签名

class sqlalchemy.sql.expression.Null (sqlalchemy.sql.expression.SingletonConstant, sqlalchemy.sql.roles.ConstExprRole, sqlalchemy.sql.expression.ColumnElement)

class sqlalchemy.sql.expression.Operators

比较和逻辑运算符的基础。

实现基本方法 Operators.operate() 和 Operators.reverse_operate()，以及 Operators.__and__()，Operators.__or__()，Operators.__invert__()。

成员

__and__(), __invert__(), __or__(), __sa_operate__(), bool_op(), op(), operate(), reverse_operate()

通常通过其最常见的子类 ColumnOperators 使用。

method sqlalchemy.sql.expression.Operators.__and__(other: Any) → Operators

实现 & 操作符。

在与 SQL 表达式一起使用时，会导致 AND 操作，等效于 and_()，即

a & b

等效于

from sqlalchemy import and_
and_(a, b)

在使用 & 时，应注意运算符优先级；& 运算符具有最高优先级。如果操作数包含进一步的子表达式，则应将它们括在括号中。

(a == 2) & (b == 4)

method sqlalchemy.sql.expression.Operators.__invert__() → Operators

实现 ~ 运算符。

在与 SQL 表达式一起使用时，会导致 NOT 操作，等效于 not_()，即

~a

等效于

from sqlalchemy import not_
not_(a)

method sqlalchemy.sql.expression.Operators.__or__(other: Any) → Operators

实现 | 运算符。

当与 SQL 表达式一起使用时，会产生一个 OR 操作，等效于 or_()，即

a | b

等效于

from sqlalchemy import or_
or_(a, b)

在使用 | 时应注意运算符优先级；| 运算符具有最高优先级。如果操作数包含进一步的子表达式，则应将其括在括号中。

(a == 2) | (b == 4)

method sqlalchemy.sql.expression.Operators.__sa_operate__(op: OperatorType, *other: Any, **kwargs: Any) → Operators

对一个参数进行操作。

这是最低级别的操作，默认情况下会引发 NotImplementedError。

在子类上覆盖它可以允许将通用行为应用于所有操作。例如，覆盖 ColumnOperators 以将 func.lower() 应用于左右两边

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 运算符可调用对象。

• *other – 操作的“另一侧”。对于大多数操作来说，它将是一个标量。

• **kwargs – 修饰符。这些可能由特殊运算符传递，例如 ColumnOperators.contains()。

method sqlalchemy.sql.expression.Operators.bool_op(opstring: str, precedence: int = 0, python_impl: Callable[[...], Any] | None = None) → Callable[[Any], Operators]

返回一个自定义布尔运算符。

此方法是调用 Operators.op() 并传递 Operators.op.is_comparison 标志为 True 的简写。使用 Operators.bool_op() 的一个主要优点是，当使用列构造时，返回表达式的“布尔”性质将对 PEP 484 目的有效。

另请参阅

Operators.op()

method sqlalchemy.sql.expression.Operators.op(opstring: str, precedence: int = 0, is_comparison: bool = False, return_type: Type[TypeEngine[Any]] | TypeEngine[Any] | None = None, python_impl: Callable[..., Any] | None = None) → Callable[[Any], Operators]

生成一个通用的操作符函数。

例如

somecolumn.op("*")(5)

生成

somecolumn * 5

此函数还可用于明确地创建位运算符。例如

somecolumn.op('&')(0xff)

是 somecolumn 中值的按位与。

参数：

• opstring – 将作为此元素和传递给生成的函数的表达式之间的中缀运算符输出的字符串。

• precedence –

  数据库在 SQL 表达式中预计应用于该运算符的优先级。此整数值充当 SQL 编译器的一个提示，让它知道何时应在特定操作周围渲染显式括号。较小的数字将导致表达式在应用于另一个优先级较高的运算符时被加括号。默认值 0 低于除逗号 (,) 和 AS 运算符之外的所有运算符。值为 100 将高于或等于所有运算符，而 -100 将低于或等于所有运算符。

  另请参阅

  我正在使用 op() 生成自定义运算符，但我的括号显示不正确 - 有关 SQLAlchemy SQL 编译器如何渲染括号的详细说明

• is_comparison –

  旧版；如果为 True，则运算符将被视为“比较”运算符，即评估为布尔值 true/false 的运算符，如 ==、> 等。提供此标志是为了让 ORM 关系能够在使用自定义联接条件时确定运算符是比较运算符。

  使用 is_comparison 参数已被使用 Operators.bool_op() 方法代替；此更简洁的运算符会自动设置此参数，但也提供正确的 PEP 484 类型支持，因为返回的对象将表示“布尔”数据类型，即 BinaryExpression[bool]。

• return_type – 一个 TypeEngine 类或对象，它将强制由该运算符生成的表达式的返回类型为该类型。默认情况下，指定 Operators.op.is_comparison 的运算符将解析为 Boolean，而那些不指定运算符将与左手操作数的类型相同。

• python_impl –

  一个可选的 Python 函数，它可以评估两个 Python 值，与在数据库服务器上运行时此运算符的工作方式相同。这对 Python 中的 SQL 表达式评估函数很有用，例如 ORM 混合属性和 ORM“评估器”，用于在多行更新或删除后匹配会话中的对象。

  例如

  >>> expr = column('x').op('+', python_impl=lambda a, b: a + b)('y')

  上述表达式的运算符也适用于非 SQL 左边和右边对象

  >>> expr.operator(5, 10)
  15

  2.0 版中的新功能。

另请参阅

Operators.bool_op()

重新定义和创建新运算符

在联接条件中使用自定义运算符

method sqlalchemy.sql.expression.Operators.operate(op: OperatorType, *other: Any, **kwargs: Any) → Operators

对一个参数进行操作。

这是最低级别的操作，默认情况下会引发 NotImplementedError。

在子类上覆盖它可以允许将通用行为应用于所有操作。例如，覆盖 ColumnOperators 以将 func.lower() 应用于左右两边

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 运算符可调用对象。

• *other – 运算的“另一侧”。对于大多数运算而言，将是一个单独的标量。

• **kwargs – 修饰符。这些可能由诸如 ColumnOperators.contains() 的特殊运算符传递。

method sqlalchemy.sql.expression.Operators.reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → Operators

对参数进行反向操作。

用法与 operate() 相同。

class sqlalchemy.sql.expression.Over

表示一个 OVER 子句。

这是一个针对所谓的“窗口”函数以及任何聚合函数的特殊运算符，它会生成相对于结果集本身的结果。大多数现代 SQL 后端现在都支持窗口函数。

成员

element

类签名

class sqlalchemy.sql.expression.Over (sqlalchemy.sql.expression.ColumnElement)

attribute sqlalchemy.sql.expression.Over.element: ColumnElement[_T]

此 Over 对象所引用的基础表达式对象。

class sqlalchemy.sql.expression.SQLColumnExpression

一个类型，可用于指示任何 SQL 列元素或充当其替代的对象。

SQLColumnExpression 是 ColumnElement 的基类，以及 ORM 元素（例如 InstrumentedAttribute）的基础类中的一部分，它可以用于 PEP 484 类型来指示应该作为列表达式工作的参数或返回值。

版本 2.0.0b4 中的新内容。

类签名

class sqlalchemy.sql.expression.SQLColumnExpression (sqlalchemy.sql.expression.SQLCoreOperations, sqlalchemy.sql.roles.ExpressionElementRole, sqlalchemy.util.langhelpers.TypingOnly)

class sqlalchemy.sql.expression.TextClause

表示一个文字 SQL 文本片段。

例如：

from sqlalchemy import text

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

使用 text() 函数可以生成 TextClause 构造；有关完整文档，请参见该函数。

另请参阅

text()

成员

bindparams(), columns(), self_group()

类签名

class sqlalchemy.sql.expression.TextClause (sqlalchemy.sql.roles.DDLConstraintColumnRole, sqlalchemy.sql.roles.DDLExpressionRole, sqlalchemy.sql.roles.StatementOptionRole, sqlalchemy.sql.roles.WhereHavingRole, sqlalchemy.sql.roles.OrderByRole, sqlalchemy.sql.roles.FromClauseRole, sqlalchemy.sql.roles.SelectStatementRole, sqlalchemy.sql.roles.InElementRole, sqlalchemy.sql.expression.Generative, sqlalchemy.sql.expression.Executable, sqlalchemy.sql.expression.DQLDMLClauseElement, sqlalchemy.sql.roles.BinaryElementRole, sqlalchemy.inspection.Inspectable)

method sqlalchemy.sql.expression.TextClause.bindparams(*binds: BindParameter[Any], **names_to_values: Any) → Self

在该 TextClause 构造中，建立绑定参数的值和/或类型。

给定一个文本构造，例如

from sqlalchemy import text
stmt = text("SELECT id, name FROM user WHERE name=:name "
            "AND timestamp=:timestamp")

可以使用 TextClause.bindparams() 方法使用简单的关键字参数来建立 :name 和 :timestamp 的初始值

stmt = stmt.bindparams(name='jack',
            timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5))

上面的内容中，将生成新的 BindParameter 对象，其名称分别为 name 和 timestamp，值分别为 jack 和 datetime.datetime(2012, 10, 8, 15, 12, 5)。类型将从给定值推断，在本例中分别为 String 和 DateTime.

当需要特定类型行为时，可以使用位置 *binds 参数来指定 bindparam() 构造。这些构造必须至少包含 key 参数，然后是可选值和类型

from sqlalchemy import bindparam
stmt = stmt.bindparams(
                bindparam('name', value='jack', type_=String),
                bindparam('timestamp', type_=DateTime)
            )

在上面，我们为 timestamp 绑定指定了 DateTime 类型，为 name 绑定指定了 String 类型。在 name 的情况下，我们还设置了 "jack" 的默认值。

可以在语句执行时提供其他绑定参数，例如

result = connection.execute(stmt,
            timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5))

可以重复调用 TextClause.bindparams() 方法，它将重新使用现有的 BindParameter 对象来添加新信息。例如，我们可以先使用类型信息调用 TextClause.bindparams()，然后使用值信息调用 TextClause.bindparams()，并且它将被合并

stmt = text("SELECT id, name FROM user WHERE name=:name "
            "AND timestamp=:timestamp")
stmt = stmt.bindparams(
    bindparam('name', type_=String),
    bindparam('timestamp', type_=DateTime)
)
stmt = stmt.bindparams(
    name='jack',
    timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5)
)

TextClause.bindparams() 方法还支持 **唯一** 绑定参数的概念。这些参数是在语句编译时根据名称进行“唯一化”的，因此，可以将多个 text() 构造组合在一起，而不会出现名称冲突。要使用此功能，请在每个 bindparam() 对象上指定 BindParameter.unique 标志

stmt1 = text("select id from table where name=:name").bindparams(
    bindparam("name", value='name1', unique=True)
)
stmt2 = text("select id from table where name=:name").bindparams(
    bindparam("name", value='name2', unique=True)
)

union = union_all(
    stmt1.columns(column("id")),
    stmt2.columns(column("id"))
)

上面的语句将呈现为

select id from table where name=:name_1
UNION ALL select id from table where name=:name_2

New in version 1.3.11: 添加了对 BindParameter.unique 标志的支持，以与 text() 构造一起使用。

method sqlalchemy.sql.expression.TextClause.columns(*cols: _ColumnExpressionArgument[Any], **types: _TypeEngineArgument[Any]) → TextualSelect

将该 TextClause 对象转换为 TextualSelect 对象，该对象在功能上等同于 SELECT 语句。

TextualSelect 是 SelectBase 层次结构的一部分，可以通过使用 TextualSelect.subquery() 方法将其嵌入到另一个语句中，以生成 Subquery 对象，然后可以从中进行 SELECT 操作。

此函数实际上弥合了完全文本 SELECT 语句与 SQL 表达式语言中“可选择”的概念之间的差距

from sqlalchemy.sql import column, text

stmt = text("SELECT id, name FROM some_table")
stmt = stmt.columns(column('id'), column('name')).subquery('st')

stmt = select(mytable).\
        select_from(
            mytable.join(stmt, mytable.c.name == stmt.c.name)
        ).where(stmt.c.id > 5)

在上面，我们向 TextClause.columns() 方法传递了一系列 column() 元素。这些 column() 元素现在成为 TextualSelect.selected_columns 列集合中的第一类元素，然后在调用 TextualSelect.subquery() 之后成为 Subquery.c 集合的一部分。

传递给 TextClause.columns() 的列表达式也可以被类型化；当我们这样做时，这些 TypeEngine 对象将成为该列的有效返回类型，以便 SQLAlchemy 的结果集处理系统可以在返回值上使用。这通常需要用于日期或布尔类型，以及在某些方言配置上的 Unicode 处理。

stmt = text("SELECT id, name, timestamp FROM some_table")
stmt = stmt.columns(
            column('id', Integer),
            column('name', Unicode),
            column('timestamp', DateTime)
        )

for id, name, timestamp in connection.execute(stmt):
    print(id, name, timestamp)

作为上面语法的快捷方式，如果只需要类型转换，可以使用引用类型的关键字参数。

stmt = text("SELECT id, name, timestamp FROM some_table")
stmt = stmt.columns(
            id=Integer,
            name=Unicode,
            timestamp=DateTime
        )

for id, name, timestamp in connection.execute(stmt):
    print(id, name, timestamp)

TextClause.columns() 的位置形式还提供了**位置列目标**的独特功能，这在使用 ORM 进行复杂文本查询时特别有用。如果我们从模型中指定列到 TextClause.columns()，结果集将按位置与这些列匹配，这意味着文本 SQL 中列的名称或来源无关紧要。

stmt = text("SELECT users.id, addresses.id, users.id, "
     "users.name, addresses.email_address AS email "
     "FROM users JOIN addresses ON users.id=addresses.user_id "
     "WHERE users.id = 1").columns(
        User.id,
        Address.id,
        Address.user_id,
        User.name,
        Address.email_address
     )

query = session.query(User).from_statement(stmt).options(
    contains_eager(User.addresses))

TextClause.columns() 方法提供了一条直接调用 FromClause.subquery() 以及 SelectBase.cte() 的路径，针对文本 SELECT 语句。

stmt = stmt.columns(id=Integer, name=String).cte('st')

stmt = select(sometable).where(sometable.c.id == stmt.c.id)

参数：

• *cols – 一系列 ColumnElement 对象，通常是来自 Table 或 ORM 级别的列映射属性的 Column 对象，表示此文本字符串将从中 SELECT 的一组列。

• **types** – 一个将字符串名称映射到 TypeEngine 类型对象的映射，指示要用于从文本字符串中 SELECT 的名称的数据类型。建议使用 *cols 参数，因为它也指示位置排序。

method sqlalchemy.sql.expression.TextClause.self_group(against: OperatorType | None = None) → Self | Grouping[Any]

对这个 ClauseElement 应用“分组”。

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

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

self_group() 的基本方法 ClauseElement 只是返回 self。

class sqlalchemy.sql.expression.TryCast

表示一个 TRY_CAST 表达式。

有关 TryCast 用法的详细信息，请参见 try_cast()。

另请参阅

try_cast()

数据转换和类型强制

成员

inherit_cache

类签名

class sqlalchemy.sql.expression.TryCast (sqlalchemy.sql.expression.Cast)

attribute sqlalchemy.sql.expression.TryCast.inherit_cache: bool | None = True

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

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

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

另请参阅

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

class sqlalchemy.sql.expression.Tuple

表示一个 SQL 元组。

成员

self_group()

类签名

class sqlalchemy.sql.expression.Tuple (sqlalchemy.sql.expression.ClauseList, sqlalchemy.sql.expression.ColumnElement)

method sqlalchemy.sql.expression.Tuple.self_group(against: OperatorType | None = None) → Self

对这个 ClauseElement 应用“分组”。

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

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

self_group() 的基本方法 ClauseElement 只是返回 self。

class sqlalchemy.sql.expression.WithinGroup

表示一个 WITHIN GROUP (ORDER BY) 子句。

这是一个针对所谓“有序集合聚合”和“假设集合聚合”函数的特殊运算符，包括 percentile_cont()、rank()、dense_rank() 等。

它只受某些数据库后端支持，例如 PostgreSQL、Oracle 和 MS SQL Server。

该 WithinGroup 结构从方法 FunctionElement.within_group_type() 中提取其类型。如果此方法返回 None，则使用该函数的 .type。

成员

filter()，over()

类签名

类 sqlalchemy.sql.expression.WithinGroup (sqlalchemy.sql.expression.ColumnElement)

方法 sqlalchemy.sql.expression.WithinGroup.filter(*criterion: _ColumnExpressionArgument[bool]) → Self | FunctionFilter[_T]

针对此函数生成 FILTER 子句。

方法 sqlalchemy.sql.expression.WithinGroup.over(*, partition_by: _ByArgument | None = None, order_by: _ByArgument | None = None, rows: typing_Tuple[int | None, int | None] | None = None, range_: typing_Tuple[int | None, int | None] | None = None) → Over[_T]

针对此 WithinGroup 结构生成 OVER 子句。

此函数的签名与 FunctionElement.over() 的签名相同。

类 sqlalchemy.sql.elements.WrapsColumnExpression

混合类，将一个 ColumnElement 定义为一个包装器，对已有名稱的表达式具有特殊的标签行为。

1.4 版中的新功能。

另请参阅

使用 CAST 或类似方法对简单列表达式进行改进的列标签。

类签名

类 sqlalchemy.sql.expression.WrapsColumnExpression (sqlalchemy.sql.expression.ColumnElement)

类 sqlalchemy.sql.expression.True_

表示 SQL 语句中的 true 关键字，或等效项。

True_ 通过 true() 函数作为常量访问。

类签名

类 sqlalchemy.sql.expression.True_ (sqlalchemy.sql.expression.SingletonConstant，sqlalchemy.sql.roles.ConstExprRole，sqlalchemy.sql.expression.ColumnElement)

类 sqlalchemy.sql.expression.TypeCoerce

表示一个 Python 端类型强制转换包装器。

TypeCoerce 提供 type_coerce() 函数；有关用法详细信息，请参阅该函数。

另请参阅

type_coerce()

cast()

成员

self_group()

类签名

类 sqlalchemy.sql.expression.TypeCoerce (sqlalchemy.sql.expression.WrapsColumnExpression)

方法 sqlalchemy.sql.expression.TypeCoerce.self_group(against: OperatorType | None = None) → TypeCoerce[_T]

对这个 ClauseElement 应用“分组”。

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

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

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

类 sqlalchemy.sql.expression.UnaryExpression

定义一个“一元”表达式。

一元表达式具有单个列表达式和一个运算符。运算符可以放置在列表达式的左侧（称为“运算符”）或右侧（称为“修饰符”）。

UnaryExpression 是几个一元运算符的基础，包括 desc()、asc()、distinct()、nulls_first() 和 nulls_last() 使用的那些运算符。

成员

self_group()

类签名

类 sqlalchemy.sql.expression.UnaryExpression (sqlalchemy.sql.expression.ColumnElement)

方法 sqlalchemy.sql.expression.UnaryExpression.self_group(against: OperatorType | None = None) → Self | Grouping[_T]

对这个 ClauseElement 应用“分组”。

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

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

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

列元素类型化实用程序

从 sqlalchemy 命名空间导入的独立实用程序函数，以通过类型检查器提高支持。

对象名称	描述
NotNullable(val)	将列或 ORM 类类型化为不可为空。
Nullable(val)	将列或 ORM 类类型化为可为空。

function sqlalchemy.NotNullable(val: _TypedColumnClauseArgument[_T | None] | Type[_T] | None) → _TypedColumnClauseArgument[_T]

将列或 ORM 类类型化为不可为空。

这可以在 select 和其他上下文中使用，以表示列的值不能为 null，例如由于对可为空列的 where 条件。

stmt = select(NotNullable(A.value)).where(A.value.is_not(None))

在运行时，此方法返回未更改的输入。

版本 2.0.20 中的新增功能。

function sqlalchemy.Nullable(val: _TypedColumnClauseArgument[_T]) → _TypedColumnClauseArgument[_T | None]

将列或 ORM 类类型化为可为空。

这可以在 select 和其他上下文中使用，以表示列的值可以为 null，例如由于外连接。

stmt1 = select(A, Nullable(B)).outerjoin(A.bs)
stmt2 = select(A.data, Nullable(B.data)).outerjoin(A.bs)

在运行时，此方法返回未更改的输入。

版本 2.0.20 中的新增功能。