企业官网建设流程全解析

ToolJet 集成 Weaviate 向量数据库：从连接配置到语义查询的完整实战指南

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

Weaviate 是一款开源向量数据库，将它与 ToolJet 集成后，应用可以获得基于向量相似度的语义检索能力——不再是依赖精确关键词匹配，而是按"含义"召回相关信息。本文以当前仓库中的 Weaviate 市场插件（位于 marketplace/plugins/weaviate）为对象，完整讲解云上与本地两种连接方式、Schema / Collection / Objects 三大类共 8 个受支持操作的全部参数与响应结构，并结合插件源码（index.ts、query_operations.ts）剖析底层 API 调用链，帮助读者在 ToolJet 中直接构建 AI 搜索、推荐系统与知识库检索类应用。

为什么在 ToolJet 中集成 Weaviate

Weaviate 的核心能力是把非结构化数据（文本、图片等）转换为高维向量并建立索引，再通过余弦相似度等距离度量完成语义查询。ToolJet 的可视化查询面板与事件处理机制，让开发者无需编写后端代码即可：

• 基于语义（而非关键词）检索文档、商品、问答对等数据；
• 为 AI 应用搭建知识检索层（RAG 的数据来源）；
• 在低代码应用中快速落地推荐系统、去重、异常检测等向量场景。

从仓库中的插件清单定义（operations.json）可以看出，该插件被声明为"type": "database"，通过 ToolJet 数据源管理界面即可添加并立即在查询编辑器中使用。

建立连接：Cloud 与 Local 两种方式

插件在创建数据源时要求先选择连接类型。从 manifest.json 可以看到，connection_type是一个下拉切换组件，默认值为cloud，可选值为Cloud与Local两项。

连接 Weaviate Cloud

连接 Weaviate 云服务需要两个凭据：

其中 API Key 在插件定义中被标记为"encrypted": true（见 manifest.json），ToolJet 会对其加密存储，不会以明文形式落库或展示。两个字段均在数据源required列表中，为必填项。

从源码 index.ts 可以看到云连接的真实请求构造逻辑：当connection_type不是local时，插件直接以instanceUrl作为基础地址，并在每次请求头中附加Authorization: Bearer <apiKey>：

BASE_URL = `${sourceOptions.instanceUrl}`; headers['Authorization'] = `Bearer ${sourceOptions.apiKey}`;

连接本地 Weaviate

本地部署只需提供Host与Port。源码中本地连接的地址拼接为http://${host}:${port}，并且不附加任何鉴权头（index.ts），因此请确保本地实例的网络访问策略可控。

文档推荐用如下 Docker 命令快速拉起一个本地容器，将 Host 设为localhost、Port 设为8080：

docker run -p 8080:8080 -p 50051:50051 cr.weaviate.io/semitechnologies/weaviate:1.28.4

其中8080是 REST API 端口，50051是 gRPC 端口。启动完成后即可在 ToolJet 数据源表单中填入localhost/8080建立连接。

连接测试的底层原理

数据源保存时 ToolJet 会调用插件实现的testConnection方法（index.ts）。它的做法是向/v1/schema发起一次GET请求：

• 本地连接：GET http://<host>:<port>/v1/schema，无请求头；
• 云连接：GET <instanceUrl>/v1/schema，带Authorization: Bearer <apiKey>。

只有响应状态为ok时才判定连接成功，否则抛出Connection failed错误。这一设计保证了"表单能保存"与"实例真正可达"是一致的。

支持的操作总览

插件的查询模型由三层结构驱动（见 types.ts）：

1. Data Type（数据类型）：schema、collection、objects三选一；
2. Operation（操作）：在所选数据类型下进一步选择具体操作；
3. 参数：不同操作暴露不同的必填/可选参数。

运行时由 index.ts 的switch (queryOptions.data_type)分发到getSchema、collectionOperation、objectsOperation三个处理函数，任一操作最终都会映射为对 Weaviate REST API 的fetch调用，结果以{ status: 'ok', data: result }形式返回给查询面板。全部支持的操作如下：

Data Type - Schema：读取数据库结构

Get Database Schema

该操作返回整个数据库的全部类（class）定义，用于快速了解实例中有哪些集合及其索引、向量与分片配置。

可选参数

• Consistency（一致性）：开关型参数，开启后确保请求由 leader 节点处理以维持读取准确性。从源码看，开启时该值会作为请求头consistency附加到GET /v1/schema请求上（query_operations.ts）。

响应示例（节选自文档，完整结构可在 Weaviate 实例中验证）：

{ "classes": [ { "class": "Createcollection", "description": "Test collection create", "invertedIndexConfig": { "bm25": { "b": 0.75, "k1": 1.2 }, "cleanupIntervalSeconds": 300, "indexNullState": true, "indexPropertyLength": true, "indexTimestamps": true, "stopwords": { "additions": ["custom1"], "preset": "en", "removals": ["the"] } }, "moduleConfig": { "text2vec-contextionary": { "vectorizeClassName": true } }, "multiTenancyConfig": { "autoTenantActivation": false, "autoTenantCreation": false, "enabled": false }, "properties": [ { "dataType": ["text"], "description": "Main text field", "indexFilterable": true, "indexRangeFilters": false, "indexSearchable": true, "name": "content", "tokenization": "word" } ], "replicationConfig": { "asyncEnabled": true, "deletionStrategy": "NoAutomatedResolution", "factor": 1 }, "shardingConfig": { "virtualPerPhysical": 128, "desiredCount": 1, "actualCount": 1, "desiredVirtualCount": 128, "actualVirtualCount": 128, "key": "_id", "strategy": "hash", "function": "murmur3" }, "vectorIndexConfig": { "skip": false, "cleanupIntervalSeconds": 300, "maxConnections": 64, "efConstruction": 128, "ef": -1, "dynamicEfMin": 100, "dynamicEfMax": 500, "dynamicEfFactor": 8, "vectorCacheMaxObjects": 1000000000000, "flatSearchCutoff": 40000, "distance": "cosine", "pq": { "enabled": false, "bitCompression": false, "segments": 0, "centroids": 256, "trainingLimit": 100000, "encoder": { "type": "kmeans", "distribution": "log-normal" } }, "bq": { "enabled": false }, "sq": { "enabled": false, "trainingLimit": 100000, "rescoreLimit": 20 }, "filterStrategy": "sweeping" }, "vectorIndexType": "hnsw", "vectorizer": "none" } ] }

这个响应中值得关注的字段包括：vectorIndexType（默认hnsw图索引）、vectorIndexConfig.distance（默认cosine余弦距离）、invertedIndexConfig.bm25（BM25 关键词排序权重）以及multiTenancyConfig（多租户开关），它们共同决定了集合的检索行为。

Data Type - Collection：集合生命周期管理

Collection 数据类型下包含三个操作，对应集合的读取、创建与删除。

Get Collection

获取单个集合的详细定义。

必填参数

• Collection Name：要查询的集合名称。

可选参数

• Consistency：与 Schema 操作相同的一致性开关，开启后附加consistency请求头。

响应示例：返回该集合的属性数组与复制/分片/向量索引配置，结构与上文的单个 class 定义一致：

{ [ { "dataType": ["text"], "description": "Main text field", "indexFilterable": true, "indexRangeFilters": false, "indexSearchable": true, "name": "content", "tokenization": "word" } ], "replicationConfig": { "asyncEnabled": true, "deletionStrategy": "NoAutomatedResolution", "factor": 1 }, "shardingConfig": { "virtualPerPhysical": 128, "desiredCount": 1, "actualCount": 1, "desiredVirtualCount": 128, "actualVirtualCount": 128, "key": "_id", "strategy": "hash", "function": "murmur3" }, "vectorIndexConfig": { "skip": false, "cleanupIntervalSeconds": 300, "maxConnections": 64, "efConstruction": 128, "ef": -1, "dynamicEfMin": 100, "dynamicEfMax": 500, "dynamicEfFactor": 8, "vectorCacheMaxObjects": 1000000000000, "flatSearchCutoff": 40000, "distance": "cosine", "pq": { "enabled": false, "bitCompression": false, "segments": 0, "centroids": 256, "trainingLimit": 100000, "encoder": { "type": "kmeans", "distribution": "log-normal" } }, "bq": { "enabled": false }, "sq": { "enabled": false, "trainingLimit": 100000, "rescoreLimit": 20 }, "filterStrategy": "sweeping" }, "vectorIndexType": "hnsw", "vectorizer": "none" }

Create Collection

创建新集合，是搭建语义检索能力的第一步。该操作参数最多，分为必填与可选两组。

必填参数

可选参数

上述参数在源码中有着明确的类型转换逻辑（query_operations.ts）：JSON 字符串参数（vector_index_config、sharding_config、bm_25、stop_words、module_config、properties）通过JSON.parse解析；factor、clean_up_interval_seconds通过Number()转换；async_enabled、index_time_stamps、index_null_state、index_property_length通过Boolean()转换，最终组装成POST /v1/schema的请求体。因此表单中输入"true"、"1"等字符串会被正确转换为布尔与数值类型。

响应示例：返回新创建集合的完整定义，包括倒排索引、模块配置、多租户、复制、分片、向量索引等全部配置项（结构同"Get Database Schema"中的 class 对象，此处不再赘述完整 JSON）。

Delete Collection

删除指定集合及其全部数据。

必填参数

• Collection Name：需要删除的集合名称。

该操作在源码中映射为DELETE /v1/schema/{collectionName}（query_operations.ts），成功时返回布尔值true。删除为不可逆操作，建议先通过 Get Collection 确认集合名称无误再执行。

Data Type - Objects：对象数据操作

Objects 数据类型对应GET/POST/DELETE /v1/objects系列接口（query_operations.ts），覆盖数据的写入、分页读取、按 ID 查询与删除。

List Objects

列出某个集合下的全部对象，支持分页与排序。

必填参数

• Collection Name：要列出对象的集合名称。

可选参数

源码中的参数映射值得注意（query_operations.ts）：include_vectors支持布尔或 JSON 解析；include、sort、order会按逗号拆分为数组；offset、limit转为数字；class参数始终固定为集合名称。空值或{}会被跳过，不会进入 URL 查询串。

响应示例：

{ "deprecations": [], "objects": [ { "class": "Testcollection", "creationTimeUnix": 1739009190787, "id": "296f9f17-628a-463a-b273-6ae369a3bb59", "lastUpdateTimeUnix": 1739009190787, "properties": { "content": "This is a test document stored in Weaviate.", "title": "New Sample Document" }, "vectorWeights": null }, { "class": "Testcollection", "creationTimeUnix": 1738941448311, "id": "550e8400-e29b-41d4-a716-446655440000", "lastUpdateTimeUnix": 1738941448311, "properties": { "content": "This is a test document stored in Weaviate.", "title": "Sample Document" }, "vectorWeights": null }, { "class": "Testcollection", "creationTimeUnix": 1739008896994, "id": "98a6628d-f07d-4f56-b64b-1b818201095c", "lastUpdateTimeUnix": 1739008896994, "properties": { "content": "This is a test document stored in Weaviate.", "title": "Sample Document" }, "vectorWeights": null } ], "totalResults": 3 }

Create Object

在指定集合内写入新对象。

必填参数

• Collection Name：要写入对象的集合名称；
• Properties：属性数组/对象，结构与 Property Object 一致，例如{"question": "This vector DB is OSS", "newProperty": 123}；
• Vector：对象的向量。源码支持两种形式：传入数组时写入vector字段，传入命名向量对象时写入vectors字段（query_operations.ts）。

可选参数

• Object uuid：对象的 UUID，不填则由 Weaviate 自动生成。

响应示例：

{ "class": "Testcollection", "creationTimeUnix": 1739009190787, "id": "296f9f17-628a-463a-b273-6ae369a3bb59", "lastUpdateTimeUnix": 1739009190787, "properties": { "content": "This is a test document stored in Weaviate.", "title": "New Sample Document" }, "vector": [0.12345, 0.12345, "......", 0.12345, 0.12345] }

Get Object By Id

按对象 ID 精确获取对象详情。

必填参数

• Collection Name：对象所属集合；
• Object ID：要查询的对象 UUID。

源码将其映射为GET /v1/objects/{collection}/{uuid}（query_operations.ts）。响应示例返回对象属性与时间戳，与 List Objects 中的单个对象结构一致：

{ "class": "Testcollection", "creationTimeUnix": 1738941448311, "id": "550e8400-e29b-41d4-a716-446655440000", "lastUpdateTimeUnix": 1738941448311, "properties": { "content": "This is a test document stored in Weaviate.", "title": "Sample Document" }, "vectorWeights": null }

Delete Object By Id

按对象 ID 删除对象。

必填参数

• Collection Name：对象所属集合；
• Object ID：要删除的对象 UUID。

源码将其映射为DELETE /v1/objects/{collection}/{uuid}（query_operations.ts），成功时返回布尔值true。

插件工作原理：一次查询的完整调用链

结合 index.ts 与 query_operations.ts，可以还原一次 ToolJet 查询的完整链路：

1. ToolJet 查询编辑器将用户填写的表单值组装为QueryOptions（结构见 types.ts）；
2. Weaviate.run()根据connection_type决定基础地址与鉴权头：本地为http://<host>:<port>（无鉴权），云端为instanceUrl+Bearer <apiKey>；
3. 按data_type分发：schema→getSchema()；collection→collectionOperation()；objects→objectsOperation()；
4. 各函数内部再次按操作类型映射到具体的 Weaviate REST 端点，并完成参数类型转换（JSON.parse/Number/Boolean）与查询串拼装；
5. 任何 HTTP 非 2xx 响应都会抛出带状态码的错误，最终包装为QueryError返回给前端，方便在查询面板中排查。

这种"表单参数 → REST 端点"的一一映射设计，意味着插件所有能力都建立在 Weaviate 官方 REST API 之上，若后续 Weaviate 版本新增端点，插件升级时只需在query_operations.ts中补充对应的映射函数即可。

在应用中消费查询结果

查询执行完成后，ToolJet 会把结果暴露为queries.<queryName>.data，可在任意组件的数据属性或事件处理器的表达式中引用，例如：

{{ queries.listObjects.data.objects }}

建议的使用模式：

• 知识库检索：先用 Create Collection + Create Object 写入带向量的文档，再用一个输入组件捕获用户问题，通过查询参数绑定把向量查询条件传入 List Objects，将结果渲染到 Table 或 Listview 组件；
• 集合管理面板：用 Get Database Schema 动态渲染全部集合，配合 Create/Delete Collection 做成可视化的 Schema 管理界面；
• 多租户数据隔离：在 List Objects 中传入 Tenant 参数，按租户过滤数据。

小结

本文从连接配置出发，完整覆盖了 ToolJet Weaviate 插件的全部 8 个操作：Schema 层的Get Database Schema、Collection 层的Get/Create/Delete Collection、Objects 层的List/Create/Get By Id/Delete By Id，并给出了每个操作的必填/可选参数、类型与默认值，以及可复现的响应示例。同时结合 marketplace/plugins/weaviate/lib 下的源码与 operations.json 配置，说明了参数如何被转换、如何映射到 Weaviate REST API。按照本文步骤，即可在 ToolJet 中快速搭建具备语义检索能力的 AI 应用、推荐系统或知识库工具。

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