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

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

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

ストレージパスと認証情報を関数呼び出し時に直接渡すだけで、残りは ClickHouse が処理します。ClickHouse のすべての SQL 構文と関数が利用でき、クエリは ClickHouse の並列実行と、効率的なネイティブ Parquet リーダーの恩恵を受けます。

Server, local or chDB

このガイドの手順は、既存の ClickHouse サーバー環境を使用して実行できます。アドホックなクエリ実行には、代わりに clickhouse-local を使用し、サーバーを起動せずに同じワークフローを完了できます。わずかな調整を行うことで、ClickHouse のインプロセス配布版である chDB を使用して同じ処理を実行することも可能です。

以下の例では、S3 上の各レイクハウス形式で保存されている hits データセットを使用します。各レイクハウス形式ごとに、各オブジェクトストレージプロバイダ専用の関数が用意されています。

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 │ -- 3.29 million
│ http://kinopoisk.ru                                │ 1625250 │ -- 1.63 million
│ 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 is an alias for 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 サポート

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

例：

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 テーブルエンジンのドキュメントを参照してください。