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

# ClickHouse Sink

> Production analytics sink with event-type routing, per-table batching, and concurrent flushes.

The ClickHouse sink is the recommended production destination. It routes events to the appropriate tables based on event type, batches inserts per table, and flushes all tables concurrently.

## Configuration

```toml theme={null}
[sinks.clickhouse]
host = "localhost:8123"
database = "tell"
username = "default"
password = ""
```

| Field            | Default     | Notes                              |
| ---------------- | ----------- | ---------------------------------- |
| `host`           | —           | ClickHouse HTTP address (required) |
| `database`       | `"default"` | Database name                      |
| `username`       | `"default"` | Authentication username            |
| `password`       | `""`        | Authentication password            |
| `batch_size`     | 1000        | Rows per table before flush        |
| `flush_interval` | `"5s"`      | Time-based flush interval          |

## Tables

The sink writes to 7 tables following the Tell v1.1 schema:

| Table          | Populated by                                  |
| -------------- | --------------------------------------------- |
| `events_v1`    | TRACK events from SDKs                        |
| `users_v1`     | IDENTIFY events (core identity)               |
| `user_devices` | IDENTIFY events (device links)                |
| `user_traits`  | IDENTIFY events (key-value traits)            |
| `context_v1`   | CONTEXT events (device/location)              |
| `logs_v1`      | Log entries from syslog and SDKs              |
| `snapshots_v1` | Integration snapshots (GitHub, Shopify, etc.) |

IDENTIFY events fan out to three tables in parallel: `users_v1`, `user_devices`, and `user_traits`.

## Performance

* **Per-table batching** — each table accumulates rows independently, so a burst of logs doesn't delay event flushes
* **Concurrent flush** — all tables are flushed in parallel using tokio tasks
* **LZ4 compression** — enabled by default for wire transport
* **Retry with backoff** — 3 attempts with exponential backoff (100ms base, 10s max) on transient failures

## Arrow HTTP transport

Two implementations are available:

* **Row-based** (default) — uses the clickhouse crate with row structs
* **Arrow-based** — sends Arrow-format HTTP inserts for higher throughput

The Arrow transport is selected automatically when available and provides better performance at high event volumes.

## Setup

Tell can create the ClickHouse schema automatically:

```bash theme={null}
tell setup-db --host localhost:8123 --database tell
```

This creates the database, all 7 tables, and the default user. See [ClickHouse Setup](/running-tell/clickhouse) for details.