s3 テーブル関数
Amazon S3 と Google Cloud Storage のファイルを選択/挿入するためのテーブルのようなインターフェイスを提供します。このテーブル関数は hdfs 関数 に似ていますが、S3 特有の機能を提供します。
クラスターに複数のレプリカがある場合は、挿入を並列化するために s3Cluster 関数 を使用できます。
s3 テーブル関数 を使用して INSERT INTO...SELECT を行うと、データはストリーミング方式で読み取られ、挿入されます。メモリには少数のデータブロックしか存在せず、S3 からブロックが継続的に読み取られ、宛先テーブルにプッシュされます。
構文
S3 テーブル関数は、GCS XML API と HMAC キーを使用して Google Cloud Storage と連携します。エンドポイントと HMAC の詳細については、Google 相互運用性ドキュメント を参照してください。
GCS では、access_key_id と secret_access_key の箇所に HMAC キーと HMAC シークレットを置き換えてください。
パラメータ
s3 テーブル関数は以下のプレーンパラメータをサポートしています：
url— ファイルへのパスを含むバケット URL。読み取り専用モードでは次のワイルドカードをサポートします:*,**,?,{abc,def}および{N..M}ただしNとMは数字、'abc'と'def'は文字列です。詳細についてはこちらを参照してください。GCSGCS URL は次の形式で、Google XML API のエンドポイントが JSON API とは異なるためです:
https://storage.cloud.google.com ではありません。
:::
NOSIGN— このキーワードを資格情報の代わりに指定すると、すべてのリクエストが署名されません。access_key_idとsecret_access_key— 特定のエンドポイントで使用する資格情報を指定するキー。オプション。session_token- 指定されたキーとともに使用するセッショントークン。キーを渡す場合はオプションです。format— ファイルの 形式。structure— テーブルの構造。形式は'column1_name column1_type, column2_name column2_type, ...'。compression_method— パラメータはオプションです。サポートされている値:none,gzipまたはgz,brotliまたはbr,xzまたはLZMA,zstdまたはzst。デフォルトでは、ファイル拡張子によって圧縮方法が自動検出されます。headers- パラメータはオプションです。S3 リクエストにヘッダーを渡すことができます。形式はheaders(key=value)です。例:headers('x-amz-request-payer' = 'requester')。
引数は ネームドコレクション を使用しても渡すことができます。この場合 url、access_key_id、secret_access_key、format、structure、compression_method は同様に機能し、いくつかの追加パラメータがサポートされます：
filename— 指定した場合は URL に追加されます。use_environment_credentials— デフォルトで有効で、環境変数AWS_CONTAINER_CREDENTIALS_RELATIVE_URI、AWS_CONTAINER_CREDENTIALS_FULL_URI、AWS_CONTAINER_AUTHORIZATION_TOKEN、AWS_EC2_METADATA_DISABLEDを使用して追加パラメータを渡すことを許可します。no_sign_request— デフォルトで無効です。expiration_window_seconds— デフォルト値は 120 です。
返される値
指定されたファイルでデータを読み書きするための指定された構造のテーブル。
例
S3 ファイル https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv から最初の 5 行を選択：
ClickHouse はファイル名の拡張子を使用してデータの形式を決定します。たとえば、CSVWithNames を指定せずに前のコマンドを実行していた場合でも、ClickHouse はファイルを自動的に解凍します。例えば、ファイルが .csv.gz 拡張子で圧縮されていた場合、ClickHouse はファイルを自動的に解凍します。
使用法
次の URI を持つ複数のファイルが S3 にあるとしましょう：
- 'https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some_prefix/some_file_1.csv'
- 'https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some_prefix/some_file_2.csv'
- 'https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some_prefix/some_file_3.csv'
- 'https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some_prefix/some_file_4.csv'
- 'https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another_prefix/some_file_1.csv'
- 'https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another_prefix/some_file_2.csv'
- 'https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another_prefix/some_file_3.csv'
- 'https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another_prefix/some_file_4.csv'
数値が 1 から 3 までのファイルの行数をカウントします：
これらの 2 つのディレクトリ内のすべてのファイルの行数を合計します：
ファイルリストに先頭ゼロを持つ数値範囲が含まれている場合は、桁ごとにブレース構文を使用するか、? を使用してください。
ファイル名が file-000.csv, file-001.csv, ... , file-999.csv のファイルの行数をカウントします：
ファイル test-data.csv.gz にデータを挿入します：
既存のテーブルからファイル test-data.csv.gz にデータを挿入します：
** を使用して再帰的なディレクトリトラバーサルを行うことができます。以下の例では、my-test-bucket-768 ディレクトリ内のすべてのファイルを再帰的に取得します：
以下は、my-test-bucket ディレクトリ内の任意のフォルダーから test-data.csv.gz という名前のすべてのファイルを再帰的に取得します：
注。サーバー構成ファイルにカスタム URL マッパーを指定することが可能です。例：
URL 's3://clickhouse-public-datasets/my-test-bucket-768/**/test-data.csv.gz' は、'http://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/**/test-data.csv.gz' に置き換えられます。
カスタムマッパーは config.xml に追加できます：
本番環境での使用例としては、ネームドコレクション の使用をお勧めします。以下はその例です：
パーティション書き込み
S3 テーブルにデータを挿入する際に PARTITION BY 式を指定すると、各パーティション値のために別々のファイルが作成されます。データを別々のファイルに分割することで、読み取り操作の効率が向上します。
例
- キーでパーティション ID を使用すると、別々のファイルが作成されます：
その結果、データは file_x.csv、file_y.csv、file_z.csv の 3 つのファイルに書き込まれます。
- バケット名にパーティション ID を使用すると、異なるバケットにファイルが作成されます：
その結果、データは異なるバケットに 3 つのファイルに書き込まれます：my_bucket_1/file.csv、my_bucket_10/file.csv、my_bucket_20/file.csv。
公開バケットへのアクセス
ClickHouse は多くの異なるタイプのソースから資格情報を取得しようとします。
時々、公開バケットにアクセスする際に問題が発生し、クライアントが 403 エラーコードを返すことがあります。
この問題は、 NOSIGN キーワードを使用することで回避でき、クライアントがすべての資格情報を無視し、リクエストを署名しないようにします。
S3 資格情報を使用する (ClickHouse Cloud)
非公開バケットの場合、ユーザーは関数に aws_access_key_id と aws_secret_access_key を渡すことができます。例えば：
これは、単発のアクセスや資格情報が簡単に回転できる場合には適切です。ただし、これは繰り返しアクセスや敏感な資格情報がある場合には推奨されません。この場合、ユーザーはロールベースのアクセスを依存することをお勧めします。
ClickHouse Cloud における S3 のロールベースのアクセスについては、こちらに記載されています。
設定後、roleARN を extra_credentials パラメータを介して s3 関数に渡すことができます。例えば：
さらなる例はこちらにあります。
アーカイブとの作業
次の 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 がインストールされているローカルファイルシステムからのみ読み取ることができます。
仮想カラム
_path— ファイルへのパス。タイプ:LowCardinality(String)。アーカイブの場合、次の形式でパスを示します:"{path_to_archive}::{path_to_file_inside_archive}"_file— ファイル名。タイプ:LowCardinality(String)。アーカイブの場合、アーカイブ内のファイルの名前を表示します。_size— ファイルのサイズ（バイト単位）。タイプ:Nullable(UInt64)。ファイルサイズが不明な場合、値はNULLです。アーカイブの場合、アーカイブ内のファイルの未圧縮サイズを示します。_time— ファイルの最終変更時間。タイプ:Nullable(DateTime)。時間が不明な場合、値はNULLです。
Hive スタイルのパーティショニング
use_hive_partitioning を 1 に設定すると、ClickHouse はパス内の Hive スタイルのパーティショニング（ /name=value/ ）を検出し、クエリ内でパーティションカラムを仮想カラムとして使用できるようになります。これらの仮想カラムは、パーティションパス内と同じ名前を持ち、_ で始まります。
例
Hive スタイルのパーティショニングで作成された仮想カラムを使用
リクエスターペイバケットへのアクセス
リクエスターペイバケットにアクセスするには、リクエストのすべてにヘッダー x-amz-request-payer = requester を渡す必要があります。これは、headers('x-amz-request-payer' = 'requester') パラメータを s3 関数に渡すことによって実現されます。例：
ストレージ設定
- s3_truncate_on_insert - 挿入前にファイルを切り詰めるようにします。デフォルトでは無効です。
- s3_create_new_file_on_insert - 各挿入時に接尾辞のある形式で新しいファイルを作成することを許可します。デフォルトでは無効です。
- s3_skip_empty_files - 読み取り中に空のファイルをスキップすることを許可します。デフォルトでは有効です。
参考