ToolJet 集成 TypeSense 数据源连接配置、六大文档操作与源码级实现解析【免费下载链接】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/ToolJetTypeSense 是一款开源、基于内存索引的模糊搜索引擎以毫秒级响应著称。ToolJet 将 TypeSense 封装为内置数据源DataSource插件使应用构建者无需编写后端代码即可在可视化编辑器中直接创建集合Collection、索引文档、执行全文搜索以及增删改查文档。本文基于 ToolJet 3.0.0-LTS 版本的官方文档与仓库源码完整讲解 TypeSense 数据源的连接方式、六种受支持操作的参数与示例并深入到插件实现plugins/packages/typesense揭示其底层调用链帮助你掌握在 ToolJet 中接入 TypeSense 的完整实战方案。连接 TypeSense 数据源ToolJet 可以通过内置的 TypeSense 插件连接你的 TypeSense 部署并对其执行读写操作。建立连接有两种入口在应用编辑器的**查询面板Query Panel**中点击 Add new Data source按钮从 ToolJet 仪表盘左侧导航进入Data Sources 页面选择 TypeSense 作为数据源并点击Add将其接入当前工作区。:::info 网络连通性要求 如果你自托管Self-hostedToolJet请确保 TypeSense 的Host/IP可以从你的 VPC 内访问如果使用 ToolJet Cloud则需要将 ToolJet 的 IP 加入 TypeSense 的白名单。 :::连接参数ToolJet 连接 TypeSense 部署需要以下四个参数参数说明默认值HostTypeSense 服务器的域名或 IP 地址localhostPortTypeSense 服务的监听端口8108API Key用于认证的 API 密钥无必填Protocol通信协议可选http或httpshttp以上默认值与协议选项均可在插件的声明文件中找到依据。在 manifest.json 中defaults定义了host为localhost、port为8108、protocol为httpproperties.protocol被声明为下拉框类型可选值为HTTP与HTTPS。同时api_key字段带有encrypted: true标记意味着 API Key 在 ToolJet 中以加密形式存储保存后不会以明文展示。所有四个参数host、port、api_key、protocol在 manifest 的required列表中均为必填项界面上的Test connection按钮可用于在保存前验证连通性。连接与连通性测试的底层实现从源码层面看连接逻辑位于 index.ts 的getConnection方法ToolJet 使用官方typesense客户端版本^1.5.1见 package.json构造连接将用户填写的host、port转换为数字、protocol组装为客户端节点配置并传入apiKey同时设置了connectionTimeoutSeconds: 2的两秒连接超时const client new Client({ nodes: [ { host: sourceOptions.host, port: sourceOptions.port, protocol: sourceOptions.protocol, }, ], apiKey: sourceOptions.api_key, connectionTimeoutSeconds: 2, });而Test connection按钮对应的testConnection方法则调用 TypeSense 的健康检查接口client.health.retrieve()根据返回的ok字段判定连接状态index.ts。这与 TypeSense 官方的健康端点语义一致能拿到health.ok true即代表服务可用且 API Key 认证通过。查询 TypeSense连接建立后即可在应用编辑器中创建针对 TypeSense 的查询点击编辑器底部查询管理器的 Add按钮选择上一步添加的TypeSense数据源从操作Operation下拉框中选择所需操作并填写对应参数点击Preview按钮预览输出或点击Run按钮直接触发查询。:::tip 查询结果可以通过**转换Transformations**做进一步处理例如过滤字段、重命名或重组数据结构。详细用法参见 Transformations 文档。 :::查询的执行入口同样位于 index.tsrun方法根据查询选项中的operation字段通过switch分发到对应操作实现并统一返回{ status: ok, data: result }结构。结合 types.ts 中的QueryOptions类型定义可以看出每个查询会携带operation、schema、collection、searchParams、document、id等字段具体哪些字段生效取决于所选操作。:::tip 重要约定 在执行任意操作时传递给服务器的文档Document或 Schema 必须是 JSON 字符串而非 JavaScript 对象。源码中每个操作都使用JSON.parse(...)解析用户输入若传入的是 JS 对象JSON.parse会直接抛错导致操作失败。 :::支持的六种操作TypeSense 数据源在 ToolJet 中支持以下六种操作全部以 TypeSense 官方 HTTP API 为底层实现。1. 创建集合Create a Collection在 TypeSense 集群中创建集合。集合等同于关系型数据库中的表创建前必须通过Schema字段定义集合的字段结构与类型。必填参数SchemaJSON 数组形式的字段定义每个元素包含name字段名与type字段类型如string、float、int32、bool等。示例[ { name: id, type: string }, { name: name, type: string }, { name: price, type: float } ]底层实现该操作对应 operations.ts 中的createCollection对用户输入的 Schema 字符串执行JSON.parse后调用client.collections().create(...)。TypeSense 官方要求集合创建请求体是一个包含name和fields的 JSON 对象因此这里的 Schema 数组会被映射为集合的字段列表。2. 索引文档Index a Document将一条文档写入索引到指定集合。文档字段必须符合集合创建时定义的 Schema。必填参数Collection目标集合名称DocumentJSON 对象形式的文档内容需包含 Schema 中定义的字段。示例{ id: 1, name: Laptop, price: 999.99 }底层实现对应indexDocumentoperations.ts解析 JSON 后调用client.collections(collection).documents().create(...)即 TypeSense 的索引单条文档端点。若文档的id已存在TypeSense 会将其视为 upsert覆盖更新。3. 搜索Search在指定集合内执行全文搜索与过滤查询是 TypeSense 数据源的核心能力。必填参数Collection要搜索的集合名称Search parameters搜索参数JSON 对象可包含过滤、排序、分页、查询关键词等条件。示例{ filter_by: price:1000, sort_by: price:desc, per_page: 10 }上例表示仅返回price小于 1000 的文档按价格降序排列每页返回 10 条。除了示例中的filter_by、sort_by、per_pageTypeSense 搜索还支持q查询关键词、query_by指定参与匹配的字段、page页码、highlight等参数均可放入该 JSON 对象。底层实现对应searchoperations.ts将searchParams解析后传给client.collections(collection).documents().search(...)。4. 获取文档Get a Document按文档id从集合中获取单条文档。必填参数Collection集合名称Id目标文档的id值。底层实现对应getDocumentoperations.ts调用client.collections(collection).documents(id).retrieve()即 TypeSense 的检索单条文档端点。5. 更新文档Update a Document更新集合中指定id文档的部分或全部字段。必填参数Collection集合名称Id目标文档的id值Document包含更新后字段值的 JSON 对象。示例将上文中创建的id1文档的name与price更新为新值{ name: Gaming Laptop, price: 1199.99 }底层实现对应updateDocumentoperations.ts调用client.collections(collection).documents(id).update(...)。TypeSense 的更新语义是部分更新请求体中只包含需要变更的字段即可未提及的字段保持不变。6. 删除文档Delete a Document按文档id从集合中删除单条文档。必填参数Collection集合名称Id要删除的文档id。底层实现对应deleteDocumentoperations.ts调用client.collections(collection).documents(id).delete()。错误处理与返回值约定所有六种操作在 operations.ts 中均采用了统一的错误处理模式操作成功时直接返回 TypeSense 客户端的结果对象失败时捕获异常并返回{ error: exception.message, status: failed }。这意味着当 Schema 格式不合法、集合不存在、文档id不存在或搜索参数解析失败时查询结果中会携带error字段与status: failed你可以在 ToolJet 的查询结果面板中直接看到具体报错信息并据此调整参数。而在run方法层面index.ts异常同样被捕获并打印到控制台最终统一返回{ status: ok, data: result }。需要留意的是操作级错误如集合不存在会以error字段形式出现在data中而连接级错误如 TypeSense 不可达则发生在getConnection阶段会直接导致查询失败——这也是连接前建议先点击Test connection验证的原因。典型应用场景结合 TypeSense 的检索能力与 ToolJet 的可视化组件可以快速构建以下类型的内部应用商品/文档检索面板用搜索操作配合filter_by、sort_by实现带过滤与排序的搜索结果绑定到 Table 或 Listview 组件展示数据录入工具用创建集合初始化结构再用索引文档批量写入配合 Form 组件实现可视化录入界面记录维护界面用获取文档回显数据、更新文档保存修改、删除文档提供删除能力形成一个完整的 CRUD 闭环。由于 TypeSense 数据源是工作区级别的全局数据源参考 Data Sources 概览连接一旦配置完成即可在同一个工作区的任意应用包括已创建的应用与新应用的查询面板中复用无需重复配置连接信息。配合 ToolJet 的 Transformations 功能还可以对搜索返回的嵌套 JSON 结果进行扁平化处理使其更适合直接绑定到表格类组件。总结本文完整覆盖了在 ToolJet 中接入 TypeSense 的完整链路从连接参数的四个必填项Host、Port、API Key、Protocol及网络白名单注意事项到查询面板中创建查询的四个步骤再到创建集合、索引文档、搜索、获取文档、更新文档、删除文档六种操作的参数、JSON 示例与底层调用实现。关键要点回顾所有文档与 Schema 必须使用JSON 字符串插件内部通过JSON.parse解析连接参数以 manifest.json 中的声明为准API Key 加密存储协议仅支持 HTTP/HTTPS插件基于官方typesensenpm 客户端封装见 index.ts各操作与 TypeSense 官方文档中的集合/文档 API 一一对应源码位于 operations.ts操作失败时会以{ error, status: failed }形式返回可用于查询结果面板中的快速排错。如需了解 TypeSense 集合与文档 API 的更多细节如集合更新、多字段搜索权重等建议结合你所使用的 TypeSense 版本查阅其官方 API 文档并将示例中的 JSON 参数按实际业务字段调整后直接复制到 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），仅供参考