DataLakeCatalog

DataLakeCatalog データベースエンジンを使用すると、ClickHouse を外部データカタログに接続し、データを複製することなくオープンテーブル形式のデータをクエリできます。これにより、ClickHouse は既存のデータレイクインフラストラクチャとシームレスに連携する強力なクエリエンジンとなります。

サポートされるカタログ

DataLakeCatalog エンジンは、以下のデータカタログに対応しています。

AWS Glue カタログ - AWS 環境内の Iceberg テーブル向け
Databricks Unity Catalog - Delta Lake および Iceberg テーブル向け
Hive Metastore - 従来の Hadoop エコシステムで使われるカタログ
REST Catalogs - Iceberg REST 仕様をサポートする任意のカタログ

データベースの作成

DataLakeCatalog エンジンを使用するには、以下の関連設定を有効にする必要があります。

SET allow_database_iceberg = 1;
SET allow_database_unity_catalog = 1;
SET allow_database_glue_catalog = 1;
SET allow_experimental_database_hms_catalog = 1;
SET allow_experimental_database_paimon_rest_catalog = 1;

DataLakeCatalog エンジンを使用するデータベースは、次の構文で作成できます。

CREATE DATABASE database_name
ENGINE = DataLakeCatalog(catalog_endpoint[, user, password])
SETTINGS
catalog_type,
[...]

以下の設定をサポートしています:

設定	説明
`catalog_type`	カタログのタイプ: `glue`, `unity` (Delta、または `use_unity_catalog_v2` を使用する場合は Delta と Iceberg), `rest` (Iceberg), `hive`, `onelake` (Iceberg), `delta_sharing` (Iceberg, フラットなネームスペース), `horizon` (Snowflake Horizon Iceberg REST)
`warehouse`	カタログで使用する warehouse/データベース名。
`catalog_credential`	カタログの認証情報 (例: API key またはトークン)
`use_unity_catalog_v2`	`catalog_type = 'unity'` の場合: Delta Lake と Iceberg テーブルの両方に対応する新しい実装を使用します。既定値: `false`。`CREATE` 時に設定するか、既存のデータベースでは `ALTER DATABASE ... MODIFY SETTING` で変更します。
`auth_header`	カタログサービスで認証を行うためのカスタム HTTP header
`auth_scope`	認証用の OAuth2 スコープ (OAuth を使用する場合)
`storage_endpoint`	基盤となるストレージのエンドポイント URL
`oauth_server_uri`	認証用 OAuth2 認可サーバーの URI
`vended_credentials`	カタログから提供される認証情報を使用するかどうかを示すブール値 (AWS S3 および Azure ADLS Gen2 をサポート)
`aws_access_key_id`	S3/Glue へのアクセスに使用する AWS access key ID (提供された認証情報を使用しない場合)
`aws_secret_access_key`	S3/Glue へのアクセスに使用する AWS secret access key (提供された認証情報を使用しない場合)
`aws_role_arn`	AWS/Glue へのアクセスのために引き受ける IAM role の ARN。これを設定すると、`aws_access_key_id` と `aws_secret_access_key` の両方が指定されている場合、ClickHouse はそれらをベース認証情報として AWS STS `AssumeRole` を使用し、それ以外の場合はデフォルトの AWS credential chain を使用します (ロールはサーバーの実行元 identity を信頼している必要があります)。
`aws_role_session_name`	AWS STS `AssumeRole` 呼び出しに使用する session 名。省略可能で、既定値は `ClickHouseSession` です。
`aws_external_id`	AWS STS `AssumeRole` に渡される external ID で、ロールの trust policy 上の `sts:ExternalId` 条件に一致します。ClickHouse Cloud などのサードパーティがそのロールを所有している場合に使用します。
`region`	サービスの AWS リージョン (例: `us-east-1`)
`dlf_access_key_id`	DLF へのアクセスに使用する access key ID
`dlf_access_key_secret`	DLF へのアクセスに使用する access key secret
`force_add_bucket`	カタログから提供される table location と `storage_endpoint` からオブジェクトストレージの URL を構築する際、エンドポイントにすでに bucket/コンテナー名が含まれている場合でも、その名前を先頭に追加します。既定値: `false`。bucket を含まないパスを返し、URL 構築時にそれを追加する必要があるカタログ (Polaris 形式のパス) では `true` に設定してください。

例

DataLakeCatalog エンジンの使用例については、以下のセクションを参照してください。

Unity Catalog
Delta Lake と Iceberg テーブルを使用する Unity Catalog use_unity_catalog_v2 = 1 を設定すると、unity カタログで Delta Lake と Iceberg テーブルの両方を扱い、各テーブルのフォーマットを自動的に判別します。

CREATE DATABASE database_name
ENGINE = DataLakeCatalog('https://<workspace>.cloud.databricks.com/api/2.1/unity-catalog')
SETTINGS
    catalog_type = 'unity',
    use_unity_catalog_v2 = 1,
    warehouse = 'my_catalog',
    catalog_credential = '<client_id>:<client_secret>';
SHOW TABLES FROM database_name;
SELECT count() FROM database_name.`schema_name.table_name`;

catalog_credential には、OAuth サービスプリンシパルを <client_id>:<client_secret> の形式で指定するか、個人用アクセストークン (dapi...)、または事前に取得した OAuth トークンを指定できます。

Glue カタログ
OneLake Catalog allow_database_iceberg を有効にすると使用できます。

CREATE DATABASE database_name
ENGINE = DataLakeCatalog(catalog_endpoint)
SETTINGS
    catalog_type = 'onelake',
    warehouse = warehouse,
    onelake_tenant_id = tenant_id,
    oauth_server_uri = server_uri,
    auth_scope = auth_scope,
    onelake_client_id = client_id,
    onelake_client_secret = client_secret;
SHOW TABLES IN database_name;
SELECT count() from database_name.table_name;

クライアントシークレットを共有せずに認証するには、onelake_client_id/onelake_client_secret の代わりに、onelake_bearer_token に事前に取得した Bearer token (https://storage.azure.com をスコープとするもの) を設定します。ClickHouse はトークンを更新しないため、有効期限が切れた後はデータベースを再作成する必要があります。

SQLリファレンス

データ型

エンジン

関数

フォーマット

設定

システムテーブル

データレイク

サポートされるカタログ

データベースの作成

例

​サポートされるカタログ

​データベースの作成

​例

サポートされるカタログ

データベースの作成

例