How to query Apache Iceberg tables from ClickHouse

ClickHouse can query an Apache Iceberg table sitting in S3 in a fraction of a second – no Spark job, with no ETL step and no need to load the data into ClickHouse’s own storage first. Using the ClickHouse Iceberg table function, you point ClickHouse at the table’s location, it reads the Iceberg metadata, figures out which files it actually needs, and returns rows.

This article focuses on exactly that: how to query Apache Iceberg tables from ClickHouse. If you still need to get events into an Iceberg table on S3, I covered the full Kafka → Kafka Connect → Iceberg pipeline in a separate walkthrough. Here we assume the table already exists and focus on querying Iceberg tables in S3 directly from ClickHouse.

This article describes an example architecture for educational purposes. Actual configurations, performance, and availability depend on customer environment, selected services, and applicable NetApp Instaclustr service terms.

Why query Apache Iceberg tables from ClickHouse instead of loading data first

The traditional pattern is to copy data into your query engine’s own storage before you can analyze it. That means a loading step, a second copy of the data, and a job to keep it in sync.

ClickHouse skips all of that. It’s a columnar OLAP engine built for analytical speed, and ClickHouse apache Iceberg integrations allow direct access to Iceberg tables stored in object storage.  Iceberg’s metadata layer tells ClickHouse which files are relevant before it touches a single byte of data, so it reads only what the query needs. The result is warehouse-style query performance against data that never left S3.

The architectural payoff: S3 stays the single source of truth, and any engine that speaks Iceberg – ClickHouse, Spark, Trino, DuckDB – can query the same table without coordination.

Learn more: Apache Iceberg table format

What you need before you start:

• An Iceberg table already written to S3. If the table was registered in a catalog like AWS Glue then that’s fine. However, the queries in this article point ClickHouse at the S3 path directly, so ClickHouse reads the Iceberg metadata files from S3 without a catalog lookup.
• A running ClickHouse cluster in the same AWS region as your bucket. Same region S3 is reachable from the cluster by default; if your bucket lives in a different region, then you will also need the AWS S3 Region Integration under Integrations -> S3 Region.
• AWS permissions that let ClickHouse read the table.

The path matters here. Glue appends .db to the namespace name, so a table created in the analytics namespace lands at warehouse/analytics.db/user_events/. That’s the path you’ll point ClickHouse at.

Step 1: Grant ClickHouse read access

Querying Iceberg needs a much smaller set of permissions than writing to it. A read engine like ClickHouse just needs to list the bucket and fetch objects. The Iceberg metadata sits in S3 alongside the data, so no catalog calls are involved either.

For query engines reading Iceberg, the role or credentials used for querying need:

• Permission – Purpose
• s3:GetObject – fetch Iceberg metadata files (metadata.json, manifest lists, manifest Avro files) and the underlying Parquet files.
• s3:ListBucket – List files in the warehouse

Then add a bucket policy so ClickHouse can read the data:

Despite the "Principal": "*", this is not a public bucket. The Condition restricts access to a single AWS account – the account that the ClickHouse cluster runs in. if you’re on Bring Your Own Cloud (BYOC), that’s your own AWS account ID. If your cluster runs in Instaclustr’s AWS account, use Instaclustr‘s account ID instead.

Step 2: Query Apache Iceberg tables from ClickHouse with iceberg() table function

Open the ClickHouse Web UI and log in with your icclickhouse credentials. Now point the iceberg() table function at the table’s S3 location:

That returns in well under a second. ClickHouse reads the Iceberg metadata, identifies which files to fetch, and returns results – no ETL, no loading step.

Aggregations work the same way, and this is where columnar storage earns its keep:

Five rows, one per event type, in a fraction of a second. You’re querying data lake files as if they were a warehouse table.

Passing credentials inline works, but repeating them on every query gets old fast. ClickHouse supports named collections – a stored bundle of connection settings you reference by name – so a query becomes FROM iceberg(my_iceberg_creds) instead. See the Instaclustr Open Table Format integration docs for the full setup.

Step 3: Create a persistent Apache Iceberg table for repeated queries

The iceberg() function is perfect for ad-hoc exploration, but typing the full S3 URL every time gets old. For queries you run often, ClickHouse can read Iceberg tables through its IcebergS3 table engine, which lets you give the table a name and query it like any other ClickHouse table.

Same direct-read behavior underneath. ClickHouse still reads from S3 and prunes files using Iceberg metadata, but now the table has a stable name your dashboards and saved queries can reference.

Why it’s this fast

The speed of querying Apache Iceberg tables from ClickHouse isn’t magic; it’s metadata. Iceberg’s manifest files carry per-file statistics – min/max values, null counts, row counts. When ClickHouse runs a query with a WHERE clause, it reads those manifests, compares your predicate against the stats, and skips entire files that can’t contain matching rows. According to Apache Iceberg’s own performance docs, that pruning can deliver up to a 10x improvement on queries against clustered data – without reading a byte of the underlying Parquet files.

So ClickHouse isn’t brute-forcing a scan of your whole bucket. It asks Iceberg which files could possibly matter first, then reads only those. ClickHouse answers the question fast, ensuring Iceberg only has to look in the right place.

Summary

Querying ClickHouse with Apache Iceberg comes down to two things: grant read access (IAM permissions plus a scoped bucket policy), and point ClickHouse at the table with the iceberg() function or the IcebergS3 engine. After that, your data lake behaves like a warehouse – queryable at analytical speed while the data itself never leaves S3.

That’s the real shift: you’re not copying data into a query engine, you’re querying it where it already lives. S3 stays the source of truth, your stack stays portable, and any Iceberg-aware engine can read the same tables.

NetApp Instaclustr provides fully managed ClickHouse and Kafka with 100% open source technologies, no vendor lock-in, and 24×7 expert support. Start a free trial on Instaclustr to query Apache Iceberg on S3 with ClickHouse – no ETL or data duplication required.