ToolJet 集成 Weaviate 向量数据库：连接配置、Schema/Collection/Objects 全操作实战指南

Weaviate 是一款开源向量数据库，将其接入 ToolJet 后，你可以在低代码应用中直接执行向量搜索与语义查询，按"含义"而非"精确关键词"检索信息，适合构建 AI 搜索引擎、推荐系统和知识检索类应用。本文以官方文档为主线，结合仓库中 weaviate 插件源码 与 operations 配置，系统讲解连接方式、三类数据类型的全部受支持操作、参数含义与底层调用链，读完即可在 ToolJet 中完成 Weaviate 数据源的配置与增删改查。

集成概览：为什么在 ToolJet 中使用 Weaviate

Weaviate 的核心能力是把非结构化数据转换为向量并支持基于向量的相似度检索。在 ToolJet 中通过 Marketplace 安装 Weaviate 插件后，数据源被定义为类型为 ai 的插件（见 manifest.json 中的 "type": "ai"），它向应用暴露 isLoading、data、rawData 三个内置变量，查询结果可无缝绑定到表格、图表、表单等组件。

从源码结构看，插件的查询执行入口是 index.ts 中的 run() 方法，它根据 data_type（schema / collection / objects）分发到 query_operations.ts 中对应的函数，最终全部落到 Weaviate 的 REST API（/v1/schema 与 /v1/objects）。这意味着你在 ToolJet 中执行的每个操作，本质上是封装好的 Weaviate HTTP 请求。

连接配置：Cloud 与 Local 两种方式

在 ToolJet 中创建 Weaviate 数据源时，需要先选择连接类型。由 manifest.json 可知，connection_type 提供 cloud（默认）与 local 两个选项，不同连接类型对应不同的必填字段。

Cloud（云端）

连接 Weaviate Cloud 需要两个参数：

参数	说明	字段类型
Instance URL	Weaviate 云实例的访问地址，如 https://your-weaviate-instance.com	文本
API Key	实例的 API 密钥	密码（encrypted: true，加密存储）

API Key 需要从 Weaviate 控制台（Weaviate Console）生成。在 manifest.json 中该字段被标记为 encrypted，与 ToolJet 对数据源凭据的统一加密策略一致。

Local（本地）

连接本地 Weaviate 只需要 Host 和 Port 两个参数（见 manifest.json 中 local 配置块），无需 API Key。插件源码 index.ts 显示，本地连接会拼接出 http://${host}:${port} 作为基础 URL，且不附加任何鉴权头；而云端连接使用 instanceUrl 并附加 Authorization: Bearer <apiKey> 请求头。

使用以下 Docker 命令在本地启动 Weaviate 容器，默认 Host 为 localhost、Port 为 8080：

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

命令同时映射了 8080（HTTP API）与 50051（gRPC）两个端口，1.28.4 是文档对应的 Weaviate 镜像版本。

提示：新建数据源后，ToolJet 会调用插件的 testConnection() 方法（见 index.ts）验证连通性——它对 /v1/schema 发起 GET 请求，本地与云端分别使用 http://host:port 和 instanceUrl，云端附加 Bearer Token，HTTP 200 即视为连接成功。

受支持操作总览

插件支持的所有操作均由 operations.json 驱动——该文件不仅定义了操作列表，还定义了每个参数的 UI 控件类型（codehinter 代码输入框、toggle 开关等）与默认占位符。所有操作按 Data Type 分为三类：

Data Type	支持的操作
Schema	Get Database Schema
Collection	Get Collection、Create Collection、Delete Collection
Objects	List Objects、Create Object、Get Object By Id、Delete Object By Id

每类操作在 UI 上都会先选择 Data Type，再选择具体 Operation，最后填写参数。

Data Type - Schema：获取数据库 Schema

Get Database Schema

该操作用于获取整个 Weaviate 实例的数据库 Schema（即全部 Collection 的定义）。

可选参数

• Consistency：布尔开关（toggle，默认 true，见 operations.json）。启用后请求会由 leader 节点处理以保证准确性，源码中该值会直接写入请求头 headers.consistency。

底层实现对应 query_operations.ts 的 getSchema()：对 ${BASE_URL}/v1/schema 发起 GET 请求，并在启用 consistency 时将开关值附加到请求头。

响应示例：

{
  "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"
    }
  ]
}

响应中的 classes 数组包含了每个集合的完整配置：倒排索引（invertedIndexConfig）、向量索引（vectorIndexConfig，如 HNSW 的 maxConnections、efConstruction、距离度量 distance: "cosine"）、分片（shardingConfig）、复制（replicationConfig）以及属性定义（properties）。

Data Type - Collection：集合级操作

Collection（集合）是 Weaviate 中与"表"等价的概念。本类包含三个操作。

Get Collection

按名称获取单个集合的详细信息。

必填参数

• Collection Name：要获取详情的集合名称。

可选参数

• Consistency：与 Schema 操作相同，启用后由 leader 节点处理。

源码中 getCollection() 对 ${BASE_URL}/v1/schema/${collectionName} 发起 GET 请求（见 query_operations.ts）。

响应示例：

{
  "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

用于创建一个新的 Collection，这是所有对象操作的前提。

必填参数（来自 operations.json 的 create_collection 配置块）：

参数	说明	输入类型/占位符示例
Collection Name	集合名称（即 Weaviate 中的 class）	codehinter
Vectorizer	用于为该集合数据对象生成向量的向量化器	JSON 对象，占位符 {}
Vector index config	向量索引类型专属设置，含距离度量（distance metric）	JSON 对象，占位符 {}
Module config	模块专属设置	JSON 对象，占位符 {}
Description	集合描述，仅供你参考	文本
Properties	属性对象数组，与 Weaviate 的 Property Object 结构一致	JSON 数组，完整占位符示例见下文

可选参数：

参数	说明	默认/占位符
Consistency	启用后由 leader 节点处理请求	开关，默认 true
Sharding config	控制集合在多节点环境下的分片行为	{}
Stop words	控制倒排索引中应忽略哪些停用词	{"preset":"","additions":[""],"removals":[""]}
Index time stamps	按内部时间戳为每个对象维护倒排索引	true
Index null state	按 null 状态为每个属性维护倒排索引	true
Index property length	按属性长度为其维护倒排索引	true
Bm 25	BM25 搜索排序算法，通过可调的 k1、b 值提升结果准确度，默认 k1 = 1.2、b = 0.75	{"k1":1,"b":1}
Factor	控制复制或分片行为以支持扩展	1
Async enabled	后台运行操作以提升性能	true
Deletion strategy	定义删除数据的处理方式（如立即删除或延迟删除）	NoAutomatedResolution
Cleanup interval seconds	设置旧数据或已删除数据的清理频率	1

Properties 参数占位符结构（完整 Property Object 示例）：

[
  {
    "dataType": [""],
    "description": "",
    "moduleConfig": {},
    "name": "",
    "indexInverted": true,
    "indexFilterable": true,
    "indexSearchable": true,
    "indexRangeFilters": true,
    "tokenization": "word",
    "nestedProperties": []
  }
]

从 query_operations.ts 的 createCollection() 实现可以看到各参数如何被组装进请求体：factor 经 Number() 转换、async_enabled 与 index_* 系列经 Boolean() 转换，而 vector_index_config、sharding_config、bm_25、stop_words、module_config、properties 均需为合法 JSON 字符串（内部通过 JSON.parse 解析）。请求通过 POST ${BASE_URL}/v1/schema 发送。

响应示例：

{
  "class":"Newcollection",
  "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"
}

Delete Collection

删除一个已存在的 Collection（会连同其中所有对象一并删除，请谨慎操作）。

必填参数

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

源码中 deleteCollection() 对 ${BASE_URL}/v1/schema/${collectionName} 发起 DELETE 请求，成功后返回 true。

Data Type - Objects：对象级操作

Objects 是存储在 Collection 中的具体数据条目（即"行"），本类包含四个操作。

List Objects

列出指定集合内的所有对象，支持分页、排序与筛选参数，是构建数据展示类应用最常用的操作。

必填参数

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

可选参数（参数解析逻辑见 query_operations.ts 的 listObjects()）：

参数	说明	占位符示例
Include vectors	指定要包含的向量名称	true 或 ['title','review_body']
After	一个阈值 UUID，仅返回排在该对象之后的对象（游标分页）	{}
Offset	结果窗口的起始索引	{}
Limit	每页返回的最大条数	10
Include	附带额外信息（如 classification 分类信息），允许值：classification、vector、interpretation	value1, value2
Sort	用于排序的属性名称	value1, value2
Order	排序方向（asc 或 desc）	value1, value2
Tenant	针对多租户类请求指定租户	value

源码中 include_vectors 会先判断是否为字符串 'true' 再尝试 JSON.parse，include/sort/order 按逗号拆分为数组，offset/limit 转为数字，所有参数通过 URLSearchParams 拼接到 GET ${BASE_URL}/v1/objects 请求中。

响应示例：

{
    "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
}

响应中每个对象包含 class（所属集合）、id（UUID）、creationTimeUnix/lastUpdateTimeUnix（创建与更新时间戳）和 properties（属性内容），totalResults 给出总数。

Create Object

在指定集合中创建新对象，即向向量数据库写入一条数据。

必填参数

• Collection Name：目标集合名称。
• Properties：属性数组，结构与 Property Object 一致。占位符示例：{'question': 'This vector DB is OSS & supports automatic property type inference on import', 'newProperty': 123}
• Vector：对象的向量数据。占位符示例：{ title: Array(1536).fill(0.12345), review_body: Array(1536).fill(0.31313), title_country: Array(1536).fill(0.05050) }

可选参数

• Object uuid：对象的 UUID。占位符示例：ed89d9e7-4c9d-4a6a-8d20-095cb0026f54。不填则由 Weaviate 自动生成。

源码 query_operations.ts 的 createObject() 显示：如果 Vector 参数传入的是数组，则写入请求体中的 vector 字段（单向量模式）；否则写入 vectors 字段（命名多向量模式）。请求通过 POST ${BASE_URL}/v1/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"
    },
    "vector":[0.12345,0.12345,.......,0.12345,0.12345]
}

Get Object By Id

通过对象的 UUID 获取其详细信息。

必填参数

• Collection Name：对象所属的集合名称。
• Object ID：要获取详情的对象 UUID。

底层实现为 GET ${BASE_URL}/v1/objects/${collection}/${uuid}（见 query_operations.ts）。

响应示例：

{
    "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

通过对象的 UUID 删除指定对象。

必填参数

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

底层实现为 DELETE ${BASE_URL}/v1/objects/${collection}/${uuid}，成功后返回 true。

源码视角：查询分发与错误处理机制

理解整个插件的运行机制只需关注三层结构（均位于 marketplace/plugins/weaviate/lib/ 目录）：

1. 入口层 index.ts：run() 先根据 connection_type 决定 BASE_URL 与鉴权头（云端附加 Authorization: Bearer），再按 data_type 分发；任何异常都会被包装为 QueryError('Query could not be completed', ...) 抛出。
2. 操作层 query_operations.ts：每个具体操作对应一个函数，统一基于原生 fetch 调用 Weaviate REST API，所有非 2xx 响应都会抛出带状态码的 HTTP 错误。
3. 类型层 types.ts：以枚举 SchemaOperation、CollectionOperation、ObjectsOperation 固化全部受支持操作，UI 参数与运行时字段一一对应。

UI 层的参数控件定义在 operations.json 中，其中大部分参数使用 codehinter 组件——这意味着你可以在参数中直接引用 ToolJet 的全局变量、查询结果（{{queries.xxx.data}}）或组件状态，实现真正的动态查询。例如在 Create Object 的 Properties 中写入 {{components.form1.data}}，即可把表单数据直接写入 Weaviate。

典型应用场景

• AI 知识检索应用：将文档向量化后存入 Weaviate，通过 List Objects + 排序组合实现"按语义返回相关内容"的检索页，替代关键词匹配。
• 推荐系统：利用对象向量与距离度量（如 cosine），在 ToolJet 中组合多个查询完成相似内容推荐。
• 数据管理后台：借助 Create/Get/Delete Object 系列操作，为内部工具提供向量数据的完整 CRUD 能力，与 ToolJet 的表单、表格组件无缝联动。
• 多租户场景：通过 List Objects 的 Tenant 参数，对启用了多租户的 Collection 做按租户隔离的数据访问。

小结

本文完整覆盖了 ToolJet 中 Weaviate 插件的全部内容：Cloud/Local 两种连接方式、Schema/Collection/Objects 三类数据类型的 8 个受支持操作、每个操作的必填/可选参数及响应结构，并结合 index.ts、query_operations.ts、operations.json 等源码文件说明了底层调用链。按本文步骤配置好数据源后，即可在 ToolJet 中搭建具备向量检索能力的 AI 应用。若需了解更深层的 Weaviate Schema 语义（如 HNSW 索引调优、BM25 参数），可参阅 Weaviate 官方 Schema 配置文档。