オープンテーブルフォーマットを直接クエリする

ClickHouse のテーブル関数を使用すると、事前設定なしでオブジェクトストレージ内の Iceberg、Delta Lake、Hudi、Paimon テーブルを読み取れます。

ClickHouse では、オブジェクトストレージ内のオープンテーブルフォーマットに保存されたデータを直接クエリできるテーブル関数を提供しています。外部カタログへの接続は不要で、AWS Athena が S3 から読み取るのと同様に、保存先のデータをそのままクエリできます。

関数呼び出しでストレージパスと認証情報を直接指定すれば、残りは ClickHouse が処理します。ClickHouse SQL のすべての構文と関数を利用でき、クエリでは ClickHouse の並列実行と高効率なネイティブ Parquet リーダーの利点を活かせます。

Server、local、または chDB

このガイドの手順は、既存の ClickHouse server インストールを使って実行できます。アドホックなクエリでは、代わりに clickhouse-local を使用して、server を起動せずに同じワークフローを完了することもできます。少し調整すれば、ClickHouse のインプロセス版である chDB を使って同じ手順を実行することも可能です。

以下の例では、各 lakehouse フォーマットで S3 に保存された hits データセットを使用します。各 lake フォーマットについて、オブジェクトストア provider ごとに専用の関数が用意されています。

Apache Iceberg

iceberg テーブル関数 (icebergS3 のエイリアス) は、オブジェクトストレージから直接 Iceberg テーブルを読み取ります。ストレージバックエンドごとに対応するバリアントが用意されています: icebergS3、icebergAzure、icebergHDFS、icebergLocal。

構文の例:

icebergS3(url [, NOSIGN | access_key_id, secret_access_key, [session_token]] [,format] [,compression_method])

icebergAzure(connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

icebergLocal(path_to_table, [,format] [,compression_method])

GCS のサポート

これらの関数の S3 版は、Google Cloud Storage (GCS) でも使用できます。

例：

SELECT
    url,
    count() AS cnt
FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

┌─url────────────────────────────────────────────────┬─────cnt─┐
│ http://liver.ru/belgorod/page/1006.jки/доп_приборы │ 3288173 │ -- 329万
│ http://kinopoisk.ru                                │ 1625250 │ -- 163万
│ http://bdsm_po_yers=0&with_video                   │  791465 │
│ http://video.yandex                                │  582400 │
│ http://smeshariki.ru/region                        │  514984 │
└────────────────────────────────────────────────────┴─────────┘

5 rows in set. Elapsed: 3.375 sec. Processed 100.00 million rows, 9.98 GB (29.63 million rows/s., 2.96 GB/s.)
Peak memory usage: 10.48 GiB.

​

クラスターバリアント

icebergS3Cluster 関数は、ClickHouse クラスター内の複数のノードに読み取りを分散します。イニシエーターノードはすべてのノードへの接続を確立し、データファイルを動的にディスパッチします。各ワーカーノードは、すべてのファイルが読み取られるまでタスクを要求して処理します。icebergCluster は icebergS3Cluster のエイリアスです。Azure (icebergAzureCluster) および HDFS (icebergHDFSCluster) 向けのバリアントも用意されています。

構文の例:

icebergS3Cluster(cluster_name, url [, NOSIGN | access_key_id, secret_access_key, [session_token]] [,format] [,compression_method])
-- icebergCluster は icebergS3Cluster のエイリアスです

icebergAzureCluster(cluster_name, connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

例 (ClickHouse Cloud):

SELECT
    url,
    count() AS cnt
FROM icebergS3Cluster(
    'default',
    'https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/'
)
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

​

テーブルエンジン

クエリのたびにテーブル関数を使用する代わりに、Iceberg テーブルエンジンを使用して永続テーブルを作成することもできます。データは引き続きオブジェクトストレージに保存され、必要に応じて読み込まれます。ClickHouse にデータがコピーされることはありません。この方法の利点は、テーブル定義が ClickHouse に保存されるため、各ユーザーがストレージのパスや認証情報を個別に指定しなくても、ユーザーやセッションをまたいで共有できる点です。ストレージバックエンドごとにエンジンのバリアントが用意されており、IcebergS3 (または Iceberg エイリアス) 、IcebergAzure、IcebergHDFS、IcebergLocal があります。

テーブルエンジンとテーブル関数はいずれも、S3、AzureBlobStorage、HDFSストレージエンジンと同じキャッシュ機構を使用したデータキャッシュをサポートしています。また、メタデータキャッシュはマニフェストファイルの情報をメモリに格納し、Icebergメタデータへの繰り返しアクセスを削減します。このキャッシュは、use_iceberg_metadata_files_cache 設定によってデフォルトで有効化されています。

構文の例:

テーブルエンジン Iceberg は IcebergS3 のエイリアスです。

CREATE TABLE iceberg_table
    ENGINE = IcebergS3(url [, NOSIGN | access_key_id, secret_access_key, [session_token]] [,format] [,compression_method])

CREATE TABLE iceberg_table
    ENGINE = IcebergAzure(connection_string|storage_account_url, container_name, blobpath, [account_name, account_key, format, compression])

CREATE TABLE iceberg_table
    ENGINE = IcebergLocal(path_to_table, [,format] [,compression_method])

GCS のサポート

Google Cloud Storage (GCS) では、テーブルエンジンの S3 バリアントを使用できます。

例：

CREATE TABLE hits_iceberg
    ENGINE = IcebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

┌─url────────────────────────────────────────────────┬─────cnt─┐
│ http://liver.ru/belgorod/page/1006.jки/доп_приборы │ 3288173 │
│ http://kinopoisk.ru                                │ 1625250 │
│ http://bdsm_po_yers=0&with_video                   │  791465 │
│ http://video.yandex                                │  582400 │
│ http://smeshariki.ru/region                        │  514984 │
└────────────────────────────────────────────────────┴─────────┘

5 rows in set. Elapsed: 2.737 sec. Processed 100.00 million rows, 9.98 GB (36.53 million rows/s., 3.64 GB/s.)
Peak memory usage: 10.53 GiB.

パーティションプルーニング、スキーマの進化、タイムトラベル、キャッシングなどのサポート済み機能については、サポートマトリックスを参照してください。完全なリファレンスについては、iceberg テーブル関数およびIceberg テーブルエンジンのドキュメントを参照してください。

Delta Lake

deltaLake テーブル関数 (deltaLakeS3 のエイリアス) は、オブジェクトストレージから Delta Lake テーブルを読み取ります。他のバックエンド向けのバリアントとして、deltaLakeAzure および deltaLakeLocal があります。

構文の例:

deltaLakeS3(url [,aws_access_key_id, aws_secret_access_key] [,format] [,structure] [,compression])

deltaLakeAzure(connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

deltaLakeLocal(path, [,format])

GCS のサポート

これらの関数の S3 バリアントは、Google Cloud Storage (GCS) でも利用できます。

例：

SELECT
    URL,
    count() AS cnt
FROM deltaLake('https://datasets-documentation.s3.amazonaws.com/lake_formats/delta_lake/')
GROUP BY URL
ORDER BY cnt DESC
LIMIT 5

┌─URL────────────────────────────────────────────────┬─────cnt─┐
│ http://liver.ru/belgorod/page/1006.jки/доп_приборы │ 3288173 │ -- 329万
│ http://kinopoisk.ru                                │ 1625250 │ -- 163万
│ http://bdsm_po_yers=0&with_video                   │  791465 │
│ http://video.yandex                                │  582400 │
│ http://smeshariki.ru/region                        │  514984 │
└────────────────────────────────────────────────────┴─────────┘

5 rows in set. Elapsed: 3.878 sec. Processed 100.00 million rows, 14.82 GB (25.78 million rows/s., 3.82 GB/s.)
Peak memory usage: 9.16 GiB.

​

クラスターバリアント

deltaLakeCluster 関数は、ClickHouse クラスター内の複数のノードに読み取りを分散します。イニシエーターノードは、並列処理のためにデータファイルをワーカーノードへ動的にディスパッチします。deltaLakeS3Cluster は deltaLakeCluster のエイリアスです。Azure バリアント (deltaLakeAzureCluster) も利用可能です。

構文の例:

deltaLakeCluster(cluster_name, url [,aws_access_key_id, aws_secret_access_key] [,format] [,structure] [,compression])
-- deltaLakeS3Cluster は deltaLakeCluster のエイリアスです

deltaLakeAzureCluster(cluster_name, connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

GCS のサポート

これらの関数では、Google Cloud Storage (GCS) に対して S3 バリアントを使用できます。

例 (ClickHouse Cloud):

SELECT
    URL,
    count() AS cnt
FROM deltaLakeCluster(
    'default',
    'https://datasets-documentation.s3.amazonaws.com/lake_formats/delta_lake/'
)
GROUP BY URL
ORDER BY cnt DESC
LIMIT 5

​

テーブルエンジン

クエリごとにテーブル関数を使用する代わりに、S3互換ストレージを使用している場合は、DeltaLake テーブルエンジンを使用して永続テーブルを作成できます。データは引き続きオブジェクトストレージに保存され、必要に応じて読み込まれます。ClickHouseにデータがコピーされることはありません。テーブル定義がClickHouseに保存されるため、各ユーザーがストレージのパスや認証情報を個別に指定しなくても、ユーザーやセッション間で共有できるという利点があります。

テーブルエンジンとテーブル関数はいずれも、S3、AzureBlobStorage、HDFSストレージエンジンと同じキャッシュ機構を使用したデータキャッシュをサポートしています。

構文の例:

CREATE TABLE delta_table
    ENGINE = DeltaLake(url [,aws_access_key_id, aws_secret_access_key])

GCS サポート

このテーブルエンジンは、Google Cloud Storage (GCS) で利用できます。

例：

CREATE TABLE hits_delta
    ENGINE = DeltaLake('https://datasets-documentation.s3.amazonaws.com/lake_formats/delta_lake/')

SELECT
    URL,
    count() AS cnt
FROM hits_delta
GROUP BY URL
ORDER BY cnt DESC
LIMIT 5

┌─URL────────────────────────────────────────────────┬─────cnt─┐
│ http://liver.ru/belgorod/page/1006.jки/доп_приборы │ 3288173 │
│ http://kinopoisk.ru                                │ 1625250 │
│ http://bdsm_po_yers=0&with_video                   │  791465 │
│ http://video.yandex                                │  582400 │
│ http://smeshariki.ru/region                        │  514984 │
└────────────────────────────────────────────────────┴─────────┘

5 rows in set. Elapsed: 3.608 sec. Processed 100.00 million rows, 14.82 GB (27.72 million rows/s., 4.11 GB/s.)
Peak memory usage: 9.27 GiB.

ストレージバックエンド、キャッシュなどのサポート済み機能については、サポートマトリックスを参照してください。詳細なリファレンスについては、deltaLake テーブル関数およびDeltaLake テーブルエンジンのドキュメントを参照してください。

Apache Hudi

hudi テーブル関数は、S3 上の Hudi テーブルを読み込みます。

構文:

hudi(url [,aws_access_key_id, aws_secret_access_key] [,format] [,structure] [,compression])

​

クラスター版

hudiCluster 関数は、ClickHouseクラスター内の複数のノードに読み取りを分散します。イニシエーター ノードは、並列処理のためにデータファイルをワーカー ノードへ動的に割り当てます。

hudiCluster(cluster_name, url [,aws_access_key_id, aws_secret_access_key] [,format] [,structure] [,compression])

​

テーブルエンジン

すべてのクエリで table function を使用する代わりに、Hudi table engine を使って永続的なテーブルを作成できます。データは引き続きオブジェクトストレージに格納され、必要に応じて読み取られるため、ClickHouse にデータがコピーされることはありません。利点は、テーブル定義が ClickHouse に保存されるため、各ユーザーがストレージパスや認証情報を指定しなくても、ユーザー間やセッション間で共有できることです。

構文:

CREATE TABLE hudi_table
    ENGINE = Hudi(url [,aws_access_key_id, aws_secret_access_key])

ストレージバックエンドなどを含むサポート対象の機能については、サポートマトリクスを参照してください。詳細については、hudi テーブル関数およびHudi テーブルエンジンのドキュメントを参照してください。

Apache Paimon

paimon テーブル関数 (paimonS3 のエイリアス) は、オブジェクトストレージ上の Paimon テーブルを読み取ります。paimonS3、paimonAzure、paimonHDFS、paimonLocal のように、ストレージバックエンドごとのバリアントがあります。

構文:

paimon(url [,access_key_id, secret_access_key] [,format] [,structure] [,compression])
paimonS3(url [,access_key_id, secret_access_key] [,format] [,structure] [,compression])

paimonAzure(connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

paimonHDFS(path_to_table, [,format] [,compression_method])

paimonLocal(path_to_table, [,format] [,compression_method])

​

クラスター版

paimonS3Cluster 関数は、ClickHouseクラスター内の複数のノードに読み取りを分散します。イニシエーターノードは、並列処理のためにデータファイルをワーカーノードへ動的に振り分けます。paimonCluster は paimonS3Cluster の別名です。Azure 向け (paimonAzureCluster) および HDFS 向け (paimonHDFSCluster) のバリアントもあります。

paimonS3Cluster(cluster_name, url [,access_key_id, secret_access_key] [,format] [,structure] [,compression])
-- paimonCluster は paimonS3Cluster のエイリアスです

paimonAzureCluster(cluster_name, connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

paimonHDFSCluster(cluster_name, path_to_table, [,format] [,compression_method])

​

テーブルエンジン

現在、Paimon 用の専用テーブルエンジンは ClickHouse にはありません。Paimon テーブルをクエリするには、上記のテーブル関数を使用してください。

ストレージバックエンドなどのサポート状況を含む対応機能については、サポートマトリクスを参照してください。詳細なリファレンスについては、paimon テーブル関数のドキュメントを参照してください。