> ## 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.

# REST catalog

> 本指南将逐步介绍如何使用 ClickHouse 和 REST Catalog 查询您的数据。

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

<Note>
  与 REST Catalog 的集成仅适用于 Iceberg 表。
  此集成同时支持 AWS S3 和其他云存储提供商。
</Note>

ClickHouse 支持与多个目录 (Unity、Glue、REST、Polaris 等) 集成。本指南将带你了解如何使用 ClickHouse 和 [REST Catalog](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml/) 规范查询数据。

REST Catalog 是 Iceberg 目录的标准化 API 规范，受到多种平台支持，包括：

* **本地开发环境** (使用 docker-compose 配置)
* **托管服务**，如 Tabular.io
* **自托管** REST Catalog 实现

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

<div id="local-development-setup">
  ## 本地开发环境设置
</div>

对于本地开发和测试，可使用容器化的 REST catalog 配置。这种方式非常适合用于学习、原型设计和开发环境。

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

1. **Docker 和 Docker Compose**：确保已安装 Docker，且 Docker 正在运行
2. **示例环境**：你可以使用各种 `docker-compose` 配置 (见下方的替代 Docker 镜像)

<div id="setting-up-local-rest-catalog">
  ### 设置本地 REST Catalog
</div>

你可以使用各种容器化的 REST catalog 实现，例如 **[Databricks docker-spark-iceberg](https://github.com/databricks/docker-spark-iceberg/blob/main/docker-compose.yml?ref=blog.min.io)**。它通过 docker-compose 提供完整的 Spark + Iceberg + REST catalog 环境，因此非常适合测试 Iceberg 集成。

\*\*步骤 1：\*\*创建一个新文件夹用于运行该示例，然后根据 [Databricks docker-spark-iceberg](https://github.com/databricks/docker-spark-iceberg/blob/main/docker-compose.yml?ref=blog.min.io) 中的配置创建文件 `docker-compose.yml`。

\*\*步骤 2：\*\*接下来，创建文件 `docker-compose.override.yml`，并将以下 ClickHouse 容器配置写入其中：

```yaml theme={null}
version: '3.8'

services:
  clickhouse:
    image: clickhouse/clickhouse-server:25.5.6
    container_name: clickhouse
    user: '0:0'  # 确保 root 权限
    ports:
      - "8123:8123"
      - "9002:9000"
    volumes:
      - ./clickhouse:/var/lib/clickhouse
      - ./clickhouse/data_import:/var/lib/clickhouse/data_import  # 挂载数据集文件夹
    networks:
      - iceberg_net
    environment:
      - CLICKHOUSE_DB=default
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_DO_NOT_CHOWN=1
      - CLICKHOUSE_PASSWORD=
```

**步骤 3：** 运行以下命令以启动这些服务：

```bash theme={null}
docker compose up
```

\*\*第 4 步：\*\*等待所有服务准备就绪。你可以查看日志：

```bash theme={null}
docker-compose logs -f
```

<Note>
  REST catalog 的配置要求先将样本数据加载到 Iceberg 表中。在尝试通过 ClickHouse 查询这些表之前，请确保 Spark 环境已创建并填充这些表。表是否可用取决于具体的 docker-compose 配置以及样本数据加载脚本。
</Note>

<div id="connecting-to-local-rest-catalog">
  ### 连接到本地 REST Catalog
</div>

连接到您的 ClickHouse 容器：

```bash theme={null}
docker exec -it clickhouse clickhouse-client
```

然后创建指向 REST catalog 的数据库连接：

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

CREATE DATABASE demo
ENGINE = DataLakeCatalog('http://rest:8181/v1', 'admin', 'password')
SETTINGS 
    catalog_type = 'rest', 
    storage_endpoint = 'http://minio:9000/lakehouse', 
    warehouse = 'demo'
```

<div id="querying-rest-catalog-tables-using-clickhouse">
  ## 使用 ClickHouse 查询 REST catalog 中的表
</div>

现在连接已建立，你可以开始通过 REST catalog 进行查询。例如：

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

SHOW TABLES;
```

如果你的环境中包含示例数据 (例如 taxi 数据集) ，你应该会看到如下表：

```response theme={null}
┌─name──────────┐
│ default.taxis │
└───────────────┘
```

<Note>
  如果你没有看到任何表，通常意味着：

  1. Spark 环境尚未创建示例表
  2. REST catalog 服务尚未完成初始化
  3. 示例数据加载过程尚未完成

  你可以查看 Spark 日志，了解表的创建进度：

  ```bash theme={null}
  docker-compose logs spark
  ```
</Note>

如要查询表 (如果有) ：

```sql theme={null}
SELECT count(*) FROM `default.taxis`;
```

```response theme={null}
┌─count()─┐
│ 2171187 │
└─────────┘
```

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

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

要查看该表的 DDL：

```sql theme={null}
SHOW CREATE TABLE `default.taxis`;
```

```response theme={null}
┌─statement─────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE demo.`default.taxis`                                                             │
│ (                                                                                             │
│     `VendorID` Nullable(Int64),                                                               │
│     `tpep_pickup_datetime` Nullable(DateTime64(6)),                                           │
│     `tpep_dropoff_datetime` Nullable(DateTime64(6)),                                          │
│     `passenger_count` Nullable(Float64),                                                      │
│     `trip_distance` Nullable(Float64),                                                        │
│     `RatecodeID` Nullable(Float64),                                                           │
│     `store_and_fwd_flag` Nullable(String),                                                    │
│     `PULocationID` Nullable(Int64),                                                           │
│     `DOLocationID` Nullable(Int64),                                                           │
│     `payment_type` Nullable(Int64),                                                           │
│     `fare_amount` Nullable(Float64),                                                          │
│     `extra` Nullable(Float64),                                                                │
│     `mta_tax` Nullable(Float64),                                                              │
│     `tip_amount` Nullable(Float64),                                                           │
│     `tolls_amount` Nullable(Float64),                                                         │
│     `improvement_surcharge` Nullable(Float64),                                                │
│     `total_amount` Nullable(Float64),                                                         │
│     `congestion_surcharge` Nullable(Float64),                                                 │
│     `airport_fee` Nullable(Float64)                                                           │
│ )                                                                                             │
│ ENGINE = Iceberg('http://minio:9000/lakehouse/warehouse/default/taxis/', 'admin', '[HIDDEN]') │
└───────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="loading-data-from-your-data-lake-into-clickhouse">
  ## 将数据从数据湖加载到 ClickHouse
</div>

如果您需要将 REST catalog 中的数据加载到 ClickHouse，请先创建一个本地 ClickHouse 表：

```sql theme={null}
CREATE TABLE taxis
(
    `VendorID` Int64,
    `tpep_pickup_datetime` DateTime64(6),
    `tpep_dropoff_datetime` DateTime64(6),
    `passenger_count` Float64,
    `trip_distance` Float64,
    `RatecodeID` Float64,
    `store_and_fwd_flag` String,
    `PULocationID` Int64,
    `DOLocationID` Int64,
    `payment_type` Int64,
    `fare_amount` Float64,
    `extra` Float64,
    `mta_tax` Float64,
    `tip_amount` Float64,
    `tolls_amount` Float64,
    `improvement_surcharge` Float64,
    `total_amount` Float64,
    `congestion_surcharge` Float64,
    `airport_fee` Float64
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(tpep_pickup_datetime)
ORDER BY (VendorID, tpep_pickup_datetime, PULocationID, DOLocationID);
```

接着，通过 `INSERT INTO SELECT` 从您的 REST catalog 表加载数据：

```sql theme={null}
INSERT INTO taxis 
SELECT * FROM demo.`default.taxis`;
```