ClickHouse and Apache Iceberg integration

How ClickHouse reads Iceberg tables your other engines already share

If your Iceberg tables are written by Spark, Trino or Flink and you want fast analytics from ClickHouse, the core answer is that a self-hosted ClickHouse cluster can read Iceberg tables directly and can write to them with limits. Two entry points do this work: the iceberg table function, which gives direct access to an existing Iceberg table for a single query, and the Iceberg table engine, which creates a persistent ClickHouse table over that data. Apache Iceberg is licensed under the Apache License 2.0, so the table format itself carries no license cost for the engines around it.

The Iceberg table engine is a dispatcher. Based on the disk setting, it resolves to IcebergS3, IcebergAzure or IcebergLocal, so the choice of storage backend is made in configuration rather than in the table definition. The practical step is to confirm which object store holds the table files, which credentials the ClickHouse servers will use to reach it, and whether the table metadata location is readable from every replica that will serve queries. Because the same Iceberg table is shared with other engines, the reader should also agree with those teams on which snapshot retention and compaction jobs run, since ClickHouse reads whatever snapshot is current when a query starts.

The ClickHouse documentation warns that the Iceberg table engine may have limitations because ClickHouse was not originally designed for tables whose schema changes outside of ClickHouse. Plan a test on a copy of the production table before relying on it. Run representative queries, confirm that schema changes made by Spark, Trino or Flink appear as expected, and confirm that the ClickHouse version you plan to run supports the Iceberg features your tables use. The ClickHouse Iceberg table engine documentation lists the current schema and write limits, and those should be checked against your release before the design is fixed.

Choosing the iceberg table function or the Iceberg table engine

The iceberg table function is the documented choice when you need direct access to an Iceberg table that another team or engine already maintains. You point a query at the table location and read it without creating anything in ClickHouse. Nothing persists on the cluster, so the table definition stays with the owner of the Iceberg metadata, and ClickHouse only reads what the current metadata describes at query time.

No persistent object: the function call is the whole definition, so there is no table in the ClickHouse catalog to drift out of sync.
Ownership stays upstream: schema, partitioning and snapshots are controlled by the writing engine such as Spark, Trino or Flink.
Ad hoc and exploratory use: it suits one-off investigations, validation of a pipeline output or quick comparisons against a MergeTree copy.
Repeated queries repeat setup: every query carries the location and credentials, so dashboards and scheduled jobs are harder to govern.
Credentials in query text: you must decide how storage and catalog access is supplied so secrets do not end up in logs or saved queries.

Before you rely on this path for production reporting, confirm the exact argument list and storage options for your ClickHouse version in the documentation.",

What you need in place before connecting ClickHouse to Iceberg

Before a single Iceberg table is queried, four things must be settled: the ClickHouse version, the storage the table files live on, the catalog that tracks them, and the table definitions themselves. Each card below is a decision or check that is cheap to make now and expensive to discover during a failed integration.

Confirm the ClickHouse version line

Pick a version from a line that still receives security updates. The security policy lists the currently supported versions, and anything outside that list is unsupported. Choose between the latest stable release and an LTS line based on how often your team can afford to upgrade. The production FAQ recommends stable releases for most production use and advises reading the changelog before upgrading, because minor backward-incompatible changes can occur. Confirm the exact build you will run before you write any Iceberg DDL, since the table engine behavior you test should match the server you deploy.

Storage location and access credentials

Decide where the Iceberg data files and metadata live: S3 or S3-compatible storage, Azure, or a local path on the ClickHouse hosts. Each option maps to a different engine path (IcebergS3, IcebergAzure or IcebergLocal). Create a dedicated, least-privilege credential for ClickHouse that can read the table prefix and, if you plan to write, the specific paths it needs. Store the secret in a managed secret store or named collection rather than in query text, and confirm that the ClickHouse hosts can reach the storage endpoint through your network controls.

A reachable catalog endpoint

Most production Iceberg setups resolve table metadata through a catalog such as AWS Glue, Unity Catalog, Polaris or a generic REST catalog. ClickHouse's data catalog guides cover several of these. Confirm the catalog endpoint, the authentication method it expects, and whether the ClickHouse network segment can reach it. Test the connection from the same hosts that will run queries, not from a workstation, because firewall rules and DNS often differ between the two. Ask the catalog owner which principal ClickHouse will use and which namespaces it may list.

Current schema and partition layout

Record the current schema, column types and partition spec of every Iceberg table you intend to read or write, along with the snapshot history your team relies on. ClickHouse documents limits for tables whose schema changes outside ClickHouse, and separate limits for creating, evolving and writing Iceberg schemas. Partition transforms and nested types are the areas most likely to differ between engines, so compare what ClickHouse reports with the metadata your Spark or Trino jobs use. Save this inventory with the integration design so later schema changes trigger a documented review.

A pre-production environment with real data

Build a non-production ClickHouse cluster that connects to a copy of the Iceberg tables, catalog and storage, or to a representative subset. The production FAQ recommends a pre-production environment with representative data and queries for upgrades and new integrations. Use it to measure query behavior, check schema reads against your real metadata and rehearse any write path. Ask the catalog and storage owners whether a sandbox namespace or bucket can be provided, because a test that reads an empty or simplified table proves very little.

Ownership and change control

Name an owner for the ClickHouse side of the integration and an owner for each Iceberg table, because schema changes made by a Spark job or a catalog administrator can break queries without any change on the ClickHouse side. Agree how upgrades of ClickHouse, the catalog and the storage service are sequenced, and who approves a change to a table definition. Write these agreements down before go-live, since the first incident is the usual moment teams discover that nobody owned the boundary between the two systems.

Configuring the Iceberg connection in sequence

This sequence takes a self-hosted ClickHouse cluster from no Iceberg access to a verified read path, and only then to a write path, with a check at each step so problems surface before any data moves.

Confirm the storage disk and credentials
Before any catalog or table is defined, the platform team confirms where the Iceberg data files live (S3, Azure or local storage) and which credentials ClickHouse will use to reach them. Store those credentials in the server configuration or named collections under your secrets process, not in table DDL that is copied into shared documentation. Make sure the ClickHouse host can reach the storage endpoint from its network segment, and that the principal has read access to the table location. The step is done when a plain file listing or a simple object read succeeds from a ClickHouse node using the same credentials, and the access is confirmed by your security team against your least-privilege policy.
Connect the catalog
Next, the team connects ClickHouse to the catalog that tracks the Iceberg table metadata. ClickHouse's catalog guide covers AWS Glue, Polaris, Unity Catalog, REST and other catalogs, so pick the one your organization already operates and follow its documented settings for endpoint, authentication and namespace. Confirm the exact catalog type and its options against the guide for the ClickHouse version you run, since catalog support changes between releases. The step is done when the catalog lists the expected namespaces and tables from a ClickHouse session, and the listing matches what the owning data team shows in its own tooling.
Choose the table function or table engine
The team decides how ClickHouse will address the table. The iceberg table function gives direct, per-query access to an existing Iceberg table, which suits exploration and one-off reads. The Iceberg table engine creates a persistent ClickHouse table that dispatches to IcebergS3, IcebergAzure or IcebergLocal based on the disk setting, which suits repeated access or a standalone Iceberg table that ClickHouse creates. Document the choice and the reason, because the engine carries schema limits that the table function does not impose in the same way. The step is done when the chosen definition is written in version control and reviewed by the data owner.
Create or point the table definition
Here the engineer creates the table definition, either by pointing ClickHouse at an existing Iceberg table or by creating a new standalone one, depending on the decision in the previous step. Check the column types that ClickHouse maps from the Iceberg schema, paying attention to nested types, decimals and timestamps, since mismatches show up later as wrong results rather than errors. ClickHouse's documentation warns that the engine may have limitations when a schema changes outside ClickHouse, so record the current schema version. The step is done when DESCRIBE on the table shows column names and types that match the Iceberg schema the data owner confirms.
Run a read against a known snapshot
Before running broad queries, the engineer reads a specific, known snapshot of the table. Pick a snapshot identifier or timestamp that the data owner has recorded, then query it and compare the result with the same snapshot read from the owning engine, such as Spark, Trino or the catalog's own tools. Using a fixed snapshot removes ambiguity about which data changes you are comparing. Keep the query small enough to finish predictably on a shared cluster. The step is done when row counts and a small set of aggregates match between the two engines for the same snapshot, and the result is saved with the snapshot identifier for later regression runs.
Compare row counts with the source engine
After the snapshot read matches, the team runs a broader comparison against the source of truth for the current table state. Compare total row counts, counts per partition or date range, and a few key aggregates such as sums of numeric measures and distinct counts on identifiers. Repeat the comparison after a recent write to the table, because a stale metadata cache or a catalog refresh delay can make ClickHouse show an older state. The step is done when the counts agree within the tolerance the data owner accepts, and any gap is traced to a named cause, such as a partition filter, a timezone difference or a snapshot that was not yet visible.
Test any write path separately
Writes are a separate decision and should be tested in isolation from reads. Confirm which write operations your ClickHouse version and the Iceberg table engine support, and read the limits for creating, evolving and writing Iceberg schemas in the ClickHouse documentation before you rely on them. Run the write against a non-production copy of the table, then verify with the reading engine that the new snapshot appears, that row counts change as expected and that time travel to the previous snapshot still returns the earlier state. The step is done when the write has been validated on a copy and the rollback to the prior snapshot is proven, with the results signed off by the data owner.

Mapping catalogs, namespaces and storage credentials

The first decision in this integration is which catalog holds the Iceberg metadata, because that choice determines how ClickHouse finds tables and which connection settings you need. ClickHouse's data catalog guide covers AWS Glue, Lakekeeper, Nessie, Fabric OneLake, Polaris, Snowflake Horizon, REST, Unity Catalog and BigLake Metastore. Your team must confirm which of these, if any, your platform already runs, and then follow the matching section of the ClickHouse catalog guide rather than assuming a generic REST setup will work. Confirm the catalog version and endpoint with the team that operates it, since catalog compatibility is a property of the specific product and release, not of the Iceberg format alone.

Namespaces and table names are where most mismatches appear. Iceberg organizes tables into namespaces, and the names the catalog exposes may not match the database and table names you expect in ClickHouse. Before building any table, list the namespaces and tables the catalog returns, then decide how each one maps to a ClickHouse database and table. Keep names lowercase and free of characters that need quoting, and record the mapping in your runbook so that a later rename in the catalog does not silently point a ClickHouse table at the wrong data. If several Iceberg namespaces contain tables with the same name, use separate ClickHouse databases or explicit table names rather than relying on defaults.

Identity needs the same care as naming. ClickHouse needs two sets of credentials: one to reach the catalog and one to read or write the data files in S3, Azure or local storage. Use a dedicated service identity for each, scoped to the namespaces and buckets this cluster needs, and avoid the broad credentials used by interactive engineers. Store these secrets in your secrets manager, not in table definitions shared between users, and confirm with the catalog and storage owners whether the catalog vends short-lived storage credentials or expects the cluster to hold long-lived keys. Restrict the ClickHouse users that can create Iceberg tables, since a new table definition can point the cluster at storage it should not reach, and follow your access control model for who may query each database.

Mapping Iceberg types, snapshots and partitions to ClickHouse

This table compares the core Apache Iceberg concepts (schema, partition spec, snapshots, time travel and rollback) with how ClickHouse exposes them through the iceberg table function and the Iceberg table engine. Read each row as a planning question: what the Iceberg side promises, what ClickHouse can reliably do with it, and where the documented limits apply. Confirm every type mapping against the ClickHouse documentation for your exact version before you build on it.

Iceberg concept	What Iceberg provides	How ClickHouse exposes it and what to plan for
Schema	Columns with stable IDs, supporting evolution without rewriting table files	ClickHouse reads the schema from table metadata, but the docs warn it was not designed for externally changing schemas. Pin the schema your queries depend on and test reads after each upstream change.
Schema evolution	Add, rename, drop and reorder columns as metadata changes	The Iceberg table engine documents separate limits for evolving schemas. Confirm which evolution operations your version reads correctly before relying on them in production.
Schema creation and writes	Engines create tables and write rows through the catalog	The docs list separate limits for creating and writing Iceberg schemas. Check which column types can be created or written from ClickHouse, since reading support does not imply write support.
Type mapping	Iceberg primitive, nested and decimal types with defined semantics	Map each Iceberg type to a ClickHouse type against the current documentation for your version. Verify nullability, decimal precision and timestamp handling with sample rows from your own data.
Partition spec	Hidden partitioning, where partition values are derived from column transforms	Partition pruning depends on the engine and version. Check with EXPLAIN on representative queries that filters on source columns skip the expected files.
Snapshot	An exact, immutable table state identified by snapshot ID	Ask which snapshot the iceberg function or engine reads by default and whether a specific snapshot can be selected in your version.
Time travel	Querying a historical snapshot or timestamp	Confirm the ClickHouse setting or syntax for historical reads in your version. Do not assume Athena or Trino syntax carries over.
Rollback	Resetting the table pointer to an earlier snapshot	Rollback is performed by the catalog or writing engine, not by ClickHouse reads. Plan rollback procedures in the owning engine and test them on a copy of the table.

Securing storage access, catalog credentials and write permissions

An Iceberg integration gives ClickHouse read and write paths into storage and catalogs that other engines also use, so a mistake in credentials or permissions reaches more than one system. The cards below cover the controls that limit that reach: storage and catalog credentials, the default user, analyst accounts, transport security, query hygiene and external authentication. Confirm each control against the catalog and storage you actually run.

Scope storage credentials to the table path

Give the ClickHouse service identity only the object storage permissions it needs, limited to the bucket prefixes that hold the Iceberg tables it reads or writes. Write access should be granted per table location, not per bucket, so a compromised cluster cannot overwrite unrelated data lake folders. Check whether your catalog vends short-lived credentials or expects long-lived keys, and ask your storage team how rotation will be handled.

Separate catalog and storage identities

The catalog and the storage layer each authenticate the cluster, and the two grants should not be tied together by default. Decide which identity the catalog uses to commit metadata changes and which identity reads data files, then grant each only the operations it needs. Confirm with your catalog product whether it can enforce this split, since the supported authentication methods differ by catalog type.

Restrict the default user

ClickHouse's access control documentation recommends restricting the default user, which starts with all permissions. Before connecting any catalog, create named administrative users through the SQL-driven workflow, then remove the default user's network access or reduce its grants. Confirm that your deployment tooling and monitoring do not depend on the default account.

Read-only roles for analysts

Analysts querying Iceberg tables need SELECT grants on the specific tables or databases exposed to them, and no rights to create or alter Iceberg tables. Combine roles with row policies where a team should only see its own partitions or tenants. Settings profiles and quotas can cap how much a query can read, which matters when a lake table is large and cost follows scanned data.

Keep write permissions with a small group

Writes to Iceberg tables change shared metadata that Spark, Trino or other engines may read at the same time. Restrict INSERT and table creation rights to a small, named set of pipeline users, and review who can change schemas, since schema changes carry their own limits in ClickHouse. Document which pipeline account owns each table so an unexpected write has a clear owner.

Encrypt traffic to the catalog

Catalog endpoints carry credentials and table metadata, so the connection should use TLS. Confirm which certificate validation settings your ClickHouse version and catalog client support, and whether a private certificate authority must be trusted by the cluster. Ask the catalog vendor to confirm the supported TLS versions and whether mutual TLS is available.

Keep credentials out of query text

Credentials written directly into CREATE TABLE or SELECT statements end up in query logs, system tables and shared SQL history. Store them in named collections or server configuration, restrict who can read them, and mask sensitive values in logs. Review query logging settings before enabling broad audit access, since the logs themselves become sensitive.

Use external authenticators where they fit

ClickHouse can delegate user authentication to LDAP directories, Kerberos, SSL X.509 certificates, an HTTP authenticator or JWT, as described in its external authenticators documentation. Choose the method that matches how your analysts already sign in, and map groups to ClickHouse roles so access changes happen in the directory. Confirm which of these methods apply to your catalog, since catalog authentication and ClickHouse user authentication are separate decisions.

Which Iceberg writes ClickHouse can safely perform

The first decision is whether ClickHouse should write to an Iceberg table at all. The ClickHouse Iceberg table engine documentation warns that the engine may have limitations because ClickHouse was not originally designed for tables with externally changing schemas, and it lists separate limits for creating, evolving and writing Iceberg schemas. Read those limits against your own plan before building a pipeline. Do not infer write support from the fact that the iceberg table function or the Iceberg table engine can read a table. Confirm, for each operation you need (create, add or change columns, insert), the exact statement and the Iceberg schema types it supports in the ClickHouse version you will run, and record the answer in your design notes.

Test every write path on a copy of the table before any production data moves. Use a copy in the same catalog and storage type as production, with representative schemas, partition layouts and file sizes, and run the same engine versions your readers use. Check the results from ClickHouse and from each other engine that reads the table, such as Spark, Trino or Athena, including row counts, column types, nulls and time travel queries against snapshots. Keep a restore path for the copy and for the source: the backup documentation notes that replication alone does not protect against human error or corruption, and a backup that has never been restore tested will probably not restore when needed.

Coordinate writers before enabling ClickHouse writes. Iceberg is designed so that several engines can work with the same tables at the same time, but that does not remove the need for an owner per table. Name which engine may create snapshots, which may change the schema, and who approves a change to either. Agree how a schema change made in one engine will reach ClickHouse, since the Iceberg table engine's schema limits apply to it. Finally, check that your catalog, such as AWS Glue, Polaris, Unity or a REST catalog, is configured to coordinate commits for every writer. Confirm the catalog-specific behavior with the catalog vendor or your platform team, because the supplied documentation does not describe it in detail.

Common failures when ClickHouse reads Iceberg tables

This table maps the failures teams most often hit when self-hosted ClickHouse reads Iceberg tables to their likely causes and first fixes. Use it as a triage starting point, then confirm version-specific behavior against the ClickHouse release you run, because the Iceberg engine's documented limits change between releases.

Failure	Likely cause	Fix to try first
Query fails after an external engine changed the schema	ClickHouse docs warn the Iceberg engine was not designed for tables whose schema changes outside ClickHouse	Refresh the table definition, confirm the new column set in the Iceberg metadata, and recreate the ClickHouse table if the change is not supported
Catalog authentication errors on connect	Wrong catalog endpoint, expired token or credential, or a catalog type that does not match the connector settings	Verify the catalog URL, credential and auth mode against the catalog guide for your catalog, then test with a minimal read
Table not found or empty results from the wrong location	Storage path, bucket or container set incorrectly, or the disk setting points at the wrong storage type (S3, Azure or local)	Check the table path and the disk setting so the engine dispatches to IcebergS3, IcebergAzure or IcebergLocal as intended
Query returns data from an older snapshot	Cached or stale table metadata after an external writer committed new snapshots	Reload or recreate the table so ClickHouse reads the current metadata pointer, then compare row counts with the source engine
Column or query fails on a data type	The Iceberg type has no matching ClickHouse mapping in the version you run	Check the type mapping for that version, cast or exclude the column in a view, and confirm the fix on a pre-production copy
Writes rejected or schema changes refused	The docs list separate limits for creating, evolving and writing Iceberg schemas	Confirm which operation is limited in your release, make schema changes in the external engine, and keep ClickHouse on read-only access where writes are not validated

Questions teams ask before connecting ClickHouse to Iceberg

Can our team connect ClickHouse to Iceberg tables without outside help?

Yes, a team with ClickHouse and Iceberg experience can run a first connection on its own, and the ClickHouse Iceberg table engine documentation and catalog guides cover the basic steps. The harder part is the design work around it: which catalog holds the tables, how schema changes will reach ClickHouse, and whether writes are needed at all. ClickHouse warns that the Iceberg table engine may have limitations because it was not originally designed for tables with externally changing schemas. Teams without someone who has tested those limits against their own tables often choose a fixed-scope review first, then build. Confirm internally who will own the catalog and the test plan before deciding.

What makes an Iceberg integration take more effort?

Four factors shape the effort most. The first is catalog count, since each catalog type (for example AWS Glue, Unity Catalog, Polaris or a REST catalog) has its own connection settings and access model. The second is schema churn, because tables that change often need a tested plan for how ClickHouse sees new columns. The third is write needs, since writes carry more limits than reads and must be verified against your Iceberg version and ClickHouse version. The fourth is storage type, because S3, Azure and local storage use different engine variants and credential paths. Each additional catalog, fast-changing schema or write path adds test cases.

What does the work need from our side?

Plan to provide read access to the catalog, credentials or role assignments for the storage location, and a small set of representative Iceberg tables with their schema history. You will also need a test window on a non-production ClickHouse cluster, because the ClickHouse production guidance recommends a pre-production environment with representative data and queries. Someone from your data platform team should be available to confirm which tables are authoritative and which queries matter. Ask for a written list of these inputs as part of the scope so that delays are visible early.

Should we use the iceberg table function or the Iceberg table engine?

Use the iceberg table function when you need direct, ad hoc access to an existing Iceberg table without creating a persistent object in ClickHouse. Use the Iceberg table engine when you want a persistent ClickHouse table that stays defined across sessions, or when you are creating a new standalone Iceberg table. The engine dispatches to IcebergS3, IcebergAzure or IcebergLocal based on the disk setting, so the storage choice is part of the decision. For tables whose schema changes outside ClickHouse, test both paths against a real schema change before committing, because the documented schema limits apply to the engine.

How is the cost structured for a fixed-scope engagement?

A fixed-scope engagement is priced from a written scope that lists the catalogs, storage types, tables, write paths and test cases in play. The cost has one-time parts, such as design, connection build, testing and handover documentation, and may have recurring parts if you later request ongoing support or upgrades as a retainer. The main cost drivers are the ones described above: catalog count, schema churn, write needs and storage type. When requesting a quote, ask for the deliverables, the acceptance tests, what is excluded, what your team must provide, and which items are optional. DeployOpen does not publish a price list, so the quote follows from that written scope.

What limits should we check before planning writes to Iceberg from ClickHouse?

Check three limits before you plan writes. ClickHouse documents separate limits for creating, evolving and writing Iceberg schemas, so confirm each one applies to your ClickHouse version and your Iceberg table definition. Confirm the Iceberg format version and catalog type are supported for the operations you need, since catalog support differs across ClickHouse's data lake guides. Finally, verify that other engines writing to the same tables, such as Spark or Trino, do not change schemas in ways ClickHouse cannot read. Record the results in a test report so that a later ClickHouse or Iceberg upgrade can be checked against the same cases.

Do we need outside auditors to sign off on this integration?

Not for the integration itself, but your compliance program may still require evidence. DeployOpen prepares systems, controls and evidence for compliance assessments, while independent auditors and certification bodies issue any audit reports or attestations. For Iceberg, useful evidence includes the catalog access model, the storage credentials scope, the query role definitions in ClickHouse, and the test results for reads and writes. Ask your assessor early which of these they expect, so the evidence can be collected during the build rather than reconstructed afterward.

How DeployOpen scopes and delivers this integration

DeployOpen works on self-hosted ClickHouse inside your own infrastructure, so the Iceberg work runs against your cluster, your storage account or bucket, and your catalog service. Each engagement starts with a written scope that names the Iceberg tables in play, the choice between the iceberg table function and the Iceberg table engine, the catalog type (for example AWS Glue, Polaris, Unity Catalog or a REST catalog), the storage backend and the users and roles that will query or write. Deliverables and timelines are agreed in writing before work begins, and the quote follows from that scope rather than from a published price list. Ask the partner to show which catalog and storage combinations they have tested against your ClickHouse version, and to state which of those tests were run in a pre-production environment with representative data.

Because the ClickHouse Iceberg documentation warns about schema limits, a meaningful part of the engagement is the test plan: a pre-production run of your real schema changes, write paths and time travel queries, with the outcome recorded as evidence. DeployOpen prepares that evidence, along with configuration, access controls and runbooks, so your team and any external assessor can review it. DeployOpen does not issue audit reports, attestations or certifications; independent auditors and certification bodies make those determinations. Ongoing support, version upgrades (including checking each release changelog against your Iceberg usage) and periodic re-testing can be covered by a retainer, which is also a sensible choice when your catalog or storage platform changes after go-live.