> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Lakehouse 运行时目录（BigLake Metastore）

> 本指南将带你逐步了解如何使用 ClickHouse 和 Lakehouse 运行时目录（BigLake Metastore）查询存储在 Google Cloud Storage 中的数据。

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 版功能。 
                <u>
                    <a href="/docs/docs/beta-and-experimental-features#beta-features">
                        了解更多。
                    </a>
                </u>
            </span>
        </div>;
};

<BetaBadge />

ClickHouse 支持与多个目录 (如 Unity、Glue、Polaris 等) 集成。本指南将逐步介绍如何通过 ClickHouse 查询 [Lakehouse 运行时目录 (即 BigLake Metastore) ](https://docs.cloud.google.com/biglake/docs/)中的 Iceberg 表。

<Note>
  由于该功能目前处于 Beta 阶段，你需要使用以下语句启用它：
  `SET allow_database_iceberg = 1;`
</Note>

<div id="prerequisites">
  ## 前置条件
</div>

在创建从 ClickHouse 到 Lakehouse 运行时目录 (BigLake Metastore) 的 connection 之前，请确保你已具备以下条件：

* 一个已启用 Lakehouse 运行时目录的 **Google Cloud 项目**
* 某个应用的 **应用默认凭据** (OAuth client ID 和 client secret) ，通过 [Google Cloud Console](https://docs.cloud.google.com/docs/authentication/provide-credentials-adc) 创建
* 通过完成具有适当作用域的 OAuth 流程获取的 **刷新令牌** (例如 `https://www.googleapis.com/auth/bigquery` 以及适用于 GCS 的存储作用域)
* **仓库** 路径：存储表的 GCS 存储桶 (以及可选前缀) ，例如 `gs://your-bucket` 或 `gs://your-bucket/prefix`

<div id="creating-a-connection">
  ## 在 Lakehouse 运行时目录与 ClickHouse 之间建立连接
</div>

完成 OAuth 凭证配置后，在 ClickHouse 中创建一个使用 [DataLakeCatalog](/docs/zh/reference/engines/database-engines/datalake) 数据库引擎的数据库：

```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>';
```

<div id="querying-lakehouse-runtime-tables">
  ## 使用 ClickHouse 查询 Lakehouse 运行时目录中的表
</div>

创建连接后，您可以查询已注册到 Lakehouse 运行时目录中的表。

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

SHOW TABLES;
```

示例输出：

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

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

<Info>
  **必须使用反引号**

  必须使用反引号，因为 ClickHouse 不支持多个命名空间。
</Info>

要查看表定义：

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

<div id="loading-data-into-clickhouse">
  ## 将 Lakehouse 中的数据加载到 ClickHouse
</div>

要将 Lakehouse 运行时目录表中的数据加载到本地 ClickHouse 表，以加快重复查询的速度，请创建一个 MergeTree 表，并从该目录插入数据：

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

初始加载完成后，查询 `clickhouse_table` 可获得更低的延迟。需要时，可重新运行 `INSERT INTO ... SELECT`，从 BigLake 刷新数据。