ClickHouse

Statuspartial
Readswith icebergS3, one table at a time; not through the catalog
Writesno
Iceberg v3not tested
Geometry, geographynot tested
Last verified2026-09-28 (ClickHouse 25.8 LTS, 26.9)

ClickHouse reads a LakehouseBox table today with its icebergS3 table function: you give it the table's storage path and the catalog's read-only key pair, and it reads the Iceberg table there, one table per call, without going through the catalog. ClickHouse's own Iceberg catalog database engine (DataLakeCatalog) connects to our catalog and lists the tables, but cannot read them yet (below). There is no writing recipe.

Before you start

  • A ClickHouse server. The runs on this page used the clickhouse/clickhouse-server images 25.8.33.6 (LTS) and 26.9.4.3.
  • The catalog's read-only key pair: lhbox connect --engine clickhouse always prints that one, whatever access you hold.

Connect

lhbox connect --catalog <catalog> --engine clickhouse --show-secrets

prints the icebergS3 statement with your catalog's storage location and read-only key pair filled in (******** for the secret without --show-secrets); replace <namespace>/<table>. Asking for --write is refused (engine_read_only). The statement, and the catalog database engine that does not work yet:

-- Reads through the catalog fail today (see below); this reads a table directly with the READ-ONLY catalog key:
SELECT count(*) FROM icebergS3('https://s3.lakehousebox.com/<handle>--<catalog>/<namespace>/<table>/', '<ro_client_id>', '<ro_client_secret>');

-- The catalog database lists tables but its reads fail (ClickHouse 25.8 LTS and 26.9):
SET allow_experimental_database_iceberg = 1;
CREATE DATABASE <catalog_name>
ENGINE = DataLakeCatalog('https://catalog.lakehousebox.com', '<client_id>', '<client_secret>')
SETTINGS catalog_type = 'rest',
         warehouse = 's3://<handle>--<catalog>/',
         catalog_credential = '<client_id>:<client_secret>',
         oauth_server_uri = 'https://catalog.lakehousebox.com/v1/oauth/tokens',
         storage_endpoint = 'https://s3.lakehousebox.com/<handle>--<catalog>';
SHOW TABLES FROM <catalog_name>;
SELECT count(*) FROM <catalog_name>.`<namespace>.<table>`;   -- fails: 403 on a doubled key (below)

Reading

Verified 2026-09-28 with ClickHouse 25.8.33.6 and 26.9.4.3, on a format-version 2 table written by PyIceberg 0.12 and appended to by Trino 483 (6 rows):

SELECT count(*), sum(pop_k) FROM icebergS3('https://s3.lakehousebox.com/<bucket>/demo/cities/', '<ro key id>', '<ro secret>');
SELECT name FROM icebergS3(...) WHERE country = 'DE' ORDER BY name;

Both versions answered 6 10865, then Berlin and Nuremberg: the same rows Trino and Polars read.

Because icebergS3 reads from storage with a static key, it does not ask the catalog for anything: the key reads every table of the catalog until it is rotated (lhbox catalog rotate <catalog>, after which every recipe of that catalog needs fetching again).

Writing

None: the recipe carries the read-only key pair, and no write from ClickHouse has been tried against the service. Write with DuckDB, PyIceberg, Spark, Trino or Polars.

Known limitations

As measured on 2026-09-28 with ClickHouse 25.8.33.6 and 26.9.4.3:

  • Reads through the catalog fail. With allow_experimental_database_iceberg, the DataLakeCatalog database engine connects and SHOW TABLES lists the tables, but every query on them fails with Failed to get object info … HTTP response code: 403. ClickHouse builds the object key from the table path and then the full metadata location again (…/demo/cities/<bucket>/demo/cities/metadata/v3.metadata.json), whatever storage_endpoint says, path-style or virtual-hosted. The catalog answers the standard location and metadata-location; the doubling is in ClickHouse. Not reported upstream yet.
  • One table per statement, by its storage path.
  • Format version 3 and geometry were not tested.
Using ClickHouse with LakehouseBox and found something missing, wrong or out of date here? Write to hello@lakehousebox.com: what you ran, the version, and what happened. Product names and logos are trademarks of their owners; their use here does not imply endorsement.