面向 Python asyncio 的统一数据层,覆盖 MongoDB、MySQL、SQLite、PostgreSQL 与本地磁盘(local) —— 用纯 JSON 定义模型,用 MongoDB 风格的 GQL 树形语法查询,开箱即得基于角色的访问控制、计算列与软删除。
English: README.en.md
py-store 让 Python 服务通过单一 schema 定义与单一查询方言同时对接 MongoDB(原生聚合)、MySQL、PostgreSQL、SQLite 与本地磁盘(local)。嵌套关系会编译为每个后端各一条原生查询 —— 你永远不必手写 $lookup 或裸 SQL。
也在找 Node.js 版本?见
nodejs-store(npmnodejs-store)。两者都是共享 Rust 引擎rust-store之上的薄宿主。Store 家族(Gitee):
rust-store(共享 Rust 核心)·nodejs-store(Node.js 宿主,npmnodejs-store)·py-store(本仓库 —— Python 宿主,pipstorepy)
安装: 发行包名为 storepy;导入包名为 py_store。
pip install storepyfrom py_store import init, store- 它是什么
- 何时使用
- 何时不应使用
- 横向对比
- 安装
- 快速开始
- 支持的后端
- 特性
- GQL 树形查询
- 聚合
- 查询与写入 API
- 多数据源连接
- 权限上下文
- 反馈事件
- Schema 参考
- 向量检索
- 事务边界
- 触发器
- 事务型能力
- 场景事例
- 性能
- 常见问题
- 相关项目
- 框架使用契约
面向 Python asyncio 的轻量、后端无关的数据层。你把模型一次性描述为纯 JSON(fields、relations、computes、indexes、read/write 角色白名单)。库会从这份描述中推导出:
- 命令规划(GQL → Mongo command JSON)—— 由 Rust 核心
rust-store-py执行, - 方言翻译(command JSON → 参数化 SQL),面向 MySQL / PostgreSQL / SQLite,
- 权限检查(schema 级 + 字段级读写、属主条件注入),
- 计算列、软删除归档,以及结果再水合(扁平的 JOIN 行 → 嵌套文档)。
MongoDB 是主方言:查询用 MongoDB 风格的 GQL 编写,其余三个关系型后端向它适配。正因如此,一份 schema 才能同时可移植到文档库与三种关系库。
┌──────────────────────────────┐
Node.js ──▶ │ nodejs-store (npm, host) │ ─┐
└──────────────────────────────┘ │ rust-store-node (napi-rs)
▼
┌───────────────────────────────┐
│ rust-store/core (pure logic) │
│ GQL · permissions · computes │
│ command planning · dialects │
└───────────────────────────────┘
▲
┌──────────────────────────────┐ │ rust-store-py (PyO3)
Python ──▶ │ py-store (pip, host) │ ─┘
└──────────────────────────────┘
Rust 核心负责 GQL 解析、权限检查、计算列、命令规划与 SQL 方言翻译 —— 它从不接触数据库。宿主(py-store、nodejs-store)负责驱动 IO、回调与占位符替换。因此 Python 与 Node.js 之间的行为不会漂移:实现只有一份。
在下列任一情形成立时,就适合选用 py-store:
- 一套代码,多个数据库。 同一服务在开发环境跑 MongoDB、生产环境跑 PostgreSQL(或按租户切换),而你不想要两套数据访问层。
- 需要嵌套 / 关系型读取,又不想写
$lookup或 JOIN。 Order → items、Course → lessons、User → orders —— 全部在 schema 中表达一次,由单条查询解析。 - 正在构建管理后台、FastAPI 服务或内部 CRUD API,希望在不引入完整 ORM 的前提下获得 schema 驱动的 CRUD、软删除、计算列与角色校验。
- 需要行级 / 字段级访问控制。 按角色配置白名单,
guest永远不能写,creator归属按doc.createdBy校验,属主条件会自动注入查询。 - 正在构建 AI / 自然语言数据问答层。 本库在设计时就考虑了 AI 查询宿主:
store.build_pipeline(...)可在不执行的情况下暴露规划好的查询,而降级 / 无法下推的路径会发出结构化反馈事件,而不是静默失败。 - 正在 MongoDB 与 SQL 之间迁移,并希望在过渡期保持同一套查询语法。
- 多租户 SaaS。 一份 schema 定义,N 个租户:通过
(source, database, schema, collection)定位 schema,并在执行时用{"source", "database", "schema"}覆盖把任意查询或写入重新指向目标。
典型具体场景(完整走查见 doc/use-cases/):
| 场景 | 为什么适合 py-store |
|---|---|
| 按租户 schema/数据库隔离的多租户 SaaS | 每租户一个 database / schema + 运行时路由覆盖,仅需一份 schema |
| FastAPI / 管理后台 | Schema 驱动 CRUD、软删除、计算列、RBAC |
| 今天 MongoDB,明天 PostgreSQL | 同一 GQL + 同一 schema,只有数据源改变 |
| AI 数据问答 / text-to-query agent | plan-only 的 build_pipeline、确定性的 command JSON、反馈事件 |
| 同一产品中混用 SQL + Mongo | 跨源查询,SQL 原生下推、Mongo 内存联邦 |
| 审计友好的 CRUD | 每个 schema 自动获得 <Model>Deleted 归档表/集合 |
把边界说清楚能帮你省时间:
- 你想要带完整版本图的 ORM 迁移(Alembic、Django migrations)。
py-store是数据层:提供白名单制的声明式迁移(store.migrate:加表 / 加列 / 加索引 / 类型放宽,逐表事务 + 版本行),但删列、改窄类型等破坏性变更仍交给你的迁移工具,它只给分步建议、绝不静默执行。它也能读取 SQL 后端的物理结构(sync_schema→ 内省);只想拿建表文本时用generate_ddl()—— 纯文本,绝不连接或写入数据库。 - 你想要以 Pydantic 模型为中心的 ORM。 这里的 schema 是运行时 JSON dict,带来的是跨语言一致性(同一 schema 可在 Python 与 Node.js 中运行),而非 Pydantic 类型校验。
- 你只用一种数据库,且很少做关联。 直接用驱动(或单库 ODM/ORM)会更简单。
- 你需要裸聚合的逃生通道。 用户
$pipeline透传已移除 —— 含$pipeline的 GQL 一律在解析期显式失败。原生逃生口只保留显式入口:store.aggregate()(严格 opt-in,默认关闭,需init(connections, {"allowNativeAggregate": True})显式开启)、execute_native()(Mongo 原生聚合)与execute_raw()(原生 SQL)。日常查询请使用$condition/$group/$having/ relations;任何无法被安全翻译的东西都会显式失败,而不是静默处理。
以下仅为整体定位,不是基准测试 —— 请始终对照各工具的最新文档核实。
| py-store | SQLAlchemy | Beanie / Motor | Tortoise ORM | SQLModel | Django ORM | |
|---|---|---|---|---|---|---|
| 主要形态 | JSON schema + GQL 数据层 | SQL 工具集 + ORM | 异步 MongoDB ODM / 驱动 | 异步 ORM | Pydantic + SQLAlchemy | Django 内置 ORM |
| 后端 | MongoDB、MySQL、SQLite、PostgreSQL、local | PostgreSQL、MySQL、SQLite、Oracle、MSSQL | MongoDB | PostgreSQL、MySQL、SQLite、Oracle、MSSQL | PostgreSQL、MySQL、SQLite、… | PostgreSQL、MySQL、SQLite、Oracle |
| Mongo 与 SQL 共用一套查询方言 | ✅(MongoDB 风格 GQL) | ➖(仅 SQL) | ➖(仅 Mongo) | ➖(仅 SQL) | ➖(仅 SQL) | ➖(仅 SQL) |
| 单条查询读出嵌套关系 | ✅ 声明式 relations → $lookup / JOIN |
selectinload/join |
✅ Link/fetch_links |
✅ prefetch_related |
✅ prefetch_related |
|
| 内置角色 / 字段级 RBAC + 属主注入 | ✅ | ➖ | ➖ | ➖ | ➖ | ➖(权限在应用层) |
| 读取时计算列(同步 / 异步 / 关系聚合) | ✅ | ➖(hybrid property) | ➖ | ➖ | ➖ | ➖ |
| 自动开通软删除归档表 | ✅ | ➖ | ➖ | ➖ | ➖ | ➖ |
| 迁移 / DDL 引擎 | ✅(白名单制声明式迁移 + generate_ddl 文本) |
✅(Alembic) | ➖ | ✅(Aerich) | ✅(Alembic) | ✅ |
| 框架耦合 | 无(asyncio) | 无 | 无 | 无 | 无 | Django |
| Python 与 Node 共享原生核心 | ✅(Rust rust-store) |
➖ | ➖ | ➖ | ➖ | ➖ |
以下仅为定位说明,基于这些项目在撰写时公开的文档 —— 请对照你自己的需求核实。
- 对比 SQLAlchemy / SQLModel / Django ORM —— 它们都只支持 SQL 并以模型类为中心:不面向 MongoDB,也都不提供 schema 声明的角色/字段级访问控制或读取时计算列。
py-store把同一段 GQL 编译为原生 MongoDB 聚合或参数化 SQL。 - 对比 Beanie / Motor —— 仅支持 MongoDB。
py-store采用相同的 MongoDB 风格查询写法,但同一条查询也能在 MySQL、SQLite 与 PostgreSQL 上运行。 - 对比 Tortoise ORM / pyloquent —— 基于 SQL 后端的异步 Python ORM,使用模型类,并且(就 Tortoise 而言)带有迁移工具。
py-store只做白名单制非破坏迁移(加表 / 加列 / 加索引 / 类型放宽),不做 Alembic 式版本图与破坏性变更;内省只读取物理结构,generate_ddl()也只渲染CREATE TABLE文本而不触碰数据库 —— 且把模型描述为普通 dict,这恰恰是 schema 能移植到 Node.js 宿主的原因。 - 对比
nodejs-store—— 同一套引擎、同一套 GQL,只不过用 JavaScript。选择与你服务相匹配的宿主即可;schema 与查询语义可互换。
一句话:想要模型类、Pydantic 校验和迁移就用 ORM;想要一份运行时 schema + 一套横跨 MongoDB 与 SQL 的查询方言,并且内置 RBAC 与计算列,就用 py-store。
pip install storepy发行包名是
storepy;导入包名是py_store:from py_store import init, store。
需要 Python 3.10+ 以及一个受支持的后端(MongoDB / MySQL / SQLite / PostgreSQL / 本地磁盘)。
可选的驱动 extra:
pip install "storepy[mysql]" # asyncmy
pip install "storepy[postgres]" # asyncpg
pip install "storepy[sqlite]" # aiosqlitefrom pymongo import AsyncMongoClient
from py_store import init, store
client = AsyncMongoClient("mongodb://localhost:27017")
await init(client["mydb"]) # 为已注册的 schema 幂等创建索引
# 注册一个 schema(纯 JSON)
store.register({
"name": "Post", # GQL 中使用的模型名
"collection": "posts", # 可选,默认取 name
"idPrefix": "PT", # 字符串 _id:前缀 + base36 时间戳 + 随机串
"fields": {
"title": {"type": "string", "default": ""},
"status": {"type": "string", "default": "draft"},
"tags": {"type": "array", "default": []},
},
"computes": {
"statusLabel": {"type": "string", "depends": ["status"],
"fn": lambda doc: doc["status"].upper()},
},
"indexes": [{"keys": {"status": 1, "createdAt": -1}}],
})
# 写入 —— 只存用户数据;默认值在读取时补齐
doc = await store.insert("Post", {"title": "Hello"})
# 查询 —— GQL 树形语法,值经 @key 从 params 中引用
items = await store.query(
"Post($condition:@c0,$sort:@s1,$limit:@l) { title, status, statusLabel }",
{"c0": {"status": "draft"}, "s1": {"createdAt": -1}, "l": 20},
)同一份 schema 与同一条查询可原封不动地在 PostgreSQL 上运行 —— 只需改动 init() 的数据源:
await init({"default": {"kind": "postgres", "exec": exec}})
items = await store.query("Post($condition:@c0) { title, status }", {"c0": {"status": "draft"}})| 后端 | 说明 |
|---|---|
| MongoDB | 原生聚合管道(find/aggregate/$lookup),PyMongo AsyncMongoClient(pymongo >= 4.9) |
| MySQL | 参数化 SQL,information_schema 内省(asyncmy) |
| SQLite | 参数化 SQL,sqlite_master + PRAGMA 内省(aiosqlite) |
| PostgreSQL | 参数化 SQL($n),支持 RETURNING(asyncpg) |
| local(本地磁盘) | 集合以 JSON 文件落盘,core 本地求值器执行(无 SQL、无驱动依赖);见本地磁盘数据源(local) |
GQL 树形查询在每个后端各编译为一条原生查询(local 源除外 —— 命令在 core 本地求值器内直接求值)—— 再也不用手写 $lookup 或裸 SQL。
零外部服务、零原生 DB 引擎:集合以 JSON 文件落盘,命令在 Rust core 的本地求值器内直接执行(语义与 MongoDB 驱动一致)。
from py_store import init, local
await init({'default': local.connect({'dir': './data/store'})})- 用法:
local.connect({'dir': …})返回连接描述符(kind: 'local'),与 Mongo/SQL 连接一样传给await init()。 - 落盘格式:
<dir>/<物理集合名>.json(文档数组);写入先写.tmp中间文件再原子rename。 - 事务语义:快照隔离 —— 事务期读写内存快照,
commit()整目录落盘、rollback()丢弃,天然原子。 - 护栏:单集合上限 100,000 文档(超限显式报错,不静默截断);不建索引(仅顺序扫描),声明
schema.indexes即发local_indexes_ignored反馈事件。 - 并发限制:仅单进程 —— 进程内写经目录锁串行化;跨进程并发不在 v1 保证范围。
- 纯 JSON schema,零代码 —— 一个模型就是一个 dict:fields、relations、computes、indexes。
- GQL 树形查询 → 单条原生查询 —— 嵌套关系在一条查询内解析;再也不用手写
$lookup。 - 规范化聚合 —— 在同一段 GQL 中支持根级
$group/$having与关系聚合谓词(semi/anti-join),并下推到全部五个后端。 - 读取时默认值与计算列 —— 写入只存用户数据;读取时补齐默认值并运行
fn/asyncFn/ 关系agg计算列。 - 智能 mutation ——
mutation()依据_id+ 唯一索引自动识别 upsert,并递归填充关系子文档。 - 内置软删除 —— 每个 schema 自动注册一个
<Model>Deleted归档集合/表;remove()先归档再删除。 - 权限上下文 —— 基于
ContextVar的角色(super_admin/admin/guest/creator…)、schema/字段级读写白名单、自动属主条件注入。 - 多数据源 & 多租户 —— 通过
(source, database, schema, collection)定位 schema;按请求用路由覆盖重新指向目标。 - 异步优先,Rust 核心 —— 构建在 PyMongo
AsyncMongoClient与共享的 Rust 核心(含 SQL 方言)之上。 - mutation 关系谓词 ——
update/remove按关联表字段过滤,下推到全部五个后端(此前 MongoDB 侧是静默 no-op)。 - 自增主键 ——
_id声明{"type": "int", "strategy": "autoincrement"}即用数据库自增整数 ID;做不到自增的场景显式报错。 - 索引 DDL ——
schema.indexes编译为真实CREATE [UNIQUE] INDEX语句(按后端、逐字节一致);生成器仍只产文本。
Model($condition:@c0,$sort:@s1,$skip:@sk,$limit:@l1) {
field1, field2, obj.subField,
Relation($condition:@c2,$sort:@s3,$limit:@l2) { f3, Nested { f4 } }
}
- 值来自 params dict:
{"c0": {...}, "s1": {...}}。 - 对象子字段使用点号表示法;关系在 schema 中声明(
type: "many" | "one")并自动解析 —— 不要手写$lookup。 many关系返回列表(为空时返回[]);one关系合并进父文档(缺失时为None)。- 关系级
$sort/$skip/$limit是按父级取 top-N(每个父级各有自己的窗口;在 SQL 上翻译为窗口函数)。
破坏性变更:用户
$pipeline透传已移除 —— 包含$pipeline的 GQL 现在在解析期显式失败(ERR_GQL_PARSE:),而不是被静默忽略,也不再按档位放行。原生聚合逃生通道只保留显式入口:store.aggregate()(严格 opt-in,默认关闭,需init(connections, {"allowNativeAggregate": True}))、execute_native()与execute_raw()。
规范化聚合内置于 GQL —— 没有独立 API,也没有裸管道。
根级 $group + $having(GROUP BY / HAVING):
rows = await store.query(
"Course($condition:@c0,$group:@g0,$having:@h0,$sort:@s0,$limit:@l0){ status, n, total }",
{
"c0": {"status": {"$ne": "deleted"}},
"g0": {"by": ["status"], "agg": {"n": {"$count": "*"}, "total": {"$sum": "price"}}},
"h0": {"n": {"$gt": 1}},
"s0": {"total": -1},
"l0": 20,
},
)- 白名单操作符:
$count/$sum/$avg/$min/$max。 - 固定执行顺序:
$condition(WHERE)→$group(GROUP BY)→$having(HAVING)→$sort→$skip/$limit→ projection。 - 省略
by(或传[])表示对全表做单组聚合;空输入情况下仍返回一行($count→0,其余 →None)。
关系聚合谓词(semi / anti-join) —— 用关系上的聚合过滤父级,而不产生扇出:
await store.query("Product($condition:@c0,$sort:@s0){ _id, name }", {
"c0": {
"$and": [
{"status": "onSale"},
{"orders": {"$count": {"$gt": 3}}}, # 订单数 > 3
{"$not": {"orders": {"$sum": {"$of": "amount", "$gt": 10000}}}}, # 不是大户
],
},
"s0": {"name": 1},
})在 SQL 上翻译为 EXISTS / NOT EXISTS,在 MongoDB 上翻译为 $lookup + $match。
关系滚动计算列 —— 在 schema 中声明一次,按名称请求:
"computes": {
"itemCount": {"type": "int", "agg": {"$count": "items"}}, # 为空时 0
"itemsTotal": {"type": "float", "agg": {"$sum": "items.qty"}}, # 为空时 None
}items = await store.query(gql, params) # list[dict]
one = await store.query_one(gql, params) # dict | None
page = await store.query_with_count(gql, params) # {'items','total','hasMore','page','pageSize'}(pageSize 上限 5000)
exists = await store.exists("Post", {"_id": pid})
n = await store.count("Post", {"status": "active"})
doc = await store.insert("Post", {...}) # 自动 _id / createdAt / updatedAt
docs = await store.insert_many("Post", [{...}, ...])
await store.update("Post", {"_id": pid}, {"status": "live"}) # 普通字段 → $set
await store.update("Post", {"_id": pid}, {"$inc": {"views": 1}}) # 以 '$' 开头的键作为操作符透传
await store.update_many("Post", {"type": t}, {"status": "live"})
r = await store.remove("Post", {"_id": pid}) # 先归档到 <collection>_deleted
await store.mutation("Post", {...}) # 智能 upsert + 递归关系子文档
await store.upsert("Post", {"code": "A1"}, {...}) # 显式条件 upsert(不做关系处理)
# 注册门面:批量 / 注销(供插件 bootstrap 的接入与回滚)
store.register_batch([{"defn": d1}, {"defn": d2}]) # 落点缺省时按 defn 推导;原子语义由 core 定
store.unregister("Post") # 幂等:未知 schema 也成功;连带清理 PostDeleted说明:
- 持久化前会剔除
None值;_id不能通过update修改。 createdAt/updatedAt由框架维护 —— 不要手动设置。单位取决于 schema 的timestamps设置:默认毫秒,当timestamps: "s"时为秒。- 带空条件(
{}、None、{"$and": []})的update_many/remove会被直接拒绝 —— 它绝不会退化为全表写入。 - 蛇形命名 API(唯一定名,无驼峰别名):
query_one、insert_many、update_many、build_pipeline、…
async def transfer():
rows = await store.execute_raw(
"default", "SELECT * FROM accounts WHERE _id = ? FOR UPDATE", [acc_id])
await store.execute_raw(
"default", "UPDATE accounts SET balance = ? WHERE _id = ?", [new_balance, acc_id],
is_write=True)
await store.transaction("default", transfer)store.transaction(source, fn)在单个 SQL 源上开启事务作用域:fn内的每个execute_raw/ CRUD 调用都落到该源的事务连接,commit/rollback作为一个整体(复用内部的run_in_transaction)。Mongo 源按运行时能力探测(replica set / sharded)以 session 事务执行;standalone 或探测失败则按原样执行fn并发mongo_transaction_unsupported(deployment: standalone|unknown)—— 绝不假装已原子。不支持事务(无with_transaction)的执行器亦按原样执行,并发出一条transaction_not_atomic反馈(允许降级,绝不静默假装已事务化)。同源嵌套 transaction 会开保存点(内层失败只回滚本层);句柄无保存点原语时降级并入外层并发nested_savepoint_unsupported。store.execute_raw(source, sql, params=None, is_write=None)执行原生 SQL,编译由 core 的raw_stmt_compile完成,按params类型自动分两档:位置档(list/tuple/None)SQL 原样透传,占位符沿用各后端原生风格(MySQL / SQLite 用?,PostgreSQL 用$1..$n);命名档(dict)SQL 文本中的:name编译为方言占位符(同名复用、跳过::cast / 引号 / 注释边界;缺名 / 多余名显式抛RawSqlError)。仅限 SQL 源 —— Mongo 源会抛出RawSqlError(py_store.RawSqlError/store.RawSqlError)。is_write缺省时按 SQL 首词推断(SELECT / WITH / EXPLAIN / SHOW / PRAGMA / TABLE 视为读,其余按写 —— 默认写是安全方向);显式传入则覆盖推断。返回{"rows", "affectedRows"}:读取行,写取影响行数。store.execute_native(source, collection, pipeline=None, options=None)在 Mongo 源上执行原生聚合管道(对标 SQL 侧execute_raw的 Mongo 对位逃生口):pipeline为原生聚合管道,options沿用驱动原生键名(allowDiskUse/batchSize/hint/maxTimeMS…,宿主不做白名单)。事务 / 会话作用域内自动透传 session(由事务强制接管,options.session不可覆盖);统一按读路径解析,$merge/$out写管道请自行开事务。仅限 Mongo 源 —— SQL 源抛NativeCommandError并指引execute_raw;MongoClient 形态须经 schema 声明database。返回{"rows"}。- 非事务路径显式提交:在 SQL 源上,
store.transaction之外的写命令由执行器显式提交(成功commit;失败先rollback再上抛)。aiosqlite默认非 autocommit,若缺少这次提交,写入只在当前连接可见、而execute_raw仍报成功 —— 是静默丢数据的隐患。需要整组原子的多语句写入,请放进store.transaction。
async with store.session() as s:
await s.insert("Order", {...})
await s.update("Account", cond, {...})
await s.execute_raw("pg_main", "SELECT ... FOR UPDATE", [1])- 会话内同一 SQL 源的全部命令落到同一事务连接:退出统一提交,异常统一回滚;
- 惰性开事务:会话内没有任何命令时不占用连接;
- 跨源写 fail-closed:同一会话内写入了 ≥2 个数据源时,退出先全部回滚再抛
NonAtomicWriteError(跨源无分布式事务,绝不提交半截); - Mongo 源按运行时能力探测(replica set / sharded)事务化;standalone 或探测失败则按原样执行(非原子),并发出一条
mongo_transaction_unsupported(deployment: standalone|unknown)反馈; - 会话可嵌套:内层作用域在已有事务上开保存点(
SAVEPOINT sp_<n>),退出按成败RELEASE(成功)/ROLLBACK TO+RELEASE(失败)——内层失败只回滚内层,外层可继续; 事务句柄未提供保存点原语时降级并入外层,并发出一条nested_savepoint_unsupported反馈。
sql = store.generate_ddl("mysql") # 所有已注册模型
sql = store.generate_ddl("postgres", ["Course", "CourseDeleted"])store.generate_ddl(backend, names=None) 把一个已注册 schema def 映射为一条 CREATE TABLE —— 是 sync_schema()(只读取)的逆操作。生成器是纯文本:它绝不连接、也绝不写入数据库(铁律 6 依然成立)。
- 只有标量字段成为列;
object/array字段不建列。 - 每张表都会获得
__present哨兵列;timestamps模型还会获得createdAt/updatedAt;<collection>_deleted归档表与其它已注册 def 一样生成。 <Name>Deleted归档 def 由 Rust core 在注册模型时自动派生;Python Host 只补镜像(collection为<c>_deleted、含deletedAt字段、idPrefix为空),绝不把它再注册进 core。因此schema.list()与generate_ddl()中每张归档表只出现一次;一旦真的出现重复(上游回归),它们会去重并发出schemaDuplicateName/ddlDuplicateTable反馈事件,而不是静默产出重复的CREATE TABLE。- 不生成
CREATE INDEX—— SQL 后端仅把索引保留为元数据。 - MySQL 的
__present为VARCHAR(255);若某 schema 的 present 令牌串会超限,则发出ddlPresentOverflow反馈事件,而非静默失败。
store.migrate() 是 DDL 生成之外的可执行迁移入口:对比「已注册 def」与数据库内省结果,
产出并执行白名单内的变更(加表 / 加列 / 加索引 / 类型放宽);白名单外显式抛
MigrationUnsupported,绝不静默跳过。幂等闸按 defn hash 记录版本行,无变更时不重复执行。
report = await store.migrate(
backend="postgres", source="default", defs={"Post": post_defn}, driver=pg_pool,
)
print(report["applied"], report["skipped"]) # 已生效的表 / 跳过原因(如 unchanged)老库升级到新版本时,缺的内建列(__present、createdAt / updatedAt、归属键)会先自动补列
再发出 migrationAutoAddBuiltinColumns 告警(含表名与列名清单);归属键列存在全 NULL 行时发出
migrationOwnerKeyNullRows 告警后继续。只有补列本身失败才中断(MigrationUnsupported),
不会因为「缺列」阻断整个升级。
每个 schema 通过 (source, database, schema(仅 PostgreSQL), collection) 定位 —— 该元组在注册表中必须全局唯一(重复注册会报错,而不是静默错误路由)。定义文件本身不携带落点;source / database / schema 由定义目录结构 + 连接配置解析。
A schema definition file contains no location fields (no source / database / schema; namespace is removed). Location is resolved from the definition directory layout plus the connection config:
- Under the definitions root
<defs-root>/: the first directory level is thedatabase; PostgreSQL adds a second level forschema(Mongo / MySQL / SQLite have no such level); deeper levels are free-form and flattened at load time (no hierarchy semantics). - The connection config (
store.config.json) declaressources(kind+databases) anddefs;kinddecides whether that database directory is read one level deeper forschema. - Location fields are
source/database/schema(PG only) /collection; the wordnamespaceis removed. - Same-named schemas: exactly one primary (no
replica); the rest declare{ "name": "...", "replica": true }, add only a link, and must not repeat the structure. Zero or two-or-more primaries is an error. - A duplicated
namewithin one load batch is an error and the service does not start; re-loading the samenameacross versions bumps its version by 1. - Writes are synchronized within a single connection, across the primary plus all links, in one transaction; a write spanning a cross-connection link is explicitly rejected or degraded with a feedback event (never silent).
# 多个 Mongo 服务端:每个连接一个 source
await init({"mongo_main": db, "pg_a": {"kind": "postgres", "exec": exec}})
# SQL 跨 database / PG-schema 关联会原生下推("db_a"."t" JOIN "db_b"."t");
# 只有 Mongo 跨库关系会回退到内存联邦。多租户路由覆盖 —— 一份 schema 定义,N 个租户。任意查询/写入都接受 { "source", "database", "schema" } 覆盖,在执行时重新定位命令(权限与计算列仍遵循结构 schema):
await store.query('User($condition:@c0){...}', params, {"database": "tenant_42"})
await store.insert("Order", data, {"source": "pg_cluster", "schema": "tenant_7"})route_override 是受信的服务端参数 —— 它不带来源校验,因此把用户可控的输入转发给它,会让调用方把 source/database/schema 重新指向另一个租户(CWE-639 授权绕过面)。切勿在此传入原始请求数据。
旧版单库用法(init(db) + 不带落点的 schema)保持不变:命令携带 source: "default",database / schema 取连接默认。
# 每个请求设置一次(在 router/依赖层)
store.set_context({"userId": uid, "roles": ["editor"]})
# 内部/定时任务 —— 绕过权限检查
await store.run_as_internal(lambda: store.remove("Post", {"_id": pid}))- 角色判决统一由 core 执行:命中豁免清单(
set_exempt_roles,默认为空——无admin/super_admin硬编码)或{"internal": true}上下文放行;其他角色按 schema 级与字段级read/write白名单检查;guest永远不能写。 - 白名单的空值语义:不配置(
None/缺省)= 未配置,不限制;空名单[]同样按「未配置」处理(5.x 旧义,升级不会因空名单立刻 403)。空名单会在注册期发workflowWhitelistEmptyAsUnconfigured类告警(workflow 层),提醒你显式表达意图。 - 拒绝读必须显式:要表达「谁都不许读」,用顶层
denyRead: true(布尔,缺省false,非布尔注册期报错)。它优先于一切角色(含internal与豁免清单),ctx=None的系统内部调用仍保持 fail-open;与read: []并存时denyRead生效。 creator是伪角色,由doc.<归属键> == ctx.userId解析(归属键由 schemaownerKey声明,缺省createdBy,可自定义如"creatorId";不得为"_id"—— 主键由系统管理,注册期即拒绝);授予它的 schema 会自动在查询上注入属主条件,并在 update/remove 时做归属校验。- 未设置上下文 → 权限检查禁用(向后兼容)。
- 拒绝访问会抛出
store.PermissionError(带status = 403)。
store.register({
"name": "AuditLog",
"fields": {"action": "string"},
"denyRead": True, # 显式拒绝读:query / count / exists / lookup 全部读路径统一拒绝
})「无上下文」既可能表示系统调用,也可能表示调用方忘了设置上下文 —— 默认情况下后者会静默通过所有检查(fail-open,为向后兼容保留)。对安全敏感宿主,可在启动时一次性启用上下文强制:
store.set_require_context(True)
# 此后每个无上下文的查询/写入都会抛出 `ERR_NO_CONTEXT:...`
# 内部任务必须显式声明:
await store.run_as_internal(lambda: store.remove("Post", {"_id": pid}))run_as_internal 会把调用标记为 {"internal": True},它在语义上区别于上下文缺失,且总能通过。set_require_context(False) 恢复默认行为。
降级 / 拒绝下推的路径绝不静默失败 —— 它们会发出结构化事件:
{type, code, layer, message, hint, ...} # federation_degraded / sql_pushdown_unsupported / ...- 默认 sink 打印到 stderr;宿主(例如 AI 数据问答服务)可接管以实现自动反馈闭环:
store.set_feedback_sink(lambda event: log.warning("store feedback: %s", event))- SQL 下推被拒会抛出
PushdownUnsupportedError(一个RuntimeError)并发出事件;捕获它即可把该段重新放到 Mongo 源上执行。
{
"name": "Order",
"collection": "orders",
"idPrefix": "OD",
"timestamps": True, # True(毫秒,默认)| False | "ms" | "s"(秒);自动维护 createdAt/updatedAt
"fields": {
"_id": "string", # 简写
"title": {"type": "string", "default": ""},
"meta": {"type": "object", "default": {}, "fields": {...}}, # 嵌套对象字段
"bidders": {"type": "array", "default": []}, # 数组字段 —— 内联 agg 目标
},
"relations": {
"items": {"model": "OrderItem", "type": "many",
"localField": "_id", "foreignField": "orderId"},
},
"computes": {
"total": {"type": "float", "depends": ["amount"], "fn": lambda d: d["amount"] * 1.1},
"itemCount": {"type": "int", "agg": {"$count": "items"}}, # 关系聚合
"biddersCount": {"type": "int", "depends": ["bidders"], "agg": {"$size": "bidders"}},
"maxBid": {"type": "float", "depends": ["bidders"], "agg": {"$max": "bidders.amount"}},
"bidderCount": {"type": "int", "depends": ["bidders"], "agg": {"$countDistinct": "bidders.bidderId"}},
},
"indexes": [
{"keys": {"status": 1}},
{"keys": {"code": 1}, "options": {"unique": True}},
],
"read": ["editor", "viewer"], # 可选的 schema 级角色白名单
"write": ["editor"],
"ownerKey": "creatorId", # 可选:`creator` 伪角色的归属键;缺省 "createdBy",不得为 "_id"。授予 creator 时该键必须在 fields 中声明
}类型:string | int | long | float | double | boolean | array | object | date | any。
值得提前了解的边界规则(全部显式失败,绝不静默降级):
- 直接对数组字段、整个对象字段或对象点路径做过滤,在每个后端都会被拒绝 —— 请把跨实体语义建模为
relations。 - 关系谓词只支持一层关系;像
orders.items.price这样的路径会被拒绝。 - 无法读取的关系是错误,而不是静默的
False。
agg 路径首段命中 fields 声明的数组字段(而非关系)时,对文档自身的数组做聚合 —— 编译进同一条管道,不新增查询阶段:
| 算子 | 路径 | 空数组 / 缺字段 |
|---|---|---|
$size |
数组字段本身 | 0 |
$sum |
数组.元素字段 |
0 |
$avg / $max / $min |
数组.元素字段 |
null |
$countDistinct |
数组.元素字段 |
0 —— 去重并剔除 null 后计数 |
规则(违规在注册期显式失败,绝不静默降级):
depends必须包含路径首段字段。- 数组元素仅一层:
bidders.amount合法;再往数组深层嵌套会被拒绝。 $count仅限关系 —— 数组请用$size。- 仅 MongoDB 与 local(进程内)求值可用;SQL 后端显式报错。
Definitions (collection, fields, referenced relation fields, computed-column keys, fnRef values, index names) may use any style; the engine translates them to the target style. Contract keys (fnRef, localField, foreignField, asyncFn, type, ...) and the schema name are never translated.
| Target | Style | Example (orderTotal) |
|---|---|---|
| MySQL / PostgreSQL / SQLite (physical) | snake_case | order_total |
| MongoDB (physical) | camelCase | orderTotal |
| Node.js / Java / C# / Rust (code; computed columns follow) | camelCase | orderTotal |
| Go (code; computed columns follow) | PascalCase (must be exported) | OrderTotal |
| Python (code; computed columns follow) | snake_case | order_total |
Canonicalization (single implementation core::naming, re-exported by the bindings; hosts must not re-implement it): split on _, -, ., space and at lower/digit-to-upper boundaries; a trailing uppercase in a run followed by a lowercase starts the next token (HTTPServer -> [http, server], userID -> [user, id]); digits stay inside a token (order2Items -> [order2, items]). Reassembly: snake = t1_t2, camel = t1T2, pascal = T1T2.
Two logical names in one schema that canonicalize equal (orderTotal vs order_total) is an error ERR_NAME_CONFLICT: and the service does not start (never silently overwritten). The fields key space is fully open — no field name is reserved: contract keys (type, default, ...) live inside a field's definition object at a different level, so fields: { type: { type: "string" } } is valid. Literal reserved names are only _id (framework primary key) and _score (vector score column).
Computed columns live at the schema top level, computes: { <key>: { type, fn | asyncFn | agg, fnRef?, depends?, read? } } (fn / asyncFn / agg are mutually exclusive).
- The logical
fnRefdefaults to<schema.name>.<computed-column key>(generated, never hand-written); sincenameis globally unique, thefnRefis globally unique too. - Host implementations bind by canonicalization: both the implementation's name in the host language style and the schema's logical
fnRefare canonicalized to token sequences and compared. So Node'sorderAmountLabeland Python'sorder_amount_labelbind to the same logical computed column. - Reusing one implementation across schemas: write an explicit shared name (e.g.
"fnRef": "common.moneyLabel"); naming goes from required to optional. - Every declared
fnRefmust have an implementation, otherwise the service fails to start withERR_FN_MISSING.
向量就是带维度与度量声明的普通字段值:你产出 embedding,存储负责持久化、排序并回传评分。 库内不内置任何 embedding 模型。
{
'name': 'Artwork',
'collection': 'artworks',
'fields': {
'title': {'type': 'string', 'default': ''},
'caption': {'type': 'string', 'default': ''},
'embedding': {'type': 'vector', 'dim': 1024, 'metric': 'cosine'}, # 'cosine' | 'l2' | 'ip'
'embeddingHash': {'type': 'string', 'default': ''}, # 可选:回填摘要
},
'indexes': [
# 声明原生近似索引意图(pgvector / Atlas Search)
{'keys': {'embedding': 'vector'}, 'options': {'metric': 'cosine', 'method': 'hnsw'}},
],
}type: 'vector'必须声明整数dim与metric: 'cosine' | 'l2' | 'ip'之一;dim/metric非法在注册期即报错,不拖到查询期。- 两个上限不可混用:存储上限 16000 维;原生索引上限更低且分后端——pgvector HNSW /
IVFFlat 为 2000 维,MongoDB Atlas
vectorSearch为 4096 维。DDL 生成对超限索引显式报错, 不静默跳过。 - 向量索引项只接受单字段:
{'keys': {<字段>: 'vector'}, 'options': {...}};选项为metric、method(hnsw|ivfflat|flat)与 Atlas 的indexName。 - 向量为
None的行(含迁移前存量行)不参与评分。
rows = await store.query(
'Artwork($condition:@c){ _id, title, _score }',
{'c': {'embedding': {'$near': {'$vector': [0.12, -0.03], '$limit': 10}}}},
)$near只接受三个键:$vector(必填查询向量)、$limit(必填 TopK,正整数)、$minScore(可选,_score下限)。其他键一律拒绝。metric由字段声明决定,不是$near的参数。三种度量统一为「越大越相似」:cosine为余弦相似度,ip为内积,l2为1 / (1 + 欧氏距离)。- 过滤条件写在同一个
$condition内、与$near同级并列,例如{'status': 'public', 'embedding': {'$near': {...}}}。 _score按需投影:必须在投影里显式写出;不含$near的查询永不返回_score键。- 向量长度与
dim不符、零向量、缺$limit在所有后端都报错。
(await store.capabilities())['vector'] 为静态能力报告:
{supported, native, backend, metrics, maxDim}。
native: True表示该目标能跑近似索引(pgvector 已安装,或声明了 Atlas Search 向量索引)。native是目标的静态属性,不会因为某次查询回退而改变。- 没有原生索引时——MySQL、未启用
vec0的 SQLite、未声明 Atlas Search 索引的自建 MongoDB, 以及嵌入式local/memory载体——查询仍按应用层精确检索执行,同时宿主记录vector_degraded降级事件。降级必须可观测,禁止静默。 - PostgreSQL 带过滤(
$condition内除$near还有条件)回退为精确扫描:pgvector 近似索引 属后过滤,会破坏 ACL 与 TopK 正确性。 - 三种观测方式:请求作用域内
py_store.degraded.begin()…store.degraded_status();反馈 通道的vector_degraded事件;store-api的x-store-degraded响应头。事件字段为type / code / layer / backend / field / metric / message / hint。
- 存量表不会被隐式改列。须显式加列并重新注册字段:
ddl.generate_migration(...)产出ALTER TABLE ... ADD COLUMN embedding vector(1024)(vector 列不接受DEFAULT;存量行在回填前 保持NULL)。 - 已存在字段的
dim/metric变更不作为迁移支持——须显式重建列与其索引。 - 回填用
await store.reindex_vectors(schema, field=..., hashField=..., sourceFields=..., embed=...): 按_id锚点分页(不用skip),对sourceFields做sha256摘要,只对摘要变化的行重新 embed。force=True全量重算;dryRun=True只报告不调embed。向量与摘要同一次 update 写入。 - 增量场景用
store.register_vector_reindex(cfg)注入<Schema>.vectorReindex触发器,按需 刷新单行。 - DDL 生成只打印索引语句,存储从不执行它。大表须在业务外执行(PostgreSQL 用
CREATE INDEX CONCURRENTLY)。
| 场景 | 原子性 |
|---|---|
单命令 API(insert / insert_many / update_many / upsert / remove / count / exists) |
单 SQL 源内天然原子(单条 SQL);Mongo 单文档原子 |
store.transaction(source, fn) |
单 SQL 源内原子:作用域内所有命令同连接、同事务;同源嵌套开保存点(内层失败只回滚本层) |
store.session(...) |
会话内单 SQL 源跨多次调用原子;跨源写被显式拦截(NonAtomicWriteError) |
| 无会话的跨源多写 | 非原子(无 2PC / Saga 支持),按数据源顺序执行,并经反馈通道声明 nonAtomic(事件 non_atomic_write,含涉及源) |
| Mongo 多步写 | replica set / sharded:单 Mongo 源原子(session 事务);standalone:非原子并显式声明 mongo_transaction_unsupported |
工作流 run(workflow.run) |
单源 run 跨步骤整体原子(外层 run_atomic 包住步骤循环、内层 mutation 嵌套并入);多源 / 源预扫失败按顺序执行并经反馈通道声明非原子 |
触发链(schema triggers,insert / update 事件) |
与源写同一 run_atomic 包络:单源真事务(同事务回滚);触及第二数据源按顺序执行并声明 non_atomic_write;store.session() 内对跨源写 fail-closed |
- Mongo 源:会话内按运行时能力探测结果事务化;不可事务(standalone / 探测失败)按原样执行,
并发出
mongo_transaction_unsupported反馈(deployment: standalone|unknown)(允许降级,绝不静默假装已事务化); - 未实现
open_transaction的 SQL 执行器:会话内按原样执行,并发出session_not_atomic反馈(允许降级,绝不静默假装已事务化); - 未实现
with_transaction的 SQL 执行器:store.transaction/ 顶层原子包络内按原样执行, 并发出transaction_not_atomic反馈(与session_not_atomic对称,允许降级,绝不静默假装已事务化); - 归档幂等:
remove的归档采用按_idupsert 的语义,因此部分失败后的重试不会再因重复_id而失败。 - 读一致性:只有在显式会话内的多条读才共享同一事务连接;会话外读不额外开启事务。
- 跨源写(非会话):一次写调用涉及 ≥2 个数据源时无法原子,按顺序执行,并发出一条
non_atomic_write反馈(code: nonAtomic,含涉及源列表)——允许降级、禁止静默。 把写收敛到单源,或放入store.session()内(后者对跨源写直接 fail-closed)。
schema 声明式触发链:写事件(insert / update / remove)由 Rust 核心在规划期展开为有序副作用步骤(plan.triggers),宿主在源写同一原子包络内依次执行。声明形态(triggers 三类键 + T 字段表)与占位符语法以 rust-store README「触发器」章节为准;core 侧展开输出跨端逐字节一致(rust-store/fixtures/triggers/cases.json golden 守护)。
回调装配(py_store/crud/triggers.py):
async def _grant_points(args, ctx, host):
await host['store'].update('User', {'_id': args['userId']}, {'$inc': {'points': args['amount']}})
store.set_trigger_fn('grantPoints', _grant_points)
store.assert_trigger_fns_covered(defns) # 启动期:声明的 fnRef 缺实现 ⇒ ERR_TRIGGER_FN_MISSING执行语义:
- 命中判定 —— update 事件先判
onFields 值真的变化(结构深比较,no-op 抑制——值未变不触发)→ 再判when(eq/ne/gt/gte/lt/lte/in/and/or/not);insert 事件无 before,跳过字段级检查;remove以归档(删除前)文档为根。系统字段(createdAt/updatedAt/deletedAt)不进触发器探针投影,其变化天然不触发。 - 占位符 ——
{{root.*}}(变化后值)/{{before.*}}(变化前值)/{{now}}只做整值替换;内嵌拼接显式报ERR_TRIGGER_PLACEHOLDER,禁静默漂移。 - 去重 —— 同一次顶层调用内
(step.name, _id)只执行一次。 - 回调式 ——
impl(args, ctx, {'store': store});回调内store.*落到当前事务连接 → 与主写同事务。 - 定时(cron) ——
schedule事件由宿主定时任务插件(py_store/scheduler/__init__.py)枚举并复用同一触发链;占位符仅允许{{now}}。
边界:单源真事务 / 跨源 nonAtomic 声明 / store.session() 内跨源 fail-closed(见事务边界);不支持级联(触发写不再触发任何触发器);update_many 不支持字段级触发(显式拒绝,禁静默降级);命令式步骤 op: "upsert" 注册期 Err。
面向事务型业务场景(订单、库存——写竞争 + 复杂读)的能力增补。完整语义、用法与显式报错清单: doc/transaction-capabilities.zh-CN.md · English.
- mutation 关系谓词 ——
update_many('Inventory', {'product': {'category': 'meat'}}, {'$inc': {'stock': 10}}):条件键命中已声明关系即 semi/anti-join,归一为 preCommand(aggregate 取_id)+_id $in。 $group byone 关系路径 ——by: ['product.category']编译为$lookup+$unwind(Mongo)/LEFT JOIN(SQL);many 路径显式报错(扇出破坏计数语义)。- 自增主键 ——
_id: {'type': 'int', 'strategy': 'autoincrement'};PG/SQLite 经INSERT…RETURNING回读、MySQL 经 lastrowid;MongoDB 与insert_many显式报AUTOINCREMENT_NOT_SUPPORTED(禁 ObjectId 静默顶替)。 - 索引 DDL ——
schema.indexes(Mongo 形态)→ddl.generate产出CREATE [UNIQUE] INDEX idx_<表>_<字段>,MySQL/PostgreSQL/SQLite 三方言逐字节一致。 - 声明式迁移 ——
ddl.diff_defs(old, new)+ddl.generate_migration(backend, old, new):白名单制(加表/加列/加索引/类型放宽),纯函数按方言产 SQL;白名单外显式报MIGRATION_UNSUPPORTED。
把「多步数据操作的编排」用数据表达:工作流定义(Workflow defn)是与 schema defn 同构的纯 JSON、
运行记录(run)落库为内建 schema __workflowRun(普通 GQL 即查,可观测性零新接口)。执行是既有
mutation 步骤序列机制的推广——线性步骤 + 步骤级 when 守卫 + fail-fast。引擎落在宿主层
(py_store/workflow.py),core 零改动;对齐 nodejs-store/src/workflow.js(双宿主输出逐字节
一致由 parity 锚单测守护)。
from py_store import workflow
workflow.register({ # 注册即静态校验;白名单外显式 Err(WORKFLOW_UNSUPPORTED)
'name': 'placeOrder',
'run': ['admin', 'ops'], # 三级白名单 read/write/run(run 缺省回退 write)
'steps': [
{'op': 'query', 'as': 'inv',
'gql': 'Inventory($condition:@c0){_id, stock}',
'params': {'c0': {'productId': '{{input.productId}}', 'warehouse': '{{input.warehouse}}'}}},
{'op': 'fail', 'when': {'exists': '{{inv._id}}', 'is': None}, 'message': '库存记录不存在'},
{'op': 'fail', 'when': {'lt': '{{inv.stock}}', 'than': '{{input.qty}}'}, 'message': '库存不足'},
{'op': 'mutation', 'model': 'Inventory',
'data': {'_id': '{{inv._id}}', 'stock': '{{dec:{{inv.stock}},{{input.qty}}}}'}},
],
})
run = await workflow.run('placeOrder', {'productId': 'p1', 'warehouse': 'w1', 'qty': 30})
# run['status'] ∈ succeeded | failed | rejected | drySucceeded | dryFailed
# 统一契约:业务失败不抛错,错误在 run['error'](失败才有值;succeeded 态恒为 null)- 步骤白名单(首批仅三种,白名单外注册即
WORKFLOW_UNSUPPORTED):query(store.query; 结果单条化,>1 行显式 Err)、mutation(store.mutation / upsert,继承其步骤序列与占位符机制)、fail(显式业务断言失败:run 记 failed + stepIndex + message)。步骤可选when守卫 (exists / is / eq / ne / lt / lte / gt / gte),不满足记skipped——显式留痕,绝不静默跳过。 - 占位符:
{{input.<path>}}(本次 run 输入)、{{<as>.<path>}}(前序步骤结果,必须前向引用)、{{dec:<a>,<b>}}(递减);整值替换保类型、内嵌替换字符串化。gql 内禁占位符(参数走 params 绑定,防注入);数组下标路径不支持(逐行处理请走宿主代码编排)。 - 权限:defn 内嵌三级角色白名单(复用四级 RBAC 语义:admin / super_admin 放行、guest 拒绝、
internal 放行、creator 按 Missing 通过);run 继承触发者 Context,每步 query/mutation 都过 core
权限判定——工作流是「权限内的一次次普通调用」,不存在超级身份。
require_context(true)开启时 无 ctx 拒跑(fail-secure 优先于 dry-run)。rejected 同样落库(拒绝可审计)。 - 原子性:单源 run 整体原子(外层
run_atomic包住整个步骤循环,内层 mutation 嵌套并入—— 任一步失败整体回滚);多源 / 预扫失败按顺序执行并发反馈事件(workflow_non_atomic/workflow_prescan_failed,禁静默)。run 记录时序:先落running(进程崩溃可见)→ 步骤事务 → 终态在事务外独立提交(业务回滚不影响失败 run 可查)。 - dry-run:
workflow.run(name, input, dry_run=True)——query 真实执行(只读安全), mutation / fail 记wouldRun;终态drySucceeded | dryFailed。 - run 落库:
__workflowRun由模块导入即自举注册(幂等);SQL 后端首次启用工作流需执行ddl.generate(backend, ['__workflowRun'])建表(Mongo 无需,首次写入自动建集合)。 其write为显式空名单(普通角色 GQL 篡改 run 审计被 R2 拒绝;模块内部写入走 internal 上下文)。
| 不做 | 理由 | 出口 |
|---|---|---|
| 循环 / 并行 / 子工作流 / 人工审批 | DAG 与人工等待语义复杂度爆炸;线性 + when 覆盖首批场景 |
宿主代码用 store API 编排 |
| 自动补偿(Saga)/ 自动重试 | 反向操作语义负担大;步骤无自动幂等保证 | 人查 run 记录显式处置 |
| 步骤级宿主回调 | 任意代码击穿白名单治理 | schema computes(读)/ 宿主代码(写) |
| 工作流定义存库 / 热更 | 依赖 schema 版本化先行(路线图下一步) | defn 暂与 schema 同模式:代码内 JSON + register |
| 定时触发 / 事件触发 | 触发器是常驻 IO 职责,属调度层,与「纯编排」正交 | 应用层自行调用 run |
| gql 内嵌占位符 / 数组下标路径 | 注入面 / 数组逐行处理语义 | params 绑定 / 宿主代码编排 |
上文参考章节逐项介绍了各能力的定义。下面用同一个库在具体业务情境中做实事 —— 每个示例都可直接复制运行,后端取自支持的后端。
业务背景。 你要给一个小服务加一个 Post 模型,不想手写 DDL、ODM 类或仓储层。模型本身是数据,不是代码。
from pymongo import AsyncMongoClient
from py_store import init, store
await init(AsyncMongoClient("mongodb://localhost:27017")["mydb"])
store.register({
"name": "Post",
"collection": "posts",
"idPrefix": "PT",
"fields": {
"title": {"type": "string", "default": ""},
"status": {"type": "string", "default": "draft"},
"tags": {"type": "array", "default": []},
},
})
await store.insert("Post", {"title": "Hello"})
items = await store.query(
"Post($condition:@c0,$sort:@s1,$limit:@l) { title, status }",
{"c0": {"status": "draft"}, "s1": {"createdAt": -1}, "l": 20},
)结果。 items 为 [{"_id": "PT…", "title": "Hello", "status": "draft"}] —— status 你从未写入,是读取时由字段 default 填充的。
优势所在。 模型就是一个普通 dict,没有类继承、没有元类、没有导入期注册仪式 —— register() 加上 init() 模型就存在了。字符串 _id 由框架生成(idPrefix + base36 时间戳 + 随机),而且这份 dict 对 Node.js 宿主(nodejs-store)同样是合法 schema,所以在这里写的 schema 不会被锁死在 Python。
业务背景。 你在本地 SQLite 文件上开发,线上是 PostgreSQL。你不想要两套查询方言,也不想上线时重写。
import aiosqlite
from py_store import executors, init, store
# 本地开发:SQLite 文件
db = await aiosqlite.connect("dev.db")
await init({"default": executors.create_connection("sqlite", db)})import asyncpg
from py_store import executors, init, store
# 生产环境:PostgreSQL 连接池
pool = await asyncpg.create_pool(dsn="postgres://user:pass@host:5432/db")
await init({"default": executors.create_connection("postgres", pool)})两种环境下,后续业务代码完全相同:
items = await store.query(
"Post($condition:@c0) { title, status }",
{"c0": {"status": "draft"}},
)结果。 两种环境返回相同结构的文档;差异仅在那两行数据源。
优势所在。 GQL 由共享的 Rust core 按后端编译 —— MongoDB 走原生聚合,SQLite/PostgreSQL/MySQL 走参数化 SQL。业务代码里既没有 SQL 字符串也没有方言分支,因此「换数据库」改的是连接、不是查询。local 本地磁盘数据源(见示例 7)以 local.connect(...) 同样接入。
业务背景。 课程详情页需要课程、它的分类、课时列表与评价。经典缺陷是 N+1:一次查课程,再为每个关系各查一次。
course = await store.query_one(
"Course($condition:@c0){ _id, title, "
" category { _id, name }, "
" lessons { _id, title, seq }, "
" reviews { _id, score } }",
{"c0": {"_id": "c1"}},
)结果。 一个文档,关系已挂载:
{"_id": "c1", "title": "Python入门",
"category": {"_id": "cat2", "name": "后端"},
"lessons": [{"_id": "l1", "title": "安装", "seq": 1}, {"_id": "l2", "title": "入门", "seq": 2}],
"reviews": [{"_id": "r1", "score": 5}, {"_id": "r2", "score": 4}]}one 关系合并进父文档,many 关系成为列表(空时 [],缺失的 one 为 None)。
优势所在。 关系在 schema 里声明一次,选择集本身就足以让引擎解析它们:MongoDB 编译为 $lookup,SQL 编译为 JOIN,每个后端只有一次查询。没有 ORM 的 selectinload / prefetch_related 需要记,也没有 $lookup 需要手写,缺失关系是 None/[] 而非崩溃。子列表还能按父级排序分页:lessons($sort:@s0,$limit:@l0){ _id, title }。
业务背景。 在线学习笔记:学生只能读写自己的笔记,审计日志仅管理员可见,课程的 secret 字段仅管理员可读。你希望这在数据层强制,而不是在每个 handler 里重写一遍。
store.register({
"name": "StudyNote", "collection": "study_notes",
"read": ["creator", "admin"], "write": ["creator", "admin"],
"fields": {"_id": {"type": "string"}, "title": {"type": "string"},
"createdBy": {"type": "string"}},
"relations": {},
})# 按请求设置一次,在路由 / 依赖层
store.set_context({"userId": "u1", "roles": ["student"]})
# 只返回 u1 的笔记 —— 属主条件自动注入
mine = await store.query("StudyNote($condition:@c0){ _id, title }", {"c0": {"title": "笔记A"}})结果。 mine == [{"_id": "n1", "title": "笔记A"}]。他人的笔记永远不会返回,显式去查也返回 [] —— 属主条件与你的条件做 AND,绝不会替换它。
优势所在。 creator 是由 doc.createdBy == ctx.userId 判定的伪角色,因此归属是数据事实而非逐 handler 的检查 —— 授予该角色的 schema 会在读 和 写路径(含 count/exists)自动注入属主条件与归属校验。字段级白名单同理:student 请求标记为 read: ["admin"] 的字段时拿不到该字段,而显式请求一个不可读的关系会抛 store.PermissionError(status = 403),而非静默返回 False。特权角色(super_admin/admin/internal)一律放行;guest 永远不能写。
业务背景。 课程列表要展示 revenue = price * enrolledCount 与 lessonCount = 课时数。你希望两者都在读取时算出,不维护任何冗余列。
store.register({
"name": "Course", "collection": "courses",
"fields": {"_id": {"type": "string"}, "price": {"type": "float"},
"enrolledCount": {"type": "int"}},
"relations": {
"lessons": {"model": "Lesson", "type": "many",
"localField": "_id", "foreignField": "courseId"},
},
"computes": {
# 同步计算列:对单个文档
"revenue": {"type": "float", "depends": ["price", "enrolledCount"],
"fn": lambda d: (d.get("price") or 0) * (d.get("enrolledCount") or 0)},
# 关系聚合计算列:相关课时数
"lessonCount": {"type": "int", "agg": {"$count": "lessons"}},
# 异步计算列:对整个结果页 (async def fn(items, ctx) -> None)
"displayName": {"type": "string", "depends": ["name"], "asyncFn": my_display_name},
},
})rows = await store.query(
"Course($condition:@c0){ _id, price, revenue, lessonCount }",
{"c0": {"_id": "c2"}},
)结果。 rows == [{"_id": "c2", "price": 100.5, "revenue": 301.5, "lessonCount": 2}]。你没有请求 enrolledCount,revenue 却算对了 —— depends 把它拉了进来 —— 且它不会泄漏到输出中。
优势所在。 依赖字段为计算自动注入、并从投影中自动移除,因此线上返回的正是你所请求的。fn 是对一行的一个回调;asyncFn 是对整个结果的一次批量处理(async def fn(items, ctx));agg 复用与查询过滤相同的关系聚合机制,所以「课时数」无需手写 join。跨 schema 复用以名字为准:给该列显式写 "fnRef": "common.moneyLabel",Python 的 common_money_label 与 Node 的 commonMoneyLabel 就绑定到同一个逻辑列(按规范化名绑定;fnRef 无实现会以 ERR_FN_MISSING 让服务启动失败)。
业务背景。 看板需要「按状态分组的课程,带数量与价格合计,只保留课程数大于 1 的分组」。与其每个指标一条 SQL,不如一次问清。
rows = await store.query(
"Course($condition:@c0,$group:@g0,$having:@h0,$sort:@s0,$limit:@l0){ status, n, total }",
{
"c0": {"status": {"$ne": "deleted"}},
"g0": {"by": ["status"], "agg": {"n": {"$count": "*"}, "total": {"$sum": "price"}}},
"h0": {"n": {"$gt": 1}},
"s0": {"total": -1},
"l0": 20,
},
)结果。 [{"status": "published", "n": 5, "total": 1000000000000110.8}] —— 即 GROUP BY status ... HAVING count(*) > 1,按价格合计排序。
优势所在。 $group / $having 是 GQL 的一部分,所以同一调用在 MongoDB 上跑原生聚合、在 SQL 上跑参数化 GROUP BY ... HAVING —— 没有单独的报表 SQL,没有方言分支。执行顺序固定且有文档(WHERE → GROUP BY → HAVING → sort → skip/limit),算子白名单是 $count / $sum / $avg / $min / $max,省略 by(或传 [])得到全表单行。父级也可用子级聚合过滤而不产生扇出 —— {"orders": {"$count": {"$gt": 3}}} 在 SQL 上变为 EXISTS / NOT EXISTS,绝不重复父行。
业务背景。 你希望同一份数据层代码能在无需安装数据库的 CI 或沙箱里运行,并有一个重启后仍在的持久缓存 —— 零外部服务。
from py_store import init, local, store
await init({"default": local.connect({"dir": "./data/store"})})
store.register({"name": "User", "collection": "users",
"fields": {"_id": {"type": "string"}, "name": {"type": "string"}},
"relations": {}})
await store.insert("User", {"name": "Ada"})
rows = await store.query("User{ _id, name }")结果。 rows == [{"_id": "…", "name": "Ada"}],且 ./data/store/users.json 现在是一个文档的 JSON 数组。
优势所在。 local.connect({"dir": …}) 返回的是普通连接描述符,因此直接塞进同一个 init(),所有 GQL/CRUD 调用照常工作 —— 无需 SQL 引擎、无需驱动(local 源由 core 的 local 求值器直接求值,语义与 MongoDB 一致)。写入走 .tmp 临时文件加原子 rename,store.transaction / store.session 得到快照隔离、构造上即原子。护栏是显式而非静默的:每集合 100,000 文档硬上限、无索引(声明 schema.indexes 会发出 local_indexes_ignored 反馈事件)、仅支持单进程。
业务背景。 「下单」是:读库存、库存记录不存在则失败、库存不足则失败、然后扣减。你希望把这些步骤及其守卫表达为数据,fail-fast 执行,事后可审计。
from py_store import workflow
workflow.register({
"name": "placeOrder",
"run": ["admin", "ops"],
"steps": [
{"op": "query", "as": "inv",
"gql": "Inventory($condition:@c0){_id, stock}",
"params": {"c0": {"productId": "{{input.productId}}", "warehouse": "{{input.warehouse}}"}}},
{"op": "fail", "when": {"exists": "{{inv._id}}", "is": None}, "message": "库存记录不存在"},
{"op": "fail", "when": {"lt": "{{inv.stock}}", "than": "{{input.qty}}"}, "message": "库存不足"},
{"op": "mutation", "model": "Inventory",
"data": {"_id": "{{inv._id}}", "stock": "{{dec:{{inv.stock}},{{input.qty}}}}"}},
],
})
run = await workflow.run("placeOrder", {"productId": "p1", "warehouse": "w1", "qty": 30})结果。 run["status"] 取 succeeded | failed | rejected | drySucceeded | dryFailed 之一;业务失败不抛错 —— 原因在 run["error"](成功时为 null)。run 落库到内建 __workflowRun schema,用普通 GQL 即可查询。
优势所在。 定义是与 schema defn 同构的纯 JSON,在 register() 时静态校验:未知步骤类型、后向占位符引用、缺操作数的 when、gql 内嵌占位符,都在注册期失败(WORKFLOW_UNSUPPORTED)而非运行期。步骤是白名单(query / mutation / fail),占位符是 {{input.x}}、{{step.field}}、{{dec:a,b}},每一步都在调用者的权限上下文下运行 —— 不存在超级身份。单源 run 端到端原子;fail 守卫把 run 记为 failed 并带上 stepIndex,绝不静默跳过。workflow.run(name, input, dry_run=True) 会真实执行读取,并把写标记为 wouldRun。
业务背景。 你要上生产,不能依赖「调用方总是记得设置上下文」。你希望安全默认就是强制默认。
from py_store import secure
# 启动时执行一次
secure.secure_mode(admin_roles=["admin"])结果。 未设置上下文时,每次查询/写入都抛 ERR_NO_CONTEXT 而非放行(fail-open → fail-secure)。后台任务必须显式声明:
await store.run_as_internal(lambda: store.remove("Post", {"_id": pid})) # 仍会放行未配置的 schema 对所有人(含 admin)拒绝,直到声明白名单为止;无上下文注册新定义也会被拒。secure.relax_mode() 恢复宽松默认;secure.is_secure() 报告当前状态。
优势所在。 secure_mode() 一并翻转三个原本独立的开关(require-context、unconfigured-roles-closed、meta-policy-closed),你不会开了其中一个却忘了另外两个。run_as_internal 与「缺失上下文」在语义上截然不同,这正是系统任务能继续工作、而忘记设置上下文能 fail-closed 的原因 —— 「无上下文」过去恰恰把这两种情况混为一谈。降级路径同样不静默:set_feedback_sink 仍会收到结构化事件,而不是让失败悄无声息。
业务背景。 用户在 MongoDB、订单在 MySQL,而一个个人主页两样都要。你不想维护两个客户端、两套查询语言,再在中间手写一次 join。
import asyncmy
from pymongo import AsyncMongoClient
from py_store import executors, init, store
await init({
"mongo_main": AsyncMongoClient("mongodb://mongo-host:27017")["shop"],
"mysql_main": executors.create_connection(
"mysql", await asyncmy.create_pool(host="mysql-host", user="app",
password="…", db="shop", autocommit=True)),
})
# 每个定义固定自己的源;关系是跨源的
store.register({
"name": "User", "collection": "users", "datasource": "mongo_main",
"fields": {"_id": {"type": "string"}, "name": {"type": "string"}},
"relations": {
"orders": {"model": "Order", "type": "many",
"localField": "_id", "foreignField": "userId"}},
})
store.register({
"name": "Order", "collection": "orders", "datasource": "mysql_main",
"fields": {"_id": {"type": "string"}, "userId": {"type": "string"},
"code": {"type": "string"}, "amount": {"type": "float"}},
"relations": {},
})
rows = await store.query_federated(
"User($condition:@c0){ _id, name, orders { code, amount } }",
{"c0": {"name": "ada"}},
)结果。 每个用户的 MySQL 订单嵌在同一份文档里返回 —— store 按源取数、内存 join、再水合成树:
[{"_id": "u1", "name": "ada", "orders": [{"code": "A1", "amount": 30.0}, ...]}]优势所在。 schema 由 (source, database, collection) 定位,每个定义携带自己的 datasource,一份注册表覆盖所有后端。SQL 跨 database / PG-schema 的 join 原生下推("db_a"."t" JOIN "db_b"."t");Mongo 跨源关系走联邦路径(query_federated)—— 某一段无法下推时你会收到结构化的 federation_degraded 事件,而不是悄悄变慢。这正是本仓库四库压测用 8 个并发 worker 跑的拓扑(Mongo 用户 → MySQL 订单,再加一个 PG 源,见性能)。
业务背景。 账户间转账:锁源行、校验余额、一侧扣款、另一侧入账、追加一条台账。任何一步失败都必须整体回滚。
async def transfer(amount, from_id, to_id):
rows = await store.execute_raw(
"pg_main", "SELECT balance FROM accounts WHERE _id = $1 FOR UPDATE", [from_id])
if rows["rows"][0]["balance"] < amount:
raise ValueError("insufficient funds") # 整个作用域回滚
await store.execute_raw(
"pg_main", "UPDATE accounts SET balance = balance - $1 WHERE _id = $2",
[amount, from_id], is_write=True)
await store.execute_raw(
"pg_main", "UPDATE accounts SET balance = balance + $1 WHERE _id = $2",
[amount, to_id], is_write=True)
await store.insert("Ledger", {"fromId": from_id, "toId": to_id, "amount": amount})
# ↑ 普通 CRUD 调用 —— 落在同一条事务连接上
await store.transaction("pg_main", lambda: transfer(30, "acc_a", "acc_b"))结果。 四条语句要么一起提交、要么一起不提交。execute_raw 返回 {"rows", "affectedRows"}(读给 rows、写给受影响行数),store.transaction(source, fn) 让 fn 内的一切复用同一条连接 —— 原生 SQL 与 CRUD 一视同仁。
优势所在。 原生 SQL 由 core 的 raw_stmt_compile 编译(命名 :name 参数或位置 ?/$1),转义与方言细节不必进你的代码,逃生舱口却完全是原生的(FOR UPDATE 照用)。Mongo 源按运行期探针(副本集 / 分片)包进 session 事务;standalone Mongo 或无事务原语的执行器按原样执行 fn 并发出 mongo_transaction_unsupported / transaction_not_atomic —— 降级会被宣告,绝不静默假装。同源嵌套作用域变成保存点:内层失败只回滚本层。
业务背景。 「创建订单」要碰三张表:插订单、扣库存、追加审计行。你希望这一切构成一个工作单元,而不是手工管连接。
async with store.session() as s:
order = await s.insert("Order", {"userId": "u1", "amount": 30})
await s.update("Inventory", {"_id": "sku1"}, {"$inc": {"stock": -1}})
await s.insert("AuditLog", {"kind": "order", "ref": order["_id"]})
# 正常退出 → 一次提交;任何异常 → 一次回滚结果。 同一 SQL 源上的每条命令都落在同一条事务连接上;会话退出时统一提交一次,任何异常统一回滚。无命令的会话绝不检出连接(惰性启动)。
优势所在。 会话可嵌套并带保存点(SAVEPOINT sp_<n>),内层失败只回滚内层、外层继续。危险情况 fail-closed:向 ≥2 个数据源写入的会话整体回滚并抛 NonAtomicWriteError —— 不存在会被静默提交一半的分布式事务。无原语的执行器发出 session_not_atomic 事件,而不是假装。
业务背景。 模型在代码里注册好了,DBA(或 Alembic)现在需要物理表。你想要一个迁移起点,且不引入第二份真相来源。
sql = store.generate_ddl("postgres") # 所有已注册模型
sql = store.generate_ddl("sqlite", ["Order", "OrderDeleted"]) # 只要这两张结果。 纯 CREATE TABLE 文本 —— 从不执行、从不写库 —— 由已注册 def 生成:
CREATE TABLE "bench_orders" (
"_id" TEXT PRIMARY KEY,
"user_id" TEXT,
"amount" REAL,
"qty" INTEGER,
"status" TEXT,
"__present" TEXT
);优势所在。 generate_ddl(backend, names) 是 sync_schema()(只读)的逆操作。自由命名的字段按后端翻译(userId 在 SQL 上是 user_id、在 Mongo 上是 userId),每张表都带 __present 哨兵列,<Model>Deleted 归档表与模型一起恰好生成一次。不发 CREATE INDEX(SQL 后端把索引当元数据保留),边界情况大声失败(ddlPresentOverflow)而非静默。
业务背景。 Order 的每次插入、改金额的更新、删除都必须留下审计行 —— 且审计写失败时,业务写也不能落地。
DEFS = [{
"name": "Order", "collection": "orders", "idPrefix": "OD",
"fields": {"_id": {"type": "string"}, "amount": {"type": "float"},
"status": {"type": "string"}},
"triggers": {
"insert": [{"name": "aud_ins", "into": "AuditLog", "op": "insert",
"data": {"_id": "{{now}}", "kind": "ins",
"ref": "{{root._id}}", "amount": "{{root.amount}}"}}],
"update": [{"name": "aud_upd", "onFields": ["amount"], "into": "AuditLog",
"op": "insert",
"data": {"_id": "{{now}}", "kind": "upd",
"ref": "{{root._id}}", "amount": "{{root.amount}}"}}],
"remove": [{"name": "aud_del", "fnRef": "auditRemove",
"args": {"id": "{{before._id}}"}}],
},
}, {
"name": "AuditLog", "collection": "audit_logs", "idPrefix": "AL",
"fields": {"_id": {"type": "string"}, "kind": {"type": "string"},
"ref": {"type": "string"}, "amount": {"type": "float"}},
}]
for d in DEFS:
store.register(d)
async def audit_remove(args, ctx, host):
await host["store"].insert("AuditLog", {"kind": "del", "ref": args["id"]})
store.set_trigger_fn("auditRemove", audit_remove)
store.assert_trigger_fns_covered(DEFS) # 启动期:声明的 fnRef 无实现 ⇒ ERR_TRIGGER_FN_MISSING结果。 写事件在 plan 期由 Rust core 展开成有序触发链,由宿主在与源写同一个原子包内执行:insert 与 update(amount) 留下命令式审计行;删除订单时以删除前文档({{before._id}})运行 auditRemove 回调。
优势所在。 触发链是数据、声明在 schema 上。update 事件只在被监视字段真的变化时触发(结构化深比较 —— 值没变绝不触发);{{root.*}} / {{before.*}} / {{now}} 是整值替换(嵌进字符串会抛 ERR_TRIGGER_PLACEHOLDER);重复的 (step.name, _id) 只跑一次;回调收到 (args, ctx, {"store": store}),回调内任何 store.* 都命中同一条事务连接。回调或命令步骤失败会整体回滚 —— 且不级联:触发器写出的数据绝不会再触发其他触发器。
业务背景。 合规要求删除也要留痕:行从所有列表里消失,但归档仍可查 —— 包括何时被删。
r = await store.remove("Order", {"_id": "o1"})
# r == {"deletedCount": 1, "archivedCount": 1}
archived = await store.query("OrderDeleted{ _id, amount, deletedAt }")结果。 文档先被复制进自动派生的 OrderDeleted 归档(带 deletedAt),再从 orders 删除。归档是普通已注册 def —— 普通 GQL 直接可查,并在 generate_ddl() 里恰好出现一次。
优势所在。 每个已注册模型在注册时由 Rust core 免费派生 <Model>Deleted 归档集合/表。归档写入按 _id upsert,所以重建相同 _id 不会冲突、部分失败后的重试会幂等重新归档。空条件的 remove 被直接拒绝 —— 忘写过滤条件不可能触发全表删除。
业务背景。 内部管理 API:分页列表、创建、软删。权限必须在数据层对每个端点强制,而不是逐路由重写。
from fastapi import Depends, FastAPI, Request
from py_store import init, store
app = FastAPI()
@app.on_event("startup")
async def startup():
await init({"default": mongo_db})
store.register({
"name": "Article", "collection": "articles", "idPrefix": "AR",
"fields": {"_id": {"type": "string"}, "title": {"type": "string", "default": ""},
"body": {"type": "string", "default": ""},
"status": {"type": "string", "default": "draft"},
"authorId": {"type": "string", "default": ""}},
"ownerKey": "authorId", # creator 归属键;必须在 fields 中声明
"read": ["editor", "viewer", "creator"],
"write": ["editor", "creator"],
})
async def current_user(request: Request) -> dict:
user = {"userId": request.headers["x-user-id"],
"roles": request.headers.getlist("x-role")}
store.set_context(user) # 一个依赖,覆盖整个请求
return user
@app.get("/articles")
async def list_articles(page: int = 0, page_size: int = 50,
user: dict = Depends(current_user)):
return await store.query_with_count(
"Article($sort:@s1){ _id, title, status }",
{"s1": {"createdAt": -1}, "page": page, "pageSize": page_size})
# → {"items", "total", "hasMore", "page", "pageSize"} (pageSize 上限 5000)
@app.delete("/articles/{article_id}")
async def delete_article(article_id: str, user: dict = Depends(current_user)):
return await store.remove("Article", {"_id": article_id}) # 先归档结果。 角色校验(schema/字段白名单、creator 归属)在每次 store 调用时自动运行,无逐路由代码;delete 留下可审计的归档行。
优势所在。 权限上下文存在 ContextVar 里,在 async 依赖里设置即覆盖整个请求路径(跑在线程池里的 sync 依赖做不到)。默认缺上下文是 fail-open(向后兼容);启动时翻转 store.set_require_context(True),忘设上下文就抛 ERR_NO_CONTEXT 而非放行。空条件写(update_many / remove 传 {})被直接拒绝,漏传过滤条件不可能变成全表写。完整演练见
doc/use-cases/04-fastapi-admin-backend.md。
下面的数字来自两个来源:撰写本 README 的这台机器上运行的微型基准(SQLite,无需任何服务 —— 查询/写入模式可直接复制运行),以及仓库自带的四库压测。
实测于 2026-10-15,Python 3.14.4,Windows amd64,aiosqlite 文件库,py-store 跑在 Rust core(rust-store-py)上。每项数字为丢弃 1 次预热后 4 次运行的中位数。种子数据:200 个用户;写入基准进行中订单表增至 30,000 行。
| 操作 | 数据量 | 中位耗时 | 吞吐 / 对比 |
|---|---|---|---|
insert_many(10 批 × 1,000) |
10,000 行 | 392 ms | ≈ 25,500 行/秒 |
循环单条 insert |
1,000 行 | 3,439 ms | ≈ 290 行/秒 → 批量快 ≈ 88 倍 |
| GQL 树查询 —— 1 次调用,关系嵌套 | 100 用户 + 15,000 子行 | 517 ms | 1 次调用 |
| 手写 N+1 —— 同一份数据 | 100 用户 + 15,000 子行 | 718 ms | 101 次调用 → 慢 1.4 倍 |
$group 下推 SQL |
10,000 行 | 15 ms | 1 次调用 |
| 全量拉回 + Python 侧 groupby | 10,000 行 | 600 ms | 慢 41 倍 |
计算列(读取时 fn) |
2,000 行 | 29 ms | ≈ 与手写循环持平(29 ms) |
怎么读这张表:
- 聚合是大头。
$group编译成在 SQLite 内部执行的GROUP BY;手写替代方案要为把 10,000 行搬过驱动、再在 Python 里重新聚合买单。 - 树查询赢在调用次数,而不只是耗时。 1 次往返对 101 次。对本机 SQLite 文件每次额外调用都很便宜,所以墙钟差距是 1.4 倍;跨网络连 MySQL/PostgreSQL/MongoDB 时,那 101 次调用每次都要付一个 RTT,差距随之拉大。
- 批量是最大的单项杠杆。 同样的行按每 1,000 行一次
insert_many写入,比 1,000 次单条插入快约 88 倍 —— 每次单条插入都要付一次规划加一次自己的提交。 - 计算列是诚实的,不是魔法。
fn逐行跑在 Python 侧,所以与手写循环持平,同时省掉你原本要手工维护的簿记工作(依赖注入、投影清理)。
stress/stress.py(本仓库)同时压 MongoDB + MySQL + PostgreSQL + SQLite —— 8 workers × 200 轮 × 每轮 5 操作(一条跨 3 源联邦查询、一次 SQLite 写、一次 PostgreSQL count、一次 Mongo 查询、一次 MySQL $inc 更新)。留档运行记录见
doc/2026-09-12-压测报告.md:8,000 次操作,0 错误,824 QPS,联邦查询 p50 19.3 ms / p95 24.2 ms。(待核实:撰写本 README 的机器未复跑 —— 需要运行中的 MySQL/PG/Mongo 服务;这些是仓库留档数字,可用该报告中的命令复现。)
- 规划在 Rust core。 GQL 解析、权限检查、计算列规划、命令规划与 SQL 方言翻译全部跑在 Rust(
rust-store-py,经 PyO3);Python 宿主每条命令过一次 FFI 边界,然后做驱动 IO —— 每命令一次跨界,不是每行一次。 - 下推优先于搬运数据。
JOIN/$lookup、GROUP BY/HAVING、EXISTS/NOT EXISTSsemi/anti-join、按父级的子列表排序分页,都编译成每个后端一条语句 —— 活儿在数据所在处干。 - 读取时再水合。 扁平 JOIN 行每次结果集只重组一次成嵌套文档;缺失的
one关系变None、空的many变[]—— 不发额外查询。 - 已知上限。 Python 侧的工作是真实存在的:
fn计算列逐行执行、asyncFn每页执行、跨源 Mongo 联邦在 Python 内存里 join。local磁盘源每集合上限 100,000 文档且不保留索引。这些数字都不是对你硬件的承诺 —— 把它们当预算前,先复跑微型基准(它只需要aiosqlite)。
如何在 Python 中用一份 schema 同时对接 MongoDB 与 PostgreSQL?
把 schema 定义为一个 dict 一次,用数据源调用 init(),然后对任一后端运行同一段 GQL。MongoDB 使用原生聚合;MySQL/PostgreSQL/SQLite 使用参数化 SQL。见快速开始。
如何在不写 $lookup 或 JOIN 的情况下查询嵌套 / 关联数据?
在 relations 中声明关系({"model", "type": "many" | "one", "localField", "foreignField"}),并在 GQL 选择集中引用关系名。在 Mongo 上它变成 $lookup,在 SQL 上变成 JOIN,以嵌套文档形式返回。
支持 GROUP BY / COUNT / SUM / AVG 吗?
支持 —— 规范化聚合是 GQL 的一部分:根级 $group / $having 与关系聚合谓词。见聚合。
我能用子级聚合来过滤父级吗(“订单数超过 3 的商品”)?
可以 —— 关系聚合谓词在不产生扇出的情况下实现 semi/anti-join;SQL 使用 EXISTS/NOT EXISTS。
如何实现行级权限?
使用 store.set_context({"userId": ..., "roles": [...]}) 加上 schema 级 read/write 白名单。creator 伪角色会带来自动的归属校验与属主条件注入(归属键由 schema ownerKey 声明,缺省 createdBy)。guest 永远不能写。开启 set_require_context(True) 可获得失败安全行为。
如何做软删除?
每个已注册模型都会自动获得一个 <Model>Deleted 归档集合/表。store.remove() 先归档文档再删除;重新创建相同的 _id 不会冲突,因为归档写入是按 _id upsert。
它能用于多租户应用吗?
可以。通过 (source, database, schema, collection) 定位 schema,并按请求传入 {"source", "database", "schema"} 路由覆盖。只把 route_override 当作受信的服务端输入。
它会执行迁移吗?
会,但只执行白名单内的非破坏变更。store.migrate(backend=..., source=..., defs=..., driver=...) 对比内省结构与 def,执行加表 / 加列 / 加索引 / 类型放宽,并在 __schemaMigration 写入版本行;白名单外(删列、改窄类型等)显式抛 MigrationUnsupported 并给分步建议,绝不静默执行或自动回滚。sync_schema() 仍只读取物理结构(introspect → 合并 overlay → 注册);只想拿 DDL 文本时用 store.generate_ddl(backend)(纯文本,绝不执行)。老库缺内建列会先自动补列再告警,不阻断升级。
能在不执行的情况下查看生成的查询吗?
可以 —— store.build_pipeline(gql, params) 返回编译后的计划,不执行、也不应用权限/计算列。
当 SQL 下推无法完成时会怎样?
命令会抛出 PushdownUnsupportedError 并通过 set_feedback_sink 发出结构化反馈事件(sql_pushdown_unsupported)。跨源分页/排序降级会发出 federation_degraded 事件。没有任何东西会静默失败。
它与 nodejs-store、rust-store 是什么关系?
rust-store 是共享的 Rust 引擎(GQL 解析、权限、计算列、命令规划、SQL 方言翻译 —— 纯逻辑、无 IO)。py-store(pip storepy)与 nodejs-store 是它前面的薄宿主:负责驱动 IO、回调与占位符替换。Python 与 Node 使用相同的 schema、相同的 GQL、相同的语义。
为什么 pip 包叫 storepy 而导入名是 py_store?
在 PyPI 上的发行包名是 storepy;可导入包是 py_store。用 pip install storepy 安装,然后 from py_store import init, store。
# 在仓库根目录运行完整测试套件(当 MySQL/PG/Mongo 不可达时 e2e 用例会自动跳过)
$env:PYTHONPATH='py-store/src'; python -m pytest py-store/tests/ -q
# 对接自定义后端
$env:MYSQL_URI='mysql://user:pass@host:3306/db'; $env:PG_URI='postgres://user:pass@host:5432/db'; $env:MONGO_URI='mongodb://host:27017/db'- 单元/契约测试套件(
test_py_store.py、test_host_contract.py、test_multi_datasource.py)无需外部服务。 - Rust 核心(
GQL 解析 / 规划 / 方言)位于../rust-store/core,通过rust-store-py绑定使用 —— 纯逻辑从不放在本仓库。 src/py_store/是薄 Host 层:驱动 IO、回调、占位符替换。请保持其如此。
nodejs-store(Gitee)—— Node.js 孪生版(npmnodejs-store,camelCase API)。rust-store(Gitee)—— 共享的 Rust 核心及其rust-store-node/rust-store-py绑定。text-to-query—— 把自然语言问题转换为该数据层的 GQL + params 的技能。
- 定义层(数据):模型 / 权限 / 编排 / 接口 —— 一律纯 JSON,可发布、可回滚、可热更。
- 回调层(代码):数据源 IO、计算列实现、外部调用、事务 —— 以
fnRef声明、启动时注入;不可序列化,禁止入库。 - 可观测层:一切降级/拦截/兜底事件落
__feedback(可用 GQL 查询),绝不静默。