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

# Lakehouse runtime catalog (BigLake Metastore)

> In this guide, we will walk you through the steps to query your data in Google Cloud Storage using ClickHouse and the Lakehouse runtime Catalog (BigLake Metastore).

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>;
};

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](https://docs.cloud.google.com/biglake/docs/) via ClickHouse.

<Note>
  As this feature is beta, you will need to enable it using:
  `SET allow_database_iceberg = 1;`
</Note>

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

Before creating a connection from ClickHouse to Lakehouse runtime catalog (BigLake Metastore), ensure you have:

* A **Google Cloud project** with Lakehouse runtime catalog enabled
* **Application Default credentials** (Oauth client ID and client secret) for an application, created via [Google Cloud Console](https://docs.cloud.google.com/docs/authentication/provide-credentials-adc)
* 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`

<h2 id="creating-a-connection">
  Creating a connection between Lakehouse runtime catalog and ClickHouse
</h2>

With the OAuth credentials in place, create a database in ClickHouse that uses the [DataLakeCatalog](/reference/engines/database-engines/datalake) database engine:

```sql theme={null}
SET allow_database_iceberg = 1;

CREATE DATABASE lakehouse_runtime_catalog
ENGINE = DataLakeCatalog('https://biglake.googleapis.com/iceberg/v1/restcatalog')
SETTINGS
    catalog_type = 'biglake',
    google_adc_client_id = '<client-id>',
    google_adc_client_secret = '<client-secret>',
    google_adc_refresh_token = '<refresh-token>',
    google_adc_quota_project_id = '<gcp-project-id>',
    warehouse = 'gs://<bucket_name>/<optional-prefix>';
```

<h2 id="querying-lakehouse-runtime-tables">
  Querying Lakehouse runtime catalog tables using ClickHouse
</h2>

Once the connection is created, you can query tables registered in the Lakehouse runtime catalog.

```sql theme={null}
USE LAKEHOUSE_RUNTIME_CATALOG;

SHOW TABLES;
```

Example output:

```response theme={null}
┌─name──────────────────────────────────────┐
│lakehouse_runtime_catalog.my_iceberg_table │   
└───────────────────────────────────────────┘
```

```sql theme={null}
SELECT count(*) FROM `lakehouse_runtime_catalog.my_iceberg_table`;
```

<Info>
  **Backticks required**

  Backticks are required because ClickHouse doesn't support more than one namespace.
</Info>

To inspect the table definition:

```sql theme={null}
SHOW CREATE TABLE `lakehouse_runtime_catalog.my_iceberg_table`;
```

<h2 id="loading-data-into-clickhouse">
  Loading data from Lakehouse into ClickHouse
</h2>

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:

```sql theme={null}
CREATE TABLE clickhouse_table
(
    `id` Int64,
    `event_time` DateTime64(3),
    `user_id` String,
    `payload` String
)
ENGINE = MergeTree
ORDER BY (event_time, id);

INSERT INTO local_events
SELECT * FROM lakehouse_runtime_catalog.`icebench.my_iceberg_table`;
```

After the initial load, query `clickhouse_table` for lower latency. Re-run the `INSERT INTO ... SELECT` to refresh data from BigLake when needed.