> ## Documentation Index
> Fetch the complete documentation index at: https://phidatainc-studio-tools-doc.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 couchbase
```

## 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
from couchbase.management.search import SearchIndex

# 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,
        overwrite=True
    ),
)

# 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)
```

<Card title="Async Support ⚡">
  <div className="mt-2">
    <p>
      Couchbase also supports asynchronous operations, enabling concurrency and leading to better performance.
    </p>

    ```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
    from couchbase.management.search import SearchIndex

    # 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,
            overwrite=True
        ),
    )

    # 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 className="mt-4">
      Use <code>aload()</code> and <code>aprint\_response()</code> methods with <code>asyncio.run()</code> for non-blocking operations in high-throughput applications.
    </Tip>
  </div>
</Card>

## 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" />