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/bigqueryand storage scope for GCS)
- A warehouse path: a GCS bucket (and optional prefix) where your tables are stored, e.g.
gs://your-bucketorgs://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: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.Backticks requiredBackticks are required because ClickHouse doesn’t support more than one namespace.
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:clickhouse_table for lower latency. Re-run the INSERT INTO ... SELECT to refresh data from BigLake when needed.