Overview
The Couchbase Vector Store node integrates with a Couchbase vector search index to manage and query vectorized documents. It supports multiple operation modes:
- Insert Documents: Add new documents with embeddings into the vector store.
- Get Many (Load): Retrieve many ranked documents based on a similarity search query.
- Retrieve Documents (As Vector Store for Chain/Tool): Fetch documents to be used as a vector store input for AI workflows or chains.
- Retrieve Documents (As Tool for AI Agent): Fetch documents to be used as a tool by AI agents.
- Update Documents: Update existing documents in the vector store by their ID.
This node is beneficial when working with AI applications that require semantic search, document retrieval, or embedding management within Couchbase. For example, you can insert product descriptions as vectors, then retrieve the most relevant products for a user query using similarity search.
Properties
| Name | Meaning |
|---|---|
| Operation Mode | The mode of operation to perform: - Get Many (load): Retrieve many ranked documents for a query. - Insert Documents (insert): Add documents to the vector store. - Retrieve Documents (retrieve): Retrieve documents as vector store. - Retrieve Documents (retrieve-as-tool): Retrieve documents as a tool for AI agent. - Update Documents (update): Update documents by ID. |
| Bucket | The Couchbase bucket to use. Can be selected from a list or specified by name. |
| Scope | The Couchbase scope within the bucket. Can be selected from a list or specified by name. |
| Collection | The Couchbase collection within the scope. Can be selected from a list or specified by name. |
| Index | The name of the vector search index to use for the operation. |
| Embedding Batch Size | Number of documents to embed in a single batch (only for insert mode). |
| Options | Additional optional parameters for the operation (varies by mode). |
| Prompt | Search prompt string to retrieve matching documents using similarity-based ranking (only for load mode). |
| Limit (topK) | Number of top results to fetch from the vector store (used in load and retrieve-as-tool modes). |
| Include Metadata | Whether to include document metadata in the results (used in load and retrieve-as-tool modes). |
| ID | ID of an embedding entry to update (only for update mode). |
| Description (toolDescription) | Description explaining what the tool does, used to help LLMs understand the tool's purpose (only for retrieve-as-tool mode). |
Output
- Insert, Load, Update Modes: Outputs standard main data containing the results of the operation (e.g., confirmation of inserted/updated documents or retrieved documents).
- Retrieve Documents (As Vector Store): Outputs a vector store object suitable for chaining with other AI nodes.
- Retrieve Documents (As Tool for AI Agent): Outputs a tool object designed for use by AI agents.
The json output field typically contains the retrieved documents or confirmation data depending on the operation. When retrieving documents, metadata can optionally be included alongside the document content.
Binary data output is not indicated for this node.
Dependencies
- Requires a valid connection to a Couchbase instance with appropriate credentials (an API key or authentication token).
- The Couchbase environment must have configured buckets, scopes, collections, and vector search indexes.
- n8n credential configuration for Couchbase API access is necessary.
- The node depends on Couchbase vector search capabilities and embedding inputs from connected AI embedding nodes.
Troubleshooting
- Unsupported Operation Mode Error: If an unsupported mode is selected during execution, the node throws an error indicating only "load", "update", and "insert" are supported in the execute method, or only "retrieve" and "retrieve-as-tool" are supported in supplyData. Ensure the correct mode is selected for the intended action.
- Missing or Incorrect Credentials: Failure to connect to Couchbase due to invalid or missing credentials will cause errors. Verify the API key or authentication token is correctly configured.
- Invalid Bucket/Scope/Collection Names: Using non-existent or misspelled resource names will result in failures. Use the provided resource locators or lists to select valid resources.
- Index Not Found: Specifying a vector index name that does not exist in Couchbase will cause search operations to fail. Confirm the index exists and is properly named.
- Batch Size Too Large: Setting an excessively large embedding batch size may cause performance issues or timeouts during insertion. Adjust batch size according to system capacity.
- Empty or Invalid Prompt: For search operations, providing an empty or invalid prompt string will yield no results or errors. Provide meaningful search queries.