尧图网站建设 
Activepieces 集成 SurrealDB 实战连接配置、Run Query 动作与 New Row 轮询触发器完全指南【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepiecesSurrealDB 是一款支持关系、文档与图模型的 Multi Model Database而activepieces/piece-surrealdb正是 Activepieces 官方社区提供的 SurrealDB 集成组件。本文围绕该组件的源码实现系统讲解如何在 Activepieces 中配置 SurrealDB 连接、通过参数化查询执行任意 SurrealQL 语句以及如何利用轮询触发器监听新数据写入读完即可在自己的工作流中直接落地使用。组件概览与构建方式SurrealDB piece 的完整源码位于 packages/pieces/community/surrealdb由四个核心 TypeScript 文件构成src/index.ts注册 piece 元信息、定义认证方式并挂载动作与触发器src/lib/common.ts封装底层 SurrealDB HTTP/sql端点调用src/lib/actions/run-query.ts实现「Run Query」动作src/lib/triggers/new-row.ts实现「New Row」轮询触发器。从 package.json 可见该组件版本为0.1.6仅依赖activepieces/pieces-common、activepieces/pieces-framework等 workspace 内部包与dayjs不依赖任何 SurrealDB 官方 SDK——所有数据库交互都是通过 HTTP 接口完成的详见下文「底层调用原理」。构建该库时官方 README 给出的命令为turbo run build --filteractivepieces/piece-surrealdb除构建外package.json 还暴露了以下脚本脚本命令作用buildtsc -p tsconfig.lib.json cp package.json dist/用 TypeScript 编译并把 package.json 复制进产物目录bundlenode ../../../../dist/packages/cli/src/index.js pieces bundle将 piece 打包为 Activepieces 可加载的 bundlelinteslint src/**/*.ts对源码执行 ESLint 检查编译配置定义在 tsconfig.lib.json 中以commonjs模块格式输出到dist目录并生成类型声明declaration与声明映射文件供其他包引用类型。连接配置五个必填参数与连接校验在 Activepieces 流程中添加 SurrealDB 连接时piece 使用PieceAuth.CustomAuth自定义认证表单见 src/index.ts共包含五个必填required: true字段字段显示名说明与示例urlConnection URL连接地址例如http://1.2.3.5:8000databaseDatabase要连接的数据库名称namespaceNamespace数据库所在的命名空间usernameUsername数据库用户名passwordPassword数据库密码在保存连接时piece 会执行一次连接校验validate回调调用surrealClient.query(auth, INFO for db)向数据库发送 SurrealQL 的INFO for db语句。若请求抛出异常则返回valid: false并携带错误信息连接无法保存反之返回valid: true。这意味着你可以在建立连接的第一时间就验证地址、命名空间、数据库与凭据是否正确而无需等到流程真正运行时才发现问题。提示INFO for db这一校验语句同样被触发器用于动态加载数据库中的表清单见下文可见它既是健康检查也是元数据读取的通用入口。Run Query 动作执行任意 SurrealQL 语句「Run Query」是当前 piece 提供的唯一动作实现在 src/lib/actions/run-query.ts作用是在 SurrealDB 上执行任意 SurrealQL 语句例如SELECT、CREATE、UPDATE、DELETE、relate、define等覆盖了专用动作无法满足的所有读写场景。动作输入参数参数类型必填默认值说明queryShortText是—要执行的 SurrealDB 查询字符串argsObject否—查询参数以键值对形式填写键名不带$前缀query_timeoutNumber否30000查询超时时间毫秒application_nameShortText否—执行查询的客户端应用标识参数化查询防注入动作界面内置了两条 Markdown 说明强烈建议使用参数化查询而非字符串拼接避免 SQL 注入动作面板明确提示 Prevent SQL injection by using parameterized queries使用示例查询可写成SELECT * FROM table_name WHERE name $name然后在args中补充参数name注意不要加$符号。也就是说SurrealQL 中以$name形式引用变量变量的实际值在「Arguments」属性中按名称提供由底层请求以 URL 查询参数的方式传给数据库。这种方式既规避了注入风险也让同一查询模板可以复用不同参数。执行结果动作将底层 HTTP 响应体response.body原样返回给流程下游步骤使用。执行失败时抛出Query execution failed: 错误信息的异常便于在流程运行日志中定位问题。从aiMetadata可以看出该动作被标记为非幂等idempotent: false——写操作每次执行都会改变数据库状态而纯SELECT查询则不会设计工作流时需留意重试可能带来的副作用。New Row 触发器轮询监听新数据「New Row」触发器实现在 src/lib/triggers/new-row.ts采用TriggerStrategy.POLLING轮询策略在目标表新增行时触发流程。触发器配置项参数类型必填默认值说明tableDropdown是—目标表名连接后自动通过INFO FOR DB动态加载当前数据库的表清单未认证时下拉框禁用并提示 Please authenticate firstorder_byShortText是created_at排序字段建议使用创建时间戳order_directionStaticDropdown是DESC排序方向升序ASC/ 降序DESC需保证最新行排在最前工作机理基于去重键的增量轮询触发器的核心是Polling对象的items回调src/lib/triggers/new-row.ts使用DedupeStrategy.LAST_ITEM去重策略仅记录上一次轮询到的最后一条记录将上一次的最后一行 IDlastItemId传入查询构造函数constructQuery生成只取更新数据的 SurrealQL对返回的每一行计算MD5哈希并将排序字段值若为合法时间则归一化为 ISO 字符串与哈希拼接成记录 IDorderValue|rowHashdata字段携带整行原始数据供下游步骤使用。constructQuerysrc/lib/triggers/new-row.ts按轮询状态生成两类语句首次轮询无lastItemASCSELECT * FROM type::table($table) ORDER BY order_by ASC LIMIT 5DESCSELECT * FROM type::table($table) ORDER BY order_by DESC LIMIT 5后续增量轮询有lastItemASCSELECT * FROM type::table($table) WHERE order_by lastOrderKey ORDER BY order_by ASCDESCSELECT * FROM type::table($table) WHERE order_by lastOrderKey ORDER BY order_by DESC其中table通过type::table($table)引用避免表名被当作字面量拼接。排序方向非法时既非ASC也非DESC触发器会抛出包含order_direction信息的明确错误。使用建议务必维护时间戳字段触发器面板中的说明强调触发器依靠排序字段取最新行并持续轮询直到追上上一次的最后一行建议为表增加created_at时间戳字段可参考如下 SurrealDB 建表语句DEFINE FIELD OVERWRITE createdAt ON table VALUE time::now() READONLY;如果表中不存在单调递增的排序字段新行检测将无法可靠工作——这是使用该触发器最重要的前提条件。底层调用原理基于 HTTP /sql 端点的实现整个 piece 不依赖 SurrealDB 官方驱动所有交互统一收敛在 src/lib/common.ts 的query函数中其实现细节如下请求方式HttpMethod.POST地址为连接 URL 下的/sql路径new URL(/sql, url)请求头Content-Type: text/plain请求体直接是 SurrealQL 查询文本Accept: application/jsonAuthorization: Basic base64(username:password)即标准 HTTP Basic 认证surreal-ns: namespace与surreal-db: database分别携带命名空间与数据库查询参数args即 Run Query 动作中的「Arguments」以 URL query params 形式传递对应 SurrealQL 中的$变量响应返回完整 HTTP 响应调用方根据自身需要取用response.body。这种设计使得「Run Query」动作、「New Row」触发器乃至连接校验INFO for db共享同一套认证与请求逻辑也与 SurrealDB 官方的 HTTP API 语义保持一致——任何能够用 curl 完成的 SurrealQL 调用都可以通过该 piece 在 Activepieces 流程中执行。多语言与发布元信息该 piece 还内置了 10 种语言的界面文案翻译src/i18n包括中文、英文、德文、法文、西班牙文、日文等其中中文翻译文件为 zh.json。在 piece 注册信息src/index.ts中还可以看到displayNameSurrealDBminimumSupportedRelease0.30.0即需要 Activepieces 0.30.0 及以上版本才能加载该 piececategoriesDEVELOPER_TOOLS开发者工具分类authorsmaarteNNNN。小结activepieces/piece-surrealdb以极轻量的架构无官方 SDK、纯 HTTP 调用为 Activepieces 提供了完整的 SurrealDB 接入能力五个必填参数 INFO for db校验保证连接可靠Run Query 动作借助参数化查询安全地执行任意 SurrealQLNew Row 触发器通过排序字段 增量轮询 去重键实现新数据监听。对开发者而言唯一需要重点设计的是为表维护稳定的created_at时间戳字段其余能力均可直接在流程编辑器中开箱即用。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Activepieces 集成 SurrealDB 实战：连接配置、Run Query 动作与 New Row 轮询触发器完全指南
Activepieces 集成 SurrealDB 实战连接配置、Run Query 动作与 New Row 轮询触发器完全指南【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepiecesSurrealDB 是一款支持关系、文档与图模型的 Multi Model Database而activepieces/piece-surrealdb正是 Activepieces 官方社区提供的 SurrealDB 集成组件。本文围绕该组件的源码实现系统讲解如何在 Activepieces 中配置 SurrealDB 连接、通过参数化查询执行任意 SurrealQL 语句以及如何利用轮询触发器监听新数据写入读完即可在自己的工作流中直接落地使用。组件概览与构建方式SurrealDB piece 的完整源码位于 packages/pieces/community/surrealdb由四个核心 TypeScript 文件构成src/index.ts注册 piece 元信息、定义认证方式并挂载动作与触发器src/lib/common.ts封装底层 SurrealDB HTTP/sql端点调用src/lib/actions/run-query.ts实现「Run Query」动作src/lib/triggers/new-row.ts实现「New Row」轮询触发器。从 package.json 可见该组件版本为0.1.6仅依赖activepieces/pieces-common、activepieces/pieces-framework等 workspace 内部包与dayjs不依赖任何 SurrealDB 官方 SDK——所有数据库交互都是通过 HTTP 接口完成的详见下文「底层调用原理」。构建该库时官方 README 给出的命令为turbo run build --filteractivepieces/piece-surrealdb除构建外package.json 还暴露了以下脚本脚本命令作用buildtsc -p tsconfig.lib.json cp package.json dist/用 TypeScript 编译并把 package.json 复制进产物目录bundlenode ../../../../dist/packages/cli/src/index.js pieces bundle将 piece 打包为 Activepieces 可加载的 bundlelinteslint src/**/*.ts对源码执行 ESLint 检查编译配置定义在 tsconfig.lib.json 中以commonjs模块格式输出到dist目录并生成类型声明declaration与声明映射文件供其他包引用类型。连接配置五个必填参数与连接校验在 Activepieces 流程中添加 SurrealDB 连接时piece 使用PieceAuth.CustomAuth自定义认证表单见 src/index.ts共包含五个必填required: true字段字段显示名说明与示例urlConnection URL连接地址例如http://1.2.3.5:8000databaseDatabase要连接的数据库名称namespaceNamespace数据库所在的命名空间usernameUsername数据库用户名passwordPassword数据库密码在保存连接时piece 会执行一次连接校验validate回调调用surrealClient.query(auth, INFO for db)向数据库发送 SurrealQL 的INFO for db语句。若请求抛出异常则返回valid: false并携带错误信息连接无法保存反之返回valid: true。这意味着你可以在建立连接的第一时间就验证地址、命名空间、数据库与凭据是否正确而无需等到流程真正运行时才发现问题。提示INFO for db这一校验语句同样被触发器用于动态加载数据库中的表清单见下文可见它既是健康检查也是元数据读取的通用入口。Run Query 动作执行任意 SurrealQL 语句「Run Query」是当前 piece 提供的唯一动作实现在 src/lib/actions/run-query.ts作用是在 SurrealDB 上执行任意 SurrealQL 语句例如SELECT、CREATE、UPDATE、DELETE、relate、define等覆盖了专用动作无法满足的所有读写场景。动作输入参数参数类型必填默认值说明queryShortText是—要执行的 SurrealDB 查询字符串argsObject否—查询参数以键值对形式填写键名不带$前缀query_timeoutNumber否30000查询超时时间毫秒application_nameShortText否—执行查询的客户端应用标识参数化查询防注入动作界面内置了两条 Markdown 说明强烈建议使用参数化查询而非字符串拼接避免 SQL 注入动作面板明确提示 Prevent SQL injection by using parameterized queries使用示例查询可写成SELECT * FROM table_name WHERE name $name然后在args中补充参数name注意不要加$符号。也就是说SurrealQL 中以$name形式引用变量变量的实际值在「Arguments」属性中按名称提供由底层请求以 URL 查询参数的方式传给数据库。这种方式既规避了注入风险也让同一查询模板可以复用不同参数。执行结果动作将底层 HTTP 响应体response.body原样返回给流程下游步骤使用。执行失败时抛出Query execution failed: 错误信息的异常便于在流程运行日志中定位问题。从aiMetadata可以看出该动作被标记为非幂等idempotent: false——写操作每次执行都会改变数据库状态而纯SELECT查询则不会设计工作流时需留意重试可能带来的副作用。New Row 触发器轮询监听新数据「New Row」触发器实现在 src/lib/triggers/new-row.ts采用TriggerStrategy.POLLING轮询策略在目标表新增行时触发流程。触发器配置项参数类型必填默认值说明tableDropdown是—目标表名连接后自动通过INFO FOR DB动态加载当前数据库的表清单未认证时下拉框禁用并提示 Please authenticate firstorder_byShortText是created_at排序字段建议使用创建时间戳order_directionStaticDropdown是DESC排序方向升序ASC/ 降序DESC需保证最新行排在最前工作机理基于去重键的增量轮询触发器的核心是Polling对象的items回调src/lib/triggers/new-row.ts使用DedupeStrategy.LAST_ITEM去重策略仅记录上一次轮询到的最后一条记录将上一次的最后一行 IDlastItemId传入查询构造函数constructQuery生成只取更新数据的 SurrealQL对返回的每一行计算MD5哈希并将排序字段值若为合法时间则归一化为 ISO 字符串与哈希拼接成记录 IDorderValue|rowHashdata字段携带整行原始数据供下游步骤使用。constructQuerysrc/lib/triggers/new-row.ts按轮询状态生成两类语句首次轮询无lastItemASCSELECT * FROM type::table($table) ORDER BY order_by ASC LIMIT 5DESCSELECT * FROM type::table($table) ORDER BY order_by DESC LIMIT 5后续增量轮询有lastItemASCSELECT * FROM type::table($table) WHERE order_by lastOrderKey ORDER BY order_by ASCDESCSELECT * FROM type::table($table) WHERE order_by lastOrderKey ORDER BY order_by DESC其中table通过type::table($table)引用避免表名被当作字面量拼接。排序方向非法时既非ASC也非DESC触发器会抛出包含order_direction信息的明确错误。使用建议务必维护时间戳字段触发器面板中的说明强调触发器依靠排序字段取最新行并持续轮询直到追上上一次的最后一行建议为表增加created_at时间戳字段可参考如下 SurrealDB 建表语句DEFINE FIELD OVERWRITE createdAt ON table VALUE time::now() READONLY;如果表中不存在单调递增的排序字段新行检测将无法可靠工作——这是使用该触发器最重要的前提条件。底层调用原理基于 HTTP /sql 端点的实现整个 piece 不依赖 SurrealDB 官方驱动所有交互统一收敛在 src/lib/common.ts 的query函数中其实现细节如下请求方式HttpMethod.POST地址为连接 URL 下的/sql路径new URL(/sql, url)请求头Content-Type: text/plain请求体直接是 SurrealQL 查询文本Accept: application/jsonAuthorization: Basic base64(username:password)即标准 HTTP Basic 认证surreal-ns: namespace与surreal-db: database分别携带命名空间与数据库查询参数args即 Run Query 动作中的「Arguments」以 URL query params 形式传递对应 SurrealQL 中的$变量响应返回完整 HTTP 响应调用方根据自身需要取用response.body。这种设计使得「Run Query」动作、「New Row」触发器乃至连接校验INFO for db共享同一套认证与请求逻辑也与 SurrealDB 官方的 HTTP API 语义保持一致——任何能够用 curl 完成的 SurrealQL 调用都可以通过该 piece 在 Activepieces 流程中执行。多语言与发布元信息该 piece 还内置了 10 种语言的界面文案翻译src/i18n包括中文、英文、德文、法文、西班牙文、日文等其中中文翻译文件为 zh.json。在 piece 注册信息src/index.ts中还可以看到displayNameSurrealDBminimumSupportedRelease0.30.0即需要 Activepieces 0.30.0 及以上版本才能加载该 piececategoriesDEVELOPER_TOOLS开发者工具分类authorsmaarteNNNN。小结activepieces/piece-surrealdb以极轻量的架构无官方 SDK、纯 HTTP 调用为 Activepieces 提供了完整的 SurrealDB 接入能力五个必填参数 INFO for db校验保证连接可靠Run Query 动作借助参数化查询安全地执行任意 SurrealQLNew Row 触发器通过排序字段 增量轮询 去重键实现新数据监听。对开发者而言唯一需要重点设计的是为表维护稳定的created_at时间戳字段其余能力均可直接在流程编辑器中开箱即用。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考