企业官网建设流程全解析

ToolJet 集成 Couchbase 插件：文档 CRUD、SQL++ 查询与全文检索实战指南

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

ToolJet 官方 Marketplace 提供了 Couchbase 数据源插件，用于在低代码应用中接入 Couchbase 的 NoSQL 文档能力与向量检索能力。本文基于仓库中的官方文档（docs/docs/marketplace/plugins/couchbase.md）与插件源码（marketplace/plugins/couchbase/lib/index.ts、marketplace/plugins/couchbase/lib/query_operations.ts），完整讲解插件的连接配置、六大核心操作（文档增删改查、SQL++ 查询、FTS 全文搜索）的参数细节、底层 HTTP 调用原理与真实请求/响应示例，帮助你直接上手构建基于 Couchbase 的内部工具、仪表盘与智能应用。

前置条件：使用 Marketplace 插件

在开始本指南前，请先确认你已经完成了 ToolJet 中安装与使用 Marketplace 插件的完整流程，包括：在 Marketplace 中安装插件、在组织（Workspace）中启用数据源插件等步骤。具体操作可参考 使用 Marketplace 插件 一节。插件安装完成后，即可在新建数据源时看到 Couchbase 选项。

连接 Couchbase 数据源

连接 Couchbase 时，需要提供以下三项凭据：

从插件清单 marketplace/plugins/couchbase/lib/manifest.json 可以看到，这三个字段的key分别对应源码中的data_api_url、username、password，且password被标记为"encrypted": true，意味着密码在保存时会进行加密处理，不会以明文形式落库；同时三个字段都在required数组中，缺一不可。源码 marketplace/plugins/couchbase/lib/index.ts 中的getConnection()方法也做了同样的校验：Username, password, and data_api_url are required，缺少任何一个都会抛出错误。

连接测试的底层原理

点击表单中的Test connection按钮时，插件会调用testConnection()（见 marketplace/plugins/couchbase/lib/index.ts）。其实现方式是向 Data API 的GET /v1/callerIdentity端点发起请求，并在请求头中携带基于用户名与密码生成的Basic认证信息：

GET {data_api_url}/v1/callerIdentity Authorization: Basic base64(username:password)

如果响应状态码不是 OK（2xx），则抛出Connection failed错误；请求成功则返回{ status: 'ok' }。这意味着 Data API Endpoint 必须是 Couchbase 对外可访问的 Data API 服务地址。若你的数据源不对外公开，通常还需要在 Couchbase 侧放行 ToolJet 的出口 IP。

支持的六种操作

插件通过操作下拉框分发到不同的实现，对应源码 marketplace/plugins/couchbase/lib/types.ts 中定义的Operation枚举：

分发逻辑位于 marketplace/plugins/couchbase/lib/index.ts 的run()方法中：根据queryOptions.operation走switch分支调用对应函数，未知操作会抛出Invalid operation错误；所有操作的成功结果统一包装为{ status: 'ok', data: result }返回给 ToolJet 前端。每个操作在查询编辑器中都以可绑定变量的形式暴露结果：data（解析后的数据）、rawData（原始响应）、isLoading（加载状态），见 marketplace/plugins/couchbase/lib/manifest.json 中的exposedVariables。

四种文档操作均基于 Couchbase Data API 的标准 REST 端点，URL 模式统一为：

{v1}/buckets/{bucket}/scopes/{scope}/collections/{collection}/documents/{document_id}

其中v1指{data_api_url}/v1。认证方式均为 HTTP Basic Auth。另外需要注意：在表单定义（marketplace/plugins/couchbase/lib/operations.json）中，Scope 与 Collection 是可选的，留空时默认使用_default，这与 Couchbase 默认作用域/集合的约定一致。

Get Document：按 ID 读取文档

通过文档 ID 从指定集合中获取单个文档。

必需参数：

• Bucket：文档所在的桶名称
• Document ID：要读取的文档唯一标识
• Scope：作用域名称（默认_default）
• Collection：集合名称（默认_default）

源码实现见 marketplace/plugins/couchbase/lib/query_operations.ts：对文档端点发起GET请求，四个参数缺一不可（Missing required parameters），响应体为文档的 JSON 内容。

示例响应：

{ "id": "user::123", "name": "John Doe", "email": "john@example.com", "age": 30, "created_at": "2023-01-15T10:30:00Z" }

Create Document：新建文档

在指定集合中创建一条新文档。

必需参数：

• Bucket：桶名称
• Scope：作用域名称（默认_default）
• Collection：集合名称（默认_default）
• Document ID：新文档的唯一标识
• Document：文档数据（JSON 对象）

实现细节（marketplace/plugins/couchbase/lib/query_operations.ts）：对文档端点发起POST请求，Document字段若是字符串会先被JSON.parse解析为对象，再作为请求体发送。表单中的默认占位示例为{ "name": "John Doe", "email": "john@example.com", "age": 30 }，字段输入模式为 JavaScript，可以直接引用 ToolJet 组件变量或查询结果生成动态文档内容。

示例响应：

Created successfully

Update Document：更新文档

更新集合中的已有文档。

必需参数：

• Bucket：桶名称
• Scope：作用域名称（默认_default）
• Collection：集合名称（默认_default）
• Document ID：要更新的文档标识
• Document：更新后的完整文档数据（JSON 对象）

实现细节（marketplace/plugins/couchbase/lib/query_operations.ts）：对文档端点发起PUT请求，Document同样支持字符串自动解析。

注意：Update 是整体替换语义。官方文档明确指出：该操作会用传入的文档整体替换原文档，而非合并字段。因此必须传入完整的文档内容，否则原有字段会丢失。如果只想修改部分字段，应先在应用中读取原文档、合并后再提交更新。

示例响应：

Updated successfully

Delete Document：删除文档

从集合中删除指定文档。

必需参数：

• Bucket：桶名称
• Scope：作用域名称（默认_default）
• Collection：集合名称（默认_default）
• Document ID：要删除的文档标识

实现细节（marketplace/plugins/couchbase/lib/query_operations.ts）：对文档端点发起DELETE请求，成功返回Deleted successfully。

示例响应：

Deleted successfully

Query：执行 SQL++ 查询

针对 Couchbase 数据库执行 SQL++（N1QL）查询，支持命名参数与查询选项。

必需参数：

• SQL++ Query：要执行的 SQL++ 语句，语句中可使用$parameter形式的命名参数占位符

可选参数：

• Arguments (Key-Value)：键值对对象，用于为查询中的$parameter占位符提供值
• Query Options：JSON 对象，包含额外的查询选项，例如readonly、timeout、query_context等

示例查询：

SELECT * FROM `travel-sample`.`inventory`.`airline` WHERE country = $country LIMIT 10

Arguments (Key-Value)：

{ "$country": "France" }

Query Options：

{ "readonly": true, "query_context": "travel-sample.inventory" }

其中query_context用于指定查询默认的数据上下文，可以省去语句中繁琐的全限定名；readonly声明只读查询。其他受支持的查询选项（如timeout等）与 Couchbase Query 服务 REST API 的请求参数保持一致。

底层实现（marketplace/plugins/couchbase/lib/query_operations.ts）有以下要点值得注意：

1. 查询请求发送到${data_api_url}/_p/query/query/service，使用POST方法，请求体结构为：

{ "statement": "SELECT ... WHERE country = $country LIMIT 10", "$country": "France", "readonly": true, "query_context": "travel-sample.inventory" }

2. Arguments与Query Options都支持直接传入对象或传入 JSON 字符串（字符串会被自动解析）。
3. 它们最终会被平铺合并到请求体中：statement字段存放 SQL++ 语句，命名参数键值对与查询选项键值对直接散列在请求体的顶层。
4. 若查询失败，错误信息中会附带服务端返回的响应体详情（details），便于定位 SQL 语法或权限问题。

示例响应：

{ "results": [ { "airline": { "id": 137, "type": "airline", "name": "Air France", "iata": "AF", "icao": "AFR", "callsign": "AIRFRANS", "country": "France" } } ], "status": "success", "metrics": { "elapsedTime": "15.2ms", "executionTime": "14.8ms", "resultCount": 1, "resultSize": 234 } }

在 ToolJet 中，查询结果会作为data暴露给后续组件与事件处理器，例如用{{queries.couchbaseQuery1.data.results}}绑定到表格组件展示数据。

FTS Search：全文检索

针对 Couchbase FTS（Full-Text Search）索引执行全文检索查询，可用于实现传统关键词搜索与基于向量索引的语义/混合检索。

必需参数：

• Bucket：要搜索的桶名称
• Scope：作用域名称
• Index Name：FTS 索引名称
• Search Query：FTS 搜索查询（JSON 对象）

示例搜索查询：

{ "query": { "match": "hotel", "field": "name" } }

底层实现（marketplace/plugins/couchbase/lib/query_operations.ts）：搜索请求发送到

POST {data_api_url}/_p/fts/api/bucket/{bucket}/scope/{scope}/index/{index_name}/query

Search Query支持直接传对象或 JSON 字符串，请求体即为整个 FTS 查询 JSON。与 Query 操作不同，FTS 的bucket、index_name与search_query为必填项，缺失时抛出Missing required parameters: bucket, index_name, and query are required。scope在源码中是可选的（拼接进 URL 时可省略），但官方文档将其列为必填参数，建议显式传入，以免命中错误的索引作用域。

示例响应：

{ "status": { "total": 1, "failed": 0, "successful": 1 }, "request": { "query": { "match": "hotel", "field": "name" } }, "hits": [ { "index": "hotel-index", "id": "hotel_123", "score": 0.8567, "fields": { "name": "Grand Hotel", "city": "Paris", "country": "France" } } ], "total_hits": 1, "max_score": 0.8567, "took": 12 }

在智能应用场景中，你可以结合 Couchbase 的向量索引（Vector Index）能力，将 FTS Search 用于语义检索与混合检索（传统关键词 + AI 向量查询），在 ToolJet 中快速构建 RAG、智能问答等 AI 类应用。

错误处理与调试建议

插件在 marketplace/plugins/couchbase/lib/index.ts 中对所有操作统一做了异常捕获与包装：底层抛出的错误会被重新包装为QueryError('Query could not be completed', errorMessage, errorDetails)，其中errorDetails会附带name、code、codeName等结构化信息，方便在 ToolJet 的查询运行结果中定位问题。调试时建议关注以下几点：

• 参数缺失：文档类操作缺参数会报Missing required parameters，请确认 Bucket/Scope/Collection/Document ID 都已填写。
• 连接失败：检查 Data API Endpoint 是否可达、用户名密码是否正确，可先点击Test connection验证。
• HTTP 状态错误：GET/POST/PUT/DELETE 任一请求返回非 2xx 时，错误信息会附带statusText（如Failed to fetch document: Not Found），通常对应文档 ID 不存在或索引/集合路径拼写错误。
• JSON 解析失败：Document、Arguments、Query Options、Search Query等字段传入字符串时会被JSON.parse解析，务必保证是合法的 JSON，否则会抛出解析异常。

扩展阅读

• 插件入口与操作分发：marketplace/plugins/couchbase/lib/index.ts
• 六种操作的具体 HTTP 实现：marketplace/plugins/couchbase/lib/query_operations.ts
• 类型定义（Operation枚举、SourceOptions、QueryOptions）：marketplace/plugins/couchbase/lib/types.ts
• 数据源表单与字段定义：marketplace/plugins/couchbase/lib/manifest.json
• 查询编辑器操作表单（含各字段占位符与默认值）：marketplace/plugins/couchbase/lib/operations.json
• 插件元信息与构建脚本：marketplace/plugins/couchbase/package.json
• Marketplace 插件使用总览：docs/docs/marketplace/marketplace_overview.md

结合 Couchbase 的 Document API、Query 服务与 FTS 服务，你可以用 ToolJet 快速搭建文档管理后台、N1QL 数据探索面板、全文/语义检索界面等内部工具；再配合 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