在工作流中使用数据库

当前工作流提供查询、新增、更新、删除和自定义 SQL 五类数据库操作。数据库节点会继续受到测试/线上环境、渠道范围、用户范围和工作空间权限约束。

数据库节点

节点或操作	主要配置	典型输出	适用场景
查询数据	数据库、查询字段、条件、排序、查询上限	记录列表和行数	按用户、状态、时间或业务键读取数据
新增数据	数据库、字段和值	新增记录或影响行数	创建订单、任务、报名或日志记录
更新数据	数据库、更新条件、字段和值	影响行数	根据记录 id 或唯一业务键修改状态
删除数据	数据库、删除条件	影响行数	删除明确范围内且允许物理删除的记录
自定义 SQL	输入变量、数据库、SQL	outputList、rowNum	标准节点无法表达的受控查询或写入

每个节点先选择当前工作空间中可用的数据库。不要把页面上看到的名称当作稳定标识；复制工作流到其他空间后，需要重新核对数据库资源和字段引用。

以下界面来自当前系统中的文档示例工作流 docs_database_memory_demo。示例绑定 daily_expenses 数据库，只保存节点配置，未执行新增、更新或删除。画布已经自动布局，截图中的节点保持分离，便于同时核对节点卡片和右侧属性面板。

查询数据

图中标记说明：

1. 在画布中选中 查询数据 节点，右侧会显示该节点的完整属性。
2. 一个查询节点只能绑定一个数据库资源；复制工作流后要重新确认资源和字段。
3. 查询字段、查询条件、排序方式和查询上限共同决定返回范围，不能只配置条件而忽略上限。

查询字段

只选择下游真正需要的字段。可以按字段配置去重，不要默认把系统字段、个人信息和无关大文本全部返回给模型。

查询条件

当前条件支持等于、不等于、大于、小于、大于等于、小于等于、包含、不包含、属于、不属于、为空、不为空、为真和为假等操作；多个条件可用“且”或“或”组合。

条件值可以来自固定值或上游变量。配置时检查变量类型与数据库字段类型一致，并处理空值：空的记录 id、用户输入或宽泛的“或”条件可能扩大查询范围。

排序与上限

按稳定字段排序，例如 created_at 和业务序号。当前节点界面提示单次查询最多 1000 条；正式流程应根据实际用途设置更小上限，并为无结果、恰好一条、多条和截断结果分别处理。

新增数据

图中标记说明：

1. 选中 新增数据 节点后，先确认节点卡片没有与其他节点重叠。
2. 绑定目标数据表后，面板会展示可写字段及其类型。
3. 逐个选择要写入的字段，并填写固定值或引用上游变量；截图中的“文档示例支出”仅用于展示配置格式。

新增节点应映射全部必填自定义字段。系统字段由平台生成，不应由模型或用户输入覆盖。

写入前校验：

• 字符串枚举、长度和格式。
• 整数、数值范围与单位。
• 布尔和时间类型。
• 业务唯一键是否已经存在。
• 重复触发时使用幂等键，避免插入多条相同记录。

更新数据

图中标记说明：

1. 选中 更新数据 节点，核对画布卡片中的数据表、更新字段和更新条件摘要。
2. 右侧面板展示当前数据库及字段，先确认表结构仍与工作流设计一致。
3. 设置字段 决定改什么，更新条件 决定改哪些记录；两者缺一不可。

更新节点由“更新条件”和“设置字段”组成。优先使用记录 id 或唯一业务键定位，避免只用状态、时间范围或用户可控文本批量更新。

更新前可以先执行查询节点，并检查结果数量：

1. 结果为 0 时返回“记录不存在”，不要无条件新增。
2. 结果为 1 时执行更新。
3. 结果大于 1 时停止并记录条件异常，除非业务明确允许批量更新。

删除数据

图中标记说明：

1. 选中 删除数据 节点后，画布卡片会显示数据表和条件摘要。
2. 删除前再次确认目标数据表，避免复制节点后仍指向旧资源。
3. 删除条件必须明确且可验证。截图使用 sys_platform = docs_demo 作为演示条件，不代表生产环境推荐按该字段删除。

删除节点必须有明确、可验证的删除条件。涉及用户数据、订单、内容发布或其他不可恢复记录时，应先查询目标记录并向用户展示影响范围，再执行删除。

需要审计和恢复能力的业务，优先通过更新节点写入 status 或 deleted_at 实现软删除。

自定义 SQL

图中标记说明：

1. 选中 SQL 自定义 节点，先核对节点输入、输出和绑定的数据表。
2. 在输入区声明变量名、类型和示例值；运行时可以改为引用上游变量。
3. SQL 中使用 {{变量名}} 引用输入，例如截图中的 {{expense_id}}，不要把用户文本直接拼进 SQL。

自定义 SQL 用于标准节点无法表达的场景。当前运行服务会限制部分高风险语句，并对返回行数设置上限，但这不能代替正确的 SQL 设计。

配置	说明
输入	声明 SQL 中引用的固定值或上游变量
数据库	选择一个数据库资源；不要跨资源拼接多库查询
SQL	使用命名参数或节点变量，不直接拼接用户文本
outputList	SQL 返回的字段和值，名称应与 SQL 选择的字段一致
rowNum	查询返回行数或写操作影响行数

旧文档中“不支持 SELECT *、不支持多表 JOIN、建议返回 100 行”的限制属于历史版本说明。当前实现提供独立的 SQL 安全校验和最高 1000 行控制；仍建议显式选择字段、避免复杂跨表操作，并把业务查询上限控制在实际需要的范围内。

测试数据与线上数据

工作流试运行通常应使用测试数据。测试结果与线上数据隔离，因此“在调试台能查到、正式渠道查不到”通常不是节点随机失败，而是环境或渠道配置不同。

发布前执行：

1. 在测试环境覆盖成功、空结果、非法输入和重复提交。
2. 核对数据库的渠道读写配置是否把正式调用渠道指向线上数据。
3. 用真实但可脱敏的最终用户身份完成一次正式渠道验收。
4. 验证单用户/多用户和渠道隔离符合预期。
5. 检查节点日志没有泄露整行个人信息或敏感字段。

身份与渠道

数据库节点依赖调用方传递的最终用户和渠道。常见问题包括：

• 调试与发布使用不同用户，单用户模式下自然查不到对方记录。
• API、Web SDK 和 AIOS 站内使用不同渠道编码，渠道隔离后记录不可互见。
• 多用户模式仅在工作流数据库节点中扩展用户范围，不会自动跨越渠道隔离。
• 渠道读写配置把调试入口指向测试数据、正式入口指向线上数据，两边记录不会同步。

安全与治理

• 默认使用单用户和渠道隔离，按业务需要逐级放宽。
• 查询只返回必要字段，并设置合理上限和稳定排序。
• 新增和更新使用参数校验、唯一键与幂等保护。
• 更新、删除先验证结果数量，高风险操作增加明确确认。
• SQL 使用参数化输入，不拼接用户文本，不返回密码、Token 或内部权限字段。
• 日志、调试输入和输出使用脱敏数据；线上错误不得通过无限重试掩盖。
• 表结构变更前检查所有引用节点，变更后重新试运行并发布工作流。

常见问题

为什么工作流查不到刚添加的数据？

按顺序检查数据库资源、测试/线上环境、渠道读写配置、sys_platform、最终用户 uuid、查询条件和当前工作流版本。

为什么多用户模式仍然查不到其他用户数据？

确认操作发生在工作流数据库节点中，并检查渠道是否一致。多用户模式扩大的是同一可访问渠道范围内的用户数据，不会自动跨渠道。

为什么更新或删除影响了多条记录？

条件不是唯一的，或“且/或”关系配置错误。立即停止后续写入，记录节点版本、条件和影响行数；从备份或业务来源恢复后，改用记录 id 或唯一业务键。

为什么调试成功，发布后没有数据？

调试和正式渠道通常指向不同数据环境。检查渠道读写配置，并在正式渠道用正确用户身份完成端到端验证。

为什么复制到其他空间后节点失效？

工作流定义可以复制，但数据库资源、数据、权限和渠道配置不会被视为同一资源。进入目标空间重新选择数据库并校验字段映射。

返回数据库概述或继续阅读配置节点与变量。