Couchbase Search Vector Store icon

Couchbase Search Vector Store

Work with your data using the Couchbase Search Vector Store. This node conducts vector retrievals using the Search service.

Overview

This node integrates with a Couchbase Search Vector Store, enabling users to perform vector-based document operations within n8n workflows. It supports multiple modes of operation including inserting documents, retrieving ranked documents based on similarity queries, updating existing documents by ID, and exposing the vector store as a tool or retriever for AI nodes.

Common scenarios where this node is beneficial include:

  • Building semantic search applications that retrieve relevant documents from a Couchbase vector index.
  • Ingesting and indexing large batches of documents with embeddings for later retrieval.
  • Updating vector embeddings or metadata for specific documents in the vector store.
  • Using the vector store as a backend for AI chains or agents that require contextual document retrieval.

Practical examples:

  • A customer support chatbot that retrieves relevant knowledge base articles using vector similarity.
  • An AI-powered document analysis pipeline that inserts new documents with embeddings into Couchbase.
  • An automated workflow that updates outdated document vectors after re-embedding content.

Properties

Name Meaning
Operation Mode The action to perform:
• Get Many (load): Retrieve many ranked documents matching a query.
• Insert Documents (insert): Add documents with embeddings to the vector store.
• Retrieve Documents (retrieve): Use as vector store retriever for AI nodes.
• Retrieve Documents (retrieve-as-tool): Use as a tool for AI agents.
• Update Documents (update): Update documents by ID.
Couchbase Bucket The Couchbase bucket name to connect to. Can be selected from a list or entered manually.
Couchbase Scope The Couchbase scope within the bucket. Depends on the selected bucket.
Couchbase Collection The Couchbase collection within the scope. Depends on the selected bucket and scope.
Use Scoped Index Boolean flag indicating whether to use a scoped search index (true) or a global one (false).
Vector Index Name The name of the vector index used for similarity search. Depends on bucket, scope, collection, and scoped index usage.
Embedding Field Key The field name in documents that contains the embedding array.
Text Field Key The field name containing the raw text data of the document.
Embedding Batch Size Number of documents to embed in a single batch when inserting (only shown in insert mode).
Prompt The search prompt string used to retrieve matching documents via similarity ranking (shown in 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 output (used in load and retrieve-as-tool modes).
ID The ID of an embedding entry to update (required in update mode).
Options (Metadata Filter) Optional metadata filters to narrow down documents during retrieval or update. Allows specifying multiple key-value pairs to filter documents by metadata fields.
Options (Add Vector Options) When inserting, allows specifying explicit IDs and metadata arrays for the vectors being added.
Tool Name Name of the vector store tool (required in retrieve-as-tool mode).
Tool Description Description explaining what the tool does, helping LLMs produce better results (required in retrieve-as-tool mode).

Output

The node outputs JSON data representing the retrieved or affected documents depending on the operation:

  • Get Many / Retrieve: Returns an array of documents ranked by similarity to the query prompt. Each document includes the raw text field, embedding vector, and optionally metadata if requested.
  • Insert Documents: Outputs confirmation or status of inserted documents; typically no complex JSON structure beyond success indication.
  • Update Documents: Outputs confirmation or status of updated document by ID.
  • Retrieve as Tool / Retriever: Outputs documents formatted to be consumed by AI nodes as vector stores or tools, including embeddings and metadata as needed.

If binary data were involved (not indicated here), it would represent document attachments or files, but this node focuses on JSON document data with embeddings.

Dependencies

  • Requires a Couchbase cluster accessible with appropriate credentials configured in n8n.
  • Needs an API key or authentication token for Couchbase access (configured as a credential in n8n).
  • Uses Couchbase Search service with vector indexes properly set up.
  • Relies on embedding generation done externally or prior to insertion (embeddings are provided as input fields).
  • Node depends on LangChain community package for Couchbase vector store integration.

Troubleshooting

  • Invalid metadata JSON format: When inserting documents with metadata, ensure the JSON array is correctly formatted. Malformed JSON will cause errors.
  • Bucket/Scope/Collection validation errors: If the specified Couchbase bucket, scope, or collection does not exist or is inaccessible, the node will throw validation errors. Verify names and permissions.
  • Connection failures: Ensure Couchbase cluster credentials are correct and network connectivity is available.
  • Missing required fields: Fields like embedding key, text field key, and vector index name are mandatory. Omitting them causes errors.
  • Empty or invalid IDs on update: When updating documents, provide valid IDs; empty or malformed IDs will cause failures.
  • Search index issues: If the vector index is not properly created or named, retrieval operations will fail.

Links and References

Discussion