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，以及绑定参数值的系列表示。虽然 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¶ –
可选的附加参数字典，这些参数将通过所有“访问”方法传递给编译器。这允许将任何自定义标志传递给自定义编译结构，例如。它也用于将 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。

在 ClauseElement 中，基类方法 self_group() 只是返回自身。

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¶

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

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

The 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']

New in version 0.9.2.

另请参阅

DialectKWArgs.dialect_kwargs - 平坦字典形式

attribute sqlalchemy.sql.base.DialectKWArgs.kwargs¶: The 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 中的完整语句。

New in version 1.4.

另请参阅

使用 Lambda 为语句生成带来显著的速度提升

类签名

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)

New in version 1.4.

另请参阅

使用 Lambda 为语句生成带来显著的速度提升

成员

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 表达式语言基础构造¶