Agent skill · data analytics · jeremylongshore
clickhouse-reference-architecture
Production reference architecture for ClickHouse-backed applications — project layout, data flow, multi-tenant patterns, and operational topology. Use when designing a new ClickHouse system, reviewing an existing analytics architecture, or establishing standards for ClickHouse integrations. Trigger with "clickhouse architecture", "clickhouse project structure", "clickhouse design", "clickhouse multi-tenant", "clickhouse reference".
Why this skill is useful
Provides specific architectural patterns and multi-tenant strategies for ClickHouse that the AI wouldn't reliably generate on its own.
What it needs
Requires grep, read installed locally. About 4k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
ClickHouse Reference Architecture Overview Production-grade architecture for ClickHouse analytics platforms covering project layout, data flow, multi-tenancy, and operational patterns. Work through the five steps below to get the high-level shape, then drill into the linked reference files for the full DDL, client code, and tenancy trade-offs. Prerequisites Understanding of ClickHouse fundamentals — table engines, ORDER BY sort keys, and partitioning. A TypeScript/Node.js project (the client examples use @clickhouse/client). When reviewing an existing codebase, Grep for createClient( to locate the current client module and Read the SQL files under clickhouse/schemas/. Instructions Step 1: Project Structure Keep SQL DDL as the source of truth under clickhouse/schemas/, named query functions under clickhouse/queries/, and ingestion/API/jobs in sibling modules. Step 2: Data Flow Architecture Data moves in one direction: sources → a batching ingestion layer → ClickHouse (raw MergeTree → materialized views → aggregate tables) → an API that reads only the aggregate tables → dashboards. Step 3: Schema Design (3-Layer Pattern) Three layers — raw append-only events, hourly aggregation, and a daily rollup for dashboards — with materialized views auto-populating each aggregate on INSERT. The essential raw-table skeleton: Full three-layer DDL, materialized views, and the rationale: see references/schema-design.md. Step 4: Multi-Tenant Patterns Choose an isolation strategy. Default to Approach A (shared table, tenantid first in ORDER BY) — it scales to 10K+ tenants: Database-per-tenant (strict isolation) and row-level security (RBAC) alternatives with trade-offs: see references/multi-tenant-patterns.md. Step 5: Client Module Use a singleton @clickhouse/client instance and parameterized queries that read from the aggregate tables. Full client + query-function code: references/client-module.md. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/clickhouse-reference-architecture