列元素和表达式

表达式 API 由一系列类组成，每个类代表 SQL 字符串中的特定词法元素。当组合成更大的结构时，它们形成一个语句结构，可以编译成可以传递给数据库的字符串表示形式。这些类组织成一个层次结构，从最底层的 ClauseElement 类开始。主要子类包括 ColumnElement，它表示 SQL 语句中任何基于列的表达式的角色，例如在 columns 子句、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, ...])	生成 SQL 语句，该语句缓存为 lambda。
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"})

当生成要多次调用的 UPDATE 或 DELETE 语句时，显式使用 bindparam() 也很常见，其中语句的 WHERE 标准在每次调用时都会更改，例如

stmt = (
    users_table.update()
    .where(user_table.c.name == bindparam("username"))
    .values(fullname=bindparam("fullname"))
)

connection.execute(
    stmt,
    [
        {"username": "wendy", "fullname": "Wendy Smith"},
        {"username": "jack", "fullname": "Jack Jones"},
    ],
)

SQLAlchemy 的 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 语句时，就“VALUES”部分而言，会自动调用 bindparam()。insert() 构造生成一个 INSERT 表达式，该表达式在语句执行时将基于传递的参数生成绑定占位符，如下所示

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

上面将生成 SQL 输出，如下所示

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

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

参数:

• key –

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

  如果省略，则会为绑定参数生成一个“匿名”名称；当给定要绑定的值时，最终结果等同于调用 literal() 函数并传入要绑定的值，特别是当还提供了 bindparam.unique 参数时。

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

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

• type_ –

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

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

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

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

• quote – 如果此参数名称需要引号，并且当前不被认为是 SQLAlchemy 保留字，则为 True；这目前仅适用于 Oracle 数据库后端，在这些后端中，绑定名称有时必须用引号引起来。

• isoutparam – 如果为 True，则应将该参数视为存储过程 “OUT” 参数。这适用于支持 OUT 参数的后端，例如 Oracle 数据库。

• expanding –

  如果为 True，则此参数将在执行时被视为“扩展”参数；参数值应为序列，而不是标量值，并且字符串 SQL 语句将在每次执行时进行转换，以适应序列，并使用可变数量的参数槽传递给 DBAPI。这是为了允许语句缓存与 IN 子句结合使用。

  另请参阅

  ColumnOperators.in_()

  使用 IN 表达式 - 与 baked 查询一起使用

  注意

  “扩展”功能不支持 “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” 绑定参数

  另请参阅

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

另请参阅

发送参数 - 在 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 表达式>, <值>) 组成，其中 SQL 表达式是布尔表达式，而 “值” 是结果值，例如

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

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

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

• value – 一个可选的 SQL 表达式，它将用作传递给 case.whens 的字典中候选值的固定“比较点”。

• else_ – 一个可选的 SQL 表达式，如果 case.whens 中的所有表达式的计算结果均为 false，则它将是 CASE 构造的计算结果。当省略时，如果所有 “when” 表达式的计算结果均为 true，则大多数数据库将产生 NULL 结果。

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

生成 CAST 表达式。

cast() 返回 Cast 的一个实例。

例如：

from sqlalchemy import cast, Numeric

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

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

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

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

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

参数:

• expression – 一个 SQL 表达式，例如 ColumnElement 表达式或将强制转换为绑定字面量值的 Python 字符串。

• type_ – 一个 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 的值传递。此外，完整的 SQL 语句最好使用 text() 构造来处理。

通过将 column() 与 table() 函数（它是 Table 的轻量级类似物）组合使用，column() 可以以类似表的方式使用，以产生具有最少样板代码的工作表构造

from sqlalchemy import table, column, select

user = table(
    "user",
    column("id"),
    column("name"),
    column("description"),
)

stmt = select(user.c.description).where(user.c.name == "wendy")

像上面说明的那样创建的 column() / table() 构造是以临时方式创建的，并且与任何 MetaData、DDL 或事件无关，这与它的 Table 对应物不同。

参数:

• text – 元素的文本。

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

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

另请参阅

列

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

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

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

distinct() 操作符与 Select.distinct() 方法不同，后者生成一个 SELECT 语句，其中 DISTINCT 应用于整个结果集，例如 SELECT DISTINCT 表达式。有关更多信息，请参阅该方法。

另请参阅

ColumnElement.distinct()

Select.distinct()

func

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

返回 Extract 构造。

这通常作为 extract() 以及来自 func 命名空间的 func.extract 提供。

参数:

• 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("hi", type_=Unicode)
...     + " "
...     + func.my_string("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 sqlalchemy.sql.expression.lambda_stmt(lmb: Callable[[], Any], enable_tracking: bool = True, track_closure_variables: bool = True, track_on: object | None = None, global_track_bound_values: bool = True, track_bound_values: bool = True, lambda_cache: MutableMapping[Tuple[Any, ...], NonAnalyzedFunction | AnalyzedFunction] | None = None) → StatementLambdaElement

生成 SQL 语句，该语句缓存为 lambda。

扫描 lambda 中的 Python 代码对象，以查找将成为绑定参数的 Python 字面量以及引用可能变化的 Core 或 ORM 构造的闭包变量。lambda 本身将仅针对检测到的特定构造集调用一次。

例如：

from sqlalchemy import lambda_stmt

stmt = lambda_stmt(lambda: table.select())
stmt += lambda s: s.where(table.c.id == 5)

result = connection.execute(stmt)

返回的对象是 StatementLambdaElement 的实例。

1.4 版本新增。

参数:

• lmb – 一个 Python 函数，通常是 lambda，它不接受任何参数并返回一个 SQL 表达式构造

• enable_tracking – 当为 False 时，将禁用对给定 lambda 的所有扫描，以查找闭包变量或绑定参数的变化。用于在所有情况下都产生相同结果且没有参数化的 lambda。

• track_closure_variables – 当为 False 时，将不会扫描 lambda 中闭包变量的变化。用于其闭包变量的状态永远不会改变 lambda 返回的 SQL 结构的 lambda。

• track_bound_values – 当为 False 时，将为给定 lambda 禁用绑定参数跟踪。用于不产生任何绑定值或初始绑定值永远不会改变的 lambda。

• 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 参数进行转换。

• type_ – 可选的 TypeEngine，它将为此字面值提供绑定参数转换。

• literal_execute –

  可选的布尔值，当为 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")
)

也可以使用 Python | 运算符来使用 or_() 连接词（但请注意，复合表达式需要用括号括起来才能与 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 表达式的结果。

Deprecated since version 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)

当字面字符串 SQL 片段被指定为更大查询的一部分时，例如 SELECT 语句的 WHERE 子句，会使用 text() 构造。

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

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

参数:

text –

要创建的 SQL 语句的文本。使用 :<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 之间的区别在于，对于不可转换的表达式，例如尝试将字符串 "hi" 转换为整数值，TRY_CAST 返回 NULL。

例如：

from sqlalchemy import select, try_cast, Numeric

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

以上代码在 Microsoft SQL Server 上将呈现为

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

2.0.14 版本新增: try_cast() 已从 SQL Server 方言推广为通用构造，可能受其他方言支持。

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

返回 Tuple。

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

from sqlalchemy import tuple_

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

1.3.6 版本更改: 添加了对 SQLite IN 元组的支持。

警告

复合 IN 构造并非所有后端都支持，目前已知可在 PostgreSQL、MySQL 和 SQLite 上工作。当调用此类表达式时，不支持的后端将引发 DBAPIError 的子类。

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

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

例如：

from sqlalchemy import type_coerce

stmt = select(type_coerce(log_table.date_string, StringDateTime()))

上述构造将生成一个 TypeCoerce 对象，它不会以任何方式修改 SQL 端的呈现，除非在列子句上下文中使用时可能会生成标签。

SELECT date_string AS date_string FROM log

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

注意

type_coerce() 构造本身不呈现任何 SQL 语法，包括它不暗示使用括号。如果需要显式使用括号，请使用 TypeCoerce.self_group()。

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

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

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

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

当将 type_coerce() 与组合表达式一起使用时，请注意不应用括号。如果 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 标志。当设置为 True 或 False 时，此 quote 标志会覆盖此标识符的自动引用行为，以便无条件地引用或不引用名称。如果保留其默认值 None，则会根据对令牌本身的检查，在每个后端的基础上将引用行为应用于标识符。

对于所谓的“名称规范化”选项，具有 quote=True 的 quoted_name 对象也被阻止修改。某些数据库后端，例如 Oracle Database、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+oracledb://some_dsn")
print(inspect(engine).has_table(quoted_name("some_table", True)))

上述逻辑将针对 Oracle Database 后端运行“has table”逻辑，并完全按 "some_table" 传递名称，而无需转换为大写。

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

成员

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

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

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

参数:

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

另请参阅

desc()

nulls_first()

nulls_last()

Select.order_by()

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

生成 BETWEEN 谓词子句。

例如：

from sqlalchemy import between

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

将生成类似于以下的 SQL：

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

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

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

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

print(between(5, 3, 7))

这将生成：

:param_1 BETWEEN :param_2 AND :param_3

参数:

• expr – 列表达式，通常是 ColumnElement 实例，或者是要强制转换为列表达式的 Python 标量表达式，用作 BETWEEN 表达式的左侧。

• lower_bound – 列或 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

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

1.2 版本更改: 如果 COLLATE 表达式区分大小写，则会自动应用引用。

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

生成降序 ORDER BY 子句元素。

例如：

from sqlalchemy import desc

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

将生成 SQL，如下所示：

SELECT id, name FROM user ORDER BY name DESC

desc() 函数是 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 语句的 columns 子句中元素的名称，通常通过 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()
)

Changed in version 1.4: nulls_first() 在以前的版本中从 nullsfirst() 重命名。之前的名称仍然可用以实现向后兼容性。

另请参阅

asc()

desc()

nulls_last()

Select.order_by()

function sqlalchemy.sql.expression.nullsfirst()

nulls_first() 函数的同义词。

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

Changed in version 1.4: nulls_last() 在以前的版本中从 nullslast() 重命名。之前的名称仍然可用以实现向后兼容性。

另请参阅

asc()

desc()

nulls_first()

Select.order_by()

function sqlalchemy.sql.expression.nullslast()

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

Changed in version 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 值表示 “unbounded”(无界)，零值表示 “current row”(当前行)，负/正整数表示 “preceding”(之前的) 和 “following”(之后的)

• 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	定义 “unary” 表达式。
WithinGroup	表示 WITHIN GROUP (ORDER BY) 子句。
WrapsColumnExpression	混合类，将 ColumnElement 定义为包装器，该包装器为已经具有名称的表达式提供特殊的标签行为。

class sqlalchemy.sql.expression.BinaryExpression

表示一个表达式，该表达式为 LEFT <operator> RIGHT。

每当在 Python 二进制表达式中使用两个列表达式时，都会自动生成 BinaryExpression

>>> 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 属性的一般指南。

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

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

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

New in version 1.4.5.

另请参阅

第三方方言的缓存

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

class 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 和数据强制转换。

类签名

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

类 sqlalchemy.sql.expression.ClauseList

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

默认情况下，以逗号分隔，例如列清单。

成员

self_group()

类签名

类 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。

ClauseElement 的基本 self_group() 方法仅返回 self。

类 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 相同的所有功能，但在行为要求仅限于简单 SQL 表达式生成的情况下，ColumnClause 类本身也可以使用。 该对象没有与模式级元数据或 Column 具有的执行时行为的关联，因此从这个意义上讲，它是 Column 的“轻量级”版本。

关于 ColumnClause 用法的完整详细信息请参见 column()。

另请参阅

column()

列

成员

get_children()

类签名

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

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

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

这用于访问遍历。

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

类 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 实际存在于此 Selectable 的子元素中时，才为给定的 ColumnElement 返回相应的列。 通常，如果列仅与此 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 对象形式的输入，或者可以**强制转换**为该对象的输入。关于 SQL 表达式，大多数（但不是全部）SQLAlchemy Core 函数遵循的强制转换规则如下：

• 字面 Python 值，例如字符串、整数或浮点值、布尔值、日期时间、Decimal 对象，或几乎任何其他 Python 对象，都将被强制转换为“字面绑定值”。这通常意味着将生成一个 bindparam()，其中包含嵌入到构造中的给定值；生成的 BindParameter 对象是 ColumnElement 的实例。Python 值最终将在执行时作为 execute() 或 executemany() 方法的参数化参数发送到 DBAPI，在应用 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

inherited from the sqlalchemy.sql.expression.ColumnOperators.__eq__ method of ColumnOperators

实现 == 运算符。

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

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

inherited from the sqlalchemy.sql.expression.ColumnOperators.__le__ method of ColumnOperators

实现 <= 运算符。

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

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

inherited from the sqlalchemy.sql.expression.ColumnOperators.__lt__ method of ColumnOperators

实现 < 运算符。

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

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

inherited from the sqlalchemy.sql.expression.ColumnOperators.__ne__ method of ColumnOperators

实现 != 运算符。

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

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

inherited from the ColumnOperators.all_() method of ColumnOperators

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

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

注意

请务必不要将较新的 ColumnOperators.all_() 方法与此方法的**旧版**混淆，即特定于 ARRAY 的 Comparator.all() 方法，它使用不同的调用样式。

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

attribute sqlalchemy.sql.expression.ColumnElement.anon_key_label

Deprecated since version 1.4: ColumnElement.anon_key_label 属性现在是私有的，公共访问器已弃用。

attribute sqlalchemy.sql.expression.ColumnElement.anon_label

Deprecated since version 1.4: ColumnElement.anon_label 属性现在是私有的，公共访问器已弃用。

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

inherited from the ColumnOperators.any_() method of ColumnOperators

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

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

注意

请务必不要将较新的 ColumnOperators.any_() 方法与此方法的**旧版**混淆，即特定于 ARRAY 的 Comparator.any() 方法，它使用不同的调用样式。

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

inherited from the ColumnOperators.asc() method of ColumnOperators

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

attribute sqlalchemy.sql.expression.ColumnElement.base_columns

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

inherited from the ColumnOperators.between() method of ColumnOperators

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

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

inherited from the ColumnOperators.bitwise_and() method of ColumnOperators

执行按位与运算，通常通过 & 运算符实现。

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

执行按位或运算，通常通过 | 运算符实现。

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

attribute sqlalchemy.sql.expression.ColumnElement.comparator

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

继承自 ClauseElement.compare() 方法，属于 ClauseElement

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

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

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

method 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 表达式呈现为字符串，可能内联绑定参数？

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

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

实现 'concat' 运算符。

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

method 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 表达式。除非将 ColumnOperators.contains.autoescape 标志设置为 True，否则 LIKE 通配符 % 和 _ 默认情况下不会被转义。

• 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 表达式。除非将 ColumnOperators.endswith.autoescape 标志设置为 True，否则 LIKE 通配符 % 和 _ 默认情况下不会被转义。

• 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({})

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

继承自 HasTraverseInternals.get_children() 方法，属于 HasTraverseInternals

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

这用于访问遍历。

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

method 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 表达式。 除非将 ColumnOperators.icontains.autoescape 标志设置为 True，否则 LIKE 通配符 % 和 _ 默认情况下不会被转义。

• 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.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 表达式。 除非将 ColumnOperators.iendswith.autoescape 标志设置为 True，否则 LIKE 通配符 % 和 _ 默认情况下不会被转义。

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

  Changed in version 1.4: 在版本 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 (?, ?, ?)

  New in version 1.2: 在版本 1.2 中新增：“expanding” 绑定参数

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

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

  New in version 1.3: 在版本 1.3 中新增：“expanding” 绑定参数现在支持空列表

• 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() 构造，其中包含设置为 True 的 bindparam.expanding 标志。

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 操作符。

通常，当与 None 值比较时，会自动生成 IS，它解析为 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 操作符。

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

Changed in version 1.4: 在版本 1.4 中更改：is_not() 操作符从之前的版本中的 isnot() 重命名。为了向后兼容，之前的名称仍然可用。

另请参阅

ColumnOperators.is_()

method 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”。

Changed in version 1.4: 在版本 1.4 中更改：is_not_distinct_from() 操作符从之前的版本中的 isnot_distinct_from() 重命名。为了向后兼容，之前的名称仍然可用。

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

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

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

实现 IS NOT 操作符。

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

Changed in version 1.4: 在版本 1.4 中更改：is_not() 操作符从之前的版本中的 isnot() 重命名。为了向后兼容，之前的名称仍然可用。

另请参阅

ColumnOperators.is_()

method 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”。

Changed in version 1.4: 在版本 1.4 中更改：is_not_distinct_from() 操作符从之前的版本中的 isnot_distinct_from() 重命名。为了向后兼容，之前的名称仍然可用。

method 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 表达式。 除非将 ColumnOperators.istartswith.autoescape 标志设置为 True，否则 LIKE 通配符 % 和 _ 默认情况下不会被转义。

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

attribute sqlalchemy.sql.expression.ColumnElement.key: str | None = None

在某些情况下，‘key’ 指的是 Python 命名空间中的这个对象。

这通常指的是在可选择对象的 .c 集合中列的 “key”，例如 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 中变更: 现在 PostgreSQL 使用 plainto_tsquery() 而不是 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 是一个空序列，编译器将生成一个 “empty not in” 表达式。在所有情况下，这默认为表达式 “1 = 1” 以产生 true。可以使用 create_engine.empty_in_strategy 来更改此行为。

在版本 1.4 中变更: not_in() 运算符已从之前的版本中的 notin_() 重命名。之前的名称为了向后兼容仍然可用。

在版本 1.2 中变更: ColumnOperators.in_() 和 ColumnOperators.not_in() 运算符现在默认为空 IN 序列生成 “static” 表达式。

另请参阅

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 是一个空序列，编译器将生成一个 “empty not in” 表达式。在所有情况下，这默认为表达式 “1 = 1” 以产生 true。可以使用 create_engine.empty_in_strategy 来更改此行为。

在版本 1.4 中变更: not_in() 运算符已从之前的版本中的 notin_() 重命名。之前的名称为了向后兼容仍然可用。

在版本 1.2 中变更: ColumnOperators.in_() 和 ColumnOperators.not_in() 运算符现在默认为空 IN 序列生成 “static” 表达式。

另请参阅

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() 重命名。之前的名称为了向后兼容仍然可用。

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

继承自 ColumnOperators.nullslast() 方法，源于 ColumnOperators

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

在版本 1.4 中变更: nulls_last() 运算符已从之前的版本中的 nullslast() 重命名。之前的名称为了向后兼容仍然可用。

method 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，则该运算符将被视为 “comparison” 运算符，即评估为布尔值 true/false 的运算符，如 ==、> 等。提供此标志是为了让 ORM 关系可以确定该运算符是在自定义连接条件中使用时的比较运算符。

  使用 is_comparison 参数已被弃用，请改用 Operators.bool_op() 方法；这种更简洁的操作符会自动设置此参数，并且还提供正确的 PEP 484 类型提示支持，因为返回的对象将表示 “boolean” 数据类型，即 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()

重新定义和创建新的操作符

在 join 条件中使用自定义操作符

method 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 – 操作的 “other” 侧。对于大多数操作，这将是单个标量。

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

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

attribute sqlalchemy.sql.expression.ColumnElement.primary_key: bool = False

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

我们正在代理的所有列的集合

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

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

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

实现数据库特定的 “regexp match” 操作符。

例如：

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 Database - 渲染 REGEXP_LIKE(x, y)

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

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

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

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

参数:

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

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

1.4 版本新增。

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

另请参阅

ColumnOperators.regexp_replace()

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

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

实现数据库特定的 “regexp replace” 操作符。

例如：

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

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

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

参数:

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

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

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

1.4 版本新增。

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

另请参阅

ColumnOperators.regexp_match()

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

对参数执行反向操作。

用法与 operate() 相同。

method 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 仅返回 self。

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

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

method 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 表达式。除非将 ColumnOperators.startswith.autoescape 标志设置为 True，否则 LIKE 通配符 % 和 _ 默认情况下不会转义。

• 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.ColumnElement.stringify_dialect = 'default'

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

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

继承自 ColumnOperators.timetuple 属性，属于 ColumnOperators

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

attribute sqlalchemy.sql.expression.ColumnElement.type: TypeEngine[_T]

method 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，以便可以使用多个语句。

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

sqlalchemy.sql.expression.ColumnExpressionArgument

通用 “列表达式” 参数。

2.0.13 版本新增。

此类型用于 “column” 类型的表达式，这些表达式通常表示单个 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() 方法，它使用不同的调用样式。

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

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

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

注意

请务必不要将较新的 ColumnOperators.any_() 方法与此方法的**旧版**混淆，即特定于 ARRAY 的 Comparator.any() 方法，它使用不同的调用样式。

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

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

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

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

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

执行按位与运算，通常通过 & 运算符实现。

2.0.2 版本新增。

另请参阅

位运算符

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

执行按位左移运算，通常通过 << 运算符实现。

2.0.2 版本新增。

另请参阅

位运算符

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

执行按位非运算，通常通过 ~ 运算符实现。

2.0.2 版本新增。

另请参阅

位运算符

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

执行按位或运算，通常通过 | 运算符实现。

2.0.2 版本新增。

另请参阅

位运算符

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

执行按位右移运算，通常通过 >> 运算符实现。

2.0.2 版本新增。

另请参阅

位运算符

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

执行按位异或运算，通常通过 ^ 运算符，或 PostgreSQL 的 # 运算符实现。

2.0.2 版本新增。

另请参阅

位运算符

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

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

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

另请参阅

collate()

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

实现 'concat' 运算符。

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

method 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 表达式。除非将 ColumnOperators.contains.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。

• 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 表达式。除非将 ColumnOperators.endswith.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。

• 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 表达式。除非将 ColumnOperators.icontains.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。

• 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 表达式。除非将 ColumnOperators.iendswith.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。

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

  Changed in version 1.4: 在版本 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 (?, ?, ?)

  New in version 1.2: 在版本 1.2 中新增：“expanding” 绑定参数

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

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

  New in version 1.3: 在版本 1.3 中新增：“expanding” 绑定参数现在支持空列表

• 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() 构造。

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

实现 IS 操作符。

通常，当与 None 值比较时，会自动生成 IS，它解析为 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 操作符。

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

Changed in version 1.4: 在版本 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”。

Changed in version 1.4: 在版本 1.4 中更改：is_not_distinct_from() 操作符从之前的版本中的 isnot_distinct_from() 重命名。为了向后兼容，之前的名称仍然可用。

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

实现 IS NOT 操作符。

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

Changed in version 1.4: 在版本 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”。

Changed in version 1.4: 在版本 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 表达式。除非将 ColumnOperators.istartswith.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。

• 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 中变更: 现在 PostgreSQL 使用 plainto_tsquery() 而不是 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 是一个空序列，编译器将生成一个 “empty not in” 表达式。在所有情况下，这默认为表达式 “1 = 1” 以产生 true。可以使用 create_engine.empty_in_strategy 来更改此行为。

在版本 1.4 中变更: not_in() 运算符已从之前的版本中的 notin_() 重命名。之前的名称为了向后兼容仍然可用。

在版本 1.2 中变更: ColumnOperators.in_() 和 ColumnOperators.not_in() 运算符现在默认为空 IN 序列生成 “static” 表达式。

另请参阅

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

method 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 是一个空序列，编译器将生成一个 “empty not in” 表达式。在所有情况下，这默认为表达式 “1 = 1” 以产生 true。可以使用 create_engine.empty_in_strategy 来更改此行为。

在版本 1.4 中变更: not_in() 运算符已从之前的版本中的 notin_() 重命名。之前的名称为了向后兼容仍然可用。

在版本 1.2 中变更: ColumnOperators.in_() 和 ColumnOperators.not_in() 运算符现在默认为空 IN 序列生成 “static” 表达式。

另请参阅

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，则该运算符将被视为 “comparison” 运算符，即评估为布尔值 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()

重新定义和创建新的操作符

在 join 条件中使用自定义操作符

方法 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()。

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

实现数据库特定的 “regexp match” 操作符。

例如：

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 Database - 渲染 REGEXP_LIKE(x, y)

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

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

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

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

参数:

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

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

1.4 版本新增。

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

另请参阅

ColumnOperators.regexp_replace()

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

实现数据库特定的 “regexp replace” 操作符。

例如：

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

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

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

参数:

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

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

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

1.4 版本新增。

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

另请参阅

ColumnOperators.regexp_match()

方法 sqlalchemy.sql.expression.ColumnOperators.reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → Operators

继承自 Operators.reverse_operate() 方法，来自 Operators

对参数执行反向操作。

用法与 operate() 相同。

方法 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 表达式。除非将 ColumnOperators.startswith.autoescape 标志设置为 True，否则 LIKE 通配符 % 和 _ 默认情况下不进行转义。

• 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.ColumnOperators.timetuple: Literal[None] = None

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

类 sqlalchemy.sql.expression.Extract

表示 SQL EXTRACT 子句，extract(field FROM expr)。

类签名

类 sqlalchemy.sql.expression.Extract (sqlalchemy.sql.expression.ColumnElement)

类 sqlalchemy.sql.expression.False_

表示 SQL 语句中的 false 关键字或等效项。

False_ 作为常量通过 false() 函数访问。

类签名

类 sqlalchemy.sql.expression.False_ (sqlalchemy.sql.expression.SingletonConstant, sqlalchemy.sql.roles.ConstExprRole, sqlalchemy.sql.expression.ColumnElement)

类 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。

self_group() 的基本方法 ClauseElement 仅返回 self。

方法 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 仅返回自身。

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

类 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 使用。

方法 sqlalchemy.sql.expression.Operators.__and__(other: Any) → Operators

实现 & 运算符。

当与 SQL 表达式一起使用时，产生 AND 运算，等同于 and_()，即

a & b

等同于

from sqlalchemy import and_

and_(a, b)

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

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

方法 sqlalchemy.sql.expression.Operators.__invert__() → Operators

实现 ~ 运算符。

当与 SQL 表达式一起使用时，产生 NOT 运算，等同于 not_()，即

~a

等同于

from sqlalchemy import not_

not_(a)

方法 sqlalchemy.sql.expression.Operators.__or__(other: Any) → Operators

实现 | 运算符。

当与 SQL 表达式一起使用时，产生 OR 运算，等同于 or_()，即

a | b

等同于

from sqlalchemy import or_

or_(a, b)

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

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

方法 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()。

方法 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()

方法 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，则该运算符将被视为 “comparison” 运算符，即评估为布尔值 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()

重新定义和创建新的操作符

在 join 条件中使用自定义操作符

方法 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()。

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

对参数执行反向操作。

用法与 operate() 相同。

类 sqlalchemy.sql.expression.Over

表示 OVER 子句。

这是一个针对所谓“窗口”函数的特殊运算符，以及任何聚合函数，它产生相对于结果集本身的结果。大多数现代 SQL 后端现在都支持窗口函数。

成员

元素

类签名

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

属性 sqlalchemy.sql.expression.Over.element: ColumnElement[_T]

此 Over 对象引用的底层表达式对象。

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

类 sqlalchemy.sql.expression.TextClause

表示字面 SQL 文本片段。

例如：

from sqlalchemy import text

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

TextClause 结构是使用 text() 函数生成的；有关完整文档，请参阅该函数。

另请参阅

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)

方法 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()，第二次使用值信息调用，它将被组合

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

1.3.11 版本新增: 添加了对 BindParameter.unique 标志的支持，以用于 text() 结构。

方法 sqlalchemy.sql.expression.TextClause.columns(*cols: _ColumnExpressionArgument[Any], **types: _TypeEngineArgument[Any]) → TextualSelect

将此 TextClause 对象转换为 TextualSelect 对象，该对象的作用与 SELECT 语句相同。

TextualSelect 是 SelectBase 层级结构的一部分，可以通过使用 TextualSelect.subquery() 方法生成 Subquery 对象，然后可以从中进行 SELECT 操作，从而嵌入到另一个语句中。

此函数本质上弥合了完全文本化的 SELECT 语句与 SQL 表达式语言中 “selectable” 的概念之间的差距

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

在上面，我们以位置参数的形式将一系列 column() 元素传递给 TextClause.columns() 方法。这些 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() 以及针对文本 SELECT 语句的 SelectBase.cte()。

stmt = stmt.columns(id=Integer, name=String).cte("st")

stmt = select(sometable).where(sometable.c.id == stmt.c.id)

参数:

• *cols – 一系列 ColumnElement 对象，通常是来自 Column 对象的 Table 或 ORM 级别的列映射属性，表示此文本字符串将从中 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 Database 和 MS SQL Server。

WithinGroup 构造从方法 FunctionElement.within_group_type() 中提取其类型。如果这返回 None，则使用该函数的 .type。

成员

filter(), over()

类签名

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

method sqlalchemy.sql.expression.WithinGroup.filter(*criterion: _ColumnExpressionArgument[bool]) → Self | FunctionFilter[_T]

生成针对此函数的 FILTER 子句。

method 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() 相同的签名。

class sqlalchemy.sql.elements.WrapsColumnExpression

混合类，将 ColumnElement 定义为包装器，该包装器为已经具有名称的表达式提供特殊的标签行为。

1.4 版本新增。

另请参阅

改进了使用 CAST 或类似方法的简单列表达式的列标签

类签名

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

class sqlalchemy.sql.expression.True_

表示 SQL 语句中的 true 关键字或等效项。

True_ 通过 true() 函数作为常量访问。

类签名

class sqlalchemy.sql.expression.True_ (sqlalchemy.sql.expression.SingletonConstant, sqlalchemy.sql.roles.ConstExprRole, sqlalchemy.sql.expression.ColumnElement)

class sqlalchemy.sql.expression.TypeCoerce

表示 Python 端类型强制转换包装器。

TypeCoerce 提供 type_coerce() 函数；有关使用详情，请参阅该函数。

另请参阅

type_coerce()

cast()

成员

self_group()

类签名

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

method 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 仅返回 self。

class sqlalchemy.sql.expression.UnaryExpression

定义 “unary” 表达式。

一元表达式具有单个列表达式和一个运算符。 运算符可以位于列表达式的左侧（称为“运算符”）或右侧（称为“修饰符”）。

UnaryExpression 是几个一元运算符的基础，包括 desc()、asc()、distinct()、nulls_first() 和 nulls_last() 使用的运算符。

成员

self_group()

类签名

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

method 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 仅返回 self。

列元素类型实用程序

从 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 版本中的新功能。