企业官网建设流程全解析

ToolJet 集成 HarperDB 数据源：连接配置与 SQL/NoSQL 双模式查询实战指南

【免费下载链接】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

HarperDB 是一款同时支持 NoSQL 与 SQL 工作负载的高性能单模型数据存储平台，其灵活的 HTTP/S 接口和用户自定义 API 非常适合从概念验证到生产环境的快速扩展。本文基于 ToolJet 官方文档与仓库内 HarperDB 插件源码，系统讲解如何在 ToolJet 中安装插件、配置连接参数，并完整演示 SQL 模式（Select / Insert / Update / Delete）与 NoSQL 模式（Insert / Update / Delete / Search by hash / Search by value / Search by conditions）共十种查询操作的配置方法与底层实现原理，读完即可在应用构建器中直接对接 HarperDB 完成数据的读写与检索。

HarperDB 数据源概览

ToolJet 通过 Marketplace 插件机制将 HarperDB 作为全局数据源（Global Datasource）集成到应用构建器中，为读取和写入数据提供了一套简洁的界面。插件本身以@tooljet-marketplace/harperdb包的形式存在于仓库的 marketplace/plugins/harperdb 目录下，其内部基于axios构建 HTTP 客户端，并支持两种查询模式：

• SQL 模式：通过 SQL 语句对数据库执行各类操作；
• NoSQL 模式：对 JSON 文档进行无模式（schema-less）的存储与检索。

插件默认暴露isLoading、data、rawData三个变量，查询结果会以结构化数据返回，供应用内的表格、文本等组件直接绑定使用（见 manifest.json）。

前置准备：启用 Marketplace 并安装插件

在开始使用前，需要先完成 Marketplace 的启用与插件安装。详细步骤可参考 Marketplace 插件使用指南，核心流程如下：

1. 启用 Marketplace 功能：在 ToolJet 的.env文件中添加环境变量：

   ENABLE_MARKETPLACE_FEATURE=true

   本地运行时需先构建 marketplace 以确保所有插件可用；同时请注意，只有Administrator角色才能访问 Marketplace 页面。

2. 安装 HarperDB 插件：点击仪表盘左下角的设置图标，从菜单中选择Marketplace，在 Marketplace 标签页中找到 HarperDB 卡片并点击Install，状态变为Installed即完成安装。

3. 使用插件：安装完成后，进入仪表盘的Data sources标签页，滚动到Plugins区域即可看到已安装的 HarperDB 插件，配置后即可作为数据源在查询面板（Query Panel）中使用。

建立连接：连接参数详解

要建立与 HarperDB 实例的连接，需要提供以下凭据（对应 manifest.json 中定义的host、port、ssl_enabled、username、password五个必填字段）：

其中密码字段在插件清单中被标记为加密存储，ssl_enabled为开关（toggle）类型，其余字段均为文本输入。

连接底层实现

从源码看，连接逻辑位于 lib/index.ts 的HarperDBClient类中，其关键行为包括：

• 协议选择：const protocol = config.ssl === false ? 'http' : 'https';——只有明确关闭 SSL 时才使用http，其余情况一律走https；
• 端口拼接：端口为空时 URL 中不会出现端口部分；
• 认证方式：使用 axios 的 Basic Auth（auth: { username, password }）进行 HTTP 基本认证；
• 超时设置：请求超时时间为 30000 毫秒；
• 请求方式：所有操作均以 JSON 格式 POST 到实例根路径，请求体通过operation字段标识具体操作（如sql、insert、search_by_hash、describe_all等）。

此外，插件的testConnection方法（同样位于 lib/index.ts）通过调用describe_all操作来验证连接是否有效，成功时返回status: 'ok'及实例描述信息，失败时返回包含错误信息的status: 'failed'结果。

查询 HarperDB：查询管理器入口

连接配置完成后，即可创建查询：

1. 在应用构建器（App Builder）底部面板的查询管理器（Query Manager）中点击+Add按钮；
2. 在查询编辑器的Global Datasource区域选择HarperDB；
3. 在查询编辑器中根据需求选择SQL mode或NoSQL mode（该模式选择默认值为 SQL，见 operations.json），并填写对应参数。

SQL 模式

SQL 模式允许通过 SQL 语句对数据库执行各类操作，对应源码中mode === 'sql'分支对queryOptions.sql_query的透传执行。以下语法示例均基于文档示例中的sampleorg.people表。

Select

SELECT 语句用于查询数据库中的数据：

SELECT * FROM sampleorg.people WHERE id = 1

该语句会返回sampleorgschema 下people表中id = 1的记录。

Insert

INSERT 语句用于向数据库表中添加一行或多行数据：

INSERT INTO sampleorg.people (id, name, age, country, hobby) VALUE (5, 'Shubh', 26, 'India', 'Football')

注意 HarperDB 的 INSERT 语法使用VALUE（单数）关键字，与常见 SQL 方言中的VALUES略有差异，写入时需保持一致。

Update

UPDATE 语句用于修改数据库表中一行或多行记录的指定属性值：

UPDATE sampleorg.people SET hobby = 'chess' WHERE id = 5

Delete

DELETE 语句用于从数据库表中移除一行或多行数据：

DELETE FROM sampleorg.people WHERE id = 5

NoSQL 模式

NoSQL 模式提供无模式（schema-less）的 JSON 文档存储与检索能力。在查询编辑器的mode下拉框中切换到 NoSQL mode 后，还需要通过Operation下拉框选择具体操作（可选值包括 Insert、Update、Delete、Search By Hash、Search By Value、Search By Conditions，见 operations.json）。

Insert（NoSQL）

向数据库表中添加一行或多行数据，需要填写以下参数：

示例 Records：

[{id: 22, name: "James Scott", age: 26, country:"Italy", hobby: "football"},...]

Update（NoSQL）

根据标识行的 hash 属性（即主键）修改一行或多行记录中指定属性的值：

示例 Records：

[{id:12, name:"Jeff Hannistor"},...] // 主键值为 12 的记录将被更新

Delete（NoSQL）

从指定表中移除一行或多行数据：

示例 Hash Values：

[6, 15] // 主键值为 6 和 15 的记录将被删除

Search by hash

根据一个或多个 hash 值返回表中的数据：

示例 Hash Values：

[124, 66] // 主键值为 124 和 66 的记录将被检索

示例 Table Attributes：

['id', 'name', 'age', 'hobby', 'country'] // 仅返回表中提供的这些列

Search by value

根据匹配的某个值返回表中的数据，支持通配符：

示例 Search Attribute：

name

示例 Search Value：

John Doe # 或使用通配符 Joh*

示例 Table Attributes：

['id', 'name', 'age', 'hobby', 'country'] // 仅返回表中提供的这些列

Search by conditions

根据一个或多个匹配条件返回表中的数据，是 NoSQL 模式下最灵活的检索方式：

示例 Table Attributes：

['id', 'name', 'age', 'hobby', 'country'] // 仅返回表中提供的这些列

示例 Conditions to filter：

[{'search_attribute': 'age', 'search_type': 'between', 'search_value': [20, 28]}, {'search_attribute': 'name', 'search_type': 'contains', 'search_value': 'Ray'}]

该示例表示：同时满足「年龄介于 20 到 28 之间」且「姓名包含 'Ray'」的记录将被检索出来（条件间默认使用And组合）。

底层实现原理：从查询参数到 HTTP 请求

为了让读者更深入地理解上述操作如何被执行，这里结合 lib/index.ts 中的run方法梳理完整调用链：

1. 模式分发：插件根据queryOptions.mode判断走 SQL 分支还是 NoSQL 分支；
2. SQL 分支：直接将sql_query文本封装为{ operation: 'sql', sql }请求体并发送；
3. NoSQL 分支：依据queryOptions.operation分发到不同操作：
   • insert/update：将records字段通过JSON5.parse解析为数组后，与schema、table一起发送；
   • delete：将hash_values解析为数组后发送；
   • search_by_hash：发送hash_values与get_attributes；
   • search_by_value：发送search_attribute、search_value与get_attributes；
   • search_by_conditions：发送operator（仅当提供时）、offset（仅当不为undefined时）、limit（仅当不为undefined时）、get_attributes与conditions；
4. 参数解析：records、hash_values、attributes、conditions等 JSON 类字段均使用JSON5.parse解析（依赖json5包），因此支持不带引号的键名等宽松 JSON 写法（如[{id: 1, name: 'Jose', age: 24}]）；
5. 返回结构：插件将响应中的result?.data ?? result ?? {}作为查询结果返回，保证结果既可直接使用data字段，也能兼容其他返回形态。

从 operations.json 还可以看到，所有输入框均为codehinter类型，这意味着每个参数都支持使用 ToolJet 的表达式语法绑定变量、组件状态或查询结果，例如把表格组件的选中行数据动态传入records或hash_values，从而构建出可交互的增删改查应用。各字段的占位符示例（如[{id: 1, name: 'Jose', age: 24}]、[123, 65]、['name', 'age']）也已在清单中给出，可直接参考填写。

查询结果的使用

查询执行完毕后，返回的数据会写入查询的data变量中，可供应用内的各类组件引用。例如将 HarperDB 查询作为表格组件的数据源，或将查询结果绑定到文本、下拉框等组件的属性上，即可快速搭建出基于 HarperDB 的数据管理界面。借助查询面板的触发器（如事件处理器）还可以将增删改操作与按钮点击等交互事件关联，形成完整的数据闭环。

插件的类型定义位于 lib/types.ts，其中SourceOptions对应连接参数（host、port、ssl_enabled、username、password），QueryOptions对应全部查询参数，需要二次开发或扩展插件能力的读者可以从这两个类型入手阅读源码，进一步了解参数如何被run方法消费。

【免费下载链接】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