Database Block

在工作流中直接操作项目的数据表，支持查询、统计、插入、更新和删除五种操作。

功能说明

Database Block 是一个数据节点，允许你在编辑器工作流中对项目的 Collection（数据表）执行 CRUD 操作。查询结果以变量形式输出，可被后续 Block 引用。所有数据输入都支持变量引用（ValueSource），可以动态使用上游 Block 的输出作为参数。

当你需要在工作流中读取数据库记录、写入新数据、更新已有记录、或删除数据时，使用 Database Block。前提是项目中已经创建了对应的 Collection（数据表）。

使用场景

• 数据驱动的 AI 生成：先查询数据库获取上下文信息，再将查询结果传给 Generation Block 生成内容
• 工作流自动化：根据 AI 生成的结构化数据自动插入或更新数据库记录
• 数据管道：查询 -> 处理 -> 回写，构建完整的数据处理流水线

配置参数

属性名	类型	说明	默认值
collectionId	string	目标数据表 ID（从下拉列表选择）	''
operation	'query' | 'count' | 'insert' | 'update' | 'delete'	操作类型	'query'
filtersJSON	string	查询过滤条件（JSON 序列化的 DatabaseFilter[]）	'[]'
sortJSON	string	排序配置（JSON 序列化的 DatabaseSort）	'{}'
page	string	从 1 开始的正安全整数页码，支持变量引用（JSON 序列化的 ValueSource）	''（默认 1）
pageSize	string	每页条数，限制在 1–100，支持变量引用（JSON 序列化的 ValueSource）	''（未配置时默认 20）
insertDataJSON	string	插入数据，字段到值的映射（JSON 序列化）	'{}'
targetRowId	string	更新/删除的目标行 ID，支持变量引用	''
updateDataJSON	string	更新数据，字段到值的映射（JSON 序列化）	'{}'
deleteRowId	string	删除的目标行 ID，支持变量引用	''
confirmBeforeWrite	boolean	写入前确认（预留功能，暂未生效）	false

过滤运算符

运算符	含义	示例
eq	等于	name = "张三"
neq	不等于	status != "deleted"
gt	大于	age > 18
gte	大于等于	score >= 60
lt	小于	price < 100
lte	小于等于	count <= 10
contains	包含	name 包含 "张"
not_contains	不包含	email 不包含 "test"

输出变量

输出变量根据操作类型不同而变化：

Query 操作

变量名	类型	说明
__default__	array	查询结果数组（同 rows）
rows	array	本页筛选后的记录数组，每项包含 id、自定义字段、_created_at、_updated_at
total	number	当前表未删除的记录总数，不受分页或 filtersJSON 影响
page	number	本次请求的页码；越界时仍保留请求页码
pageSize	number	本次查询使用的每页条数，限制在 1–100
totalPages	number	总页数，按 total/pageSize 向上取整；空表为 0
hasMore	boolean	是否还有下一页，即 page < totalPages
nextPage	number | null	有下一页时为 page + 1；终页或合法越界页为 null

一次 Query 只读取指定页，不会自动读取全表。缺少 page 的旧工作流仍读取第 1 页；需要读取更多记录时，须分别传入后续页码。

filtersJSON 在取得本页后执行。total/totalPages/hasMore/nextPage 依据整表未删除记录计算，不能当作筛选匹配数；筛选后 rows=[] 仍可能 hasMore=true，不能用空数组判断读取完成。

终页、空表或合法越界页返回 hasMore=false/nextPage=null；合法越界页的 rows=[]。非法页码、无法解析的页码变量、超出安全分页范围、取消或读取失败会报错，不能当作成功终页。nextPage 可用作下一次手工查询或上游流程提供的页码；它不会自动更新 Loop 变量。

Count 操作

变量名	类型	说明
__default__	number	记录总数
total	number	记录总数

Insert 操作

变量名	类型	说明
__default__	object	新创建的记录对象
row	object	新创建的记录，含 id、自定义字段、_created_at、_updated_at

Update 操作

变量名	类型	说明
__default__	object	更新后的记录对象
row	object	更新后的完整记录

Delete 操作

变量名	类型	说明
__default__	boolean	true 表示删除成功
success	boolean	true 表示删除成功
deletedId	string	被删除行的 UUID

引用语法

{{database_0}}                 -- 默认输出（类型随操作不同）
{{database_0.rows}}            -- 查询结果数组
{{database_0.rows.0.id}}       -- 第一条记录的 ID
{{database_0.rows.0.name}}     -- 第一条记录的 name 字段
{{database_0.total}}           -- 记录总数
{{database_0.page}}            -- 本次请求页码
{{database_0.pageSize}}        -- 本次每页条数
{{database_0.totalPages}}      -- 总页数
{{database_0.hasMore}}         -- 是否还有下一页
{{database_0.nextPage}}        -- 下一页页码或 null
{{database_0.row}}             -- 新建/更新后的记录
{{database_0.row.id}}          -- 新建/更新记录的 ID
{{database_0.success}}         -- 删除是否成功
{{database_0.deletedId}}       -- 被删除行的 ID

使用示例

示例 1：分页读取 105 条用户记录并遍历处理

假设 users 表有稳定的 105 条未删除记录，且查询不设置过滤条件。每页读取 10 条，在运行前算好固定次数：105 ÷ 10 向上取整为 11。

1. 创建名为 pages 的 Loop Block，选择计数循环，次数填 11。
2. 在其内部放入名为 db_users 的 Database Block，操作为 Query，选择 users 表，每页条数填 10；页码输入选择变量 pages.count。
3. 在 Query 后放入名为 users 的 Loop Block，选择列表循环，列表引用 db_users.rows。
4. 在列表循环内部生成当前用户的内容，引用 users.item.name 和 users.item.email。

[Loop Block: pages] — 计数循环，固定 11 次
  [Database Block: db_users] — Query，表: users
    页码: {{pages.count}}，每页: 10，无过滤条件
  [Loop Block: users] — 列表循环，列表: {{db_users.rows}}
    [Generation Block] — "为 {{users.item.name}} 生成欢迎邮件，邮箱: {{users.item.email}}"

pages.count 在循环体执行前就已赋值，从 1 开始，所以首轮查询第 1 页。前 10 页各返回 10 条，第 11 页返回 5 条。循环结束后查看最后一轮 Query 输出，或在后续 Block 分别引用 db_users.page、db_users.hasMore 和 db_users.nextPage；本例末页应为 page=11/hasMore=false/nextPage=null。若最后仍为 hasMore=true，说明固定次数不足，尚未读完。

此例逐页处理记录，不自动累计跨页数组或核对总数。无过滤且数据稳定时，各页条数合计应为 105。多执行一轮查询合法越界页只会返回空页。条件 Loop 默认迭代上限为 10；本例使用显式 11 次计数循环，不依赖条件循环或尚未生成的上轮输出。

示例 2：查询 -> 判断 -> 插入

查询订单数量，超过阈值时插入告警记录：

[Database Block: order_count] — 操作: Count, 表: orders
    |
[Condition Block] — 条件: {{order_count.total}} > 1000
  ├─ true:
  │   └─ [Database Block: alert] — 操作: Insert, 表: alerts
  │       字段 message = "订单数超过 1000"
  │       字段 count = {{order_count.total}}
  └─ false:
      └─ (跳过)

运行时约束

• 适用文档类型：所有文档类型（workflow、skill 均可使用）
• 可插入上下文：顶层文档、Condition 分支、Loop 内、Promise 分支
• 不可嵌套场景：无特殊限制

注意事项

1. 必须先创建数据表：使用前需在项目的「数据库」页面中创建 Collection 并定义 Schema，否则配置面板中无法选择目标表
2. 过滤条件在分页后执行：只筛选本页；总数和翻页状态仍基于整表未删除记录，筛选后空页也可能还有下一页
3. 指定页查询：Query 支持页码，默认第 1 页；一次只读取一页，读取多页需由工作流传入后续页码
4. 分页边界：page 必须解析为正安全整数；pageSize 未配置时默认 20，限制在 1–100。小页增加执行次数，深页 offset 和精确总数统计有性能成本；执行仍受任务预算和取消限制
5. 软删除：Delete 操作是软删除（设置 deleted_at），数据不会被物理移除，可在数据库页面的回收站中恢复
6. 排序与并发：目前只能按系统字段（created_at、updated_at）排序，自定义字段排序会降级为按创建时间排序；追加行 ID 确定同时间戳记录的顺序。分页没有跨页快照，并发增删可能造成重复或遗漏，完整遍历应在数据稳定时执行
7. 所有值输入支持变量引用：page、pageSize、targetRowId、deleteRowId 以及 Insert/Update 的每个字段值都可以引用上游 Block 的输出变量