水平分片¶

水平分片支持。

定义一个基本的“水平分片”系统，它允许 Session 在多个数据库之间分配查询和持久化作。

有关使用示例，请参阅源代码分配中包含的水平分片示例。

深度炼金术

水平分片扩展是一项高级功能，涉及复杂的语句 -> 数据库交互以及对非平凡情况使用半公开 API。更简单的方法引用多个数据库“分片”，最常见的是使用不同的在使用这个更复杂且经过较少生产测试的系统之前，应始终首先考虑每个“分片”的会话。

API 文档¶

对象名称	描述
set_shard_id	一个 loader 选项，用于将特定分片 ID 应用于主查询以及其他关系和列加载程序的语句。
分片查询	Query 类。
分片会话

sqlalchemy.ext.horizontal_shard 类。分片会话¶

成员

__init__（）、connection_callable（）、get_bind（）

类签名

类 sqlalchemy.ext.horizontal_shard.ShardedSession （ sqlalchemy.orm.session.Session ）

方法 sqlalchemy.ext.horizontal_shard.ShardedSession. __init__（shard_chooser： ShardChooser， identity_chooser： Optional[IdentityChooser] = None， execute_chooser： Optional[Callable[[ORMExecuteState]， Iterable[Any]]] = None， shards： Optional[Dict[str， Any]] = None， query_cls：Type[Query[_T]] = <class 'sqlalchemy.ext.horizontal_shard.ShardedQuery'>， *， id_chooser： optional[Callable[[query[_T]， Iterable[_T]]， Iterable[Any]]] = None， query_chooser： Optional[[Callable[[Executable]， Iterable[Any]]] = None， **kwargs： Any）→ 无¶

构造 ShardedSession。

参数

shard_chooser¶– 一个可调用对象，通过传递 Mapper、映射实例和可能的 SQL 子句，返回分片 ID。此 ID 可能基于对象中存在的属性，也可能基于某些循环方案。如果方案基于选择，则应在实例上设置任何状态，以便将来将其标记为参与该分片。
identity_chooser¶ –

一个可调用对象，传递了一个 Mapper 和主键参数，该参数应返回此主键可能所在的分片 ID 列表。

在 2.0 版更改： identity_chooser 参数取代 id_chooser 参数。
execute_chooser¶ –

对于给定的 ORMExecuteState，返回应向其中发出查询的 shard_ids 的列表。返回的所有分片的结果将合并到一个列表中。

在 1.4 版本发生变更： execute_chooser 参数取代 query_chooser 参数。
shards¶— Engine 对象的字符串分片名称字典。

方法 sqlalchemy.ext.horizontal_shard.ShardedSession. connection_callable（mapper：Mapper[_T]None=None， instance：AnyNone=None， shard_id：ShardIdentifierNone=None， **kw： Any）→连接¶: 提供 Connection （连接）以用于工作单元刷新流程。

方法 sqlalchemy.ext.horizontal_shard.ShardedSession. get_bind（mapper：_EntityBindKey[_O]None=None， *， shard_id：ShardIdentifierNone=None， instance：AnyNone=None， clause：ClauseElementNone=None， **kw： Any）→ _SessionBind¶

返回此 Session 绑定到的 “bind”。

“bind” 通常是 Engine 的一个实例，除非 Session 已经显式地直接绑定到 Connection。

对于多重绑定或未绑定的 Session， mapper 或 clause 参数用于确定要返回的适当 BIND。

请注意，当通过 ORM作（例如 Session.query（））调用 Session.get_bind（） 时，通常存在 “mapper” 参数，每个单个 INSERT/UPDATE/DELETE作 Session.flush（）、调用等。

解决顺序为：

如果存在 mapper given 和 Session.binds，则首先根据正在使用的 mapper 找到一个 bind，然后是正在使用的 Map 类，然后是 Map 类的__mro__中存在的任何基类，从更具体的超类到更通用的超类。
if 子句给定且 Session.binds 存在，则根据 Session.binds 中存在的给定子句中找到的 Table 对象找到绑定。
如果存在 Session.binds，则返回该 Session.binds。
if 子句，尝试返回链接到最终与子句关联的 MetaData 的 bind。
如果给定 mapper，则尝试返回链接到 MetaData 的绑定，该 MetaData 最终与 Table 或 mapper 映射到的其他可选内容相关联。
找不到 bind，UnboundExecutionError 被提升。

请注意，可以在 Session 的用户定义子类上覆盖 Session.get_bind（） 方法以提供任何类型的的绑定解析方案。请参阅以下示例自定义垂直分区。

参数

mapper¶——可选的 map 类或相应的 Mapper 实例。首先，通过查阅与此 Session 关联的 “binds” 映射，然后通过查阅与 Mapper 映射到的 Table 关联的 MetaData 来派生绑定。
clause¶– 一个 ClauseElement （即 select（）中， text（） 等）。如果 mapper 参数不存在或无法生成绑定，则将在给定的表达式构造中搜索绑定元素，通常是 Table 关联 bound MetaData 的 Bound MetaData 中。

另请参阅

分区策略（例如，每个 Session 多个数据库后端）

Session.binds

Session.bind_mapper（）

Session.bind_table（）

sqlalchemy.ext.horizontal_shard 类。set_shard_id¶

一个 loader 选项，用于将特定分片 ID 应用于主查询以及其他关系和列加载程序的语句。

set_shard_id 选项可以使用任何可执行语句的 Executable.options（） 方法应用：

stmt = (
    select(MyObject)
    .where(MyObject.name == "some name")
    .options(set_shard_id("shard1"))
)

在上面，调用该语句时将限制为 “shard1” 分片 identifier 以及 all relationship 和列加载策略，包括 Eager Loader，例如 selectInLoad（）、延迟列加载器（如 defer（））和惰性关系加载器 lazyload（）。

这样，set_shard_id 选项的范围要宽得多范围，而不是shard_id在 Session.execute.bind_arguments 字典。

2.0.0 版本的新Function。

成员

__init__（）， propagate_to_loaders

类签名

类 sqlalchemy.ext.horizontal_shard.set_shard_id （sqlalchemy.orm.ORMOption）

方法 sqlalchemy.ext.horizontal_shard.set_shard_id. __init__（shard_id： str， propagate_to_loaders： bool = True）¶

构造一个 set_shard_id 选项。

参数

shard_id¶ – 分片标识符
propagate_to_loaders¶ – 如果保留为默认值 True，则 shard 选项将用于惰性加载器，例如 lazyload（） 和 defer（）;如果为 False，则该选项将不会传播到已加载的对象。请注意，defer（） 在任何情况下，始终限制为父行的shard_id，因此参数对 lazyload（） 策略。

属性 sqlalchemy.ext.horizontal_shard.set_shard_id. propagate_to_loaders¶: 如果为 True，则指示此选项应应用于关系延迟加载器以及属性加载/刷新作的“辅助”SELECT 语句。

sqlalchemy.ext.horizontal_shard 类。分片查询¶

Query 类。

旧版功能

ShardedQuery 是旧版 Query 类。ShardedSession 现在支持通过 ShardedSession.execute（） 方法进行 2.0 样式执行。

成员

set_shard（）

类签名

类 sqlalchemy.ext.horizontal_shard.ShardedQuery （sqlalchemy.orm.Query）

方法 sqlalchemy.ext.horizontal_shard.ShardedQuery. set_shard（shard_id： str）→ Self¶

返回一个新查询，仅限于单个分片 ID。

使用返回的查询的所有后续作都将针对单个分片，而不管其他状态如何。

可以将 shard_id传递给 Session.execute（） 的 bind_arguments 字典以进行 2.0 样式的执行：

results = session.execute(stmt, bind_arguments={"shard_id": "my_shard"})

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy ORM

水平分片¶

API 文档¶