SQL 自定义节点

SQL 自定义节点用于在指定数据表上执行自定义 SQL，适合可视化增删改查节点无法表达的查询、聚合或精确更新场景。

自定义 SQL 权限更大、风险也更高。普通单表新增、查询、更新和删除应优先使用对应的可视化节点；只有确实需要 SQL 表达能力时再使用本节点。

添加与配置

在节点面板的 数据库 分类中添加 SQL自定义 节点。属性面板依次提供输入、数据表、SQL、输出和异常处理配置。

SQL 自定义节点完整配置

输入

输入区域定义 SQL 中要使用的动态参数。每一项包含变量名、变量类型和变量值：

变量值可以填写固定值，也可以引用上游节点输出；
变量名应稳定、唯一，并与 SQL 中的占位符保持一致；
参数类型应与数据表字段和比较操作相匹配。

截图示例定义了 String 参数 record_id。不要把整段 SQL、表名、字段名或排序关键字直接交给不可信的用户输入控制。

数据表

单击 添加数据表 从资源库数据库中选择数据表。每个 SQL 自定义节点支持添加一个数据表；选中后可查看字段信息，也可以移除后重新选择。

执行 SQL 前应确认：

数据表属于正确的工作空间和环境；
当前工作流和执行身份具有所需权限；
表结构、字段类型和约束与 SQL 一致；
调试数据是否与正式数据隔离，应以目标环境的实际配置和试运行结果为准。

SQL

SQL 编辑区支持引用输入参数。为避免文档站点把语法解析为模板，下例使用全角花括号展示；在编辑器中必须输入半角花括号：

sql

SELECT id, uuid, created_at
FROM daily_expenses
WHERE id = ｛｛record_id｝｝;

一个节点应只承担一项清晰、可验证的数据库操作。不要依赖多条语句、隐式事务或跨表副作用；需要多步操作时拆成多个节点，并明确失败后的补偿方案。

输出

节点提供两个固定输出：

输出	类型	说明
`outputList`	`Array＜Object＞`	SQL 执行返回的记录列表；可按实际返回字段添加子项
`rowNum`	`Integer`	返回记录数或写操作受影响行数，具体语义以实际 SQL 和执行结果为准

为 outputList 添加子项时，变量名应与 SQL 返回字段或别名一致，类型应与真实结果一致。查询未命中时，下游应能处理空列表；写操作应检查 rowNum 是否符合预期。

错误处理应以异常分支或运行结果为准。

异常处理

新建节点的默认设置为：

整体执行超时：60 秒；
重试次数：不重试；
异常处理方式：中断流程。

写操作不要盲目开启重试，否则可能产生重复插入或重复副作用。需要重试时，应先建立业务幂等键、唯一约束或明确的幂等机制。

安全与验证

对动态值使用节点输入参数，不直接拼接未经校验的用户文本；
不允许用户控制表名、字段名、排序表达式或完整 SQL；
使用最小权限数据库资源，读流程不要授予写权限；
更新和删除前先以相同条件执行查询，核对命中数量和样例记录；
写操作先在明确的测试数据上验证，并记录必要的业务审计信息；
不要假定多个数据库节点自动组成同一事务。

示例：按记录 ID 查询

新增 String 输入参数 record_id，固定填写测试 ID 或引用上游输入；
选择 daily_expenses 数据表；
编写按 id 查询所需字段的 SQL；
为 outputList 添加与返回列匹配的子项；
试运行后检查 outputList 和 rowNum，再连接下游节点。

常见问题

为什么 SQL 中的参数没有被替换？

检查输入变量名与占位符是否完全一致，并确认使用的是半角双花括号。还要确认输入值不是空值，且引用的上游节点在当前路径上已经执行。

为什么 `outputList` 有数据，但下游看不到字段？

在 outputList 下添加与 SQL 返回列或别名一致的子项，并配置正确类型。修改 SQL 的返回字段后，应同步更新输出结构和下游引用。

为什么查询没有结果？

依次核对数据表、环境、参数值、字段类型和 SQL 条件，并直接查看所选资源后试运行确认。

为什么不建议对写 SQL 开启自动重试？

超时不等于数据库没有执行成功。没有幂等保护时重试可能重复插入或重复更新，必须先确认操作可安全重放。