ClickHouse Sink

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

[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:

tell setup-db --host localhost:8123 --database tell

This creates the database, all 7 tables, and the default user. See ClickHouse Setup for details.

Getting Started

Tracking

Pipeline

Analytics

Installing

ClickHouse Sink

Configuration

Tables

Performance

Arrow HTTP transport

Setup

​Configuration

​Tables

​Performance

​Arrow HTTP transport

​Setup

Configuration

Tables

Performance

Arrow HTTP transport

Setup