> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-67bc7bf8.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> How to connect a data catalog for Iceberg or Delta tables in ClickHouse Cloud via the Data sources UI.

# Connect a data catalog in ClickHouse Cloud

export const galaxyOnClick = eventName => () => {
  try {
    if (typeof window !== "undefined" && window.galaxy && eventName) {
      window.galaxy.track(eventName, {
        interaction: "click"
      });
    }
  } catch (e) {}
};

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <Icon />
                <span>Beta</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                Beta feature. 
                <u>
                    <a href="/docs/beta-and-experimental-features#beta-features">
                        Learn more.
                    </a>
                </u>
            </span>
        </div>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

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.

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-67bc7bf8/Rr-iJdB8JE6ZiXd5/images/cloud/features/data-catalogs-ui.png?fit=max&auto=format&n=Rr-iJdB8JE6ZiXd5&q=85&s=f6756609de037228f793e16a6d1e919c" size="md" alt="ClickHouse Cloud UI with data catalog integrations" width="4944" height="2610" data-path="images/cloud/features/data-catalogs-ui.png" />

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](/engines/table-engines/mergetree-family/mergetree) tables, and use them as sources for [materialized views](/materialized-views).

<h2 id="prerequisites">
  Prerequisites
</h2>

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** or the service settings pages 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](#add-your-catalog-connection) below.

<h2 id="connect-your-catalog">
  Connect your catalog
</h2>

<Steps>
  <Step title="Open the data catalog flyout">
    1. Select **Data sources** in the left navigation.
    2. Click **+ Add catalog** if you haven't set up any data sources. Otherwise, click **Add data source** > **Add data lake catalog**.
    3. 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**.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-67bc7bf8/r3BwMiGgv3zibkVM/images/integrations/data-catalogs/catalog-flyout-select.png?fit=max&auto=format&n=r3BwMiGgv3zibkVM&q=85&s=931d7e56e31c3b2c31828d18f9d61af4" alt="Connect your data catalog flyout with Select catalog dropdown showing AWS Glue, BigLake Metastore, Microsoft OneLake, Polaris, REST Catalog, and Unity Catalog" size="lg" width="4490" height="2842" data-path="images/integrations/data-catalogs/catalog-flyout-select.png" />
  </Step>

  <Step title="Add your catalog connection">
    <a id="add-your-catalog-connection" />

    Select your catalog below for guidance and prerequisites. Then fill in the connection parameters, along with a **Database name** — the ClickHouse database that exposes your catalog tables in the SQL console.

    <Tabs>
      <Tab title="AWS Glue">
        [AWS Glue Catalog](/use-cases/data-lake/glue-catalog) exposes [Iceberg](/engines/table-engines/integrations/iceberg) tables registered in the Glue Data Catalog.

        Before you connect, confirm:

        * ClickHouse version 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](/cloud/data-sources/secure-iceberg) 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.
        </Note>
      </Tab>

      <Tab title="Unity Catalog (Iceberg)">
        Query Unity Catalog managed [Iceberg](/engines/table-engines/integrations/iceberg) tables using OAuth client credentials from a Databricks service principal. See the [Unity Catalog guide](/use-cases/data-lake/unity-catalog#read-iceberg) for full setup.

        Before you connect, confirm:

        * ClickHouse version 25.12+.
        * [Unity Catalog is configured for external data access](https://docs.databricks.com/aws/en/external-access/admin).
        * Databricks [service principal](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) with OAuth client ID and secret. The service principal has `USE CATALOG`, `USE SCHEMA`, `USE EXTERNAL SCHEMA` and `SELECT` privileges on the tables you want to query.

        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.
      </Tab>

      <Tab title="Unity Catalog (Delta)">
        Query Unity Catalog [Delta Lake](/engines/table-engines/integrations/deltalake) tables using a Databricks Personal Access Token (PAT). See the [Unity Catalog guide](/use-cases/data-lake/unity-catalog#read-delta) for full setup.

        Before you connect, confirm:

        * ClickHouse version 25.12+.
        * [Unity Catalog is configured for external data access](https://docs.databricks.com/aws/en/external-access/admin).
        * Databricks [Personal Access Token](https://docs.databricks.com/aws/en/dev-tools/auth/pat) with at least `EXTERNAL USE SCHEMA`, `USE CATALOG`, `USE SCHEMA`, and `SELECT` on the target tables.

        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.
        </Note>
      </Tab>

      <Tab title="REST catalog">
        Connect to any catalog that implements the [Iceberg REST Catalog](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml) specification. See the [REST catalog guide](/use-cases/data-lake/rest-catalog) for full setup.

        Before you connect, confirm:

        * ClickHouse version 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.
      </Tab>

      <Tab title="Microsoft OneLake">
        Query [Iceberg](/engines/table-engines/integrations/iceberg) tables in Microsoft Fabric OneLake using Azure AD application credentials. See the [Fabric OneLake guide](/use-cases/data-lake/onelake-catalog) for full setup.

        Before you connect, confirm:

        * ClickHouse version 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](https://learn.microsoft.com/en-us/fabric/onelake/table-apis/table-apis-overview#prerequisites) for help locating these values.

        In the flyout:

        1. Enter your Fabric **Workspace ID**.
        2. Enter the **Data Item ID** — use your Lakehouse ID. Warehouse IDs aren't 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.
      </Tab>

      <Tab title="Polaris">
        Connect to a Snowflake Open Catalog (Polaris) deployment for [Iceberg](/engines/table-engines/integrations/iceberg) tables. See the [Polaris catalog guide](/use-cases/data-lake/polaris-catalog) for full setup.

        Before you connect, confirm:

        * ClickHouse version 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.
      </Tab>

      <Tab title="BigLake Metastore">
        Connect to Google Cloud BigLake Metastore (aka Lakehouse runtime catalog) for [Iceberg](/engines/table-engines/integrations/iceberg) tables in GCS. See the [BigLake Metastore guide](/use-cases/data-lake/biglake-catalog) for full setup.

        Before you connect, confirm:

        * ClickHouse version 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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Save the connection">
    <a id="save-connection" />

    After filling in the fields:

    1. Click **Add catalog**. ClickHouse validates the connection and credentials when saving.
    2. 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 catalog's database from ClickHouse — it doesn't delete any data in your external catalog.
  </Step>
</Steps>

<h2 id="query-data">
  Query your data
</h2>

<Steps>
  <Step title="View your catalog tables">
    <a id="view-tables" />

    On the **Data sources** page, find your catalog in the **Linked catalogs** table and click **View tables**.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-67bc7bf8/r3BwMiGgv3zibkVM/images/integrations/data-catalogs/linked-catalogs-table.png?fit=max&auto=format&n=r3BwMiGgv3zibkVM&q=85&s=c95d060b98526d5e755131d253000dd9" alt="Linked catalogs table with View tables action" size="lg" width="3510" height="868" data-path="images/integrations/data-catalogs/linked-catalogs-table.png" />

    ClickHouse opens the SQL console with your catalog database selected and lists the available tables.

    <Note>
      Tables may not appear immediately after you connect a catalog. Depending on the catalog, it can take up to 3 minutes for all tables to be listed.
    </Note>

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-67bc7bf8/r3BwMiGgv3zibkVM/images/integrations/data-catalogs/catalog-tables-browser.png?fit=max&auto=format&n=r3BwMiGgv3zibkVM&q=85&s=a1af305aece791d8a47546c04406f64b" alt="SQL console table browser showing catalog tables" size="lg" width="3560" height="1578" data-path="images/integrations/data-catalogs/catalog-tables-browser.png" />
  </Step>

  <Step title="Run a query">
    <a id="run-a-query" />

    Write a query in the SQL editor and click **Run**. Wrap the full table name in backticks:

    ```sql theme={null}
    SELECT * FROM `identity_profiles.identity_profiles_iceberg`
    ```

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-67bc7bf8/r3BwMiGgv3zibkVM/images/integrations/data-catalogs/catalog-sql-query.png?fit=max&auto=format&n=r3BwMiGgv3zibkVM&q=85&s=cf018eadb8698120c1da8591dccd80ad" alt="SQL query with results using backticks for dotted table name" size="lg" width="2810" height="1172" data-path="images/integrations/data-catalogs/catalog-sql-query.png" />
  </Step>
</Steps>

<h2 id="troubleshooting">
  Troubleshooting
</h2>

* If you don't see your tables in the SQL console: verify credentials, network access, and table types in the catalog. Make sure the tables you expect to see are in supported file and table formats.

<h2 id="see-also">
  See also
</h2>

* [Accelerating analytics on lakehouse data](/use-cases/data-lake/getting-started/accelerating-analytics) — load catalog tables into MergeTree for repeated queries
* [Accessing Iceberg data securely](/cloud/data-sources/secure-iceberg) — IAM role setup for AWS Iceberg and Glue access