ToolJet 查询构建实战从编写 PostgreSQL 查询到高级触发器配置【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet查询Query是 ToolJet 应用中最核心的数据交互单元它把数据源的能力以可视化的方式暴露给应用构建者。本篇教程基于 ToolJet 开源仓库的官方教程文档 building-queries.md完整讲解查询编辑器的使用方式如何为已连接的 PostgreSQL 数据源创建一条查询、如何在不影响应用状态的前提下预览结果以及“页面加载时运行”“运行前确认”“成功通知”等高级选项的含义与底层实现。读完本文你将掌握 ToolJet 查询从创建、验证到触发配置的完整链路并能对照源码理解每个开关背后真实生效的配置项。查询编辑器应用构建器底部的数据工作台在 ToolJet 的应用构建器中查询编辑器Query Editor位于页面底部是进行数据源交互的默认工作区。无论是编写 SQL、调用 REST API还是运行 JavaScript/Python 代码片段都统一在这个面板中完成。从源码结构看查询编辑器的前端实现位于 frontend/src/AppBuilder/QueryManager其中 QueryManagerBody.jsx 负责渲染查询编辑器的全部区域数据源选择、查询体Query Body、数据转换Transformations、高级选项Triggers与预览面板。编辑器还支持静态数据源如 REST API、Run JavaScript、Run Python、ToolJet Database与通过插件注册的动态数据源如 PostgreSQL、MySQL 等静态数据源的清单定义在 constants.js 中。:::tip 小技巧 点击查询编辑器右上角的enlarge放大图标可以展开查询编辑器面板获得更大的编写空间适合编写较长的 SQL 或脚本。 :::创建第一条查询连接 PostgreSQL 后的第一步本教程假设你已经完成了前一步骤——在应用构建器中连接 PostgreSQL 数据源完整过程见 adding-a-datasource.md在左侧边栏的数据源管理器中点击Add datasource选择 PostgreSQL填入连接凭据并通过Test Connection校验。需要留意的是数据源是基于应用app级别创建的而非工作区级别因此同一条数据源仅在当前应用内可见、可复用。连接好数据源后按以下步骤创建第一条查询点击查询编辑器中的加号图标新建一条查询在弹出的数据源选择器中选择上一步创建的 PostgreSQL 数据源将下面的 SQL 语句复制并粘贴到查询编辑区域SELECT * FROM customers;将查询模式切换为 SQL mode确保语句按 SQL 语法解析。完成以上步骤后一条查询便创建成功。在查询面板的左侧你可以重命名查询、复制查询或将其删除查询名称在后续绑定组件、配置事件时会被引用。预览查询结果只读验证不改变应用状态编写完 SQL 后点击preview预览按钮即可在预览面板中查看查询返回的结果。:::info 关键语义预览查询不会改变应用的状态。也就是说预览不会把结果写入任何组件、不会触发绑定变量的更新也不会影响应用的运行行为——它只是单纯地执行一次查询并展示返回数据供你验证 SQL 正确性与返回结构。 :::预览面板本身提供了两种查看视图其实现见 Preview.jsxJSON 视图当返回结果是一个对象/数组时自动切换以 JSON 树形结构展示便于观察嵌套字段Raw 视图以原始文本形式展示返回内容。面板高度可以拖拽调整展开后点击结果区域会自动滚动到预览位置方便对照查询语句检查数据。预览之后如果确认无误查询便可用于下一步——绑定到按钮、表格等组件的事件上作为应用的正式数据来源。高级选项三种触发器开关查询的高级选项Advanced Options区域集中在查询编辑器的“Triggers”设置中对应源码 QueryManagerBody.jsx 渲染的触发器列表。每种开关的定义动作键、标签、测试选择器都集中在 constants.js 的customToggles配置中下面逐一说明。在页面加载时运行查询Run query on page load开启此选项后查询会在应用首次加载时自动执行一次。该开关对应的配置键为runOnPageLoad在源码中其 UI 标签为 “Run this query on application load”。需要特别说明的是查询可以拥有多个触发器即同一查询除了在页面加载时运行后续还可以通过其他事件再次触发例如按钮的点击事件On Click表格的行选中事件On Row Selected其他组件事件下拉框选择、文本框内容变化等。这一设计意味着“页面加载运行”只是查询的触发方式之一而非唯一入口。此外在当前的源码版本中触发器区域还额外提供了runOnDependencyChange依赖变化时运行开关定义见 constants.js它允许查询在其依赖的组件值或变量变化时自动重新执行——注意该开关对runjs、runpy类型查询不可用见 QueryManagerBody.jsx 中UNSUPPORTED_DEPENDENCY_CHANGE_KINDS的处理逻辑。运行前请求确认Request confirmation before running query开启此选项后每次查询执行前都会弹出一个确认提示框要求用户确认后再真正运行适用于删除、批量更新等高风险操作。该开关对应的配置键为requestConfirmation源码中通过 ConfirmationInputs.jsx 实现确认逻辑。值得展开的两个细节自定义确认消息开启后会出现 “Confirmation message” 输入框默认占位文本为Do you want to run this query - {queryName}?你可以改写为更贴合业务场景的提示语FX 表达式模式该开关支持fx表达式模式对应配置键requestConfirmationFx即确认与否不再是一个固定开关而可以写成{{true}}/{{false}}或任意求值表达式由应用运行时的动态值决定是否需要确认——这在条件化地保护危险操作时非常有用。成功时显示通知Show notification on success开启此选项后查询成功完成时会弹出一条自定义通知消息同时可以设置通知的展示时长。其实现见 SuccessNotificationInputs.jsx对应配置键为showSuccessNotification相关参数包括参数说明默认值/占位successMessage成功通知中显示的自定义消息占位文本 “Query ran successfully”notificationDuration通知展示时长单位秒占位数值5通知时长的输入框类型为数字输入typenumber单位为秒。利用这一能力你可以为耗时较长的数据刷新操作提供明确的完成反馈提升最终用户的使用体验。源码视角触发器开关如何落到真实配置从源码看上述三个开关runOnPageLoad、requestConfirmation、showSuccessNotification与依赖变化开关一起被统一建模为查询的options配置项随查询定义持久化存储。每个开关在 constants.js 中都带有一个dataCy标识例如run-on-app-load→ 页面加载运行开关confirmation-before-run→ 运行前确认开关notification-on-success→ 成功通知开关。这些dataCy标识被 Cypress 端到端测试直接复用例如 cypress-tests/cypress/constants/selectors/postgreSql.js 与 cypress-tests/cypress/constants/selectors/dataSource.js 中通过[data-cyrun-on-app-load-toggle-label]、[data-cynotification-on-success-toggle-switch]等选择器定位开关验证查询触发配置的 UI 交互。这意味着每个开关不仅有稳定的数据结构还有可自动化的测试保障。除了上述文档明确提及的三个选项当前版本的查询设置中还包含若干与触发器并列的增强能力同为 QueryManagerBody.jsx 渲染Timeout (ms)以毫秒为单位设置查询超时时间防止慢查询长时间占用Disable query通过表达式如{{components.toggleswitch1.value}}动态禁用查询并配套Disable message自定义禁用提示Events事件处理器查询支持onDataQuerySuccess查询成功与onDataQueryFailure查询失败两类事件事件定义见 constants.js可在成功或失败时级联触发其他查询、控制组件状态或弹出提示实现完整的数据驱动流程。从查询到应用查询的下一步去向查询创建并通过预览验证后通常有三种典型用途绑定到组件在表格、下拉框等组件的属性中通过{{queries.查询名.data}}引用查询返回数据让组件展示查询结果作为事件动作在按钮等组件的交互事件中选择Run Query动作指向该查询由用户操作触发执行进入数据转换流程如果返回数据需要二次加工去重、映射、过滤等可在查询编辑器的Transformations区域编写转换逻辑详见 transformations.md转换后的数据同样通过{{queries.查询名.data}}暴露给组件。至此一条 PostgreSQL 查询从创建、预览、触发配置到接入界面的完整闭环已经打通。掌握了查询编辑器与高级选项的用法你就可以在此基础上继续构建更复杂的多查询联动应用——结合“成功/失败事件”与“依赖变化运行”等触发器ToolJet 查询体系足以支撑仪表盘、业务应用等大多数内部工具场景的数据流编排。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ToolJet 查询构建实战：从编写 PostgreSQL 查询到高级触发器配置
ToolJet 查询构建实战从编写 PostgreSQL 查询到高级触发器配置【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet查询Query是 ToolJet 应用中最核心的数据交互单元它把数据源的能力以可视化的方式暴露给应用构建者。本篇教程基于 ToolJet 开源仓库的官方教程文档 building-queries.md完整讲解查询编辑器的使用方式如何为已连接的 PostgreSQL 数据源创建一条查询、如何在不影响应用状态的前提下预览结果以及“页面加载时运行”“运行前确认”“成功通知”等高级选项的含义与底层实现。读完本文你将掌握 ToolJet 查询从创建、验证到触发配置的完整链路并能对照源码理解每个开关背后真实生效的配置项。查询编辑器应用构建器底部的数据工作台在 ToolJet 的应用构建器中查询编辑器Query Editor位于页面底部是进行数据源交互的默认工作区。无论是编写 SQL、调用 REST API还是运行 JavaScript/Python 代码片段都统一在这个面板中完成。从源码结构看查询编辑器的前端实现位于 frontend/src/AppBuilder/QueryManager其中 QueryManagerBody.jsx 负责渲染查询编辑器的全部区域数据源选择、查询体Query Body、数据转换Transformations、高级选项Triggers与预览面板。编辑器还支持静态数据源如 REST API、Run JavaScript、Run Python、ToolJet Database与通过插件注册的动态数据源如 PostgreSQL、MySQL 等静态数据源的清单定义在 constants.js 中。:::tip 小技巧 点击查询编辑器右上角的enlarge放大图标可以展开查询编辑器面板获得更大的编写空间适合编写较长的 SQL 或脚本。 :::创建第一条查询连接 PostgreSQL 后的第一步本教程假设你已经完成了前一步骤——在应用构建器中连接 PostgreSQL 数据源完整过程见 adding-a-datasource.md在左侧边栏的数据源管理器中点击Add datasource选择 PostgreSQL填入连接凭据并通过Test Connection校验。需要留意的是数据源是基于应用app级别创建的而非工作区级别因此同一条数据源仅在当前应用内可见、可复用。连接好数据源后按以下步骤创建第一条查询点击查询编辑器中的加号图标新建一条查询在弹出的数据源选择器中选择上一步创建的 PostgreSQL 数据源将下面的 SQL 语句复制并粘贴到查询编辑区域SELECT * FROM customers;将查询模式切换为 SQL mode确保语句按 SQL 语法解析。完成以上步骤后一条查询便创建成功。在查询面板的左侧你可以重命名查询、复制查询或将其删除查询名称在后续绑定组件、配置事件时会被引用。预览查询结果只读验证不改变应用状态编写完 SQL 后点击preview预览按钮即可在预览面板中查看查询返回的结果。:::info 关键语义预览查询不会改变应用的状态。也就是说预览不会把结果写入任何组件、不会触发绑定变量的更新也不会影响应用的运行行为——它只是单纯地执行一次查询并展示返回数据供你验证 SQL 正确性与返回结构。 :::预览面板本身提供了两种查看视图其实现见 Preview.jsxJSON 视图当返回结果是一个对象/数组时自动切换以 JSON 树形结构展示便于观察嵌套字段Raw 视图以原始文本形式展示返回内容。面板高度可以拖拽调整展开后点击结果区域会自动滚动到预览位置方便对照查询语句检查数据。预览之后如果确认无误查询便可用于下一步——绑定到按钮、表格等组件的事件上作为应用的正式数据来源。高级选项三种触发器开关查询的高级选项Advanced Options区域集中在查询编辑器的“Triggers”设置中对应源码 QueryManagerBody.jsx 渲染的触发器列表。每种开关的定义动作键、标签、测试选择器都集中在 constants.js 的customToggles配置中下面逐一说明。在页面加载时运行查询Run query on page load开启此选项后查询会在应用首次加载时自动执行一次。该开关对应的配置键为runOnPageLoad在源码中其 UI 标签为 “Run this query on application load”。需要特别说明的是查询可以拥有多个触发器即同一查询除了在页面加载时运行后续还可以通过其他事件再次触发例如按钮的点击事件On Click表格的行选中事件On Row Selected其他组件事件下拉框选择、文本框内容变化等。这一设计意味着“页面加载运行”只是查询的触发方式之一而非唯一入口。此外在当前的源码版本中触发器区域还额外提供了runOnDependencyChange依赖变化时运行开关定义见 constants.js它允许查询在其依赖的组件值或变量变化时自动重新执行——注意该开关对runjs、runpy类型查询不可用见 QueryManagerBody.jsx 中UNSUPPORTED_DEPENDENCY_CHANGE_KINDS的处理逻辑。运行前请求确认Request confirmation before running query开启此选项后每次查询执行前都会弹出一个确认提示框要求用户确认后再真正运行适用于删除、批量更新等高风险操作。该开关对应的配置键为requestConfirmation源码中通过 ConfirmationInputs.jsx 实现确认逻辑。值得展开的两个细节自定义确认消息开启后会出现 “Confirmation message” 输入框默认占位文本为Do you want to run this query - {queryName}?你可以改写为更贴合业务场景的提示语FX 表达式模式该开关支持fx表达式模式对应配置键requestConfirmationFx即确认与否不再是一个固定开关而可以写成{{true}}/{{false}}或任意求值表达式由应用运行时的动态值决定是否需要确认——这在条件化地保护危险操作时非常有用。成功时显示通知Show notification on success开启此选项后查询成功完成时会弹出一条自定义通知消息同时可以设置通知的展示时长。其实现见 SuccessNotificationInputs.jsx对应配置键为showSuccessNotification相关参数包括参数说明默认值/占位successMessage成功通知中显示的自定义消息占位文本 “Query ran successfully”notificationDuration通知展示时长单位秒占位数值5通知时长的输入框类型为数字输入typenumber单位为秒。利用这一能力你可以为耗时较长的数据刷新操作提供明确的完成反馈提升最终用户的使用体验。源码视角触发器开关如何落到真实配置从源码看上述三个开关runOnPageLoad、requestConfirmation、showSuccessNotification与依赖变化开关一起被统一建模为查询的options配置项随查询定义持久化存储。每个开关在 constants.js 中都带有一个dataCy标识例如run-on-app-load→ 页面加载运行开关confirmation-before-run→ 运行前确认开关notification-on-success→ 成功通知开关。这些dataCy标识被 Cypress 端到端测试直接复用例如 cypress-tests/cypress/constants/selectors/postgreSql.js 与 cypress-tests/cypress/constants/selectors/dataSource.js 中通过[data-cyrun-on-app-load-toggle-label]、[data-cynotification-on-success-toggle-switch]等选择器定位开关验证查询触发配置的 UI 交互。这意味着每个开关不仅有稳定的数据结构还有可自动化的测试保障。除了上述文档明确提及的三个选项当前版本的查询设置中还包含若干与触发器并列的增强能力同为 QueryManagerBody.jsx 渲染Timeout (ms)以毫秒为单位设置查询超时时间防止慢查询长时间占用Disable query通过表达式如{{components.toggleswitch1.value}}动态禁用查询并配套Disable message自定义禁用提示Events事件处理器查询支持onDataQuerySuccess查询成功与onDataQueryFailure查询失败两类事件事件定义见 constants.js可在成功或失败时级联触发其他查询、控制组件状态或弹出提示实现完整的数据驱动流程。从查询到应用查询的下一步去向查询创建并通过预览验证后通常有三种典型用途绑定到组件在表格、下拉框等组件的属性中通过{{queries.查询名.data}}引用查询返回数据让组件展示查询结果作为事件动作在按钮等组件的交互事件中选择Run Query动作指向该查询由用户操作触发执行进入数据转换流程如果返回数据需要二次加工去重、映射、过滤等可在查询编辑器的Transformations区域编写转换逻辑详见 transformations.md转换后的数据同样通过{{queries.查询名.data}}暴露给组件。至此一条 PostgreSQL 查询从创建、预览、触发配置到接入界面的完整闭环已经打通。掌握了查询编辑器与高级选项的用法你就可以在此基础上继续构建更复杂的多查询联动应用——结合“成功/失败事件”与“依赖变化运行”等触发器ToolJet 查询体系足以支撑仪表盘、业务应用等大多数内部工具场景的数据流编排。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考