メインコンテンツまでスキップ
メインコンテンツまでスキップ

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 設定ファイルに次のセクションを追加します:
  1. ClickHouse storage_configuration セクションからキャッシュ設定（したがってキャッシュストレージ）を再利用します。ここで説明されています

PARTITION BY​

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

月別にパーティショニングするには、toYYYYMM(date_column) 式を使用します。ここで date_column は Date 型の日付を持つカラムです。パーティション名は "YYYYMM" フォーマットになります。

パーティション化されたデータのクエリ​

この例では、ClickHouse と MinIO を統合したdocker composeレシピを使用しています。エンドポイントと認証情報を置き換えることで、S3 を使用して同じクエリを再現できるはずです。

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

注記

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

S3 にパーティション化されたデータを書き込む主なユースケースは、そのデータを別の ClickHouse システムに転送することを可能にすることです（たとえば、オンプレミスシステムから ClickHouse Cloud に移動する）。ClickHouse データセットは非常に大きいことが多く、ネットワークの信頼性が時々不完全であるため、データセットを部分セットで転送することが理にかなっています。したがって、パーティション化された書き込みが行われます。

テーブルを作成する​

データを挿入する​

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

ヒント

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

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

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

制限​

Select * from p を実行しようとするかもしれませんが、上記のように、このクエリは失敗します。前のクエリを使用してください。

データの挿入​

新しいファイルにのみ行を挿入できることに注意してください。マージサイクルやファイル分割操作はありません。ファイルが書き込まれた後、追加の挿入は失敗します。これを回避するには、s3_truncate_on_insert と s3_create_new_file_on_insert 設定を使用できます。詳細は こちら を参照してください。

仮想カラム​

  • _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形式のファイルが複数あるとします:

これらの6つのファイルから構成されるテーブルを作成するには、いくつかの方法があります。

  1. ファイル接尾辞の範囲を指定する:
  1. some_file_ プレフィックスを持つすべてのファイルを取得する（両フォルダーにはそのようなプレフィックスの余分なファイルがない必要があります）:
  1. 両方のフォルダー内のすべてのファイルを取得する（すべてのファイルはクエリで記述された形式およびスキーマを満たす必要があります）:

ストレージ設定​

  • 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 を指定する必要もあります。

エンドポイントベースの設定​

次の設定は、設定ファイルの指定されたエンドポイントに対して指定できます（URL の完全なプレフィックスによって一致します）：

  • 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 — 指定されている場合、S3 オブジェクトに対する SSE-C 暗号化アクセスに必要なヘッダーが設定されます。オプションです。
  • 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のいくつかのアーカイブファイルがあるとします:

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

注記

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

パブリックバケットへのアクセス​

ClickHouse はさまざまなタイプのソースから資格情報を取得しようとします。時々、パブリックなバケットへのアクセス時に問題が発生することがあり、クライアントが 403 エラーコードを返すことがあります。この問題は、NOSIGN キーワードを使用して、クライアントがすべての認証情報を無視し、リクエストを署名しないように強制することで回避できます。

パフォーマンスの最適化​

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

参照​