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

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

列元素类文档

这里的类是使用 列元素基础构造函数 和 列元素修饰符构造函数 列出的构造函数生成的。

class sqlalchemy.sql.expression.BinaryExpression

代表一个LEFT  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 

类签名

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

类签名

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

attribute effective_value

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

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

attribute inherit_cache: bool | None = True

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

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

如果与对象对应的 SQL 不基于仅属于此类而不是其超类的属性更改，则可以在特定类上将此标志设置为True。

另请参阅

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

method render_literal_execute() → BindParameter[_T]

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

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

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

类签名

类 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() - 一种仅在 Python 端强制类型的 CAST 替代方法，通常足以生成正确的 SQL 和数据强制转换。

类签名

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

class 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）。

method self_group(against=None)

对此ClauseElement应用“分组”。

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

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

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

class sqlalchemy.sql.expression.ColumnClause

表示来自任何文本字符串的列表达式。

ColumnClause，类似于Column类的轻量级模拟，通常使用column()函数调用，如下所示：

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

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

SELECT id, name FROM user

ColumnClause是模式特定的Column对象的直接超类。虽然Column类具有与ColumnClause相同的所有功能，但ColumnClause类可单独使用，用于那些行为要求仅限于简单的 SQL 表达式生成的情况。该对象没有与模式级元数据或执行时行为相关的关联，因此在这个意义上是Column的“轻量级”版本。

ColumnClause用法的完整详细信息在column()。

另请参阅

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)

method get_children(*, column_tables=False, **kw)

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

这用于访问遍历。

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

class sqlalchemy.sql.expression.ColumnCollection

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

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

ColumnCollection 具有类似映射和序列的行为。 ColumnCollection 通常存储 Column 对象，然后可以通过映射样式访问以及属性访问样式访问。

要使用普通属性样式访问方式访问 Column 对象，请像访问任何其他对象属性一样指定名称，例如下面访问了一个名为 employee_name 的列：

>>> employee_table.c.employee_name

要访问具有特殊字符或空格名称的列，使用索引样式访问，例如下面演示了如何访问名为 employee ' payment 的列：

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

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

>>> employee_table.c["values"]

通常情况下，Column存在的名称是 Column.key 参数的值。在某些上下文中，例如使用 Select.set_label_style() 方法设置标签样式的 Select 对象，某个键的列可能被表示为特定标签名称，如tablename_columnname：

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

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

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

从 1.4 版开始：ColumnCollection 允许基于整数的索引访问集合。

遍历集合按顺序产生列表达式：

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

基本的ColumnCollection对象可以存储重复项，这可能意味着具有相同键的两个列，此时通过键访问返回的列是任意的：

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

或者它也可以多次表示相同的列。这些情况是支持的，因为ColumnCollection用于表示 SELECT 语句中的列，该语句可能包含重复项。

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

自版本 1.4 更改：ColumnCollection现在也存储重复的列键以及同一列在多个位置的情况。在这些情况下，添加了DedupeColumnCollection类以保持以前的行为，其中需要去重以及额外的替换/移除操作。

成员

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

类签名

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

method add(column: ColumnElement[Any], key: _COLKEY | None = None) → None

向这个ColumnCollection添加一列。

注意

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

method as_readonly() → ReadOnlyColumnCollection[_COLKEY, _COL_co]

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

method clear() → NoReturn

对于ColumnCollection，未实现字典清除()。

method compare(other: ColumnCollection[Any, Any]) → bool

根据键的名称将此ColumnCollection与另一个进行比较

method contains_column(col: ColumnElement[Any]) → bool

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

method corresponding_column(column: _COL, require_embedded: bool = False) → _COL | _COL_co | None

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

参数：

• column – 要匹配的目标ColumnElement。
  
• require_embedded – 仅在给定的ColumnElement实际存在于此Selectable的子元素中时返回相应的列。通常，如果列仅与此Selectable的导出列之一共享共同的祖先，则列将匹配。
  

另请参阅

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

在 1.4 版本中更改：corresponding_column的实现已移至ColumnCollection本身。

method get(key: str, default: _COL_co | None = None) → _COL_co | None

基于此ColumnCollection中的字符串键名获取一个ColumnClause或Column对象。

method items() → List[Tuple[_COLKEY, _COL_co]]

为此集合中的所有列返回一个(key, column)元组序列，每个元组由一个字符串键名和ColumnClause或Column对象组成。

method keys() → List[_COLKEY]

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

method update(iter_: Any) → NoReturn

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

method values() → List[_COL_co]

为此集合中的所有列返回一个ColumnClause或Column对象序列。

class sqlalchemy.sql.expression.ColumnElement

表示适用于语句的“columns”子句、WHERE 子句等的面向列的 SQL 表达式。

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

一系列广泛的 SQLAlchemy 核心函数在 SQL 表达式级别工作，并旨在接受ColumnElement的实例作为参数。这些函数通常会记录它们接受一个“SQL 表达式”作为参数。在 SQLAlchemy 中，这通常指的是一个已经是ColumnElement对象形式的输入，或者可以强制转换为其中一个的值。大多数 SQLAlchemy 核心函数关于 SQL 表达式的强制转换规则如下：

• 一个字面的 Python 值，比如字符串、整数或浮点值、布尔值、日期时间、Decimal对象，或者几乎任何其他 Python 对象，都将被强制转换为“字面绑定值”。这通常意味着将生成一个包含给定值嵌入到结构中的bindparam()；最终产生的BindParameter对象是ColumnElement的一个实例。Python 值最终将在执行时作为参数化参数传递给execute()或executemany()方法，之后会应用 SQLAlchemy 类型特定的转换器（例如任何相关的TypeEngine对象提供的转换器）。
• 
  
• 任何特殊对象值，通常是 ORM 级别的构造，其中包含一个名为__clause_element__()的访问器。当将一个否则未知类型的对象传递给一个希望将参数强制转换为ColumnElement和有时是SelectBase表达式的函数时，核心表达式系统会查找这个方法。在 ORM 中，它用于将 ORM 特定的对象（如映射类和映射属性）转换为核心表达式对象。
• 
  
• 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

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

类签名

类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 __eq__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__eq__ 方法的 ColumnOperators

实现==运算符。

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

method __le__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__le__ 方法的 ColumnOperators

实现<=运算符。

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

method __lt__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__lt__ 方法的 ColumnOperators

实现<运算符。

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

method __ne__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__ne__ 方法的 ColumnOperators

实现!=运算符。

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

method all_() → ColumnOperators

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

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

请参阅all_()的文档以获取示例。

注意

一定要注意不要将新的ColumnOperators.all_()方法与旧版方法混淆，旧版方法是Comparator.all()方法，该方法专用于ARRAY，其使用不同的调用风格。

attribute allows_lambda = True

attribute anon_key_label

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

attribute anon_label

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

method any_() → ColumnOperators

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

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

查看 any_() 的文档以获取示例。

注意

请确保不要混淆较新的 ColumnOperators.any_() 方法与这个方法的传统版本，即特定于 ARRAY 的 Comparator.any() 方法，它使用不同的调用风格。

method asc() → ColumnOperators

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

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

attribute base_columns

method between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators

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

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

method bitwise_and(other: Any) → ColumnOperators

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

产生一个按位与操作，通常通过&运算符实现。

新版本 2.0.2 中新增。

另请参阅

位运算符

method bitwise_lshift(other: Any) → ColumnOperators

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

执行按位 LSHIFT 操作，通常通过 << 运算符。

版本 2.0.2 中的新内容。

另请参阅

按位运算符

method bitwise_not() → ColumnOperators

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

执行按位 NOT 操作，通常通过 ~ 运算符。

版本 2.0.2 中的新内容。

另请参阅

按位运算符

method bitwise_or(other: Any) → ColumnOperators

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

执行按位 OR 操作，通常通过 | 运算符。

版本 2.0.2 中的新内容。

另请参阅

按位运算符

method bitwise_rshift(other: Any) → ColumnOperators

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

执行按位 RSHIFT 操作，通常通过 >> 运算符。

版本 2.0.2 中的新内容。

另请参阅

按位运算符

method bitwise_xor(other: Any) → ColumnOperators

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

执行按位异或操作，通常通过 ^ 运算符，或者对于 PostgreSQL 是 #。

版本 2.0.2 中的新内容。

另请参阅

按位运算符

method 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 cast(type_: _TypeEngineArgument[_OPT]) → Cast[_OPT]

产生一个类型转换，即 CAST( AS )。

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

另请参阅

数据转换和类型强制转换

cast()

type_coerce()

method collate(collation: str) → ColumnOperators

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

产生一个针对父对象的 collate() 子句，给定排序字符串。

另请参阅

collate()

attribute comparator

method compare(other: ClauseElement, **kw: Any) → bool

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

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

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

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

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

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

编译这个 SQL 表达式。

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

参数：

• bind – 一个 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 concat(other: Any) → ColumnOperators

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

实现 ‘concat’ 运算符。

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

method contains(other: Any, **kw: Any) → ColumnOperators

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

实现 ‘contains’ 运算符。

产生一个 LIKE 表达式，用于测试字符串值中间的匹配：

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

例如：

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

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

参数：

• other – 待比较的表达式。通常是纯字符串值，但也可以是任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非设置了 ColumnOperators.contains.autoescape 标志为 True。
  
• autoescape –
  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中所有的 "%"、"_" 和转义字符本身的出现次数，假定比较值为字面字符串而不是 SQL 表达式。
  诸如以下表达式：

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

• 将呈现为：

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

• 值为 :param 的情况下为 "foo/%bar"。
• escape –
  一个字符，当给定时，将呈现为带有 ESCAPE 关键字以将该字符设定为转义字符。然后，可以将该字符放置在 % 和 _ 的前面，以允许它们作为自身而不是通配符字符。
  诸如以下表达式：

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

• 将呈现为：

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

• 参数也可以与 ColumnOperators.contains.autoescape 结合使用：

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

• 在上述情况下，给定的字面参数将在传递到数据库之前转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.startswith()

ColumnOperators.endswith()

ColumnOperators.like()

method desc() → ColumnOperators

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

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

attribute description

继承自 ClauseElement 的 ClauseElement.description 属性

method distinct() → ColumnOperators

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

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

method 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，在表达式中存在的通配符字符"%"和"_"也将像通配符一样工作。对于文字字符串值，可能会将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 entity_namespace

继承自 ClauseElement 的 ClauseElement.entity_namespace 属性

attribute expression

返回列表达式。

检查界面的一部分；返回自身。

attribute foreign_keys: AbstractSet[ForeignKey] = frozenset({})

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

继承自 HasTraverseInternals 的 HasTraverseInternals.get_children() 方法

返回此HasTraverseInternals的即时子元素。

这用于访问遍历。

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

method 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，因此存在于表达式中的通配符字符"%"和"_"也将像通配符一样行事。对于字面字符串值，可以将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 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，因此在表达式中存在的通配符字符"%"和"_"也将像通配符一样起作用。对于文字字符串值，可以将ColumnOperators.iendswith.autoescape标志设置为True，以对字符串值中这些字符的出现应用转义，使它们作为自身而不是通配符字符进行匹配。或者，ColumnOperators.iendswith.escape参数将建立一个给定字符作为转义字符，当目标表达式不是文字字符串时，这可能会有用。

参数：

• other – 要比较的表达式。通常是一个简单的字符串值，但也可以是任意的 SQL 表达式。默认情况下，LIKE 通配符字符 % 和 _ 不会被转义，除非将 ColumnOperators.iendswith.autoescape 标志设置为 True。
  
• autoescape –
  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值内的所有 "%"、"_" 和转义字符本身的出现，假设比较值是一个文字字符串而不是一个 SQL 表达式。
  诸如：

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

• 将渲染为：

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

• 其中，:param 的值为 "foo/%bar"。
• escape –
  给定的字符会与 ESCAPE 关键字一起渲染，以将该字符确定为转义字符。然后可以将此字符放置在 % 和 _ 的前面，以使它们能够充当它们自己而不是通配符字符。
  诸如：

somecolumn.iendswith("foo/%bar", escape

• 将渲染为：

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

• 该参数也可以与ColumnOperators.iendswith.autoescape结合使用：

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

• 上述情况下，给定的文字参数将在传递到数据库之前转换为 "foo^%bar^^bat"。

另请参见

ColumnOperators.endswith()

method 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 in_(other: Any) → ColumnOperators

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

实现 in 运算符。

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

给定参数 other 可能是：

• 字面值的列表，例如：

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

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

WHERE COL IN (?, ?, ?)

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

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

• 空列表，例如：

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

• 在此调用形式中，该表达式呈现一个“空集”表达式。这些表达式针对各个后端进行了定制，并且通常试图将空 SELECT 语句作为子查询。例如在 SQLite 上，该表达式是：

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

• 在 1.4 版本中更改：所有情况下，空 IN 表达式现在都使用执行时生成的 SELECT 子查询。
• 如果包括 bindparam.expanding 标志，则可以使用绑定参数，例如 bindparam()：

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

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

WHERE COL IN ([EXPANDING_value])

• 此占位符表达式在语句执行时被拦截，以转换为前面示例中的变量数量的绑定参数形式。如果执行语句为：

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

• 对于每个值，数据库将传递一个绑定参数：

WHERE COL IN (?, ?, 

• 1.2 版本中的新功能：添加了“expanding”绑定参数
  如果传递了空列表，则会呈现一个特殊的“空列表”表达式，该表达式特定于正在使用的数据库。在 SQLite 上，这将是：

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

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

参数：

其他 – 一组文字，select() 构造，或者包括 bindparam() 构造的 bindparam() 构造，并将 bindparam.expanding 标志设置为 True。

attribute inherit_cache: bool | None = None

继承自 HasCacheKey 的 HasCacheKey.inherit_cache 属性

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

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

如果对象对于本类是本地的，而不是其超类，则可以在特定类上将此标志设置为True，如果 SQL 不基于本类的属性而变化。

另请参见

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

method is_(other: Any) → ColumnOperators

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

实现 IS 运算符。

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

另请参见

ColumnOperators.is_not()

attribute is_clause_element = True

method 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 is_dml = False

method is_not(other: Any) → ColumnOperators

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

实现 IS NOT 运算符。

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

在版本 1.4 中更改：is_not() 运算符从先前的发布中重命名为 isnot()。以前的名称仍然可用以保持向后兼容性。

另请参见

ColumnOperators.is_()

method is_not_distinct_from(other: Any) → ColumnOperators

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

实现 IS NOT DISTINCT FROM 运算符。

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

在版本 1.4 中更改：is_not_distinct_from() 运算符从先前的发布中重命名为 isnot_distinct_from()。以前的名称仍然可用以保持向后兼容性。

attribute is_selectable = False

method isnot(other: Any) → ColumnOperators

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

实现IS NOT运算符。

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

在 1.4 版本中更改：is_not()运算符从以前的版本中的isnot()更名。以前的名称仍然可用于向后兼容。

另请参阅

ColumnOperators.is_()

method isnot_distinct_from(other: Any) → ColumnOperators

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

实现IS NOT DISTINCT FROM运算符。

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

在 1.4 版本中更改：is_not_distinct_from()运算符从以前的版本中的isnot_distinct_from()更名。以前的名称仍然可用于向后兼容。

method 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，因此存在于表达式中的通配符字符"%"和"_"也将像通配符一样行为。对于字面字符串值，可以将ColumnOperators.istartswith.autoescape标志设置为True，以对字符串值中这些字符的出现应用转义，以使它们与自身匹配而不是作为通配符字符。或者，ColumnOperators.istartswith.escape参数将建立一个给定的字符作为转义字符，当目标表达式不是字面字符串时可能会有用。

参数：

• other – 要比较的表达式。通常这是一个普通的字符串值，但也可以是任意的 SQL 表达式。默认情况下，LIKE 通配符%和_不会被转义，除非ColumnOperators.istartswith.autoescape标志设置为 True。
  
• autoescape –
  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中的所有出现的"%"、"_"和转义字符本身，假定比较值为字面字符串而不是 SQL 表达式。
  诸如下面的表达式：

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

• 将呈现为：

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

• 值为:param的"foo/%bar"。
• escape –
  一个字符，给定时将使用ESCAPE关键字来建立该字符作为转义字符。然后，可以将此字符放置在%和_之前，以允许它们充当自身而不是通配符字符。
  诸如下面的表达式：

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

• 将呈现为：

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

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

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

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

另请参阅

ColumnOperators.startswith()

attribute key: str | None = None

在某些情况下指的是 Python 命名空间中的对象的“键”。

这通常是指在可选择的.c集合中出现的列的“键”，例如sometable.c["somekey"]将返回具有“somekey”.key的Column。

method label(name: str | None) → Label[_T]

生成列标签，即 AS 。

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

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

method 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 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 negation_clause: ColumnElement[bool]

method 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 not_in(other: Any) → ColumnOperators

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

实现NOT IN运算符。

这等同于使用ColumnOperators.in_()进行否定，即 ~x.in_(y)。

如果other是一个空序列，编译器会生成一个“空 not in”表达式。默认情况下，这会产生表达式“1 = 1”，以在所有情况下产生 true。可以使用create_engine.empty_in_strategy来更改这种行为。

在版本 1.4 中更改：not_in()运算符从先前版本的notin_()重命名。以前的名称仍可用于向后兼容。

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

请参见

ColumnOperators.in_()

method 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 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 notin_(other: Any) → ColumnOperators

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

实现NOT IN运算符。

这相当于使用带有ColumnOperators.in_()的否定，即~x.in_(y)。

在other为空序列的情况下，编译器生成一个“空 not in”表达式。这默认为表达式“1 = 1”，以在所有情况下产生 true。create_engine.empty_in_strategy 可用于更改此行为。

在版本 1.4 中发生了变化：not_in() 运算符从之前的版本中的 notin_() 重新命名。以前的名称仍然可用于向后兼容。

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

另请参见

ColumnOperators.in_()

method 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 nulls_first() → ColumnOperators

从 ColumnOperators.nulls_first() 方法继承 自 ColumnOperators。

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

在版本 1.4 中发生了变化：nulls_first() 运算符从之前的版本中的 nullsfirst() 重新命名。以前的名称仍然可用于向后兼容。

method nulls_last() → ColumnOperators

从 ColumnOperators.nulls_last() 方法继承 自 ColumnOperators。

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

在版本 1.4 中发生了变化：nulls_last() 运算符从之前的版本中的 nullslast() 重新命名。以前的名称仍然可用于向后兼容。

method nullsfirst() → ColumnOperators

从 ColumnOperators.nullsfirst() 方法继承 自 ColumnOperators。

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

在 1.4 版本中更改：nulls_first()运算符从先前的版本中的nullsfirst()重命名。之前的名称仍然可用于向后兼容。

method nullslast() → ColumnOperators

继承自 ColumnOperators.nullslast() 方法 ColumnOperators

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

在 1.4 版本中更改：nulls_last()运算符从先前的版本中的nullslast()重命名。之前的名称仍然可用于向后兼容。

method op(opstring: str, precedence: int = 0, is_comparison: bool = False, return_type: Type[TypeEngine[Any]] | TypeEngine[Any] | None = None, python_impl: Callable[..., Any] | None = None) → Callable[[Any], Operators]

继承自 Operators.op() 方法 Operators

生成通用运算符函数。

例如：

somecolumn.op("*")(5)

产生：

somecolumn * 5

此函数也可用于使位运算符明确化。例如：

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

是somecolumn中的值的按位与。

参数：

• opstring – 将作为此元素与传递给生成函数的表达式之间的中缀运算符输出的字符串。
  
• precedence –
  数据库预期应用于 SQL 表达式中的运算符的优先级。这个整数值作为一个提示，让 SQL 编译器知道何时应该在特定操作周围渲染明确的括号。较低的数字将导致在与具有更高优先级的另一个运算符应用时对表达式进行括号化。默认值为0，低于所有运算符，除了逗号（,）和AS运算符。值为 100 将高于或等于所有运算符，-100 将低于或等于所有运算符。
  另见
  我使用 op()生成自定义运算符，但我的括号没有正确显示 - SQLAlchemy SQL 编译器如何渲染括号的详细描述
  
• is_comparison –
  传统上；如果为 True，则该运算符将被视为“比较”运算符，即评估为布尔值 true/false 的运算符，例如==、>等。提供此标志是为了让 ORM 关系在自定义连接条件中使用时确认该运算符是一个比较运算符。
  使用is_comparison参数已经被使用Operators.bool_op()方法取代；这个更简洁的运算符会自动设置该参数，但也会提供正确的PEP 484类型支持，因为返回的对象将表达“布尔”数据类型，即BinaryExpression[bool]。
  
• return_type – 一个TypeEngine 类或对象，将强制此运算符生成的表达式的返回类型为该类型。默认情况下，指定了Operators.op.is_comparison的运算符将解析为Boolean，而没有指定的运算符将与左操作数的类型相同。
  
• python_impl –
  一个可选的 Python 函数，可以以与数据库服务器上运行此运算符时相同的方式评估两个 Python 值。用于在 Python 中的 SQL 表达式评估函数，例如 ORM 混合属性，以及在多行更新或删除后用于匹配会话中的对象的 ORM“评估器”。
  例如：

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

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

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

• 2.0 版中的新功能。

另请参阅

Operators.bool_op()

重新定义和创建新的运算符

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

method operate(op: OperatorType, *other: Any, **kwargs: Any) → ColumnElement[Any]

对参数进行操作。

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

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

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

参数：

• op – 运算符可调用。
  
• *other – 操作的“另一侧”。对于大多数操作，将是一个单一的标量。
  
• **kwargs – 修饰符。这些可以通过特殊的运算符传递，比如ColumnOperators.contains()。
  

method params(_ClauseElement__optionaldict: Mapping[str, Any] | None = None, **kwargs: Any) → Self

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

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

返回一个将 bindparam() 元素替换为给定字典中的值的此 ClauseElement 的副本：

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

attribute primary_key: bool = False

attribute proxy_set: util.generic_fn_descriptor[FrozenSet[Any]]

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

从 2.0 开始，这是显式的去注释列。之前它实际上是去注释的列，但并没有被强制执行。注释列应该尽可能不要进入集合，因为它们的哈希行为非常低效。

method regexp_match(pattern: Any, flags: str | None = None) → ColumnOperators

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

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

例如：

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

ColumnOperators.regexp_match() 试图解析为后端提供的类似于 REGEXP 的函数或操作符，但是具体的正则表达式语法和可用的标志并不是后端无关的。

示例包括：

• PostgreSQL - 在否定时渲染 x ~ y 或 x !~ y。
  
• Oracle - 渲染 REGEXP_LIKE(x, y)
  
• SQLite - 使用 SQLite 的 REGEXP 占位符运算符，并调用 Python 的 re.match() 内置函数。
  
• 其他后端可能提供特殊的实现。
  
• 没有任何特殊实现的后端将作为“REGEXP”或“NOT REGEXP”发出该操作符。例如，这与 SQLite 和 MySQL 兼容。
  

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

参数：

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

1.4 版本中的新功能。

在版本 1.4.48 改变：2.0.18 注意，由于一个实现错误，“flags”参数先前接受了 SQL 表达式对象，如列表达式，除了普通的  Python 字符串。这种实现与缓存一起使用时不能正常工作，已被删除；应该只传递字符串作为“flags”参数，因为这些标志在 SQL  表达式中被呈现为文字内联值。

另请参见

ColumnOperators.regexp_replace()

method regexp_replace(pattern: Any, replacement: Any, flags: str | None = None) → ColumnOperators

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

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

例如：

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

ColumnOperators.regexp_replace() 试图解析后端提供的类似 REGEXP_REPLACE 的函数，通常会生成函数 REGEXP_REPLACE()。但是，具体的正则表达式语法和可用标志不是跨后端的。

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

参数：

• pattern – 正则表达式模式字符串或列子句。
  
• pattern – 替换字符串或列子句。
  
• flags – 要应用的任何正则表达式字符串标志，仅传递为普通的 Python 字符串。这些标志是特定于后端的。一些后端，如 PostgreSQL 和 MariaDB，可能会将标志作为模式的一部分来指定。
  

新版版本 1.4。

在版本 1.4.48 改动：2.0.18 请注意，由于实现错误，之前“flags”参数接受 SQL  表达式对象，例如列表达式，而不仅限于普通的 Python  字符串。这种实现与缓存不兼容，并已删除；应仅传递字符串作为“flags”参数，因为这些标志会作为 SQL 表达式中的文字内联值呈现。

另请参阅

ColumnOperators.regexp_match()

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

在参数上执行反向操作。

使用方法与 operate() 相同。

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

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

method shares_lineage(othercolumn: ColumnElement[Any]) → bool

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

method startswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

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

实现 startswith 操作符。

生成一个 LIKE 表达式，用于测试字符串值的开头是否匹配：

column LIKE <other> || '%'

例如：

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

由于操作符使用 LIKE，存在于 表达式中的通配符字符 "%" 和 "_" 也会像通配符一样起作用。对于字面字符串值，可以将 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 stringify_dialect = 'default'

attribute supports_execution = False

attribute timetuple: Literal[None] = None

继承自 ColumnOperators.timetuple 属性的 ColumnOperators

Hack，允许将日期时间对象与左侧进行比较。

attribute type: TypeEngine[_T]

method unique_params(_ClauseElement__optionaldict: Dict[str, Any] | None = None, **kwargs: Any) → Self

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

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

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

attribute uses_inspection = True

sqlalchemy.sql.expression.ColumnExpressionArgument

通用“列表达式”参数。

新版本 2.0.13 中新增。

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

class sqlalchemy.sql.expression.ColumnOperators

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

默认情况下，所有方法都调用 operate() 或 reverse_operate()，传入 Python 内置 operator 模块的适当运算符函数或来自 sqlalchemy.expression.operators 的特定于 SQLAlchemy 的运算符函数。例如 __eq__ 函数：

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

当 operators.eq 实际上是：

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

核心列表达单元 ColumnElement 覆盖 Operators.operate() 和其他方法以返回更多的 ColumnElement 构造，因此上述的 == 操作被替换为一个子句构造。

另请参阅

重新定义和创建新的运算符

TypeEngine.comparator_factory

ColumnOperators

PropComparator

成员

add(), and(), eq(), floordiv(), ge(), getitem(), gt(), hash(), invert(), le(), lshift(), lt(), mod(), mul(), ne(), neg(), or(), radd(), rfloordiv(), rmod(), rmul(), rshift(), rsub(), rtruediv(), sa_operate(), sub(), truediv(),  all_(), any_(), asc(), between(), bitwise_and(), bitwise_lshift(),  bitwise_not(), bitwise_or(), bitwise_rshift(), bitwise_xor(), bool_op(),  collate(), concat(), contains(), desc(), distinct(), endswith(),  icontains(), iendswith(), ilike(), in_(), is_(), is_distinct_from(),  is_not(), is_not_distinct_from(), isnot(), isnot_distinct_from(),  istartswith(), like(), match(), not_ilike(), not_in(), not_like(),  notilike(), notin_(), notlike(), nulls_first(), nulls_last(),  nullsfirst(), nullslast(), op(), operate(), regexp_match(),  regexp_replace(), reverse_operate(), startswith(), timetuple

类签名

类sqlalchemy.sql.expression.ColumnOperators（sqlalchemy.sql.expression.Operators）

method __add__(other: Any) → ColumnOperators

实现+运算符。

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

method __and__(other: Any) → Operators

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

实现&运算符。

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

a & b

等同于：

from sqlalchemy import and_
and_(a, b)

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

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

method __eq__(other: Any) → ColumnOperators

实现==运算符。

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

method __floordiv__(other: Any) → ColumnOperators

实现//运算符。

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

版本 2.0 中的新功能。

method __ge__(other: Any) → ColumnOperators

实现>=运算符。

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

method __getitem__(index: Any) → ColumnOperators

实现[]运算符。

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

method __gt__(other: Any) → ColumnOperators

实现>运算符。

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

method __hash__()

返回hash(self)。

method __invert__() → Operators

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

实现~运算符。

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

~a

等同于：

from sqlalchemy import not_
not_(a)

method __le__(other: Any) → ColumnOperators

实现<=运算符。

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

method __lshift__(other: Any) → ColumnOperators

实现<<运算符。

不被 SQLAlchemy 核心使用，这是为想要使用 << 作为扩展点的自定义运算符系统提供的。

method __lt__(other: Any) → ColumnOperators

实现<运算符。

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

method __mod__(other: Any) → ColumnOperators

实现%运算符。

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

method __mul__(other: Any) → ColumnOperators

实现*运算符。

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

method __ne__(other: Any) → ColumnOperators

实现!=运算符。

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

method __neg__() → ColumnOperators

实现-运算符。

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

method __or__(other: Any) → Operators

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

实现 | 运算符。

在与 SQL 表达式一起使用时，导致 OR 操作的结果，等效于 or_()，即：

a | b

等价于：

from sqlalchemy import or_
or_(a, b)

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

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

method __radd__(other: Any) → ColumnOperators

以反向方式实现 + 运算符。

参见 ColumnOperators.__add__()。

method __rfloordiv__(other: Any) → ColumnOperators

以反向方式实现 // 运算符。

参见 ColumnOperators.__floordiv__()。

method __rmod__(other: Any) → ColumnOperators

以反向方式实现 % 运算符。

参见 ColumnOperators.__mod__()。

method __rmul__(other: Any) → ColumnOperators

以反向方式实现 * 运算符。

参见 ColumnOperators.__mul__()。

method __rshift__(other: Any) → ColumnOperators

实现 >> 运算符。

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

method __rsub__(other: Any) → ColumnOperators

以反向方式实现 - 运算符。

参见 ColumnOperators.__sub__()。

method __rtruediv__(other: Any) → ColumnOperators

以反向方式实现 / 运算符。

参见 ColumnOperators.__truediv__()。

method __sa_operate__(op: OperatorType, *other: Any, **kwargs: Any) → Operators

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

对参数进行操作。

这是操作的最低级别，默认引发 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 __sub__(other: Any) → ColumnOperators

实现 - 运算符。

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

method __truediv__(other: Any) → ColumnOperators

实现 / 运算符。

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

2.0 版本中的更改：针对两个整数的 truediv 运算现在被认为返回数值。在特定后端上的行为可能会有所不同。

method all_() → ColumnOperators

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

请参阅 all_() 的文档以获取示例。

注意

请务必不要将较新的 ColumnOperators.all_() 方法与此方法的传统版本混淆，即 Comparator.all() 方法，该方法专用于 ARRAY，其使用不同的调用样式。

method any_() → ColumnOperators

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

请参阅 any_() 的文档以获取示例。

注意

请务必不要将较新的 ColumnOperators.any_() 方法与此方法的传统版本混淆，即 Comparator.any() 方法，该方法专用于 ARRAY，其使用不同的调用样式。

method asc() → ColumnOperators

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

method between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators

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

method bitwise_and(other: Any) → ColumnOperators

执行按位 AND 运算，通常通过 & 运算符执行。

新版本 2.0.2 中的更新。

另请参阅

按位运算符

method bitwise_lshift(other: Any) → ColumnOperators

执行按位 LSHIFT 运算，通常通过 << 运算符执行。

新版本 2.0.2 中的更新。

另请参阅

按位运算符

method bitwise_not() → ColumnOperators

执行按位 NOT 运算，通常通过 ~ 运算符执行。

新版本 2.0.2 中的更新。

另请参阅

按位运算符

method bitwise_or(other: Any) → ColumnOperators

执行按位 OR 运算，通常通过 | 运算符执行。

新版本 2.0.2 中的更新。

另请参阅

按位运算符

method bitwise_rshift(other: Any) → ColumnOperators

执行按位 RSHIFT 运算，通常通过 >> 运算符执行。

新版本 2.0.2 中的更新。

另请参阅

按位运算符

method bitwise_xor(other: Any) → ColumnOperators

执行按位 XOR 运算，通常通过 ^ 运算符执行，或 PostgreSQL 中使用 #。

新版本 2.0.2 中的更新。

另请参阅

按位运算符

method 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 collate(collation: str) → ColumnOperators

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

另见

collate()

method concat(other: Any) → ColumnOperators

实现‘concat’运算符。

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

method contains(other: Any, **kw: Any) → ColumnOperators

实现‘contains’运算符。

生成针对字符串值中间的匹配的 LIKE 表达式：

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

例如：

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

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

参数：

• other – 要比较的表达式。通常这是一个简单的字符串值，但也可以是任意的 SQL 表达式。除非将ColumnOperators.contains.autoescape标志设置为 True，否则 LIKE 通配符字符%和_不会被转义。
  
• autoescape –
  boolean；当为 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 desc() → ColumnOperators

产生一个针对父对象的 desc() 子句。

method distinct() → ColumnOperators

产生一个针对父对象的 distinct() 子句。

method 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，因此在 表达式中存在的通配符字符 "%" 和 "_" 也会像通配符一样起作用。对于字面字符串值，可以将 ColumnOperators.endswith.autoescape 标志设置为 True，以对字符串值中这些字符的出现进行转义，使它们与自身匹配而不是作为通配符字符。或者，ColumnOperators.endswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是字面字符串时，这可能是有用的。

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