ToolJet 集成 Elasticsearch 数据源完全指南连接配置、13 种查询操作与源码实现解析【免费下载链接】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/ToolJetToolJet 内置了对 Elasticsearch 集群的完整支持允许用户在可视化画布中直接对索引执行数据读写与各类查询操作。本文以 ToolJet 3.0.0-LTS 版本文档为骨架结合仓库中 Elasticsearch 插件源码 与操作定义文件系统讲解数据源连接方式、SSL 证书配置、全部 13 种受支持操作的参数与示例并深入底层剖析查询执行的真实调用链。读完本文你将能够独立完成 ToolJet 与 Elasticsearch 的对接并在查询面板中熟练执行搜索、文档增删改查、批量操作、滚动分页等常见任务。连接 Elasticsearch 数据源在 ToolJet 中连接 Elasticsearch 数据源有两种入口在查询面板Query Panel中点击 Add new data source按钮在 ToolJet 仪表盘中导航到 Data Sources 页面 添加。添加时需要填写以下连接信息参数说明HostElasticsearch 集群所在主机地址默认值为localhostPort集群对外服务端口默认值为9200Username访问集群的用户名可留空Password访问集群的密码可留空网络可达性提醒如果你自托管 ToolJet请确保 Elasticsearch 的Host/IP能从你的 VPC 内访问如果使用 ToolJet Cloud则需要将 ToolJet 的 IP 加入 Elasticsearch 的白名单。SSL 证书连接支持ToolJet 同时支持基于 SSL 证书的加密连接。在 SSL 配置中你可以选择以下两种证书方式之一CA certificate上传 CA 证书内容用于校验服务端身份Client certificate同时提供客户端证书Client cert、客户端私钥Client key与根证书Root cert实现双向 TLS 认证。从插件的数据源描述文件 manifest.json 可以看到ssl_certificate是一个下拉组件可选值为ca_certificate、client_certificate、none默认并且password、ca_cert、client_key、client_cert、root_cert均被标记为encrypted: true意味着这些敏感字段在存储时会经过加密处理。连接配置的源码级解读插件的数据源连接逻辑位于 index.ts 的getConnection方法中其构建客户端的过程清晰揭示了表单字段的底层映射const host sourceOptions.host; const port sourceOptions.port; const username encodeURIComponent(sourceOptions.username); const password encodeURIComponent(sourceOptions.password); const sslEnabled sourceOptions.ssl_enabled; const protocol this.determineProtocol(sourceOptions);URL 组装用户名与密码会先经过encodeURIComponent编码再以${protocol}://${username}:${password}${host}:${port}的形式拼入节点地址若用户名密码均为空则直接使用${protocol}://${host}:${port}协议判定determineProtocol方法index.ts优先读取历史遗留的scheme字段——早期版本将协议硬编码为https若存在scheme且未设置ssl_enabled则向后兼容地返回https否则按ssl_enabled开关返回https或httpSSL 装配当启用 SSL 且选择ca_certificate时仅注入ca选择client_certificate时则同时注入ca、cert、key三个字段分别对应表单中的根证书、客户端证书与客户端私钥请求超时客户端统一设置了requestTimeout: 1000010 秒因此对慢查询请结合业务在操作参数层面控制数据规模。需要说明的是插件底层使用的是 OpenSearch 官方 Node.js 客户端opensearch-project/opensearch见 package.json它兼容 Elasticsearch 的 REST API 语义。这一点在响应示例的meta元数据中也有体现name: opensearch-js以及user-agent: opensearch-js/1.2.0。在查询面板中使用 Elasticsearch连接建立后按以下步骤发起查询点击编辑器底部查询管理器Query Manager中的 Add按钮选择前面添加的 Elasticsearch 数据源选择要执行的操作Operation。提示查询结果可以通过 Transformations数据变换进一步加工处理具体用法参见 Transformations 教程。插件支持的 13 种操作由 operations.json 中的operation下拉列表定义运行时则由 index.ts 中的switch语句分派到对应的执行函数。下面逐一说明每种操作的参数与示例。支持的 13 种操作详解Search搜索执行搜索查询并返回匹配的命中结果hits。必填参数Index要搜索的索引名称QueryJSON 格式的搜索查询体。可选参数Scroll滚动scroll保留时间用于分批拉取大量结果。示例Index: books Query: { query: { match: { title: The Great Gatsby } }, size: 20 } Scroll: 1m # 时间格式支持 1m、1h、1d 等源码实现operations.ts将query通过JSON.parse解析后传入client.search并把可选的scroll透传给底层客户端——这正是 Search 操作中Scroll参数能生效的原理。Index a Document索引文档向指定索引或数据流新增一条 JSON 文档。必填参数Index要写入文档的索引名称BodyJSON 格式的文档内容。示例Index: books Body: { title: 1984, author: George Orwell, year: 1949, genre: Dystopian Fiction }Get a Document获取文档按文档 ID 从索引中取回指定 JSON 文档。必填参数Index文档所在的索引名称Id要检索的文档 ID。示例Index: books Id: FJXTSZEBsuzUn2y4wZ-WUpdate a Document更新文档使用脚本或部分文档对指定文档执行更新。必填参数Index文档所在索引名称Id要更新的文档 IDBodyJSON 格式的更新脚本或部分文档如{ doc: { ... } }。示例Index: books Id: FJXTSZEBsuzUn2y4wZ-W Body: { doc: { title: 1984, author: George Orwell, year: 1949, genre: Fiction } }Delete a Document删除文档从指定索引中删除一条 JSON 文档。必填参数Index文档所在索引名称Id要删除的文档 ID。示例Index: books Id: FJXTSZEBsuzUn2y4wZ-WBulk Operation批量操作在一次 API 调用中执行多条 index/update/delete 操作适合大批量数据写入场景。必填参数OperationsJSON 格式的批量操作列表。示例[ { index: { _index: books, _id: book1 } }, { title: The Great Gatsby, author: F. Scott Fitzgerald, year: 1925 }, { delete: { _index: books, _id: book2 } }, { index: { _index: books, _id: book3 } }, { title: Moby-Dick, author: Herman Melville, year: 1851 }, { delete: { _index: books, _id: book4 } } ]批量操作在源码中直接映射为client.bulk({ body: JSON.parse(operations) })operations.ts操作列表整体作为 bulk body 提交。Count Documents统计文档数返回满足搜索条件的文档数量。必填参数Index要统计文档数的索引。可选参数QueryJSON 格式的过滤查询可选。示例{ query: { range: { timestamp: { gte: 1901 } } } }源码实现operations.ts会在query为空时直接不传 body相当于统计索引内全部文档。Check Document Existence检查文档是否存在判断指定索引中是否存在某条文档。必填参数Index待检查的索引名称Id待检查的文档 ID。示例Index: books Id: FJXTSZEBsuzUn2y4wZ-W该操作底层调用client.exists返回布尔值适合在画布逻辑中做条件判断。Multi Get批量获取通过一次请求批量取回多条文档。必填参数OperationsJSON 格式的批量获取操作。示例{ docs: [ { _index: books, _id: book124 }, { _index: books, _id: book125 } ] }Scroll Search滚动搜索基于上一次 Search 返回的 Scroll ID持续分批拉取单次搜索请求的大量结果。必填参数Scroll ID搜索返回的滚动 IDScroll滚动保留时间。示例Scroll ID: DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAOWQWYm9vbDItY1NCOUExal9TcTBjeUEyZw Scroll: 60m使用滚动搜索的典型流程是先用带Scroll参数的 Search 操作取得首批结果与_scroll_id再反复使用 Scroll Search 拉取后续批次最后用 Clear Scroll 释放搜索上下文。Clear Scroll清理滚动释放指定滚动搜索占用的服务端上下文。必填参数Scroll ID要清理的滚动 ID。示例Scroll ID: DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAOWQWYm9vbDItY1NCOUExal9TcTBjeUEyZwGet Cat Indices获取索引列表以紧凑、列对齐的形式查看集群中的索引概况。该操作无必填参数点击即可执行。底层调用client.cat.indices({ format: json })operations.ts因此返回体中的body是一个 JSON 数组。响应示例{ body: [ { health: yellow, status: open, index: 1, uuid: JQOzqxK7Rdar7ROOlqXwkA, pri: 1, rep: 1, docs.count: 2, docs.deleted: 0, store.size: 9.2kb, pri.store.size: 9.2kb }, { health: yellow, status: open, index: recipes, uuid: eNGdAsG4TMWvs9f0eLERlQ, pri: 1, rep: 1, docs.count: 20, docs.deleted: 0, store.size: 30kb, pri.store.size: 30kb } ], statusCode: 200, headers: { x-elastic-product: Elasticsearch, content-type: application/json, content-length: 558 }, meta: { name: opensearch-js, connection: { url: http://xx.2xx.183.199:9200/, status: alive } } }Get Cluster Health获取集群健康状态返回集群健康状态信息green/yellow/red无必填参数。底层调用client.cluster.health()operations.ts。响应示例{ body: { cluster_name: docker-cluster, status: yellow, timed_out: false, number_of_nodes: 1, number_of_data_nodes: 1, active_primary_shards: 10, active_shards: 10, relocating_shards: 0, initializing_shards: 0, unassigned_shards: 3, delayed_unassigned_shards: 0, number_of_pending_tasks: 0, number_of_in_flight_fetch: 0, task_max_waiting_in_queue_millis: 0, active_shards_percent_as_number: 76.92307692307693 }, statusCode: 200 }上述两个响应示例中的meta字段来自底层客户端opensearch-js其中connection.url即你配置的集群节点地址。实际使用时可将{{queries.查询名.data.body}}之类的表达式用于前端组件渲染实现索引列表与集群状态的实时可视化。查询执行链路与错误处理从源码结构看所有操作共用同一条执行链路index.tsrun方法首先通过getConnection根据数据源配置构建并复用 OpenSearch 客户端根据queryOptions.operation进入switch分支将index、query、body、id、operations、scroll_id、scroll等参数分发到 operations.ts 中对应的函数其中query、body、operations均先经过JSON.parse解析为对象任一环节抛出异常都会被捕获并包装为QueryError(Query could not be completed, err.message, {})返回避免将底层堆栈直接暴露给前端成功时统一返回{ status: ok, data: result }结构。此外数据源还实现了testConnection方法index.ts通过调用client.info()探测集群连通性这也是你在连接配置界面点击“测试连接”按钮时的底层行为。实战建议参数中的表达式能力所有操作的 Index、Id、Query、Body 等输入框均为代码提示codehinter组件见 operations.json支持直接引用画布组件状态、全局变量或前一个查询的输出如{{ components.table1.selectedRow.id }}因此完全可以把 Search 的Id或Query做成动态值实现“选中表格行 → 查询对应文档”的典型联动场景大批量导出优先滚动数据量超过单次返回上限如size: 20时使用 Scroll 参数 Scroll Search 分批拉取结束后务必 Clear Scroll 释放上下文敏感信息加密存储密码与各类证书在插件定义中均标记为encrypted可以放心将连接配置保存在组织内共享测试文件位置插件的自动化测试骨架位于 plugins/packages/elasticsearch/tests/elasticsearch.test.js后续如需为自定义操作补充回归用例可在此扩展。【免费下载链接】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），仅供参考