メインコンテンツへスキップ
メインコンテンツへスキップ

データカタログへの接続

前のセクションでは、ストレージパスを直接指定してオープンなテーブル形式に対してクエリを実行しました。実際には、ほとんどの組織はテーブルのメタデータを データカタログ を通じて管理します。これは、テーブルの場所、スキーマ、およびパーティションを追跡する集中管理されたレジストリです。DataLakeCatalog データベースエンジンを使用して ClickHouse をカタログに接続すると、カタログ全体を ClickHouse のデータベースとして扱えるようになります。カタログ内のすべてのテーブルは自動的に認識され、テーブルごとのパスや認証情報を把握・管理することなく、ClickHouse の SQL をフルに利用してクエリできます。

このガイドでは、Databricks Unity Catalog への接続手順を説明します。ClickHouse は次のカタログにも対応しており、完全なセットアップ手順については、それぞれのリファレンスガイドを参照してください。

CatalogReference guide
AWS GlueAWS Glue カタログ
Iceberg REST CatalogREST カタログ
LakekeeperLakekeeper カタログ
Project NessieNessie カタログ
Microsoft OneLakeFabric OneLake

Unity Catalog への接続​

Beta feature. Learn more.

ここでは例として Unity Catalog を使用します。

Databricks Unity Catalog は、Databricks レイクハウス環境のデータに対する一元的なガバナンスを提供します。

Databricks は、そのレイクハウスに対して複数のデータ形式をサポートしています。ClickHouse を使用すると、Unity Catalog のテーブルを Delta および Iceberg としてクエリできます。

注記

Unity Catalog との連携は、マネージドテーブルおよび外部テーブルで動作します。 この連携機能は現在、AWS 環境上でのみサポートされています。

Databricks での Unity の構成​

ClickHouse から Unity Catalog と連携できるようにするには、Unity Catalog が外部リーダーからのアクセスを許可するよう構成されている必要があります。これは、"Enable external data access to Unity Catalog" ガイドに従うことで実現できます。

外部アクセスを有効化することに加えて、テーブルを含むスキーマに対して、連携を構成するプリンシパルが EXTERNAL USE SCHEMA 権限 を持っていることを確認してください。

カタログの構成が完了したら、ClickHouse 用のクレデンシャルを生成する必要があります。Unity との接続モードに応じて、2 つの異なる方法を使用できます。

  • Iceberg クライアントの場合は、service principal を使って認証します。

  • Delta クライアントの場合は、Personal Access Token（PAT）を使用します。

カタログに接続する​

認証情報を使用して、対象のエンドポイントに接続し、Iceberg または Delta テーブルに対してクエリを実行できます。

Unity Catalog は、Delta 形式のデータにアクセスするために使用します。

SET allow_experimental_database_unity_catalog = 1;

CREATE DATABASE unity
ENGINE = DataLakeCatalog('https://<workspace-id>.cloud.databricks.com/api/2.1/unity-catalog')
SETTINGS warehouse = 'CATALOG_NAME', catalog_credential = '<PAT>', catalog_type = 'unity';

テーブルを一覧表示する​

カタログへの接続が確立されたら、テーブルを一覧表示できます。

SHOW TABLES FROM unity

┌─name───────────────────────────────────────────────┐
│ unity.logs                                         │
│ unity.single_day_log                               │
└────────────────────────────────────────────────────┘

31 rows in set.

テーブルスキーマの探索​

標準の SHOW CREATE TABLE コマンドを使用して、テーブルがどのように作成されたかを確認できます。

Backticks required

ネームスペースとテーブル名をバッククォートで囲んで指定する必要がある点に注意してください。ClickHouse は複数のネームスペースをサポートしていません。

以下では、REST Iceberg カタログに対してクエリを実行することを前提としています。

SHOW CREATE TABLE unity.`icebench.single_day_log`

CREATE TABLE unity.`icebench.single_day_log`
(
    `pull_request_number` Nullable(Int64),
    `commit_sha` Nullable(String),
    `check_start_time` Nullable(DateTime64(6, 'UTC')),
    `check_name` Nullable(String),
    `instance_type` Nullable(String),
    `instance_id` Nullable(String),
    `event_date` Nullable(Date32),
    `event_time` Nullable(DateTime64(6, 'UTC')),
    `event_time_microseconds` Nullable(DateTime64(6, 'UTC')),
    `thread_name` Nullable(String),
    `thread_id` Nullable(Decimal(20, 0)),
    `level` Nullable(String),
    `query_id` Nullable(String),
    `logger_name` Nullable(String),
    `message` Nullable(String),
    `revision` Nullable(Int64),
    `source_file` Nullable(String),
    `source_line` Nullable(Decimal(20, 0)),
    `message_format_string` Nullable(String)
)
ENGINE = Iceberg('s3://...')

テーブルをクエリする​

すべての ClickHouse 関数が利用可能です。繰り返しになりますが、ネームスペースとテーブル名はバッククォートで囲む必要があります。


SELECT count()
FROM unity.`icebench.single_day_log`

┌───count()─┐
│ 282634391 │ -- 282.63 million
└───────────┘

1 row in set. Elapsed: 1.265 sec.

セットアップの全手順については、Unity Catalog リファレンスガイドを参照してください。