Couchbase

Couchbase is an award-winning distributed NoSQL cloud database that delivers unmatched versatility, performance, scalability, and financial value for all of your cloud, mobile, AI, and edge computing applications.

If you want to see a detailed usage example, see Couchbase Vector Store.

Installation and Setup

Install the langchain-couchbase package along with embedding dependencies:

pip

pip install langchain-couchbase langchain-openai

Vector store

Couchbase provides two different vector store implementations for LangChain:

Vector Store	Index Type	Minimum Version	Best For
CouchbaseSearchVectorStore	Search Vector Index	Couchbase Server 7.6+	Hybrid searches combining vector similarity with Full-Text Search (FTS) and geospatial searches
CouchbaseQueryVectorStore	Hyperscale Vector Index or Composite Vector Index	Couchbase Server 8.0+	Large-scale pure vector searches or searches combining vector similarity with scalar filters

CouchbaseSearchVectorStore

from langchain_couchbase import CouchbaseSearchVectorStore
from langchain_openai import OpenAIEmbeddings

import getpass
import os

# Get credentials
COUCHBASE_CONNECTION_STRING = getpass.getpass(
    "Enter the connection string for the Couchbase cluster: "
)
DB_USERNAME = getpass.getpass("Enter the username for the Couchbase cluster: ")
DB_PASSWORD = getpass.getpass("Enter the password for the Couchbase cluster: ")
OPENAI_API_KEY = getpass.getpass("Enter your OpenAI API key: ")

os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY

# Create Couchbase connection object
from datetime import timedelta

from couchbase.auth import PasswordAuthenticator
from couchbase.cluster import Cluster
from couchbase.options import ClusterOptions

auth = PasswordAuthenticator(DB_USERNAME, DB_PASSWORD)
options = ClusterOptions(auth)
options.apply_profile("wan_development")
cluster = Cluster(COUCHBASE_CONNECTION_STRING, options)

# Wait until the cluster is ready for use.
cluster.wait_until_ready(timedelta(seconds=5))

# Set up embeddings
embeddings = OpenAIEmbeddings(model="text-embedding-3-large")

# Create vector store
vector_store = CouchbaseSearchVectorStore(
    cluster=cluster,
    bucket_name="my_bucket",
    scope_name="_default",
    collection_name="_default",
    embedding=embeddings,
    index_name="my_search_index",
)

# Add documents
texts = ["Couchbase is a NoSQL database", "LangChain is a framework for LLM applications"]
vector_store.add_texts(texts)

# Search
query = "What is Couchbase?"
docs = vector_store.similarity_search(query)

API Reference: CouchbaseSearchVectorStore

CouchbaseQueryVectorStore

from langchain_couchbase import CouchbaseQueryVectorStore
from langchain_openai import OpenAIEmbeddings

# (After setting up cluster connection as shown above)

embeddings = OpenAIEmbeddings(model="text-embedding-3-large")

vector_store = CouchbaseQueryVectorStore(
    cluster=cluster,
    bucket_name="my_bucket",
    scope_name="_default",
    collection_name="_default",
    embedding=embeddings,
    index_name="my_vector_index",
)

# Create index (if needed)
vector_store.create_index(
    index_type=IndexType.HYPERSCALE,
    index_description="IVF,SQ8",
    index_name="my_vector_index",
)

# Add documents and search
vector_store.add_documents([
    Document(page_content="Couchbase is a NoSQL database", metadata={"source": "couchbase"}),
    Document(page_content="LangChain is a framework for LLM applications", metadata={"source": "langchain"}),
])
docs = vector_store.similarity_search("What is Couchbase?")

API Reference: CouchbaseQueryVectorStore

Document loader

See a usage example.

from langchain_community.document_loaders.couchbase import CouchbaseLoader

connection_string = "couchbase://localhost"  # valid Couchbase connection string
db_username = (
    "Administrator"  # valid database user with read access to the bucket being queried
)
db_password = "Password"  # password for the database user

# query is a valid SQL++ query
query = """
    SELECT h.* FROM `travel-sample`.inventory.hotel h
        WHERE h.country = 'United States'
        LIMIT 1
        """

loader = CouchbaseLoader(
    connection_string,
    db_username,
    db_password,
    query,
)

docs = loader.load()

LLM caches

CouchbaseCache

Use Couchbase as a cache for prompts and responses.

To import this cache:

from langchain_couchbase.cache import CouchbaseCache

To use this cache with your LLMs:

from langchain_core.globals import set_llm_cache

cluster = couchbase_cluster_connection_object

set_llm_cache(
    CouchbaseCache(
        cluster=cluster,
        bucket_name=BUCKET_NAME,
        scope_name=SCOPE_NAME,
        collection_name=COLLECTION_NAME,
    )
)

API Reference: CouchbaseCache

CouchbaseSemanticCache

Semantic caching allows users to retrieve cached prompts based on the semantic similarity between the user input and previously cached inputs. Under the hood it uses Couchbase as both a cache and a vectorstore. The CouchbaseSemanticCache needs a Search Index defined to work. Please look at the usage example on how to set up the index.

To import this cache:

from langchain_couchbase.cache import CouchbaseSemanticCache

To use this cache with your LLMs:

from langchain_core.globals import set_llm_cache

# use any embedding provider...
from langchain_openai.Embeddings import OpenAIEmbeddings

embeddings = OpenAIEmbeddings()
cluster = couchbase_cluster_connection_object

set_llm_cache(
    CouchbaseSemanticCache(
        cluster=cluster,
        embedding = embeddings,
        bucket_name="my_bucket",
        scope_name="_default",
        collection_name="_default",
        index_name="my_search_index",
    )
)

API Reference: CouchbaseSemanticCache

---

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.