S3テーブルエンジン

このエンジンは、Amazon S3エコシステムとの統合を提供します。このエンジンは、HDFSエンジンに似ていますが、S3特有の機能を提供します。

例

テーブルの作成

エンジンパラメータ

• path — ファイルへのパスを持つバケットのURL。読み取り専用モードで次のワイルドカードをサポートします: *, **, ?, {abc,def} および {N..M} （ここで N, M は数字、'abc', 'def' は文字列）。詳細については、下記を参照してください。
• NOSIGN - このキーワードが認証情報の代わりに指定されると、すべてのリクエストは署名されません。
• format — ファイルのフォーマット。
• aws_access_key_id, aws_secret_access_key - AWSアカウントユーザーの長期的な認証情報。これらを使用してリクエストを認証できます。パラメータはオプションです。認証情報が指定されていない場合、それらは構成ファイルから使用されます。詳細については、S3をデータストレージとして使用するを参照してください。
• compression — 圧縮タイプ。サポートされている値: none, gzip/gz, brotli/br, xz/LZMA, zstd/zst。パラメータはオプションです。デフォルトでは、ファイル拡張子によって圧縮が自動的に検出されます。

データキャッシュ

S3テーブルエンジンは、ローカルディスク上でデータキャッシングをサポートします。ファイルシステムキャッシュの構成オプションと使用法については、このセクションを参照してください。キャッシングは、ストレージオブジェクトのパスとETagに依存して行われるため、ClickHouseは古いキャッシュバージョンを読み込みません。

キャッシングを有効にするには、設定 filesystem_cache_name = '<name>' と enable_filesystem_cache = 1 を使用します。

キャッシュ定義には、構成ファイルで次の2つの方法があります。

1. ClickHouse構成ファイルに次のセクションを追加します:

2. ClickHouseの storage_configuration セクションからキャッシュ構成（およびそれに伴うキャッシュストレージ）を再利用します。こちらで説明されています

PARTITION BY

PARTITION BY — オプションです。ほとんどの場合、パーティションキーは必要なく、必要な場合でも、通常は月単位よりも詳細なパーティションキーは必要ありません。パーティショニングはクエリの速度を上げるものではありません（ORDER BY式とは対照的に）。あまり細かいパーティショニングは使用しないでください。クライアント識別子や名前でデータをパーティショニングしないでください（代わりに、クライアント識別子または名前をORDER BY式の最初のカラムにします）。

月単位でのパーティショニングには、toYYYYMM(date_column)式を使用します。ここで、date_columnはDate型の日付を持つカラムです。パーティション名は「YYYYMM」形式になります。

パーティショニングデータのクエリ

この例では、docker composeレシピを使用して、ClickHouseとMinIOを統合しています。同様のクエリをS3で再現するには、エンドポイントと認証値を置き換えるだけで済みます。

ENGINE構成内のS3エンドポイントは、S3オブジェクト（ファイル名）の一部としてパラメータトークン{_partition_id}を使用しており、SELECTクエリはそれらの結果となるオブジェクト名（例: test_3.csv）に対して選択します。

注記

例のように、パーティショニングされたS3テーブルからのクエリは 現時点では直接サポートされていませんが、S3テーブル関数を使用して 個々のパーティションをクエリすることで実現できます。

S3にパーティション化されたデータを書く主なユースケースは、 そのデータを別のClickHouseシステムに転送できるようにすることです （例えば、オンプレミスシステムからClickHouse Cloudへの移行）。
ClickHouseデータセットは非常に大きいことが多く、ネットワークの信頼性が 時々完璧ではないため、データセットをサブセットに分けて転送することが理にかなっています、したがってパーティショニングされた書き込みが必要です。

テーブルの作成

データを挿入

パーティション3から選択

ヒント

このクエリはs3テーブル関数を使用しています。

パーティション1から選択

パーティション45から選択

制限

あなたは自然に Select * from p を試みるかもしれませんが、先に述べたように、このクエリは失敗します; 前述のクエリを使用してください。

仮想カラム

• _path — ファイルへのパス。型: LowCardinality(String)。
• _file — ファイルの名前。型: LowCardinality(String)。
• _size — ファイルのサイズ（バイト単位）。型: Nullable(UInt64)。サイズが不明な場合、値はNULLになります。
• _time — ファイルの最終更新時刻。型: Nullable(DateTime)。時刻が不明な場合、値はNULLになります。
• _etag — ファイルのETag。型: LowCardinality(String)。etagが不明な場合、値はNULLになります。

仮想カラムの詳細については、こちらを参照してください。

実装の詳細

• 読み取りと書き込みは並行して行うことができます。

• サポートされていないもの:

  • ALTERおよびSELECT...SAMPLE操作。
  • インデックス。
  • ゼロコピーレプリケーションは可能ですが、サポートされていません。
  ゼロコピーのレプリケーションは本番環境には適していません

  ゼロコピーのレプリケーションは、ClickHouseバージョン22.8以降でデフォルトで無効になっています。この機能は本番環境での使用は推奨されません。

パス内のワイルドカード

path引数は、bashスタイルのワイルドカードを使用して複数のファイルを指定できます。処理されるファイルは存在し、全パスパターンに一致する必要があります。ファイルのリストはSELECT中に決定されます（CREATE時ではありません）。

• * — 任意の数の任意の文字（/を除く）を空文字列も含めて代替します。
• ** — 任意の数のあらゆる文字（/を含む）を空文字列も含めて代替します。
• ? — 任意の単一文字を代替します。
• {some_string,another_string,yet_another_one} — 文字列のいずれかを代替します 'some_string', 'another_string', 'yet_another_one'。
• {N..M} — NからMまでの範囲内の任意の数字を代替します。NとMは先頭ゼロを含むことができます。例: 000..078。

{}を使用した構文は、リモートテーブル関数に似ています。

注記

ファイルのリストに先頭ゼロ付きの数字範囲が含まれている場合、各数字ごとに波括弧付きの構文を使用するか、?を使用してください。

ワイルドカードを使用した例1

file-000.csv、file-001.csv、...、file-999.csvという名前のファイルでテーブルを作成します:

ワイルドカードを使用した例2

次のURIでCSV形式のいくつかのファイルがS3にあるとします:

• 'https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some_folder/some_file_1.csv'
• 'https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some_folder/some_file_2.csv'
• 'https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some_folder/some_file_3.csv'
• 'https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another_folder/some_file_1.csv'
• 'https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another_folder/some_file_2.csv'
• 'https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another_folder/some_file_3.csv'

次の方法で6つのファイルからなるテーブルを作成できます:

1. ファイルの接尾辞範囲を指定します:

2. some_file_という接頭辞を持つすべてのファイルを取り込みます（両方のフォルダにその接頭辞を持つ余計なファイルがないべきです）:

3. 両方のフォルダ内のすべてのファイルを取り込みます（すべてのファイルは、クエリで記述された形式とスキーマに一致するべきです）:

ストレージ設定

• s3_truncate_on_insert - 挿入前にファイルを切り捨てることを許可します。デフォルトでは無効です。
• s3_create_new_file_on_insert - 各挿入時に新しいファイルを作成することを許可します。デフォルトでは無効です。
• s3_skip_empty_files - 読み取り時に空のファイルをスキップすることを許可します。デフォルトでは有効です。

S3関連設定

以下の設定は、クエリ実行前に設定するか、構成ファイルに配置できます。

• s3_max_single_part_upload_size — S3に単一パートアップロードを使用してアップロードするオブジェクトの最大サイズ。デフォルト値は32Mbです。
• s3_min_upload_part_size — S3マルチパートアップロード中にアップロードされる部分の最小サイズ。デフォルト値は16Mbです。
• s3_max_redirects — 許可される最大S3リダイレクトホップ数。デフォルト値は10です。
• s3_single_read_retries — 単一読み取り中の最大試行回数。デフォルト値は4です。
• s3_max_put_rps — スロットリングの前に許可される最大PUTリクエストの毎秒レート。デフォルト値は0（無制限）です。
• s3_max_put_burst — リクエスト毎秒制限に達する前に、同時に発行できるリクエストの最大数。デフォルト値（0値）はs3_max_put_rpsに等しいです。
• s3_max_get_rps — スロットリングの前に許可される最大GETリクエストの毎秒レート。デフォルト値は0（無制限）です。
• s3_max_get_burst — リクエスト毎秒制限に達する前に、同時に発行できるリクエストの最大数。デフォルト値（0値）はs3_max_get_rpsに等しいです。
• s3_upload_part_size_multiply_factor - s3_min_upload_part_sizeを、この係数で毎回s3_multiply_parts_count_thresholdパーツがS3にアップロードされるごとに乗算します。デフォルト値は2です。
• s3_upload_part_size_multiply_parts_count_threshold - この数のパーツがS3にアップロードされるたびに、s3_min_upload_part_sizeがs3_upload_part_size_multiply_factorで乗算されます。デフォルト値は500です。
• s3_max_inflight_parts_for_one_file - 1つのオブジェクトに対して同時に実行できるPUTリクエストの数を制限します。この数は制限する必要があります。値0は無制限を意味します。デフォルト値は20です。各進行中部分は、最初のs3_upload_part_size_multiply_factorパーツについてs3_min_upload_part_sizeのサイズを持つバッファを持ち、ファイルが十分に大きければ追加のサイズを持ちます。デフォルト設定で、アップロードされたファイルは8G未満の場合、最大320Mbを消費します。大きいファイルの場合、消費は大きくなります。

セキュリティ考慮: 悪意のあるユーザーが任意のS3 URLを指定できる場合、s3_max_redirectsはゼロに設定する必要があり、SSRF攻撃を避けなければなりません。あるいは、サーバー構成にremote_host_filterを指定する必要があります。

エンドポイントに基づく設定

以下の設定は、特定のエンドポイントの構成ファイルに指定できます（エンドポイントの正確な接頭辞で一致します）:

• endpoint — エンドポイントの接頭辞を指定します。必須です。
• access_key_id と secret_access_key — 与えられたエンドポイントに使用する認証情報を指定します。オプションです。
• use_environment_credentials — trueに設定すると、S3クライアントは環境変数および指定されたエンドポイントのAmazon EC2メタデータから認証情報を取得します。オプションで、デフォルト値はfalseです。
• region — S3リージョン名を指定します。オプションです。
• use_insecure_imds_request — trueに設定すると、S3クライアントは、Amazon EC2メタデータから認証情報を取得する際に安全でないIMDSリクエストを使用します。オプションで、デフォルト値はfalseです。
• expiration_window_seconds — 有効期限ベースの認証情報が期限切れかどうかを確認するための猶予時間。オプションで、デフォルト値は120です。
• no_sign_request - すべての認証情報を無視し、リクエストに署名しないようにします。公開バケットにアクセスする場合に便利です。
• header — 指定されたHTTPヘッダーを指定されたエンドポイントへのリクエストに追加します。オプションで、複数回指定できます。
• access_header - 他のソースからの他の認証情報がない場合に、指定されたHTTPヘッダーを指定されたエンドポイントへのリクエストに追加します。
• server_side_encryption_customer_key_base64 — 指定された場合、SSE-C暗号化されたS3オブジェクトへのアクセスに必要なヘッダーが設定されます。オプションです。
• server_side_encryption_kms_key_id - 指定された場合、SSE-KMS暗号化されたS3オブジェクトへのアクセスに必要なヘッダーが設定されます。空の文字列が指定された場合、AWS管理のS3キーが使用されます。オプションです。
• server_side_encryption_kms_encryption_context - server_side_encryption_kms_key_idと一緒に指定された場合、SSE-KMS用の指定された暗号化コンテキストヘッダーが設定されます。オプションです。
• server_side_encryption_kms_bucket_key_enabled - server_side_encryption_kms_key_idと一緒に指定された場合、SSE-KMS用のS3バケットキーを有効にするためのヘッダーが設定されます。オプションで、trueまたはfalseで設定でき、デフォルトでは何も設定されていません（バケットレベルの設定に一致します）。
• max_single_read_retries — 単一読み取り中の最大試行回数。デフォルト値は4です。オプションです。
• max_put_rps, max_put_burst, max_get_rpsおよび max_get_burst - 特定のエンドポイントに対してクエリごとの代わりに使用するスロットリング設定（上記の説明を参照）です。オプションです。

例:

アーカイブの操作

次のURIでS3にいくつかのアーカイブファイルがあるとします:

• 'https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-10.csv.zip'
• 'https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-11.csv.zip'
• 'https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-12.csv.zip'

これらのアーカイブからデータを抽出するには、::を使用します。グロブはURL部分およびアーカイブ内のファイル名部分の両方で使用できます。

注記

ClickHouseは3つのアーカイブ形式をサポートしています： ZIP TAR 7Z ZIPおよびTARアーカイブは、サポートされている任意のストレージロケーションからアクセスできますが、7ZアーカイブはClickHouseがインストールされているローカルファイルシステムからのみ読み取ることができます。

公開バケットへのアクセス

ClickHouseはさまざまなソースから認証情報を取得しようとします。時には、公開バケットにアクセスする際に、クライアントが403エラーコードを返す問題が発生する場合があります。この問題は、NOSIGNキーワードを使用することで回避できます。これにより、クライアントはすべての認証情報を無視し、リクエストを署名しなくなります。

パフォーマンスの最適化

s3関数のパフォーマンスを最適化する詳細については、当社の詳細ガイドを参照してください。

参照

• s3テーブル関数