SqlAlchemy 2.0 中文文档(三十四)(4)https://developer.aliyun.com/article/1562871
列元素类文档
这里的类是使用列元素基础构造函数和列元素修饰符构造函数列出的构造函数生成的。
对象名称 | 描述 |
BinaryExpression | 代表一个LEFT <operator> RIGHT 的表达式。 |
BindParameter | 代表一个“绑定表达式”。 |
Case | 代表一个CASE 表达式。 |
Cast | 代表一个CAST 表达式。 |
ClauseList | 描述由运算符分隔的子句列表。 |
ColumnClause | 代表来自任何文本字符串的列表达式。 |
ColumnCollection | 包含ColumnElement 实例的集合,通常用于FromClause 对象。 |
ColumnElement | 代表一个以列为导向的 SQL 表达式,适用于语句的“columns”子句、WHERE 子句等。 |
ColumnExpressionArgument | 通用的“列表达式”参数。 |
ColumnOperators | 为 ColumnElement 表达式定义布尔、比较和其他运算符。 |
Extract | 代表一个 SQL EXTRACT 子句,extract(field FROM expr) 。 |
False_ | 代表 SQL 语句中的 false 关键字或等效项。 |
FunctionFilter | 代表一个函数 FILTER 子句。 |
Label | 表示列标签 (AS)。 |
Null | 代表 SQL 语句中的 NULL 关键字。 |
Operators | 比较和逻辑运算符的基础。 |
Over | 代表一个 OVER 子句。 |
SQLColumnExpression | 可以用来表示任何 SQL 列元素或充当之一的对象的类型。 |
TextClause | 代表一个文字 SQL 文本片段。 |
True_ | 代表 SQL 语句中的 true 关键字或等效项。 |
TryCast | 代表一个 TRY_CAST 表达式。 |
Tuple | 代表一个 SQL 元组。 |
TypeCoerce | 代表一个 Python 端的类型强制转换包装器。 |
UnaryExpression | 定义一个‘一元’表达式。 |
WithinGroup | 代表一个 WITHIN GROUP (ORDER BY) 子句。 |
WrapsColumnExpression | 定义一个 ColumnElement 作为具有特殊标签行为的包装器的混合。 |
class sqlalchemy.sql.expression.BinaryExpression
代表一个 LEFT <operator> RIGHT
的表达式。
当两个列表达式在 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 端仅强制类型的替代方法,通常足以生成正确的 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()
的 FROM 子句中时被select()
构造使用。(请注意,子查询通常应使用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
。要将Column
添加到现有的Table
对象中,请使用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 值最终将在执行时作为参数化参数传递给 DBAPI,作为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
继承自 ColumnOperators
的 sqlalchemy.sql.expression.ColumnOperators.__eq__
*方法。
实现==
运算符。
在列上下文中,生成子句a = b
。如果目标是None
,则生成a IS NULL
。
method __le__(other: Any) → ColumnOperators
继承自 ColumnOperators
的 sqlalchemy.sql.expression.ColumnOperators.__le__
*方法。
实现<=
运算符。
在列上下文中,生成子句a <= b
。
method __lt__(other: Any) → ColumnOperators
继承自 ColumnOperators
的 sqlalchemy.sql.expression.ColumnOperators.__lt__
*方法。
实现<
运算符。
在列上下文中,生成子句a < b
。
method __ne__(other: Any) → ColumnOperators
继承自 ColumnOperators
的 sqlalchemy.sql.expression.ColumnOperators.__ne__
*方法。
实现!=
运算符。
在列上下文中,生成子句a != b
。如果目标是None
,则生成a IS NOT NULL
。
method all_() → ColumnOperators
继承自 ColumnOperators
的 ColumnOperators.all_()
*方法。
生成针对父对象的all_()
子句。
请参阅all_()
的文档以获取示例。
注意
请确保不要混淆较新的ColumnOperators.all_()
方法与此方法的传统版本,即特定于ARRAY
的 Comparator.all()
方法,其使用不同的调用风格。
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_()
方法与这个方法的 旧版,即 Comparator.any()
方法混淆,后者是专门针对 ARRAY
的,并且使用了不同的调用样式。
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
执行按位左移操作,通常通过<<
运算符。
新版本 2.0.2 中新增。
另请参阅
按位运算符
method bitwise_not() → ColumnOperators
继承自 ColumnOperators.bitwise_not()
方法的 ColumnOperators
执行按位非操作,通常通过~
运算符。
新版本 2.0.2 中新增。
另请参阅
按位运算符
method bitwise_or(other: Any) → ColumnOperators
继承自 ColumnOperators.bitwise_or()
方法的 ColumnOperators
执行按位或操作,通常通过|
运算符。
新版本 2.0.2 中新增。
另请参阅
按位运算符
method bitwise_rshift(other: Any) → ColumnOperators
继承自 ColumnOperators.bitwise_rshift()
方法的 ColumnOperators
执行按位右移操作,通常通过>>
运算符。
新版本 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(<expression> AS <type>)
。
这是对 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 '/'
- 其中参数的值为
"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
的 ColumnOperators.distinct()
方法
产生一个针对父对象的 distinct()
子句。
method endswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators
继承自 ColumnOperators
的 ColumnOperators.endswith()
方法
实现‘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.get_children()
方法的 HasTraverseInternals
返回此HasTraverseInternals
的直接子HasTraverseInternals
元素。
用于访问遍历。
**kw 可能包含更改返回的集合的标志,例如返回子项的子集以减少更大的遍历,或者返回来自不同上下文的子项(例如模式级集合而不是子句级集合)。
method icontains(other: Any, **kw: Any) → ColumnOperators
继承自 ColumnOperators
的 ColumnOperators.icontains()
*方法
实现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 表达式。默认情况下,LIKE 通配符字符%
和_
不会被转义,除非设置了ColumnOperators.icontains.autoescape
标志为 True。autoescape
–
boolean;当为 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
的 ColumnOperators.iendswith()
方法
实现 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>
。
给定的参数other
可以是:
- 一个文字值列表,例如:
stmt.where(column.in_([1, 2, 3]))
- 在这种调用形式中,项目列表将转换为与给定列表长度相同的一组绑定参数:
WHERE COL IN (?, ?, ?)
- 如果比较是针对包含多个表达式的
tuple_()
的元组列表:
from sqlalchemy import tuple_ stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
- 一个空列表,例如:
stmt.where(column.in_([]))
- 在这种调用形式中,该表达式渲染为一个“空集合”表达式。这些表达式针对各个后端进行了定制,并且通常试图将一个空的 SELECT 语句作为子查询。例如在 SQLite 上,该表达式为:
WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
- 1.4 版本中的更改:空的 IN 表达式现在在所有情况下都使用执行时生成的 SELECT 子查询。
- 可以使用绑定参数,例如
bindparam()
,如果它包含了bindparam.expanding
标志:
stmt.where(column.in_(bindparam('value', expanding=True)))
- 在这种调用形式中,该表达式渲染为一个特殊的非 SQL 占位符表达式,看起来像:
WHERE COL IN ([EXPANDING_value])
- 此占位符表达式在语句执行时被拦截,转换为前面示例中所示的可变数量的绑定参数形式。如果执行的语句为:
connection.execute(stmt, {"value": [1, 2, 3]})
- 数据库将为每个值传递一个绑定参数:
WHERE COL IN (?, ?, ?)
- 1.2 版本中的新功能:添加了“扩展”绑定参数
如果传递了一个空列表,则会渲染一个特殊的“空列表”表达式,该表达式特定于正在使用的数据库。在 SQLite 上,这将是:
WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
- 1.3 版本中的新功能:“扩展”绑定参数现在支持空列表
- 一个
select()
构造,通常是一个相关的标量选择:
stmt.where( column.in_( select(othertable.c.y). where(table.c.x == othertable.c.x) ) )
- 在这种调用形式中,
ColumnOperators.in_()
渲染如下:
WHERE COL IN (SELECT othertable.y FROM othertable WHERE othertable.x = table.x)
参数:
other – 一个字面值列表,一个 select()
构造,或者一个包含设置了 bindparam.expanding
标志的 bindparam()
构造。
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]
生成列标签,即 <columnname> AS <name>
。
这是一个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
是一个空序列,编译器会生成一个“空不在其中”的表达式。这会默认为表达式“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
中值的按位 AND。
参数:
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
的 ClauseElement.params()
方法
返回一个带有替换了 bindparam()
元素的副本。
返回此 ClauseElement 的副本,其中包含从给定字典中取出的 bindparam()
元素的值:
>>> 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
实现了特定于数据库的 ‘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 - 渲染为
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.regexp_replace()
方法的 ColumnOperators
实现了数据库特定的“正则替换”运算符。
例如:
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.startswith()
方法的 ColumnOperators
实现startswith
操作符。
产生一个 LIKE 表达式,用于测试字符串值的开头是否有匹配项:
column LIKE <other> || '%'
例如:
stmt = select(sometable).\ where(sometable.c.column.startswith("foobar"))
由于该操作符使用LIKE
,因此存在于表达式中的通配符字符"%"
和"_"
也将像通配符一样工作。对于文字字符串值,可以将ColumnOperators.startswith.autoescape
标志设置为True
,以将这些字符在字符串值中的出现情况应用转义,使它们与自身匹配而不是作为通配符字符。或者,ColumnOperators.startswith.escape
参数将建立一个给定字符作为转义字符,当目标表达式不是文字字符串时可能会有用。
参数:
other
- 要比较的表达式。这通常是一个纯字符串值,但也可以是任意的 SQL 表达式。默认情况下,LIKE 通配符字符%
和_
不会被转义,除非将ColumnOperators.startswith.autoescape
标志设置为 True。autoescape
-
布尔值;当为 True 时,在 LIKE 表达式中建立转义字符,然后将其应用于比较值中的所有"%"
、"_"
和转义字符本身的出现次数,假定比较值是一个文字字符串而不是一个 SQL 表达式。
例如,表达式如下:
somecolumn.startswith("foo%bar", autoescape=True)
- 将呈现为:
somecolumn LIKE :param || '%' ESCAPE '/'
- 使用值
:param
为"foo/%bar"
。 escape
–
一个字符,当给定时,将使用ESCAPE
关键字来将该字符设为转义字符。然后可以将此字符放在%
和_
的前面,以使它们作为自身而不是通配符字符。
例如:
somecolumn.startswith("foo/%bar", escape="^")
- 将呈现为:
somecolumn LIKE :param || '%' ESCAPE '^'
- 该参数也可以与
ColumnOperators.startswith.autoescape
结合使用:
somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
- 在上述情况下,给定的文字参数将在传递到数据库之前转换为
"foo^%bar^^bat"
。
另请参阅
ColumnOperators.endswith()
ColumnOperators.contains()
ColumnOperators.like()
attribute 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_()
方法与这个方法的旧版,即特定于ARRAY
的Comparator.all()
方法,它使用不同的调用风格。
method any_() → ColumnOperators
针对父对象生成一个any_()
子句。
查看any_()
的文档以获取示例。
注意
请确保不要混淆较新的ColumnOperators.any_()
方法与这个方法的旧版,即特定于ARRAY
的Comparator.any()
方法,它使用不同的调用风格。
method asc() → ColumnOperators
针对父对象生成一个asc()
子句。
method between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators
针对父对象生成一个between()
子句,给定下限和上限范围。
method bitwise_and(other: Any) → ColumnOperators
执行按位与操作,通常通过&
运算符。
新功能在版本 2.0.2 中。
另请参阅
位运算符
method bitwise_lshift(other: Any) → ColumnOperators
执行按位左移操作,通常通过<<
运算符。
新功能在版本 2.0.2 中。
另请参阅
位运算符
method bitwise_not() → ColumnOperators
执行按位非操作,通常通过~
运算符。
新功能在版本 2.0.2 中。
另请参阅
位运算符
method bitwise_or(other: Any) → ColumnOperators
执行按位或操作,通常通过|
运算符。
新功能在版本 2.0.2 中。
另请参阅
位运算符
method bitwise_rshift(other: Any) → ColumnOperators
执行按位右移操作,通常通过>>
运算符。
新功能在版本 2.0.2 中。
另请参阅
位运算符
method bitwise_xor(other: Any) → 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 collate(collation: str) → ColumnOperators
根据给定的排序字符串生成针对父对象的 collate()
子句。
另请参阅
collate()
method concat(other: Any) → ColumnOperators
实现‘concat’运算符。
在列上下文中,产生子句 a || b
,或在 MySQL 上使用 concat()
运算符。
method contains(other: Any, **kw: Any) → ColumnOperators
实现‘包含’运算符。
生成一个 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
产生一个针对父对象的 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
可以将给定字符确定为转义字符,这在目标表达式不是字面字符串时可能会有用。
参数:
other
– 要进行比较的表达式。这通常是一个简单的字符串值,但也可以是任意的 SQL 表达式。除非将ColumnOperators.endswith.autoescape
标志设置为 True,否则 LIKE 通配符字符%
和_
默认不会被转义。autoescape
–
boolean;当为 True 时,在 LIKE 表达式中建立一个转义字符,然后将其应用于比较值中的所有"%"
、"_"
和转义字符本身的出现,假定比较值是一个字面字符串而不是 SQL 表达式。
例如:
somecolumn.endswith("foo%bar", autoescape=True)
- 将呈现为:
somecolumn LIKE '%' || :param ESCAPE '/'
- 使用参数的值
"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 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
,存在于表达式内部的通配符字符"%"
和"_"
也将像通配符一样工作。对于文字字符串值,可以将ColumnOperators.icontains.autoescape
标志设置为True
,以对字符串值内部的这些字符的出现应用转义,使它们作为自身而不是通配符字符进行匹配。或者,ColumnOperators.icontains.escape
参数将确定给定的字符作为转义字符,当目标表达式不是文字字符串时可能会有用。
参数:
other
– 要进行比较的表达式。通常这是一个简单的字符串值,但也可以是任意的 SQL 表达式。默认情况下,LIKE 通配符字符"%"
和"_"
不会被转义,除非将ColumnOperators.icontains.autoescape
标志设置为 True。autoescape
–
布尔值;当为 True 时,在 LIKE 表达式中建立一个转义字符,然后将其应用于比较值中的所有"%"
、"_"
和转义字符本身的出现,假设比较值是一个文字字符串而不是 SQL 表达式。
例如:
somecolumn.icontains("foo%bar", autoescape=True)
- 将呈现为:
lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
- 使用值为
:param
的"foo/%bar"
。 escape
–
一个字符,当给定时,将与ESCAPE
关键字一起渲染,将该字符建立为转义字符。然后可以将此字符放在%
和_
的前面,以允许它们作为自身而不是通配符字符。
例如表达式:
somecolumn.icontains("foo/%bar", escape="^")
- 渲染为:
lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
- 参数还可以与
ColumnOperators.contains.autoescape
结合使用:
somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
- 在上述情况下,给定的字面参数将在传递到数据库之前转换为
"foo^%bar^^bat"
。
另请参阅
ColumnOperators.contains()
method 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
,因此存在于表达式中的通配符字符"%"
和"_"
也将像通配符一样起作用。对于字面字符串值,可以将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 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 in_(other: Any) → ColumnOperators
实现 in
运算符。
在列上下文中,生成子句 column IN <other>
。
给定参数 other
可能是:
- 字面值列表,例如:
stmt.where(column.in_([1, 2, 3]))
- 在此调用形式中,项目列表将转换为与给定列表长度相同的一组绑定参数:
WHERE COL IN (?, ?, ?)
- 如果比较是针对包含多个表达式的
tuple_()
,则可以提供元组列表:
from sqlalchemy import tuple_ stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
- 空列表,例如:
stmt.where(column.in_([]))
- 在此调用形式中,表达式呈现为空集合表达式。这些表达式针对各个后端进行了定制,并且通常尝试将一个空的 SELECT 语句作为子查询。例如在 SQLite 上,表达式为:
WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
- 1.4 版本中的变更:在所有情况下,空 IN 表达式现在都使用执行时生成的 SELECT 子查询。
- 可以使用绑定参数,例如
bindparam()
,如果包含bindparam.expanding
标志:
stmt.where(column.in_(bindparam('value', expanding=True)))
- 在此调用形式中,表达式呈现为一个特殊的非 SQL 占位符表达式,如下所示:
WHERE COL IN ([EXPANDING_value])
- 此占位符表达式在语句执行时拦截,以转换为前面所示的变量数目的绑定参数形式。如果语句执行如下所示:
connection.execute(stmt, {"value": [1, 2, 3]})
- 数据库将为每个值传递一个绑定参数:
WHERE COL IN (?, ?, ?)
- 1.2 版本中新增:“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)
参数:
other – 一个字面量列表,一个select()
构造,或一个包含设置为 True 的bindparam()
构造,其中包括bindparam.expanding
标志。
method is_(other: Any) → ColumnOperators
实现IS
运算符。
通常,当与None
的值进行比较时,会自动生成IS
,这会解析为NULL
。然而,在某些平台上,如果与布尔值进行比较,则可能希望显式使用IS
。
另请参阅
ColumnOperators.is_not()
method is_distinct_from(other: Any) → ColumnOperators
实现IS DISTINCT FROM
运算符。
大多数平台上呈现“a IS DISTINCT FROM b”; 在某些平台上,如 SQLite,可能呈现“a IS NOT b”。
method is_not(other: Any) → ColumnOperators
实现IS NOT
运算符。
通常,当与None
的值进行比较时,会自动生成IS NOT
,这会解析为NULL
。然而,在某些平台上,如果与布尔值进行比较,则可能希望显式使用IS NOT
。
在 1.4 版本中更改:is_not()
运算符从先前版本的isnot()
重命名。以前的名称仍可用于向后兼容。
另请参阅
ColumnOperators.is_()
method is_not_distinct_from(other: Any) → ColumnOperators
实现IS NOT DISTINCT FROM
运算符。
大多数平台上呈现“a IS NOT DISTINCT FROM b”; 在某些平台上���如 SQLite,可能呈现“a IS b”。
在 1.4 版本中更改:is_not_distinct_from()
运算符从先前版本的isnot_distinct_from()
重命名。以前的名称仍可用于向后兼容。
method isnot(other: Any) → ColumnOperators
实现IS NOT
运算符。
通常,当与None
的值进行比较时,会自动生成IS NOT
,这会解析为NULL
。然而,在某些平台上,如果与布尔值进行比较,则可能希望显式使用IS NOT
。
在 1.4 版本中更改:is_not()
运算符从先前版本的isnot()
重命名。以前的名称仍可用于向后兼容。
另请参阅
ColumnOperators.is_()
method isnot_distinct_from(other: Any) → ColumnOperators
实现IS NOT DISTINCT FROM
运算符。
大多数平台上呈现“a IS NOT DISTINCT FROM b”; 在某些平台上,如 SQLite,可能呈现“a IS b”。
在 1.4 版本中更改:is_not_distinct_from()
运算符从先前版本的isnot_distinct_from()
重命名。以前的名称仍可用于向后兼容。
method 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
,存在于 表达式中的通配符字符 "%"
和 "_"
也将像通配符一样行为。对于字面字符串值,可以设置 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
关键字将其渲染为转义字