例
テーブルを作成する
エンジンパラメータ
path— ファイルへのパスを含むバケット URL。readonly モードでは、次のワイルドカードをサポートします:*,**,?,{abc,def}および{N..M}。ここで、N,Mは数値、'abc','def'は文字列です。詳細は以下を参照してください。NOSIGN- 認証情報の代わりにこのキーワードを指定すると、すべてのリクエストに署名が行われません。format— ファイルのフォーマット。aws_access_key_id,aws_secret_access_key- AWS アカウントユーザー向けの長期認証情報です。これらを使用してリクエストを認証できます。このパラメータは任意です。認証情報が指定されていない場合は、設定ファイルのものが使用されます。詳細は Using S3 for Data Storage を参照してください。compression— 圧縮タイプ。サポートされる値:none,gzip/gz,brotli/br,xz/LZMA,zstd/zst。このパラメータは任意です。デフォルトでは、ファイル拡張子から圧縮方式を自動検出します。partition_strategy– オプション:WILDCARDまたはHIVE。WILDCARDでは、パス内に{_partition_id}が必要で、これがパーティションキーに置き換えられます。HIVEではワイルドカードは使用できず、パスがテーブルのルートであるとみなし、ファイル名に Snowflake ID、拡張子にファイルフォーマットを使用した Hive スタイルのパーティションディレクトリを生成します。デフォルトはfile_like_engine_default_partition_strategy設定です (26.6より古いcompatibility設定ではWILDCARD、それ以外ではHIVE) 。partition_columns_in_data_file-HIVEパーティション方式でのみ使用されます。データファイル内にパーティションカラムが書き込まれているものとして ClickHouse が扱うかどうかを指定します。デフォルトはfalseです。storage_class_name- オプション:STANDARDまたはINTELLIGENT_TIERING。AWS S3 Intelligent Tiering を指定できます。extra_credentials- 任意。ClickHouse Cloud でロールベースアクセス用のrole_arnを渡すために使用します。設定手順については Secure S3 を参照してください。
データキャッシュ
S3 テーブルエンジンは、ローカルディスクへのデータキャッシュをサポートしています。
ファイルシステムキャッシュの設定オプションと使用方法については、このセクションを参照してください。
キャッシュはストレージオブジェクトのパスと ETag に基づいて行われるため、ClickHouse が古いキャッシュを読み込むことはありません。
キャッシュを有効にするには、設定 filesystem_cache_name = '<name>' と enable_filesystem_cache = 1 を使用します。
- ClickHouseの設定ファイルに次のセクションを追加します。
- ClickHouse の
storage_configurationセクションにある cache の設定 (つまり cache ストレージ) を再利用します。詳しくはこちらを参照してください
PARTITION BY
PARTITION BY — 任意です。ほとんどの場合、パーティションキーは不要です。必要な場合でも、通常は月単位より細かいパーティションキーは必要ありません。パーティション化してもクエリは高速化されません (ORDER BY 式とは対照的です) 。細かすぎるパーティション化は絶対に避けてください。クライアント識別子や名前でデータをパーティション化しないでください (代わりに、クライアント識別子または名前を ORDER BY 式の最初のカラムにしてください) 。
月単位でパーティション化するには、toYYYYMM(date_column) 式を使用します。ここで、date_column は Date 型の日付カラムです。ここでのパーティション名は "YYYYMM" フォーマットになります。
パーティション方式
WILDCARD: ファイルパス内の {_partition_id} ワイルドカードを実際のパーティションキーに置き換えます。読み取りはサポートされていません。デフォルトで選択されるのは、26.6 より前の compatibility 設定の場合のみです。それ以外では、デフォルトは HIVE です (file_like_engine_default_partition_strategy 設定を参照) 。
HIVE は、読み取りと書き込みで Hive スタイルのパーティション化を実装します。読み取りは再帰的な glob パターンを使用して実装されており、SELECT * FROM s3('table_root/**.parquet') と同等です。
書き込みでは、次のフォーマットでファイルが生成されます: <prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>。
注: HIVE パーティション方式を使用する場合、use_hive_partitioning 設定は効果がありません。
HIVE パーティション方式の例:
パーティション化されたデータのクエリ
ENGINE 設定の S3 エンドポイントでは、S3 オブジェクト (ファイル名) の一部としてパラメータートークン {_partition_id} が使われており、SELECT クエリでは生成されたそのオブジェクト名 (例: test_3.csv) を対象にしている点に注目してください。
この例が示すように、パーティション化された S3 テーブルに対するクエリは
現時点では直接サポートされていませんが、各パーティションに対して
S3 テーブル関数 を使ってクエリすることで実現できます。S3 への
パーティション化されたデータの書き込みの主な用途は、そのデータを別の
ClickHouse システムへ転送できるようにすることです (たとえば、オンプレミス環境から ClickHouse
Cloud へ移行する場合など) 。ClickHouse のデータセットは非常に大きくなることが多く、またネットワークの
信頼性も常に十分とは限らないため、データセットを
一部ずつ転送できるようにしておくのが合理的です。これが、パーティション化書き込みを行う理由です。
テーブルを作成
データを挿入する
パーティション 3 から取得
パーティション 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です。_tags— ファイルのタグ。型:Map(String, String). タグが存在しない場合、値は空のマップ{}'です。
実装の詳細
- 読み取りと書き込みは並行して実行できます
- サポートされていません:
ALTERおよびSELECT...SAMPLE操作。- 索引。
- Zero-copy レプリケーションは可能ですが、サポート対象外です。
ゼロコピー レプリケーションは本番環境には未対応ですゼロコピー レプリケーションは、ClickHouse バージョン 22.8 以降ではデフォルトで無効になっています。この機能を本番環境で使用することは推奨されません。
path 内のワイルドカード
path 引数では、bash 形式のワイルドカードを使って複数のファイルを指定できます。処理対象のファイルは実在し、path パターン全体に一致している必要があります。ファイルの一覧は SELECT の実行時に決定されます (CREATE 時ではありません) 。
*— 空文字列を含む、/を除く任意の文字列に置き換えられます。**— 空文字列を含む、/を含む任意の文字列に置き換えられます。?— 任意の 1 文字に置き換えられます。{some_string,another_string,yet_another_one}—'some_string'、'another_string'、'yet_another_one'のいずれかの文字列に置き換えられます。{N..M}— N から M までの範囲内の任意の数値 (両端を含む) に置き換えられます。N と M には先頭の 0 を付けることもできます (例:000..078) 。
{} を使う構文は、remote table function と似ています。
ファイル一覧に先頭の 0 を含む数値範囲がある場合は、各桁ごとに波かっこを使った構文を使用するか、
? を使用してください。file-000.csv、file-001.csv、…、file-999.csv という名前のファイルに対するテーブルを作成します:
- ‘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'
- ファイル名の接尾辞の範囲を指定します。
some_file_プレフィックスを持つすべてのファイルを対象にします (どちらのフォルダーにも、このプレフィックスを持つ余分なファイルがあってはいけません) :
- 両方のフォルダ内にあるすべてのファイルを対象とします (すべてのファイルは、クエリで記述されたフォーマットとスキーマに適合している必要があります) :
ストレージ設定
- s3_truncate_on_insert - ファイルに insert する前に、そのファイルを切り詰めることを許可します。デフォルトでは無効です。
- s3_create_new_file_on_insert - フォーマットに接尾辞がある場合、insert のたびに新しいファイルを作成することを許可します。デフォルトでは無効です。
- s3_skip_empty_files - 読み取り時に空のファイルをスキップすることを許可します。デフォルトでは有効です。
S3 関連の設定
s3_max_single_part_upload_size— S3 へのシングルパートアップロードでアップロードするオブジェクトの最大サイズです。デフォルト値は32Mbです。s3_min_upload_part_size— S3 Multipart upload を使用したマルチパートアップロード時にアップロードするパートの最小サイズです。デフォルト値は16Mbです。s3_max_redirects— 許可される S3 リダイレクトホップの最大数です。デフォルト値は10です。s3_single_read_retries— 単一読み取り時の最大再試行回数です。デフォルト値は4です。s3_max_put_rps— スロットリングが適用されるまでの PUT リクエストの最大毎秒レートです。デフォルト値は0(無制限) です。s3_max_put_burst— 1 秒あたりのリクエスト制限に達する前に同時に発行できる最大リクエスト数です。デフォルトでは (値が0の場合) 、s3_max_put_rpsと同じです。s3_max_get_rps— スロットリングが適用されるまでの GET リクエストの最大毎秒レートです。デフォルト値は0(無制限) です。s3_max_get_burst— 1 秒あたりのリクエスト制限に達する前に同時に発行できる最大リクエスト数です。デフォルトでは (値が0の場合) 、s3_max_get_rpsと同じです。s3_upload_part_size_multiply_factor- S3 への 1 回の書き込みでs3_multiply_parts_count_threshold個のパートがアップロードされるたびに、s3_min_upload_part_sizeにこの係数を掛けます。デフォルト値は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のバッファが割り当てられ、ファイルが十分に大きい場合はさらに大きくなります。upload_part_size_multiply_factorを参照してください。デフォルト設定では、アップロードされる 1 ファイルあたりの消費量は、8G未満のファイルで320Mbを超えません。より大きなファイルでは消費量は増加します。
s3_max_redirects を 0 に設定する必要があります。あるいは、サーバー設定で remote_host_filter を指定する必要があります。
エンドポイントベースの設定
endpoint— エンドポイントのプレフィックスを指定します。必須です。access_key_idandsecret_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- すべての認証情報を無視し、リクエストに署名しないようにします。公開 bucket へのアクセスに便利です。header— 指定したエンドポイントへのリクエストに、指定した HTTP ヘッダーを追加します。任意で、複数回指定できます。access_header- 他のソースから認証情報が提供されていない場合に、指定したエンドポイントへのリクエストに指定した HTTP ヘッダーを追加します。server_side_encryption_customer_key_base64— 指定すると、SSE-C で暗号化された S3 object にアクセスするために必要なヘッダーが設定されます。任意です。server_side_encryption_kms_key_id- 指定すると、SSE-KMS encryption で暗号化された S3 object にアクセスするために必要なヘッダーが設定されます。空文字列を指定した場合は、AWS 管理の S3 key が使用されます。任意です。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 bucket key を有効にするヘッダーが設定されます。任意で、trueまたはfalseを指定できます。デフォルトでは何も設定されず、bucket レベルの設定に従います。max_single_read_retries— 1 回の読み取りでの最大再試行回数です。デフォルト値は4です。任意です。max_put_rps,max_put_burst,max_get_rpsandmax_get_burst- クエリ単位ではなく、特定のエンドポイントに対して使用するスロットリング設定です (説明は上記を参照) 。任意です。
アーカイブの操作
- ‘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'
ClickHouse は次の 3 つのアーカイブフォーマットをサポートしています:
ZIP
TAR
7Z
ZIP アーカイブと TAR アーカイブには、サポートされている任意のストレージ上の場所からアクセスできますが、7Z アーカイブを読み取れるのは、ClickHouse がインストールされているローカルファイルシステム上からのみです。
公開バケットへのアクセス
403 エラーコードを返すことがあります。
この問題は、NOSIGN キーワードを使用してクライアントがすべての認証情報を無視し、リクエストに署名しないようにすることで回避できます。
パフォーマンスの最適化
ロールベースのアクセス
extra_credentials パラメーターで roleARN を渡せます。
external_id は、role_arn とあわせて指定することもできます。これは AWS STS の AssumeRole 呼び出しの ExternalId パラメーターとして渡され、ロールの信頼ポリシーで共有シークレットを必須にできるため、confused deputy problem の軽減に役立ちます。