Obsidian V25 Core | 完整开发者 API 手册

BaaS Engine Reference

系统架构与全局规范

Obsidian V25 是构建于 Cloudflare Workers 与 D1 SQLite 之上的百万级高并发 Serverless 引擎。所有 API 请求均强制采用 POST 方法与 application/json 载荷，以防范跨站请求伪造 (CSRF) 并最大化边缘路由性能。

全局特性约束：

软删除保护：若表中存在 deleted_at 字段，查询和更新时引擎会自动注入 deleted_at IS NULL，除非手动设置 excludeDeleted: false。
全局速率限制：每个 IP 被底层防火墙限制为 300次/分钟。
自动时间戳：写入数据时，引擎会自动维护 created_at 和 updated_at。
防崩溃全表扫描：禁止 /update 和 /delete 在不传递 where 参数时运行。

身份认证 (Auth)

引擎支持两种身份级别的调用。所有请求必须携带 Authorization 头。

身份类型	请求头示例	权限范围
管理员 (Root)	`Bearer <ADMIN_KEY>`	拥有绝对控制权。可调用 `/issueApp`、`/raw`、`/telemetry`。操作无视表名前缀沙盒。
应用/开发者 (App)	`Bearer <JWT_TOKEN>`	通过 `/issueApp` 签发的 JWT 令牌。只能操作沙盒前缀（如 `appID_users`）内的表。

* 管理员可通过传递 X-DB-Binding: db_2 请求头来动态穿透路由，强制指定操作的物理集群节点。

查询语法树 (AST Compiler) 指南

引擎内置了安全且强大的 JSON 转 SQL 编译器。它用于 select、update、delete、count、aggregate 接口中的 where 字段。

1. 基础等值匹配与多字段 AND

"where": {
  "status": "active",
  "role": "admin" // 默认为 AND 关系
}

2. 关系操作符

支持：$gt(>), $gte(>=), $lt(<), $lte(<=), $ne(!=), $like, $match

"where": {
  "age": { "$gte": 18, "$lt": 35 },
  "username": { "$like": "%admin%" }
}

3. 集合与范围操作符

支持：$in (数组), $nin (不在数组中), $between (两个元素的数组)

"where": {
  "category_id": { "$in": [1, 2, 5, 9] },
  "created_at": { "$between":["2026-01-01", "2026-12-31"] }
}

4. 逻辑操作符 ($or / $and)

必须传入对象数组，最大嵌套深度 5 层。

"where": {
  "deleted_at": { "$isNull": true },
  "$or":[
    { "status": "pending" },
    { "balance": { "$lt": 0 } }
  ]
}

5. JSON 动态路径解析 (提取 JSON 内部字段)

当数据库列存储的是 JSON 字符串时，可用 点(.) 语法深度查询。

"where": {
  "profile.address.city": "Shanghai"  // 编译为: "profile"->>'$.address.city' = 'Shanghai'
}

POST /select

获取数据列表。支持游标分页、边缘缓存加速和子查询连表（Relations）。

参数 Payload

参数名	类型	描述
table	String	必需。目标数据表名称。
columns	Array	可选。要查询的字段列表。例如 `["id", "name", "profile.avatar"]`。默认 `["*"]`。
where	Object	可选。AST 格式查询条件。详见上文 AST 指南。
limit	Number	可选。单页数量，默认 100，最大 1000。
offset / page	Number	可选。传统偏移量分页。推荐使用 cursor 替代。
cursor	String	可选。游标字符串（基于 orderBy 字段自动生成，在响应中返回），用于千万级数据高效翻页。
orderBy	String	可选。排序字段，支持 JSON 路径 `"profile.age"`。
orderDesc	Boolean	可选。是否降序排列。默认 false (ASC)。
relations	Array	可选。连表映射数组（自动利用 JSON_GROUP_ARRAY 组装子查询）。最多支持 5 组关联。
strategy	String	可选。传 `"fast"` 可开启 Isolate 级别的 L1 短暂内存缓存（约 3 秒），抵御瞬间读并发洪峰。
excludeDeleted	Boolean	可选。如果传 `false`，将返回包含被软删除的数据。默认 true。

请求示例 (包含 Relations 连表)

{
  "table": "users",
  "limit": 10,
  "orderBy": "created_at",
  "orderDesc": true,
  "relations":[
    {
      "table": "orders",
      "fKey": "user_id",    // 子表的外键
      "lKey": "id",         // 主表的主键
      "as": "user_orders",  // 映射后的别名
      "columns": ["id", "amount", "status"]
    }
  ]
}

响应示例

{
  "data":[
    {
      "id": "u_001",
      "name": "Alice",
      "user_orders":[
        {"id": "ord_1", "amount": 250},
        {"id": "ord_2", "amount": 10}
      ]
    }
  ],
  "nextCursor": "eyIkZ3QiOiIyMDI2LTA0LTAzIn0="
}

POST /insert

新增实体数据，支持单条或多条（数组）批量写入，支持 Edge Buffer 高并发排队缓冲。

参数 Payload

参数名	类型	描述
table	String	必需。目标数据表名称。
values	Obj/Arr	必需。要插入的实体对象或对象数组。若未传 `id` 将自动生成 UUID。
buffered	Boolean	可选。设为 `true` 将请求存入 Worker 内存队列后立即返回 200，由后台协程组装批量刷盘。极大幅度提升写入吞吐。
webhookUrl	String	可选。插入成功后，引擎后台会向该 URL 异步发送 POST 请求（CDC 数据变更捕获）。

{
  "table": "logs",
  "buffered": true,
  "values": {
    "action": "login",
    "ip": "192.168.1.1",
    "metadata": { "browser": "Chrome" }
  }
}

POST /upsert

原子级的存在则更新、不存在则插入。利用了 SQLite 的 ON CONFLICT(id) DO UPDATE 原生语法，无竞态问题。

规范要求

实体对象必须包含 id 字段。
目标表必须显式设置了 id 为主键或唯一索引。

{
  "table": "user_stats",
  "values": {
    "id": "stat_user_001",
    "login_days": 15,
    "last_login": "2026-04-03"
  }
}

POST /update

参数 Payload

参数名	类型	描述
table	String	必需。目标数据表名称。
where	Object	必需。AST 匹配条件。严禁为空（防呆全表覆写）。
values	Object	必需。要更新的键值对。自动忽略 `id` 和 `created_at`。
webhookUrl	String	可选。更新后的 CDC 推送。

POST /delete

参数 Payload

参数名	类型	描述
table	String	必需。目标数据表名称。
where	Object	必需。AST 匹配条件。严禁为空。
softDelete	Boolean	可选。若设为 `true` 且表有 `deleted_at` 字段，则执行软删除（UPDATE deleted_at），否则执行硬删除 (DELETE)。

POST /aggregate

在数据库底层执行数学统计操作，支持同时聚合多个字段，并支持边缘内存加速。

{
  "table": "orders",
  "where": { "status": "completed" },
  "sum": ["amount", "fee"],
  "avg": ["processing_time"],
  "max": ["amount"],
  "strategy": "fast" // 对于实时大屏建议开启
}

响应示例: {"data":[{"sum_amount": 10500, "sum_fee": 300, "avg_processing_time": 1.5, "max_amount": 4999}]}

POST /batch

将最多 50 个互不相关的操作（查、插、删、改）打包为单次 HTTP 请求。引擎在底层开启事务，确保执行顺序与原子性。

{
  "ops":[
    {
      "action": "insert",
      "payload": { "table": "users", "values": { "id": "u1", "name": "Tom" } }
    },
    {
      "action": "update",
      "payload": { "table": "stats", "where": {"type": "users"}, "values": {"total": 10} }
    },
    {
      "action": "select",
      "payload": { "table": "users", "limit": 1 }
    }
  ]
}

响应将是一个数组，按严格索引顺序返回 ops 中每一个 action 的执行结果。

Admin Root Only

管理员集群接口

POST

/issueApp

创建子应用空间。引擎会自动扫描所有节点，并将新 App 路由至负载最低的物理集群上，最后签发永久 JWT。

{ "appName": "E-Commerce Frontend" }

POST

/migrate

集群级架构定义 (DDL)。支持创建表和建立常规/联合索引。底层会自动对表名进行 AppID 沙盒化拼接。

{
  "tables":[
    {
      "name": "products",
      "columns":[
        { "name": "id", "type": "TEXT PRIMARY KEY" },
        { "name": "title", "type": "TEXT" },
        { "name": "price", "type": "INTEGER" },
        { "name": "created_at", "type": "DATETIME DEFAULT CURRENT_TIMESTAMP" }
      ],
      "indexes":[
        "title",              // 单列索引
        ["category", "price"] // 复合索引
      ]
    }
  ]
}

POST

/raw

执行无沙盒防御、无安全限制的底层原生 SQL 穿透。极其危险，仅作调试和特殊数据干预使用。

{
  "db": "db_2", // 强制穿透至 db_2 节点，不传则使用默认主节点
  "sql": "DELETE FROM sqlite_sequence WHERE name = ?",
  "params":["public_users"]
}