> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse Persistence

> Columnar vector store for large-scale knowledge retrieval and analytics

ClickHouse stores knowledge embeddings for fast vector search at scale — ideal for large document collections and analytics workloads.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import os
from praisonaiagents import Agent

os.environ["PRAISONAI_KNOWLEDGE_STORE"] = "clickhouse"
os.environ["CLICKHOUSE_HOST"] = "localhost"

agent = Agent(
    name="Analyst",
    instructions="Answer from our knowledge base",
    knowledge=["docs/"],
)
agent.start("Summarise our refund policy")
```

The user asks from your knowledge base; ClickHouse vector search retrieves relevant chunks at scale.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Agent[🤖 Agent] --> Knowledge[📚 Knowledge]
    Knowledge --> CH[📊 ClickHouse]
    CH --> Vectors[🔢 Vector Search]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef data fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef storage fill:#10B981,stroke:#7C90A0,color:#fff

    class Agent agent
    class Knowledge data
    class CH,Vectors storage
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install clickhouse-connect praisonai
    export PRAISONAI_KNOWLEDGE_STORE=clickhouse
    export CLICKHOUSE_HOST=localhost
    export CLICKHOUSE_PORT=8123
    ```

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Analyst",
        instructions="Answer from docs",
        knowledge=["docs/"],
    )
    agent.start("What are our key metrics?")
    ```
  </Step>

  <Step title="With Configuration">
    Create the store directly for full control:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai.persistence import create_knowledge_store

    store = create_knowledge_store(
        "clickhouse",
        host="localhost",
        port=8123,
        username="default",
        password="",
        database="praisonai",
        secure=False,
    )
    store.create_collection("docs", dimension=1536)
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Agent
    participant RAG as Knowledge / RAG
    participant CH as ClickHouseKnowledgeStore

    Agent->>RAG: Query with knowledge sources
    RAG->>CH: Vector search (cosine distance)
    CH-->>RAG: Top-k documents
    RAG-->>Agent: Retrieved context
```

ClickHouse is a **knowledge store** (vector search), not a primary conversation backend. Pair it with SQLite or PostgreSQL for chat history via `db()`.

***

## Configuration Options

| Option     | Type   | Default       | Description                        |
| ---------- | ------ | ------------- | ---------------------------------- |
| `host`     | `str`  | `"localhost"` | ClickHouse server hostname         |
| `port`     | `int`  | `8123`        | HTTP port                          |
| `username` | `str`  | `"default"`   | Database username                  |
| `password` | `str`  | `""`          | Database password                  |
| `database` | `str`  | `"praisonai"` | Database name (created if missing) |
| `secure`   | `bool` | `False`       | Use HTTPS connection               |

Environment variables: `CLICKHOUSE_HOST`, `CLICKHOUSE_PORT`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`.

***

## Docker Setup

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
docker run -d \
  --name praisonai-clickhouse \
  --ulimit nofile=262144:262144 \
  -p 8123:8123 \
  -p 9000:9000 \
  clickhouse/clickhouse-server:latest

curl "http://localhost:8123/?query=SELECT%20version()"
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use ClickHouse for knowledge, not conversations">
    Store embeddings and retrieval in ClickHouse; keep conversation history in PostgreSQL, MySQL, or SQLite.
  </Accordion>

  <Accordion title="Batch inserts for throughput">
    Insert documents in batches of 1000+ rows for better write performance on large corpora.
  </Accordion>

  <Accordion title="Partition large tables by time">
    Use `PARTITION BY toYYYYMM(timestamp)` when logging retrieval events for analytics.
  </Accordion>

  <Accordion title="Set secure=True in production">
    Enable TLS and authentication when connecting to remote ClickHouse clusters.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Database Persistence" icon="database" href="/docs/features/persistence">
    Compare all persistence backends
  </Card>

  <Card title="Persistence Backend Plugins" icon="puzzle-piece" href="/docs/features/persistence-backend-plugins">
    Register custom storage backends
  </Card>
</CardGroup>