Skip to main content
Skip to main content
Edit this page
Beta feature. Learn more.

Connect a data catalog in ClickHouse Cloud

References

Data catalog integrations in ClickHouse Cloud are in public beta.

Connect ClickHouse Cloud to your data catalogs to access your open table format tables. You can set up connections in the Data sources UI. For setup via SQL, use the [DataLakeCatalog](/engines/database-engines/datalakecatalog) database engine in your SQL editor of choice.

Once connected, catalog tables show up in the SQL console under the database name you choose. You can query them with standard ClickHouse SQL, join them with MergeTree tables, and use them as sources for materialized views.

Prerequisites​

Before you connect a catalog, confirm the following:

  • Service permissions. You need the control-plane:service:manage permission to access the Data sources page and add catalogs.
  • Running service. If the service is idle, wake it from the Data sources page or the service overview before connecting or viewing linked catalogs.
  • Catalog credentials. Gather connection details for your catalog type before opening the flyout. Each catalog uses different fields and authentication — see Add your catalog connection below.

Connect your catalog​

Make sure you're logged in to your ClickHouse Cloud account.

  1. In the console, open the ClickHouse Cloud service you want to connect.
  2. Select Data sources in the left navigation.
  3. Click + Add catalog if you haven't set up any data sources. Click Add data source > Add data lake catalog.
  4. In the Connect your data catalog flyout, select your catalog from the Select catalog dropdown. If the catalog supports multiple open table formats, choose the format in Open table format.

Add your catalog connection​

  1. Fill in the connection parameters and Database name for your catalog type. The Database name is the ClickHouse database that exposes your catalog tables in the SQL console. Select your catalog below for field-level guidance and prerequisites.

AWS Glue Catalog exposes Iceberg tables registered in the Glue Data Catalog.

Before you connect, confirm:

  • ClickHouse version on 25.12+.
  • Iceberg tables are registered in AWS Glue Data Catalog in your target region.
  • For access key authentication, you have an IAM user access key with permissions to read Glue metadata and the underlying S3 objects.
  • For IAM role authentication (26.2+), you have an IAM role that trusts your ClickHouse service role. Include the service role ARN from Settings → Network security information in the role trust policy. See Accessing Iceberg data securely for IAM policy examples.

In the flyout, enter your AWS Region (e.g. us-west-2), then choose an authentication method:

Access key authentication

  1. Select AWS Access Key as the Authentication method.
  2. Enter your Access Key ID and Secret Access Key.
  3. Enter a Database name for the ClickHouse database that exposes your Glue tables.

IAM role authentication (26.2+)

  1. Select AWS IAM Role as the Authentication method.
  2. Copy the Service role ID (IAM) from the flyout panel and add it to your IAM role trust policy.
  3. Enter your AWS Role ARN and an optional AWS Role Session Name.
  4. Enter a Database name for the ClickHouse database that exposes your Glue tables.
Note

Glue supports multiple table formats, but ClickHouse only reads Iceberg tables from Glue.

Query Unity Catalog managed Iceberg tables using OAuth client credentials from a Databricks service principal. See the Unity Catalog guide for full setup.

Before you connect, confirm:

In the flyout:

  1. Enter your Databricks Workspace URL (e.g. dbc-1234567a-cbde).
  2. Enter the Databricks catalog name to connect (e.g. icebench).
  3. Enter the OAuth Client ID and Client secret for your service principal.
  4. Enter a Database name for the ClickHouse database that exposes your Unity Catalog tables.

Query Unity Catalog Delta Lake tables using a Databricks Personal Access Token (PAT). See the Unity Catalog guide for full setup.

Before you connect, confirm:

In the flyout:

  1. Enter your Databricks Workspace URL (e.g. dbc-1234567a-cbde.azuredatabricks.net).
  2. Enter the Databricks catalog name to connect.
  3. Enter your Personal Access Token.
  4. Enter a Database name for the ClickHouse database that exposes your Delta tables.
Note

Iceberg and Delta use different authentication in the UI. This will require two separate ClickHouse databases to access both types of tables.

Connect to any catalog that implements the Iceberg REST Catalog specification. See the REST catalog guide for full setup.

Before you connect, confirm:

  • ClickHouse version on 25.12+.
  • Your REST catalog endpoint is reachable from ClickHouse Cloud.
  • You have OAuth client credentials or a bearer token, depending on your catalog configuration.
  • You have an S3 or compatible Storage Endpoint URI for table data (e.g. s3://my-bucket/path).

In the flyout:

  1. Enter the Catalog URL (e.g. https://catalog.example.com/v1).
  2. Enter the Warehouse or catalog namespace (e.g. demo).
  3. Enter the Storage Endpoint URI prefix for table storage.
  4. Select an Authentication method: OAuth Client Credentials or Bearer Token, then enter the matching credentials.
  5. Enter a Database name for the ClickHouse database that exposes your REST catalog tables.

Query Iceberg tables in Microsoft Fabric OneLake using Azure AD application credentials. See the Fabric OneLake guide for full setup.

Before you connect, confirm:

  • ClickHouse version on 25.12+.
  • Iceberg tables exist in a Fabric workspace.
  • You have an Entra ID (Azure AD) application with client ID and secret.
  • You have your tenant ID, workspace ID, and a data item ID. Use your Lakehouse ID from the Lakehouse page URL. See Microsoft OneLake prerequisites for help locating these values.

In the flyout:

  1. Enter your Fabric Workspace ID.
  2. Enter the Data Item ID — use your Lakehouse GUID. Warehouse IDs are not supported.
  3. Enter your Entra ID Tenant ID, Application (client) ID, and Client secret.
  4. Enter a Database name for the ClickHouse database that exposes your OneLake tables.

Connect to a Snowflake Open Catalog (Polaris) deployment for Iceberg tables. See the Polaris catalog guide for full setup.

Before you connect, confirm:

  • ClickHouse version on 26.2+.
  • You have a Polaris catalog with OAuth client credentials.
  • You have a storage endpoint URI for Iceberg table data (e.g. s3://company-iceberg-prod/warehouse/).

In the flyout:

  1. Enter the Catalog Account Identifier (e.g. ab12345.snowflakecomputing.com).
  2. Enter the Catalog Name (e.g. snowflake_open_catalog).
  3. Enter the OAuth Client ID and Client Secret.
  4. Enter the Storage Endpoint URI prefix for table storage.
  5. Enter a Database name for the ClickHouse database that exposes your Polaris tables.

Connect to Google Cloud BigLake Metastore (aka Lakehouse runtime catalog) for Iceberg tables in GCS. See the BigLake Metastore guide for full setup.

Before you connect, confirm:

  • ClickHouse version on 26.2+.
  • You have a BigLake Metastore instance with Iceberg tables in GCS.
  • You have Google Application Default Credentials (ADC) with client ID, client secret, refresh token, and quota project ID.

In the flyout:

  1. Enter your Google ADC Client ID, Client Secret, Refresh Token, and Quota Project ID.

  2. Enter the Cloud Storage Bucket URI for table data (e.g. gs://biglake-public-nyc-taxi-iceberg).

  3. Enter a Database name for the ClickHouse database that exposes your BigLake tables.

  4. Click Add catalog. ClickHouse validates the connection and credentials when saving.

  5. On success, a confirmation toast appears with a View in SQL console link. Your catalog is listed in the Linked catalogs table with its connection status and table count.

From the Actions menu on a linked catalog row, you can drop the catalog connection. Dropping removes the ClickHouse database binding — it does not delete data in your external catalog.

Query your data​

  1. On the Data sources page, find your catalog in the Linked catalogs table and click View tables.
  1. ClickHouse opens the SQL console with your catalog database selected and lists the available tables.
  1. Write a query in the SQL editor and click Run.

Wrap the full table name in backticks:

SELECT * FROM `identity_profiles.identity_profiles_iceberg`

See also:

Troubleshooting​

  • If you don't see your tables in the SQL console: verify credentials, network access, and table types in catalog. Make sure the tables you expect to see are in supported file and table formats.
  • Open up a support ticket if you aren't able to debug.