thevar1able/ClickHouse

Fork 0

mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-12-12 09:22:05 +00:00

Miki Matsumoto 1e15312729 add translated Japanese docs

2024-11-18 11:58:58 +09:00

17 KiB

Raw Blame History

slug

sidebar_position

sidebar_label

keywords

/ja/sql-reference/table-functions/s3

180

gcs

bucket

s3 テーブル関数

Amazon S3 と Google Cloud Storage 内のファイルを選択/挿入するためのテーブルのようなインターフェースを提供します。このテーブル関数は hdfs 関数に似ていますが、S3 固有の機能を提供します。

クラスターに複数のレプリカがある場合は、挿入を並列化するためにs3Cluster 関数を代わりに使用できます。

INSERT INTO...SELECT と共に s3 テーブル関数 を使用する場合、データはストリーミング方式で読み込まれ、挿入されます。S3からデータを連続的に読み込み、宛先テーブルに押し込む間、メモリには少しのデータブロックのみが存在します。

構文

s3(url [, NOSIGN | access_key_id, secret_access_key, [session_token]] [,format] [,structure] [,compression_method])
s3(named_collection[, option=value [,..]])

:::tip GCS 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' — 文字列。詳細はこちらを参照してください。 :::note GCS GCS のURL形式はGoogle XML APIのエンドポイントがJSON APIと異なるため、以下の形式です：
```
https://storage.googleapis.com/<bucket>/<folder>/<filename(s)>
```
および ~~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。デフォルトでは、ファイル拡張子によって圧縮方法を自動検出します。

引数はまた指定されたコレクションを使用して渡すこともできます。この場合、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 行を選択する：

SELECT *
FROM s3(
   'https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv',
   'CSVWithNames'
)
LIMIT 5;

┌───────Date─┬────Open─┬────High─┬─────Low─┬───Close─┬───Volume─┬─OpenInt─┐
│ 1984-09-07 │ 0.42388 │ 0.42902 │ 0.41874 │ 0.42388 │ 23220030 │       0 │
│ 1984-09-10 │ 0.42388 │ 0.42516 │ 0.41366 │ 0.42134 │ 18022532 │       0 │
│ 1984-09-11 │ 0.42516 │ 0.43668 │ 0.42516 │ 0.42902 │ 42498199 │       0 │
│ 1984-09-12 │ 0.42902 │ 0.43157 │ 0.41618 │ 0.41618 │ 37125801 │       0 │
│ 1984-09-13 │ 0.43927 │ 0.44052 │ 0.43927 │ 0.43927 │ 57822062 │       0 │
└────────────┴─────────┴─────────┴─────────┴─────────┴──────────┴─────────┘

:::note ClickHouse はファイルの形式を決定するためにファイル名の拡張子を使用します。たとえば、前のコマンドを CSVWithNames なしで実行することもできます：

SELECT *
FROM s3(
   'https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv'
)
LIMIT 5;

ClickHouse はファイルの圧縮方法も決定できます。たとえば、ファイルが .csv.gz 拡張子で圧縮されている場合、ClickHouse は自動的にファイルを解凍します。 :::

使用方法

以下の URI を持つ複数のファイルが S3 にあると仮定します:

1から3までの数字で終わるファイルの行数をカウント:

SELECT count(*)
FROM s3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}.csv', 'CSV', 'name String, value UInt32')

┌─count()─┐
│      18 │
└─────────┘

これらの2つのディレクトリ内のすべてのファイルの合計行数をカウント：

SELECT count(*)
FROM s3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/{some,another}_prefix/*', 'CSV', 'name String, value UInt32')

┌─count()─┐
│      24 │
└─────────┘

:::tip ファイルの一覧に先行ゼロ付きの数字範囲が含まれている場合は、各桁ごとに中括弧を使うか ? を使ってください。 :::

ファイル名 file-000.csv, file-001.csv, ... , file-999.csv のファイルの合計行数をカウント：

SELECT count(*)
FROM s3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/big_prefix/file-{000..999}.csv', 'CSV', 'name String, value UInt32');

┌─count()─┐
│      12 │
└─────────┘

ファイル test-data.csv.gz にデータを挿入：

INSERT INTO FUNCTION s3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
VALUES ('test-data', 1), ('test-data-2', 2);

既存のテーブルからファイル test-data.csv.gz にデータを挿入：

INSERT INTO FUNCTION s3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
SELECT name, value FROM existing_table;

グロブ ** を使用して再帰的なディレクトリトラバーサルが可能です。以下の例を考察してください。これは my-test-bucket-768 ディレクトリ内のすべてのファイルを再帰的に取得します:

SELECT * FROM s3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/**', 'CSV', 'name String, value UInt32', 'gzip');

以下のコマンドは、my-test-bucket ディレクトリ内の任意のフォルダー内のすべての test-data.csv.gz ファイルからデータを取得します:

SELECT * FROM s3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/**/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip');

注意点として、サーバー構成ファイル内でカスタムURLマッパーを指定することが可能です。例：

SELECT * FROM s3('s3://clickhouse-public-datasets/my-test-bucket-768/**/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip');

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 に追加できます:

<url_scheme_mappers>
   <s3>
      <to>https://{bucket}.s3.amazonaws.com</to>
   </s3>
   <gs>
      <to>https://{bucket}.storage.googleapis.com</to>
   </gs>
   <oss>
      <to>https://{bucket}.oss.aliyuncs.com</to>
   </oss>
</url_scheme_mappers>

本番環境での使用には指定されたコレクションを使用することをおすすめします。以下に例を示します:


CREATE NAMED COLLECTION creds AS
        access_key_id = '***',
        secret_access_key = '***';
SELECT count(*)
FROM s3(creds, url='https://s3-object-url.csv')

パーティション分けされた書き込み

S3 テーブルにデータを挿入する際に PARTITION BY 式を指定すると、各パーティション値に対して別々のファイルが作成されます。データを別々のファイルに分けることで、読み取り操作の効率が向上します。

例

キーにパーティションIDを使用して別々のファイルが作成されます：

INSERT INTO TABLE FUNCTION
    s3('http://bucket.amazonaws.com/my_bucket/file_{_partition_id}.csv', 'CSV', 'a String, b UInt32, c UInt32')
    PARTITION BY a VALUES ('x', 2, 3), ('x', 4, 5), ('y', 11, 12), ('y', 13, 14), ('z', 21, 22), ('z', 23, 24);

その結果、データは3つのファイルに書き込まれます: file_x.csv, file_y.csv, そして file_z.csv。

バケット名にパーティションIDを使用して、異なるバケットにファイルが作成されます：

INSERT INTO TABLE FUNCTION
    s3('http://bucket.amazonaws.com/my_bucket_{_partition_id}/file.csv', 'CSV', 'a UInt32, b UInt32, c UInt32')
    PARTITION BY a VALUES (1, 2, 3), (1, 4, 5), (10, 11, 12), (10, 13, 14), (20, 21, 22), (20, 23, 24);

その結果、データは異なるバケット内の3つのファイルに書き込まれます: my_bucket_1/file.csv, my_bucket_10/file.csv, そして my_bucket_20/file.csv。

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

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

SELECT *
FROM s3(
   'https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv',
   NOSIGN,
   'CSVWithNames'
)
LIMIT 5;

S3 クレデンシャルの使用 (ClickHouse Cloud)

非公開バケットの場合、ユーザーは aws_access_key_id と aws_secret_access_key を関数に渡すことができます。例：

SELECT count() FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/mta/*.tsv', '<KEY>', '<SECRET>','TSVWithNames')

これは一回限りのアクセスや資格情報を簡単にローテーションできる場合に適しています。しかし、繰り返しのアクセスが必要な長期的な解決策としては推奨されませんし、資格情報が機密である場合も問題です。この場合、ロールベースのアクセスに依存することをおすすめします。

ClickHouse CloudのS3用ロールベースアクセスについてはこちらに記載されています。

設定が完了したら、extra_credentials パラメータを介し roleARN を s3 関数に渡すことができます。例：

SELECT count() FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/mta/*.tsv','CSVWithNames',extra_credentials(role_arn = 'arn:aws:iam::111111111111:role/ClickHouseAccessRole-001'))

さらなる例はこちらで見つけることができます。

アーカイブを扱う

以下のURIのアーカイブファイルがS3にあると想定します：

これらのアーカイブからデータを抽出することが可能です。URLの部分とアーカイブ内のファイル名を指定する部分（::の後）でグロブを使用できます。

SELECT *
FROM s3(
   'https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-1{0..2}.csv.zip :: *.csv'
);

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

仮想カラム

_path — ファイルへのパス。タイプ: LowCardinalty(String)。アーカイブの場合、"{path_to_archive}::{path_to_file_inside_archive}"の形式でパスを表示します。
_file — ファイル名。タイプ: LowCardinalty(String)。アーカイブの場合、アーカイブ内ファイルの名前を表示します。
_size — ファイルのサイズ（バイト単位）。タイプ: Nullable(UInt64)。ファイルサイズが不明な場合、その値は NULL です。アーカイブの場合、アーカイブ内ファイルの非圧縮サイズを示します。
_time — ファイルの最終変更時刻。タイプ: Nullable(DateTime)。時間が不明な場合、その値は NULL です。

Hive 形式のパーティション分割

use_hive_partitioning 設定が1に設定されている場合、ClickHouseはパス内のHive形式のパーティション分割（/name=value/）を検出し、クエリ内でパーティションカラムを仮想カラムとして使用できるようにします。これらの仮想カラムは分割されたパス内と同じ名前を持ちますが、_ で始まります。

例

Hive形式のパーティション分割で作成された仮想カラムを使用する

SET use_hive_partitioning = 1;
SELECT * from s3('s3://data/path/date=*/country=*/code=*/*.parquet') where _date > '2020-01-01' and _country = 'Netherlands' and _code = 42;

ストレージ設定

s3_truncate_on_insert - 挿入前にファイルを切り詰めることを許可します。デフォルトでは無効です。
s3_create_new_file_on_insert - フォーマットに接尾辞がある場合に挿入のたびに新しいファイルを作成することを許可します。デフォルトでは無効です。
s3_skip_empty_files - 読み取り時に空のファイルをスキップすることを許可します。デフォルトでは無効です。

関連項目

S3エンジン

17 KiB Raw Blame History Unescape Escape