> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Couchbase Vector Database

> Use Couchbase as a vector database for your Knowledge Base.

## Setup

### Local Setup (Docker)

Run Couchbase locally using Docker:

```shell theme={null}
docker run -d --name couchbase-server \
  -p 8091-8096:8091-8096 \
  -p 11210:11210 \
  -e COUCHBASE_ADMINISTRATOR_USERNAME=Administrator \
  -e COUCHBASE_ADMINISTRATOR_PASSWORD=password \
  couchbase:latest
```

1. Access the Couchbase UI at: [http://localhost:8091](http://localhost:8091)
2. Login with username: `Administrator` and password: `password`
3. Create a bucket named `recipe_bucket`, a scope `recipe_scope`, and a collection `recipes`

### Managed Setup (Capella)

For a managed cluster, use [Couchbase Capella](https://cloud.couchbase.com/):

* Follow Capella's UI to create a database, bucket, scope, and collection

### Environment Variables

Set up your environment variables:

```shell theme={null}
export COUCHBASE_USER="Administrator"
export COUCHBASE_PASSWORD="password"
export COUCHBASE_CONNECTION_STRING="couchbase://localhost"
export OPENAI_API_KEY=xxx
```

For Capella, set `COUCHBASE_CONNECTION_STRING` to your Capella connection string.

### Install Dependencies

```shell theme={null}
uv pip install -U couchbase pypdf openai agno
```

## Example

```python agent_with_knowledge.py theme={null}
import os
import time
from agno.agent import Agent
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.couchbase import CouchbaseSearch
from couchbase.options import ClusterOptions, KnownConfigProfiles
from couchbase.auth import PasswordAuthenticator

# Couchbase connection settings
username = os.getenv("COUCHBASE_USER")
password = os.getenv("COUCHBASE_PASSWORD")
connection_string = os.getenv("COUCHBASE_CONNECTION_STRING")

# Create cluster options with authentication
auth = PasswordAuthenticator(username, password)
cluster_options = ClusterOptions(auth)
cluster_options.apply_profile(KnownConfigProfiles.WanDevelopment)

knowledge_base = Knowledge(
    vector_db=CouchbaseSearch(
        bucket_name="recipe_bucket",
        scope_name="recipe_scope",
        collection_name="recipes",
        couchbase_connection_string=connection_string,
        cluster_options=cluster_options,
        search_index="vector_search_fts_index",
        embedder=OpenAIEmbedder(
            id="text-embedding-3-large",
            dimensions=3072,
            api_key=os.getenv("OPENAI_API_KEY")
        ),
        wait_until_index_ready=60,
    ),
)

# Load the knowledge base
knowledge_base.insert(
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"
)

# Wait for the vector index to sync with KV
time.sleep(20)

# Create and use the agent
agent = Agent(knowledge=knowledge_base)
agent.print_response("How to make Thai curry?", markdown=True)
```

Passing `search_index` as a string requires an FTS index with that name to already exist on the collection. To define and create the index in code, pass a `SearchIndex` object instead. See [Couchbase usage](https://agno-v2.mintlify.site/knowledge/vector-stores/couchbase/usage/couchbase-db.md).

> **Async Support ⚡**
>
> Couchbase also supports asynchronous operations, enabling concurrency and leading to better performance.
>
> ```python async_couchbase.py theme={null}
> import asyncio
> import os
> import time
> from agno.agent import Agent
> from agno.knowledge.embedder.openai import OpenAIEmbedder
> from agno.knowledge.knowledge import Knowledge
> from agno.vectordb.couchbase import CouchbaseSearch
> from couchbase.options import ClusterOptions, KnownConfigProfiles
> from couchbase.auth import PasswordAuthenticator
>
> # Couchbase connection settings
> username = os.getenv("COUCHBASE_USER")
> password = os.getenv("COUCHBASE_PASSWORD")
> connection_string = os.getenv("COUCHBASE_CONNECTION_STRING")
>
> # Create cluster options with authentication
> auth = PasswordAuthenticator(username, password)
> cluster_options = ClusterOptions(auth)
> cluster_options.apply_profile(KnownConfigProfiles.WanDevelopment)
>
> knowledge_base = Knowledge(
>     vector_db=CouchbaseSearch(
>         bucket_name="recipe_bucket",
>         scope_name="recipe_scope",
>         collection_name="recipes",
>         couchbase_connection_string=connection_string,
>         cluster_options=cluster_options,
>         search_index="vector_search_fts_index",
>         embedder=OpenAIEmbedder(
>             id="text-embedding-3-large",
>             dimensions=3072,
>             api_key=os.getenv("OPENAI_API_KEY")
>         ),
>         wait_until_index_ready=60,
>     ),
> )
>
> # Create and use the agent
> agent = Agent(knowledge=knowledge_base)
>
> async def run_agent():
>     await knowledge_base.ainsert(
>       url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
>     )
>     time.sleep(5)  # Wait for the vector index to sync with KV
>     await agent.aprint_response("How to make Thai curry?", markdown=True)
>
> if __name__ == "__main__":
>     asyncio.run(run_agent())
> ```
>
> > [!TIP]
> >
> > Use `ainsert()` and `aprint_response()` methods with `asyncio.run()` for non-blocking operations in high-throughput applications.

## Key Configuration Notes

### Connection Profiles

Use `KnownConfigProfiles.WanDevelopment` for both local and cloud deployments to handle network latency and timeouts appropriately.

## Couchbase Params

<Snippet file="vectordb_couchbase_params.mdx" />


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.