Examples and recipes for building with ClickHouse, from your first SQL query to applications, data pipelines, observability, and AI agents. Explore a product below, or jump to the repository contents.
Try ClickHouse Cloud · Documentation · SQL playground · Learn ClickHouse with Mark
ClickHouse is an open-source, column-oriented SQL database for fast analytics on large datasets. It powers real-time dashboards, reporting, observability, and applications that need to query data as it arrives.
You can use the engine as a managed Cloud service, run your own server, embed it in Python with chDB, or query files from the command line with clickhouse-local. The wider ClickHouse ecosystem brings together Postgres for transactions, ClickStack for observability, and LibreChat for working with data through AI agents.
For a managed service, sign up for ClickHouse Cloud and follow the Cloud quickstart. To run ClickHouse yourself, follow the installation guide. You can also explore public datasets in the SQL playground or start with the local file examples below.
To run an example, clone this repository:
git clone https://github.com/ClickHouse/examples.git
cd examplesOpen the example's README for its prerequisites, setup, and commands. Each example documents the tools and services it needs.
Use ClickHouse to ingest, transform, and query analytical data with SQL. ClickHouse Cloud runs it as a fully managed service on AWS, Google Cloud, and Azure, handling infrastructure, scaling, and upgrades so you can focus on your application.
- Real-time stock data with Massive: Stream trades and quotes into ClickHouse and explore them in a React dashboard.
- Report results and run history: Build a TypeScript application that provisions ClickHouse Cloud, stores report results, and queries across completed runs.
- Docker Compose recipes: Run ClickHouse locally alongside Grafana, Dagster, Redpanda, SeaweedFS, and RustFS, or explore replicated clusters.
- Learn ClickHouse with Mark: Work through SQL techniques, JSON, aggregations, geospatial queries, and more, with companion videos.
ClickHouse ships official client libraries for C# / .NET, Java (Client V2 and JDBC), Rust, Go, C++, Python, and Node.js. The language clients example writes one small program in every one of them against a ClickHouse Cloud service provisioned with clickhousectl: connect over TLS, create a table, batch insert typed rows, bind query parameters, stream results, map aggregates into typed records, and handle a server error.
- Language client tour: Pick your language, run it, and compare it side by side with the others. Every implementation prints the same output.
clickhousectl is the CLI for managing local ClickHouse installations and ClickHouse Cloud. Install and switch local versions, start development servers, provision and scale Cloud services, run queries, and manage Postgres and ClickPipes. JSON output and installable agent skills make it useful for scripts and AI coding agents. See the CLI repository for source code and installation options.
- Provision a database for a TypeScript application: Use
clickhousectlto create the Cloud service for a report-history application. - Investigate and resolve a latency SLA breach: Give an agent access to
clickhousectlto inspect a live service and apply a scaling change.
Postgres managed by ClickHouse is a managed PostgreSQL service in ClickHouse Cloud for transactional applications, with native integration into ClickHouse for analytics. Use Postgres for application records and transactions, then replicate changes to ClickHouse for reporting and aggregation.
ClickPipes provides managed ingestion into ClickHouse Cloud, including Postgres change data capture (CDC), streaming sources, and object storage.
- Postgres-to-ClickHouse data modeling: Replicate a tiny fixture from PostgreSQL to ClickHouse with PeerDB, then verify inserts, updates, and deletes. Follow the separate managed Postgres and ClickPipes walkthrough for ClickHouse Cloud; a larger Stack Overflow import is optional.
ClickStack is an open-source observability stack that combines ClickHouse, OpenTelemetry, and the HyperDX UI. Use it to investigate application behavior and correlate telemetry in one place. Run it yourself or use Managed ClickStack in ClickHouse Cloud.
- Instrument an OpenAI client: Send OpenTelemetry traces to ClickStack and inspect LLM calls.
- Observe LibreChat and the ClickHouse MCP server: Trace an AI chat application as it queries ClickHouse.
LibreChat is an open-source chat interface for working with different LLM providers and building AI agents. Connect it to the ClickHouse MCP server so agents can explore datasets and answer questions using SQL. The Agentic Data Stack brings together LibreChat, ClickHouse, MCP, and Langfuse for LLM tracing and evaluation.
- LibreChat with the ClickHouse MCP server: Run a chat interface connected to the public ClickHouse playground.
- More MCP integrations: Connect ClickHouse to other chat interfaces and agent frameworks.
chDB embeds the ClickHouse engine in your Python process. Query files and DataFrames with SQL, or use its pandas-compatible DataStore API, without running a database server. It's useful for notebooks, data exploration, scripts, and embedded analytics.
- Read and analyze Parquet in Python: Filter and aggregate a Parquet dataset with the DataStore API.
- Flatten nested JSON: Turn nested records into data you can analyze.
- Build a Streamlit app with chDB: Explore energy usage in an interactive application.
clickhouse-local runs the ClickHouse engine from the command line. Query local or remote files, join datasets, and convert formats without starting a server or loading data into a running database. It uses the same clickhouse binary, invoked as clickhouse local.
- Start with clickhouse-local: Try queries, schema inspection, joins, and remote data access.
- Query CSV files or Parquet files: Run SQL directly over your files.
- Convert CSV to Parquet: Explore format conversion, compression, and inferred types.
Browse all local analytics examples for more file formats, conversions, and Python recipes.
| Directory | What you'll find |
|---|---|
| applications | Application examples, including report results and run history with ClickHouse Cloud. |
| ai | AI agents, MCP integrations, and workflows using clickhousectl. |
| blog-examples | Code and resources accompanying the ClickHouse Blog. |
| clickstack | Observability examples for LLM applications and MCP servers. |
| docker-compose-recipes | Local deployments, integrations, and cluster configurations. |
| ethereum | Blockchain schemas, batch and streaming ingestion, and queries. |
| language-clients | The same client tour in C#, Java, Rust, Go, C++, Python, and Node.js against ClickHouse Cloud. |
| LearnClickHouseWithMark | Code accompanying Mark Needham's ClickHouse video tutorials. |
| local-analytics | File queries and conversions with clickhouse-local and chDB. |
| postgresql-clickhouse-data-modeling | PostgreSQL replication and data modeling with PeerDB and ClickHouse. |
Anyone is welcome to contribute to this repository by submitting a PR!
New contributors will need to sign the CLA when submitting their first PR.
If there's an example you'd love to see, feel free to open an issue to request it (or submit a PR!).
- All examples should be self-contained, including documentation to use the example without relying on external resources (i.e., include a full README.md in the repo and do not just link to an external article).
- Directories and files should use kebab-case.
The blog-examples directory contains resources that support the ClickHouse Blog. If you are writing a blog post and want to store resources in this repo, add a new directory here and follow the same standards and conventions as other examples in this repo.
ClickHouse, the ClickHouse logo, and related marks are trademarks or registered trademarks of ClickHouse, Inc. or its affiliates.