SQL 表达式语言基础结构¶

用于组合 SQL 表达式语言元素的基类和混合。

对象名称	描述
缓存键	用于标识 SQL 编译缓存中的 SQL 语句构造的键。
子句元素	以编程方式构造的 SQL 表达式的元素的基类。
方言KWArgs	建立类具有具有 defaults 和构造函数验证的特定于方言的参数的能力。
HasCacheKey 的	Mixin 表示可以生成缓存键的对象。
LambdaElement （Lambda元素）	一种 SQL 结构，其中状态存储为未调用的 lambda。
语句LambdaElement	将可组合 SQL 语句表示为 `LambdaElement`。

类 sqlalchemy.sql.expression 中。CacheKey¶

用于标识 SQL 编译缓存中的 SQL 语句构造的键。

另请参阅

SQL 编译缓存

成员

bindparams、键、to_offline_string（）

类签名

类 sqlalchemy.sql.expression.CacheKey （builtins.tuple）

attribute sqlalchemy.sql.expression.CacheKey. bindparams： Sequence[BindParameter[Any]]¶: 字段编号 1 的别名

属性 sqlalchemy.sql.expression.CacheKey. 键： Tuple[Any， ...]¶: 字段编号 0 的别名

方法 sqlalchemy.sql.expression.CacheKey. to_offline_string（statement_cache： MutableMapping[Any， str]， 语句： ClauseElement， parameters： _CoreSingleExecuteParams）→ str¶

生成此 CacheKey 的 “offline string” 形式

“offline string” 基本上是语句的字符串 SQL 加上 repr 的 bound参数值 series。CacheKey 对象依赖于内存中的身份才能用作缓存键，而 “offline” 版本适用于也适用于其他进程的缓存。

给定的 statement_cache 是一个类似字典的对象，其中语句本身的字符串形式将被缓存。此字典应位于生存期较长的范围内，以减少字符串化语句所花费的时间。

类 sqlalchemy.sql.expression 中。ClauseElement（子句元素）¶

以编程方式构造的 SQL 表达式的元素的基类。

成员

compare（）， compile（）， get_children（）， inherit_cache， params（）， self_group（）， unique_params（）

类签名

类 sqlalchemy.sql.expression.ClauseElement （ sqlalchemy.sql.annotation.SupportsWrappingAnnotations ， sqlalchemy.sql.cache_key.MemoizedHasCacheKey ， sqlalchemy.sql.traversals.HasCopyInternals ， sqlalchemy.sql.visitors.ExternallyTraversible sqlalchemy.sql.expression.CompilerElement ，）

method sqlalchemy.sql.expression.ClauseElement. compare（other： ClauseElement， **kw： Any）→ bool¶

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

子类应覆盖默认行为，即直接的恒等比较。

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

method sqlalchemy.sql.expression.ClauseElement. compile（bind：_HasDialectNone=None， dialect：DialectNone=None， **kw： Any）→ 已编译¶

继承自CompilerElement 的 CompilerElement.compile（） 方法

编译此 SQL 表达式。

返回值是一个 Compiled 对象。对返回值调用 str（） 或 unicode（） 将产生一个 string 表示形式。这 Compiled 对象还可以使用 params 访问器返回绑定参数名称和值的字典。

参数

bind¶– 一个 Connection 或 Engine，可以提供 Dialect 以生成 Compiled 对象。如果 bind 和 dialect 参数都省略了，而是使用默认的 SQL 编译器。
column_keys¶ – 用于 INSERT 和 UPDATE 语句，编译语句的 VALUES 子句中应存在的列名列表。如果为 None，则呈现目标表对象中的所有列。
dialect¶- 一个可以生成 Compiled 对象的 Dialect 实例。此参数优先于 bind 参数。
compile_kwargs¶ –

附加参数的可选字典，将在所有 “visit” 方法中传递给编译器。例如，这允许将任何自定义标志传递给自定义编译构造。它还用于传递 literal_binds 标志的情况：
```
from sqlalchemy.sql import table, column, select

t = table("t", column("x"))

s = select(t).where(t.c.x == 5)

print(s.compile(compile_kwargs={"literal_binds": True}))
```

另请参阅

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

方法 sqlalchemy.sql.expression.ClauseElement. get_children（*， omit_attrs： Tuple[str， ...] = （）， **kw： Any）→ Iterable[HasTraverseInternals]¶

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

返回紧接的子 HasTraverseInternals 元素中。

这用于访问遍历。

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

属性 sqlalchemy.sql.expression.ClauseElement. inherit_cache：boolNone = None¶

继承自HasCacheKey 的 HasCacheKey.inherit_cache属性

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

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

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

另请参阅

启用对自定义构造的缓存支持 - 设置 HasCacheKey.inherit_cache 第三方或用户定义的 SQL 构造的属性。

method sqlalchemy.sql.expression.ClauseElement. params（_ClauseElement__optionaldict：Mapping[str，Any]None=None， **kwargs： Any）→ Self¶

返回替换了 bindparam（） 元素的副本。

返回此 ClauseElement 的副本，其中包含 bindparam（） 元素替换为从给定字典中获取的值：

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

方法 sqlalchemy.sql.expression.ClauseElement. self_group（against：OperatorTypeNone=None）→ ClauseElement¶

将 'grouping' 应用于此 ClauseElement。

此方法被 subclasses 覆盖以返回 “grouping” 结构，即括号。特别是，当它被 “binary” 表达式用于在放入更大的表达式时提供围绕自身的分组，以及 select（） 构造 select（） 的（请注意，子查询通常应使用 Select.alias（） 方法创建，因为许多平台需要命名嵌套的 SELECT 语句）。

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

的 base self_group（） 方法 子句元素 只返回 self。

方法 sqlalchemy.sql.expression.ClauseElement. unique_params（_ClauseElement__optionaldict：Dict[str，Any]None=None， **kwargs： Any）→ Self¶

返回替换了 bindparam（） 元素的副本。

与 ClauseElement.params（） 功能相同，但添加了 unique=True 添加到受影响的绑定参数中，以便多个语句可以使用。

类 sqlalchemy.sql.base。方言KWArgs¶

建立类具有具有 defaults 和构造函数验证的特定于方言的参数的能力。

DialectKWArgs 与 DefaultDialect.construct_arguments 出现在方言中。

成员

argument_for（）、dialect_kwargs、dialect_options、kwargs

另请参阅

DefaultDialect.construct_arguments

类方法 sqlalchemy.sql.base.DialectKWArgs. argument_for（dialect_name， argument_name， default）¶

为此类添加一种新的特定于方言的关键字参数。

例如：

Index.argument_for("mydialect", "length", None)

some_index = Index("a", "b", mydialect_length=5)

DialectKWArgs.argument_for（） 方法是按参数计算的方式向 DefaultDialect.construct_arguments 字典。此字典代表方言提供各种架构级构造接受的参数名称列表。

新方言通常应将此字典一次性指定为 dialect 类的数据成员。临时添加参数名称的用例通常用于最终用户代码，这些代码也使用使用额外参数的自定义编译方案。

参数

dialect_name¶ – 方言的名称。方言必须是可定位的，否则会引发 NoSuchModuleError 。这 dialect 还必须包含现有的 DefaultDialect.construct_arguments collection，表示它参与关键字参数验证和默认系统，否则会引发 ArgumentError。如果 dialect 不包含此集合，则已经可以代表此 dialect 指定任何 keyword 参数。SQLAlchemy 中打包的所有方言都包含此集合，但对于第三方方言，支持可能会有所不同。
argument_name¶ – 参数的名称。
default¶ – 参数的默认值。

属性 sqlalchemy.sql.base.DialectKWArgs. dialect_kwargs¶

指定为此构造的特定于方言的选项的关键字参数的集合。

这些论点以原始的 <dialect>_<kwarg> 显示格式。仅包含实际传递的参数; 与 DialectKWArgs.dialect_options 集合不同，后者包含此方言已知的所有选项，包括 defaults。

该集合也是可写的;接受 <dialect>_<kwarg> 形式的键，其中值将组合到选项列表中。

另请参阅

DialectKWArgs.dialect_options - 嵌套词典形式

属性 sqlalchemy.sql.base.DialectKWArgs. dialect_options¶

指定为此构造的特定于方言的选项的关键字参数的集合。

这是一个两级嵌套注册表，键为 <dialect_name> 和 <argument_name>。例如，postgresql_where 参数将定位为：

arg = my_object.dialect_options["postgresql"]["where"]

在 0.9.2 版本加入.

另请参阅

DialectKWArgs.dialect_kwargs - 平面词典形式

属性 sqlalchemy.sql.base.DialectKWArgs. kwargs¶: DialectKWArgs.dialect_kwargs 的同义词。

类 sqlalchemy.sql.traversals 的HasCacheKey（哈斯缓存密钥）¶

Mixin 表示可以生成缓存键的对象。

此类通常位于以 HasTraverseInternals 基，但这是可选的。现在该类应该能够独立工作，而无需包含 HasTraverseInternals 的 HasTraverseInternals 中。

成员

inherit_cache

另请参阅

缓存键

SQL 编译缓存

属性 sqlalchemy.sql.traversals.HasCacheKey. inherit_cache：boolNone = None¶

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

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

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

另请参阅

启用对自定义构造的缓存支持 - 设置 HasCacheKey.inherit_cache 第三方或用户定义的 SQL 构造的属性。

类 sqlalchemy.sql.expression 中。LambdaElement（流点元素）¶

一种 SQL 结构，其中状态存储为未调用的 lambda。

每当将 lambda 表达式传递到 SQL 构造中时，都会以透明方式生成 LambdaElement，例如：

stmt = select(table).where(lambda: table.c.col == parameter)

LambdaElement 是 StatementLambdaElement，它表示 lambda 中的完整语句。

在 1.4 版本加入.

另请参阅

使用 Lambda 显著提高语句生产速度

类签名

类 sqlalchemy.sql.expression.LambdaElement （ sqlalchemy.sql.expression.ClauseElement ）

类 sqlalchemy.sql.expression 中。StatementLambdaElement¶

将可组合 SQL 语句表示为 LambdaElement。

StatementLambdaElement 是使用 lambda_stmt（） 函数：

from sqlalchemy import lambda_stmt

stmt = lambda_stmt(lambda: select(table))

构建完成后，可以通过添加后续 lambda 在语句上构建其他条件，这些 lambda 接受现有语句对象作为单个参数：

stmt += lambda s: s.where(table.c.col == parameter)

在 1.4 版本加入.

另请参阅

使用 Lambda 显著提高语句生产速度

成员

add_criteria（）、is_delete、is_dml、is_insert、is_select、is_text、is_update、spoil（）

类签名

类 sqlalchemy.sql.expression.StatementLambdaElement （ sqlalchemy.sql.roles.AllowsLambdaRole ， sqlalchemy.sql.lambdas.LambdaElement ， sqlalchemy.sql.expression.Executable ）

方法 sqlalchemy.sql.expression.StatementLambdaElement. add_criteria（其他： Callable[[Any]， Any]， enable_tracking： bool = True， track_on：AnyNone=None， track_closure_variables： bool = True， track_bound_values： bool = True）→ StatementLambdaElement¶

向此 StatementLambdaElement 添加新条件。

例如：

>>> def my_stmt(parameter):
...     stmt = lambda_stmt(
...         lambda: select(table.c.x, table.c.y),
...     )
...     stmt = stmt.add_criteria(lambda: table.c.x > parameter)
...     return stmt

StatementLambdaElement.add_criteria() 方法是等效于使用 Python 加法运算符添加新的 lambda，但可以添加其他参数，包括 track_closure_values 和 track_on：

>>> def my_stmt(self, foo):
...     stmt = lambda_stmt(
...         lambda: select(func.max(foo.x, foo.y)),
...         track_closure_variables=False,
...     )
...     stmt = stmt.add_criteria(lambda: self.where_criteria, track_on=[self])
...     return stmt

有关接受的参数的描述，请参阅 lambda_stmt（） 。

属性 sqlalchemy.sql.expression.StatementLambdaElement. is_delete¶

属性 sqlalchemy.sql.expression.StatementLambdaElement. is_dml¶

属性 sqlalchemy.sql.expression.StatementLambdaElement. is_insert¶

属性 sqlalchemy.sql.expression.StatementLambdaElement. is_select¶

属性 sqlalchemy.sql.expression.StatementLambdaElement. is_text¶

属性 sqlalchemy.sql.expression.StatementLambdaElement. is_update¶

方法 sqlalchemy.sql.expression.StatementLambdaElement. spoil（）→ NullLambdaStatement¶: 返回一个新的 StatementLambdaElement，该元素每次都将无条件运行所有 lambda。

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy 核心

SQL 表达式语言基础结构¶