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.

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.

Quick Start

1. Simple Usage

   pip install clickhouse-connect praisonai
   export PRAISONAI_KNOWLEDGE_STORE=clickhouse
   export CLICKHOUSE_HOST=localhost
   export CLICKHOUSE_PORT=8123
   

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Analyst",
       instructions="Answer from docs",
       knowledge=["docs/"],
   )
   agent.start("What are our key metrics?")
   
2. With Configuration

   Create the store directly for full control:

   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)
   

---

How It Works

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

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

Use ClickHouse for knowledge, not conversations

Store embeddings and retrieval in ClickHouse; keep conversation history in PostgreSQL, MySQL, or SQLite.

Batch inserts for throughput

Insert documents in batches of 1000+ rows for better write performance on large corpora.

Partition large tables by time

Use PARTITION BY toYYYYMM(timestamp) when logging retrieval events for analytics.

Set secure=True in production

Enable TLS and authentication when connecting to remote ClickHouse clusters.

---

Related

Database Persistence

Compare all persistence backends

Persistence Backend Plugins

Register custom storage backends