thevar1able/ClickHouse
1
0
Fork 0
mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-12-14 02:12:21 +00:00
Code Issues Packages Projects Releases Wiki Activity
1e15312729
ClickHouse/docs/ja/sql-reference/table-functions/s3.md
Miki Matsumoto 1e15312729 add translated Japanese docs
2024-11-18 11:58:58 +09:00

323 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
slug: /ja/sql-reference/table-functions/s3
sidebar_position: 180
sidebar_label: s3
keywords: [s3, gcs, bucket]
---
# s3 テーブル関数
[Amazon S3](https://aws.amazon.com/s3/) と [Google Cloud Storage](https://cloud.google.com/storage/) 内のファイルを選択/挿入するためのテーブルのようなインターフェースを提供します。このテーブル関数は [hdfs 関数](../../sql-reference/table-functions/hdfs.md) に似ていますが、S3 固有の機能を提供します。
クラスターに複数のレプリカがある場合は、挿入を並列化するために[s3Cluster 関数](../../sql-reference/table-functions/s3Cluster.md)を代わりに使用できます。
[`INSERT INTO...SELECT`](../../sql-reference/statements/insert-into#inserting-the-results-of-select) と共に `s3 テーブル関数` を使用する場合、データはストリーミング方式で読み込まれ、挿入されます。S3からデータを連続的に読み込み、宛先テーブルに押し込む間、メモリには少しのデータブロックのみが存在します。
**構文**
``` sql
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 インターオペラビリティ ドキュメント](https://cloud.google.com/storage/docs/interoperability)を参照してください。
GCS の場合、`access_key_id` および `secret_access_key` の場所に HMAC キーおよび HMAC シークレットを置き換えてください。
:::
**パラメータ**
`s3` テーブル関数は以下のプレーンパラメータをサポートします:
- `url` — ファイルへのパスを含むバケットのURL。読み取り専用モードで以下のワイルドカードをサポートします: `*`, `**`, `?`, `{abc,def}` および `{N..M}` ただし `N`, `M` — 数字、 `'abc'`, `'def'` — 文字列。詳細は[こちら](../../engines/table-engines/integrations/s3.md#wildcards-in-path)を参照してください。
:::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` — ファイルの[フォーマット](../../interfaces/formats.md#formats)。
- `structure` — テーブルの構造。フォーマット `'column1_name column1_type, column2_name column2_type, ...'`。
- `compression_method` — パラメータはオプションです。サポートされる値: `none`, `gzip/gz`, `brotli/br`, `xz/LZMA`, `zstd/zst`。デフォルトでは、ファイル拡張子によって圧縮方法を自動検出します。
引数はまた[指定されたコレクション](/docs/ja/operations/named-collections.md)を使用して渡すこともできます。この場合、`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 行を選択する：
``` sql
SELECT *
FROM s3(
'https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv',
'CSVWithNames'
)
LIMIT 5;
```
```response
┌───────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` なしで実行することもできます：
``` sql
SELECT *
FROM s3(
'https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv'
)
LIMIT 5;
```
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までの数字で終わるファイルの行数をカウント:
``` sql
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')
```
``` text
┌─count()─┐
│ 18 │
└─────────┘
```
これらの2つのディレクトリ内のすべてのファイルの合計行数をカウント：
``` sql
SELECT count(*)
FROM s3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/{some,another}_prefix/*', 'CSV', 'name String, value UInt32')
```
``` text
┌─count()─┐
│ 24 │
└─────────┘
```
:::tip
ファイルの一覧に先行ゼロ付きの数字範囲が含まれている場合は、各桁ごとに中括弧を使うか `?` を使ってください。
:::
ファイル名 `file-000.csv`, `file-001.csv`, ... , `file-999.csv` のファイルの合計行数をカウント：
``` sql
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');
```
``` text
┌─count()─┐
│ 12 │
└─────────┘
```
ファイル `test-data.csv.gz` にデータを挿入：
``` sql
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` にデータを挿入：
``` sql
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` ディレクトリ内のすべてのファイルを再帰的に取得します:
``` sql
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` ファイルからデータを取得します:
``` sql
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マッパーを指定することが可能です。例：
``` sql
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` に追加できます:
``` 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>
```
本番環境での使用には[指定されたコレクション](/docs/ja/operations/named-collections.md)を使用することをおすすめします。以下に例を示します:
``` sql
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` 式を指定すると、各パーティション値に対して別々のファイルが作成されます。データを別々のファイルに分けることで、読み取り操作の効率が向上します。
**例**
1. キーにパーティションIDを使用して別々のファイルが作成されます：
```sql
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`。
2. バケット名にパーティションIDを使用して、異なるバケットにファイルが作成されます：
```sql
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` キーワードを使用して、クライアントがすべての資格情報を無視し、リクエストに署名しないように強制することで回避できます。
``` sql
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` を関数に渡すことができます。例：
```sql
SELECT count() FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/mta/*.tsv', '<KEY>', '<SECRET>','TSVWithNames')
```
これは一回限りのアクセスや資格情報を簡単にローテーションできる場合に適しています。しかし、繰り返しのアクセスが必要な長期的な解決策としては推奨されませんし、資格情報が機密である場合も問題です。この場合、ロールベースのアクセスに依存することをおすすめします。
ClickHouse CloudのS3用ロールベースアクセスについては[こちら](/docs/ja/cloud/security/secure-s3#access-your-s3-bucket-with-the-clickhouseaccess-role)に記載されています。
設定が完了したら、`extra_credentials` パラメータを介し `roleARN` を s3 関数に渡すことができます。例：
```sql
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'))
```
さらなる例は[こちら](/docs/ja/cloud/security/secure-s3#access-your-s3-bucket-with-the-clickhouseaccess-role)で見つけることができます。
## アーカイブを扱う
以下の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の部分とアーカイブ内のファイル名を指定する部分（::の後）でグロブを使用できます。
``` sql
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がインストールされているローカルファイルシステムからのみ読み取ることができます。
:::
## 仮想カラム {#virtual-columns}
- `_path` — ファイルへのパス。タイプ: `LowCardinalty(String)`。アーカイブの場合、"{path_to_archive}::{path_to_file_inside_archive}"の形式でパスを表示します。
- `_file` — ファイル名。タイプ: `LowCardinalty(String)`。アーカイブの場合、アーカイブ内ファイルの名前を表示します。
- `_size` — ファイルのサイズ（バイト単位）。タイプ: `Nullable(UInt64)`。ファイルサイズが不明な場合、その値は `NULL` です。アーカイブの場合、アーカイブ内ファイルの非圧縮サイズを示します。
- `_time` — ファイルの最終変更時刻。タイプ: `Nullable(DateTime)`。時間が不明な場合、その値は `NULL` です。
## Hive 形式のパーティション分割 {#hive-style-partitioning}
`use_hive_partitioning` 設定が1に設定されている場合、ClickHouseはパス内のHive形式のパーティション分割（`/name=value/`）を検出し、クエリ内でパーティションカラムを仮想カラムとして使用できるようにします。これらの仮想カラムは分割されたパス内と同じ名前を持ちますが、`_` で始まります。
**例**
Hive形式のパーティション分割で作成された仮想カラムを使用する
``` sql
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;
```
## ストレージ設定 {#storage-settings}
- [s3_truncate_on_insert](/docs/ja/operations/settings/settings.md#s3_truncate_on_insert) - 挿入前にファイルを切り詰めることを許可します。デフォルトでは無効です。
- [s3_create_new_file_on_insert](/docs/ja/operations/settings/settings.md#s3_create_new_file_on_insert) - フォーマットに接尾辞がある場合に挿入のたびに新しいファイルを作成することを許可します。デフォルトでは無効です。
- [s3_skip_empty_files](/docs/ja/operations/settings/settings.md#s3_skip_empty_files) - 読み取り時に空のファイルをスキップすることを許可します。デフォルトでは無効です。
**関連項目**
- [S3エンジン](../../engines/table-engines/integrations/s3.md)
Reference in New Issue View Git Blame Copy Permalink