Skip to main content
ClickHouse supports integration with multiple catalogs (Unity, Glue, Polaris, etc.). This guide will walk you through the steps to query your Iceberg tables in Lakehouse runtime catalog aka BigLake Metastore via ClickHouse.
As this feature is beta, you will need to enable it using: SET allow_database_iceberg = 1;

Prerequisites

Before creating a connection from ClickHouse to Lakehouse runtime catalog (BigLake Metastore), ensure you have:
  • A Google Cloud project with Lakehouse runtime catalog enabled
  • Credentials, one of:
    • A service account key: a JSON key file of a service account that has access to the catalog and to the GCS bucket, created via Google Cloud Console. This is the recommended option for servers, because it does not depend on a user session.
    • Application Default credentials (Oauth client ID and client secret) for an application, created via Google Cloud Console, and a refresh token obtained by completing the OAuth flow with the appropriate scopes (e.g. https://www.googleapis.com/auth/bigquery and storage scope for GCS)
  • A warehouse path: a GCS bucket (and optional prefix) where your tables are stored, e.g. gs://your-bucket or gs://your-bucket/prefix

Creating a connection between Lakehouse runtime catalog and ClickHouse

With the OAuth credentials in place, create a database in ClickHouse that uses the DataLakeCatalog database engine:
To authenticate with a service account key instead, pass the content of the JSON key file in google_service_account_key and the project in google_project_id. ClickHouse signs a JWT with the key, exchanges it for an access token, and renews it automatically. The same token is used to read the data files from GCS. The key is masked in SHOW CREATE DATABASE and in the logs.
google_service_account_key and the google_adc_* settings are mutually exclusive. Neither can be combined with the disk setting, because a table on a disk reads its data files with the credentials of the disk rather than with the credentials of the catalog.

Querying Lakehouse runtime catalog tables using ClickHouse

Once the connection is created, you can query tables registered in the Lakehouse runtime catalog.
Example output:
Backticks requiredBackticks are required because ClickHouse doesn’t support more than one namespace.
To inspect the table definition:

Loading data from Lakehouse into ClickHouse

To load data from a Lakehouse runtime catalog table into a local ClickHouse table for faster repeated queries, create a MergeTree table and insert from the catalog:
After the initial load, query clickhouse_table for lower latency. Re-run the INSERT INTO ... SELECT to refresh data from BigLake when needed.