REST カタログ - ClickHouse Documentation

REST カタログとのインテグレーションは、Iceberg テーブルでのみ利用できます。このインテグレーションは、AWS S3 とその他の Cloud ストレージプロバイダーの両方をサポートします。

ClickHouse は複数のカタログ (Unity、Glue、REST、Polaris など) とのインテグレーションをサポートしています。このガイドでは、ClickHouse と REST カタログ仕様を使用してデータをクエリする手順を説明します。 REST カタログは Iceberg カタログ向けの標準化された API 仕様で、以下を含むさまざまなプラットフォームでサポートされています。

ローカル開発環境 (docker-compose 構成を使用)
Tabular.io などのマネージドサービス
セルフホストの REST カタログ実装

この機能はベータであるため、次を使用して有効にする必要があります。 SET allow_database_iceberg = 1;

ローカル開発環境のセットアップ

ローカルでの開発やテストには、コンテナー化された REST カタログ構成を利用できます。この方法は、学習、プロトタイピング、開発用途に適しています。

前提条件

Docker と Docker Compose: Docker がインストールされ、起動していることを確認してください
サンプル環境のセットアップ: 各種 docker-compose セットアップを利用できます (以下の「Alternative Docker Images」を参照)

ローカル REST カタログのセットアップ

各種のコンテナー化された REST カタログ実装を利用できます。たとえば Databricks docker-spark-iceberg は、docker-compose を使って Spark + Iceberg + REST カタログの一式がそろった環境を提供しており、Iceberg インテグレーションのテストに最適です。 ステップ 1: まず、サンプルを実行するための新しいフォルダーを作成し、Databricks docker-spark-iceberg の設定を使って docker-compose.yml ファイルを作成します。 ステップ 2: 次に、docker-compose.override.yml ファイルを作成し、以下の ClickHouse コンテナー設定をそこに記述します。

version: '3.8'

services:
  clickhouse:
    image: clickhouse/clickhouse-server:25.5.6
    container_name: clickhouse
    user: '0:0'  # ルート権限を確保する
    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: サービスを起動するには、次のコマンドを実行します:

docker compose up

ステップ 4: すべてのサービスが準備完了になるまで待ちます。ログは次のように確認できます:

docker-compose logs -f

REST カタログのセットアップでは、あらかじめサンプルデータが Iceberg テーブルにロードされている必要があります。ClickHouse 経由でこれらのテーブルにクエリを実行する前に、Spark 環境でテーブルが作成され、データが投入されていることを確認してください。利用可能なテーブルは、使用する docker-compose の構成やサンプルデータのロード用スクリプトによって異なります。

ローカル REST カタログに接続する

ClickHouse コンテナーに接続します。

docker exec -it clickhouse clickhouse-client

次に、REST カタログへの接続用データベースを作成します。

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'

ClickHouse を使用した REST カタログテーブルのクエリ

接続が確立されたので、REST カタログ経由でクエリを実行できます。たとえば、次のとおりです。

USE demo;

SHOW TABLES;

セットアップにサンプルデータ (タクシーデータセットなど) が含まれている場合は、次のようなテーブルが表示されます。

┌─name──────────┐
│ default.taxis │
└───────────────┘

テーブルがまったく表示されない場合、通常は次のいずれかが原因です。

Spark 環境でまだサンプルテーブルが作成されていない
REST カタログサービスの初期化がまだ完了していない
サンプルデータの読み込み処理がまだ完了していない

テーブル作成の進捗を確認するには、Spark のログを確認してください。

docker-compose logs spark

テーブルをクエリするには (利用可能な場合) :

SELECT count(*) FROM `default.taxis`;

┌─count()─┐
│ 2171187 │
└─────────┘

バッククォートは必須ですClickHouse は複数のネームスペースをサポートしていないため、バッククォートが必要です。

テーブルの DDL を確認するには:

SHOW CREATE TABLE `default.taxis`;

┌─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]') │
└───────────────────────────────────────────────────────────────────────────────────────────────┘

データレイクから ClickHouse にデータを読み込む

REST カタログから ClickHouse にデータを読み込む必要がある場合は、まずローカルの ClickHouse テーブルを作成します。

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 カタログのテーブルからデータを読み込みます。

INSERT INTO taxis 
SELECT * FROM demo.`default.taxis`;

​ローカル開発環境のセットアップ

​前提条件

​ローカル REST カタログのセットアップ

​ローカル REST カタログに接続する

​ClickHouse を使用した REST カタログテーブルのクエリ

​データレイクから ClickHouse にデータを読み込む

ローカル開発環境のセットアップ

前提条件

ローカル REST カタログのセットアップ

ローカル REST カタログに接続する

ClickHouse を使用した REST カタログテーブルのクエリ

データレイクから ClickHouse にデータを読み込む