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/ToolJetToolJet 官方 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 时需要提供以下三项凭据配置项说明表单类型Data API EndpointCouchbase Data API 的端点 URL形如https://your-data-api-endpoint文本输入UsernameCouchbase 用户名文本输入PasswordCouchbase 密码密码输入加密存储从插件清单 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)如果响应状态码不是 OK2xx则抛出Connection failed错误请求成功则返回{ status: ok }。这意味着 Data API Endpoint 必须是 Couchbase 对外可访问的 Data API 服务地址。若你的数据源不对外公开通常还需要在 Couchbase 侧放行 ToolJet 的出口 IP。支持的六种操作插件通过操作下拉框分发到不同的实现对应源码 marketplace/plugins/couchbase/lib/types.ts 中定义的Operation枚举操作枚举值说明Get Documentget_document按 ID 读取单个文档Create Documentcreate_document新建文档Update Documentupdate_document整体替换更新文档Delete Documentdelete_document按 ID 删除文档Queryquery执行 SQLN1QL查询FTS Searchfts_search对 FTS 索引执行全文检索分发逻辑位于 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作用域名称默认_defaultCollection集合名称默认_default源码实现见 marketplace/plugins/couchbase/lib/query_operations.ts对文档端点发起GET请求四个参数缺一不可Missing required parameters响应体为文档的 JSON 内容。示例响应{ id: user::123, name: John Doe, email: johnexample.com, age: 30, created_at: 2023-01-15T10:30:00Z }Create Document新建文档在指定集合中创建一条新文档。必需参数Bucket桶名称Scope作用域名称默认_defaultCollection集合名称默认_defaultDocument ID新文档的唯一标识Document文档数据JSON 对象实现细节marketplace/plugins/couchbase/lib/query_operations.ts对文档端点发起POST请求Document字段若是字符串会先被JSON.parse解析为对象再作为请求体发送。表单中的默认占位示例为{ name: John Doe, email: johnexample.com, age: 30 }字段输入模式为 JavaScript可以直接引用 ToolJet 组件变量或查询结果生成动态文档内容。示例响应Created successfullyUpdate Document更新文档更新集合中的已有文档。必需参数Bucket桶名称Scope作用域名称默认_defaultCollection集合名称默认_defaultDocument ID要更新的文档标识Document更新后的完整文档数据JSON 对象实现细节marketplace/plugins/couchbase/lib/query_operations.ts对文档端点发起PUT请求Document同样支持字符串自动解析。注意Update 是整体替换语义。官方文档明确指出该操作会用传入的文档整体替换原文档而非合并字段。因此必须传入完整的文档内容否则原有字段会丢失。如果只想修改部分字段应先在应用中读取原文档、合并后再提交更新。示例响应Updated successfullyDelete Document删除文档从集合中删除指定文档。必需参数Bucket桶名称Scope作用域名称默认_defaultCollection集合名称默认_defaultDocument ID要删除的文档标识实现细节marketplace/plugins/couchbase/lib/query_operations.ts对文档端点发起DELETE请求成功返回Deleted successfully。示例响应Deleted successfullyQuery执行 SQL 查询针对 Couchbase 数据库执行 SQLN1QL查询支持命名参数与查询选项。必需参数SQL Query要执行的 SQL 语句语句中可使用$parameter形式的命名参数占位符可选参数Arguments (Key-Value)键值对对象用于为查询中的$parameter占位符提供值Query OptionsJSON 对象包含额外的查询选项例如readonly、timeout、query_context等示例查询SELECT * FROM travel-sample.inventory.airline WHERE country $country LIMIT 10Arguments (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有以下要点值得注意查询请求发送到${data_api_url}/_p/query/query/service使用POST方法请求体结构为{ statement: SELECT ... WHERE country $country LIMIT 10, $country: France, readonly: true, query_context: travel-sample.inventory }Arguments与Query Options都支持直接传入对象或传入 JSON 字符串字符串会被自动解析。它们最终会被平铺合并到请求体中statement字段存放 SQL 语句命名参数键值对与查询选项键值对直接散列在请求体的顶层。若查询失败错误信息中会附带服务端返回的响应体详情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 FTSFull-Text Search索引执行全文检索查询可用于实现传统关键词搜索与基于向量索引的语义/混合检索。必需参数Bucket要搜索的桶名称Scope作用域名称Index NameFTS 索引名称Search QueryFTS 搜索查询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}/querySearch 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、QueryOptionsmarketplace/plugins/couchbase/lib/types.ts数据源表单与字段定义marketplace/plugins/couchbase/lib/manifest.json查询编辑器操作表单含各字段占位符与默认值marketplace/plugins/couchbase/lib/operations.json插件元信息与构建脚本marketplace/plugins/couchbase/package.jsonMarketplace 插件使用总览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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考