SQL 表达式语言基础构造¶

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

对象名称	描述
CacheKey	用于在 SQL 编译缓存中标识 SQL 语句构造的关键码。
ClauseElement	以编程方式构造的 SQL 表达式的元素的基础类。
DialectKWArgs	建立一个类，使其能够使用带有默认值和构造函数验证的方言特定参数。
HasCacheKey	用于可以生成缓存键的对象的 Mixin。
LambdaElement	一种 SQL 构造，其中状态存储为未调用的 lambda。
StatementLambdaElement	将可组合的 SQL 语句表示为 `LambdaElement`。

class sqlalchemy.sql.expression.CacheKey¶

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

另请参阅

SQL 编译缓存

成员

bindparams, key, to_offline_string()

类签名

class sqlalchemy.sql.expression.CacheKey (builtins.tuple)

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

attribute sqlalchemy.sql.expression.CacheKey.key: Tuple[Any, ...]¶: 字段编号 0 的别名

method sqlalchemy.sql.expression.CacheKey.to_offline_string(statement_cache: MutableMapping[Any, str], statement: ClauseElement, parameters: _CoreSingleExecuteParams) → str¶

生成此 CacheKey 的“离线字符串”形式

“离线字符串”基本上是语句的 SQL 字符串，加上一系列绑定参数值的 repr。虽然 CacheKey 对象依赖于内存中的标识才能作为缓存键工作，但“离线”版本适用于也可用于其他进程的缓存。

给定的 statement_cache 是一个类似字典的对象，其中语句本身的字符串形式将被缓存。为了减少字符串化语句所花费的时间，此字典应具有更长的生命周期。

class sqlalchemy.sql.expression.ClauseElement¶

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

成员

compare(), compile(), get_children(), inherit_cache, params(), self_group(), unique_params()

类签名

class 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: _HasDialect | None = None, dialect: Dialect | None = None, **kw: Any) → Compiled¶

继承自 CompilerElement.compile() 方法，来自 CompilerElement

编译此 SQL 表达式。

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

参数:

bind¶ – 一个 Connection 或 Engine，可以提供 Dialect 以生成 Compiled 对象。如果 bind 和 dialect 参数都被省略，则使用默认的 SQL 编译器。
column_keys¶ – 用于 INSERT 和 UPDATE 语句，应存在于已编译语句的 VALUES 子句中的列名称列表。如果为 None，则呈现目标表对象中的所有列。
dialect¶ – 一个 Dialect 实例，可以生成 Compiled 对象。此参数优先于 bind 参数。
compile_kwargs¶ –
将在所有“visit”方法中传递给编译器的可选的附加参数字典。这允许将任何自定义标志传递给自定义编译构造，例如。它也用于传递 literal_binds 标志的情况
```
from sqlalchemy.sql import table, column, select

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

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

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

另请参阅

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

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

继承自 HasTraverseInternals.get_children() 方法，来自 HasTraverseInternals

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

这用于访问遍历。

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

attribute sqlalchemy.sql.expression.ClauseElement.inherit_cache: bool | None = None¶

继承自 HasCacheKey.inherit_cache 属性，来自 HasCacheKey

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

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

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

另请参阅

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

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}

method sqlalchemy.sql.expression.ClauseElement.self_group(against: OperatorType | None = None) → ClauseElement¶

将“分组”应用于此 ClauseElement。

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

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

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

method sqlalchemy.sql.expression.ClauseElement.unique_params(_ClauseElement__optionaldict: Dict[str, Any] | None = None, **kwargs: Any) → Self¶

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

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

class sqlalchemy.sql.base.DialectKWArgs¶

建立一个类，使其能够使用带有默认值和构造函数验证的方言特定参数。

DialectKWArgs 与方言上存在的 DefaultDialect.construct_arguments 交互。

成员

argument_for(), dialect_kwargs, dialect_options, kwargs

另请参阅

DefaultDialect.construct_arguments

classmethod 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_name¶ – 方言的名称。方言必须是可定位的，否则会引发 NoSuchModuleError 异常。方言还必须包含现有的 DefaultDialect.construct_arguments 集合，表明它参与了关键字参数验证和默认系统，否则会引发 ArgumentError 异常。如果方言不包含此集合，则已经可以代表此方言指定任何关键字参数。SQLAlchemy 中打包的所有方言都包含此集合，但是对于第三方方言，支持可能会有所不同。
argument_name¶ – 参数的名称。
default¶ – 参数的默认值。

attribute sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs¶

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

参数以其原始 <dialect>_<kwarg> 格式在此处显示。仅包含实际传递的参数；与 DialectKWArgs.dialect_options 集合不同，后者包含此方言已知的所有选项，包括默认值。

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

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

attribute 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 - 平面字典形式

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

class sqlalchemy.sql.traversals.HasCacheKey¶

用于可以生成缓存键的对象的 Mixin。

此类通常位于以 HasTraverseInternals 基类开始的层次结构中，但这并非必须。目前，该类应该能够独立工作，而无需包含 HasTraverseInternals。

成员

inherit_cache

另请参阅

CacheKey

SQL 编译缓存

attribute sqlalchemy.sql.traversals.HasCacheKey.inherit_cache: bool | None = None¶

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

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

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

另请参阅

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

class sqlalchemy.sql.expression.LambdaElement¶

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

The LambdaElement 在将 lambda 表达式传递到 SQL 构造时透明地生成，例如：

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

The LambdaElement 是 StatementLambdaElement 的基础，后者表示 lambda 中的完整语句。

1.4 版本新增。

另请参阅

使用 Lambdas 显著提升语句生成速度

类签名

class sqlalchemy.sql.expression.LambdaElement (sqlalchemy.sql.expression.ClauseElement)

class sqlalchemy.sql.expression.StatementLambdaElement¶

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

The 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 版本新增。

另请参阅

使用 Lambdas 显著提升语句生成速度

成员

add_criteria(), is_delete, is_dml, is_insert, is_select, is_text, is_update, spoil()

类签名

class sqlalchemy.sql.expression.StatementLambdaElement (sqlalchemy.sql.roles.AllowsLambdaRole, sqlalchemy.sql.lambdas.LambdaElement, sqlalchemy.sql.expression.Executable)

method sqlalchemy.sql.expression.StatementLambdaElement.add_criteria(other: Callable[[Any], Any], enable_tracking: bool = True, track_on: Any | None = 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()。

attribute sqlalchemy.sql.expression.StatementLambdaElement.is_delete¶

attribute sqlalchemy.sql.expression.StatementLambdaElement.is_dml¶

attribute sqlalchemy.sql.expression.StatementLambdaElement.is_insert¶

attribute sqlalchemy.sql.expression.StatementLambdaElement.is_select¶

attribute sqlalchemy.sql.expression.StatementLambdaElement.is_text¶

attribute sqlalchemy.sql.expression.StatementLambdaElement.is_update¶

method sqlalchemy.sql.expression.StatementLambdaElement.spoil() → NullLambdaStatement¶: 返回一个新的 StatementLambdaElement，它将在每次运行时无条件地运行所有 lambda。

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy Core

项目版本

SQL 表达式语言基础构造¶