How do I give AI agents context about my ClickHouse data?
Bruin runs the whole pipeline against ClickHouse from one project: ingestion, SQL and Python transformations, and quality checks are all assets in the same dependency graph, so bruin run resolves the order and executes them in sequence. Loads use a batched INSERT and incremental assets use ReplacingMergeTree, or an INSERT with a version column. The alternative is assembling an ingestion tool, a transformation framework, and an orchestrator, which works but leaves you owning the glue between them.
Command
bruin runDefined in
SQL + Python + YAML
Works with
ClickHouse + Bruin CLI
What you get
How to do it
- 1
Run bruin init and add a clickhouse connection for ClickHouse.
- 2
Declare an ingestion asset so raw data lands in ClickHouse via a batched INSERT.
- 3
Add a SQL asset that models the raw table, with depends naming its upstream.
- 4
Declare column checks on the keys and amounts that matter.
- 5
Run bruin validate to confirm the graph resolves, then bruin run.
- 6
Schedule it in CI or Bruin Cloud, and switch heavy assets to ReplacingMergeTree, or an INSERT with a version column.
How it works in code
/* @bruin
name: mart.orders
materialization:
type: table
depends: [raw.orders]
columns:
- name: order_id
checks:
- name: unique
@bruin */
SELECT order_id, customer_id, order_total
FROM raw.ordersRun bruin run and Bruin builds the asset on ClickHouse and runs its checks before anything downstream reads it.
Worth knowing
On ClickHouse, many small inserts create many parts and merges will consume the cluster; batch your writes
Other ways to do this
Bruin is not always the right answer. Here is where the alternatives are stronger.
| Option | When it is the better choice |
|---|---|
| Bruin | Build and run a complete ClickHouse pipeline with Bruin: ingest, transform in SQL or Python, and check the output, all from one project. |
| dbt + Fivetran + Airflow | The conventional split. Mature and well documented, but three tools to run and integrate for one ClickHouse pipeline. |
| SQLMesh | Strong on ClickHouse with virtual environments that cut the compute cost of reviewing a change. Transformation only, so you still need ingestion. |
| Native ClickHouse tooling | Staying inside ClickHouse avoids another vendor, at the cost of portability if you ever move warehouse. |
Common questions
How do I build an end-to-end data pipeline on ClickHouse?
Define each stage as an asset in one project and let the framework resolve the order. With Bruin, ingestion, SQL and Python transformations, and quality checks are all assets, and bruin run executes the graph against ClickHouse. Loads use a batched INSERT.
Do I need an orchestrator to run ClickHouse pipelines?
Not for a straightforward pipeline. bruin run resolves dependencies itself, so a CI runner on a schedule is enough. A dedicated orchestrator earns its keep once you need complex retries, backfills, and cross-team scheduling.
What is the cheapest way to run pipelines on ClickHouse?
On ClickHouse the main lever is the ORDER BY key, which determines how much data a query has to read. Incremental models using ReplacingMergeTree, or an INSERT with a version column matter more than which tool you pick.
Related use cases
Build a context layer on Snowflake for AI agents
How do I give AI agents context about my Snowflake data?
AI contextBuild a context layer on BigQuery for AI agents
How do I give AI agents context about my BigQuery data?
AI contextBuild a context layer on Databricks for AI agents
How do I give AI agents context about my Databricks data?
One pipeline, end to end
Open source. Ingestion, SQL and Python transformations, and checks in one graph.