ClickHouse/docs/ja/engines/table-engines/integrations/s3.md

---
slug: /ja/engines/table-engines/integrations/s3
sidebar_position: 180
sidebar_label: S3
---

# S3 テーブルエンジン

このエンジンは [Amazon S3](https://aws.amazon.com/s3/) エコシステムとの統合を提供します。このエンジンは [HDFS](../../../engines/table-engines/special/file.md#table_engines-hdfs) エンジンに似ていますが、S3特有の機能を提供します。

## 例

``` sql
CREATE TABLE s3_engine_table (name String, value UInt32)
    ENGINE=S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'gzip')
    SETTINGS input_format_with_names_use_header = 0;

INSERT INTO s3_engine_table VALUES ('one', 1), ('two', 2), ('three', 3);

SELECT * FROM s3_engine_table LIMIT 2;
```

```text
┌─name─┬─value─┐
│ one  │     1 │
│ two  │     2 │
└──────┴───────┘
```

## テーブルの作成 {#creating-a-table}

``` sql
CREATE TABLE s3_engine_table (name String, value UInt32)
    ENGINE = S3(path [, NOSIGN | aws_access_key_id, aws_secret_access_key,] format, [compression])
    [PARTITION BY expr]
    [SETTINGS ...]
```

### エンジンのパラメータ {#parameters}

- `path` — ファイルへのパスを含むバケットURL。以下のワイルドカードを読み取り専用モードでサポートします：`*`, `**`, `?`, `{abc,def}` および `{N..M}`（`N`, `M` は数値、 `'abc'`, `'def'` は文字列）。詳細は[下記](#wildcards-in-path)を参照してください。
- `NOSIGN` - このキーワードがクレデンシャルの代わりに指定されている場合、すべてのリクエストは署名されません。
- `format` — ファイルの[フォーマット](../../../interfaces/formats.md#formats)。
- `aws_access_key_id`, `aws_secret_access_key` - [AWS](https://aws.amazon.com/) アカウントユーザーの長期クレデンシャル。これを使用してリクエストの認証が可能です。このパラメータはオプションです。クレデンシャルが指定されていない場合、設定ファイルから使用されます。詳細は[Using S3 for Data Storage](../mergetree-family/mergetree.md#table_engine-mergetree-s3)を参照してください。
- `compression` — 圧縮タイプ。サポートされる値は `none`, `gzip/gz`, `brotli/br`, `xz/LZMA`, `zstd/zst`。このパラメータはオプションで、デフォルトではファイル拡張子によって圧縮形式を自動的に検出します。

### データキャッシュ {#data-cache}

`S3` テーブルエンジンはローカルディスクへのデータキャッシュをサポートします。
ファイルシステムキャッシュの構成オプションと使用法については、この[セクション](/docs/ja/operations/storing-data.md/#using-local-cache)を参照してください。
キャッシュはパスとストレージオブジェクトのETagに基づいて行われるため、ClickHouseは古いキャッシュバージョンを読みません。

キャッシュを有効にするには、設定 `filesystem_cache_name = '<name>'` と `enable_filesystem_cache = 1` を使用してください。

```sql
SELECT *
FROM s3('http://minio:10000/clickhouse//test_3.csv', 'minioadmin', 'minioadminpassword', 'CSV')
SETTINGS filesystem_cache_name = 'cache_for_s3', enable_filesystem_cache = 1;
```

構成ファイルでキャッシュを定義する方法は2つあります。

1. 次のセクションをClickHouseの構成ファイルに追加します：

``` xml
<clickhouse>
    <filesystem_caches>
        <cache_for_s3>
            <path>キャッシュディレクトリへのパス</path>
            <max_size>10Gi</max_size>
        </cache_for_s3>
    </filesystem_caches>
</clickhouse>
```

2. ClickHouseの `storage_configuration` セクションからキャッシュ構成を再利用し、キャッシュストレージを使用します。詳細は[こちら](/docs/ja/operations/storing-data.md/#using-local-cache)をご覧ください。

### PARTITION BY

`PARTITION BY` — オプションです。ほとんどの場合、分割キーは必要ありませんが、必要な場合でも通常は1ヶ月単位より細かい分割キーは必要ありません。パーティショニングはクエリの高速化に寄与しません（ORDER BY 表現とは対照的に）。決して細かすぎるパーティショニングを使ってはいけません。クライアントIDや名前でデータを分割するのではなく、クライアントIDや名前を ORDER BY 表現の最初のカラムにするべきです。

月単位で分割するには、`toYYYYMM(date_column)` 式を使用します。ここで `date_column` は [Date](/docs/ja/sql-reference/data-types/date.md) 型の日付を持つカラムです。ここでのパーティション名は `"YYYYMM"` フォーマットです。

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

この例は、ClickHouseとMinIOを統合する[ドッカーコンポーズレシピ](https://github.com/ClickHouse/examples/tree/5fdc6ff72f4e5137e23ea075c88d3f44b0202490/docker-compose-recipes/recipes/ch-and-minio-S3)を使用します。同じクエリを使用して、エンドポイントや認証値を置き換えることで、S3を利用することができます。

`ENGINE` 構成のS3エンドポイントには、S3オブジェクト（ファイル名）の一部として `_partition_id` パラメータトークンを使用し、それらの結果オブジェクト名（例：`test_3.csv`）を選択します。

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

主なユースケースは、S3でパーティション化されたデータを書き込むことにより、データを他の ClickHouseシステムに転送すること（例えば、オンプレミスシステムからClickHouse Cloudに移行）です。ClickHouseのデータセットは非常に大きいことが多いため、ネットワークの信頼性が欠けることもあるので、データセットを部分ごとに転送するのが合理的です。したがって、パーティション化された書き込みが役立ちます。
:::

#### テーブルの作成
```sql
CREATE TABLE p
(
    `column1` UInt32,
    `column2` UInt32,
    `column3` UInt32
)
ENGINE = S3(
# highlight-next-line
           'http://minio:10000/clickhouse//test_{_partition_id}.csv',
           'minioadmin',
           'minioadminpassword',
           'CSV')
PARTITION BY column3
```

#### データの挿入
```sql
insert into p values (1, 2, 3), (3, 2, 1), (78, 43, 45)
```

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

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

```sql
SELECT *
FROM s3('http://minio:10000/clickhouse//test_3.csv', 'minioadmin', 'minioadminpassword', 'CSV')
```
```response
┌─c1─┬─c2─┬─c3─┐
│  1 │  2 │  3 │
└────┴────┴────┘
```

#### パーティション 1 からの選択
```sql
SELECT *
FROM s3('http://minio:10000/clickhouse//test_1.csv', 'minioadmin', 'minioadminpassword', 'CSV')
```
```response
┌─c1─┬─c2─┬─c3─┐
│  3 │  2 │  1 │
└────┴────┴────┘
```

#### パーティション 45 からの選択
```sql
SELECT *
FROM s3('http://minio:10000/clickhouse//test_45.csv', 'minioadmin', 'minioadminpassword', 'CSV')
```
```response
┌─c1─┬─c2─┬─c3─┐
│ 78 │ 43 │ 45 │
└────┴────┴────┘
```

#### 制限

当然 `Select * from p` を試してみたくなるかもしれませんが、前述の通り、このクエリは失敗します。前のクエリを使用してください。

```sql
SELECT * FROM p
```
```response
Received exception from server (version 23.4.1):
Code: 48. DB::Exception: Received from localhost:9000. DB::Exception: Reading from a partitioned S3 storage is not implemented yet. (NOT_IMPLEMENTED)
```

## 仮想カラム {#virtual-columns}

- `_path` — ファイルへのパス。型: `LowCardinalty(String)`。
- `_file` — ファイル名。型: `LowCardinalty(String)`。
- `_size` — ファイルのバイト単位のサイズ。型: `Nullable(UInt64)`。サイズが不明な場合、値は `NULL`。
- `_time` — ファイルの最終変更時間。型: `Nullable(DateTime)`。時間が不明な場合、値は `NULL`。
- `_etag` — ファイルのETag。型: `LowCardinalty(String)`。ETagが不明な場合、値は `NULL`。

仮想カラムについての詳細は[こちら](../../../engines/table-engines/index.md#table_engines-virtual_columns)をご覧ください。

## 実装の詳細 {#implementation-details}

- 読み書きは並行して行うことが可能
- サポートされていません:
    - `ALTER` および `SELECT...SAMPLE` 操作。
    - インデックス。
    - [ゼロコピーの](../../../operations/storing-data.md#zero-copy)レプリケーションは可能ですが、サポートされていません。

  :::note
  プロダクションにはゼロコピーのレプリケーションは推奨されません
  ゼロコピーのレプリケーションはClickHouseバージョン22.8以降でデフォルトで無効になっています。この機能はプロダクション環境での使用は推奨されません。
  :::

## パス内のワイルドカード {#wildcards-in-path}

`path` 引数はbashのようなワイルドカードを用いて複数のファイルを指定できます。処理されるためには、ファイルが存在し、パスパターン全体に一致する必要があります。ファイルのリストは `SELECT` 時に決定されます（`CREATE` の時点ではありません）。

- `*` — `/` を除く任意の数の任意の文字を空文字列も含めて代替します。
- `**` — `/` を含む任意の数の任意の文字を空文字列も含めて代替します。
- `?` — 任意の単一の文字を代替します。
- `{some_string,another_string,yet_another_one}` — 文字列 `'some_string', 'another_string', 'yet_another_one'` のいずれかを代替します。
- `{N..M}` — NからMまでの範囲のいずれかの数を含む。範囲にはNとMも含まれます。NおよびMは先頭にゼロを含めることができます（例：`000..078`）。

`{}` を使った構造は、[remote](../../../sql-reference/table-functions/remote.md) テーブル関数に似ています。

:::note
ファイルのリストに先頭にゼロがある数値の範囲を含む場合、各桁ごとにかっこで構成するか、または `?` を使用してください。
:::

**ワイルドカードを使用した例 1**

ファイル名が `file-000.csv`, `file-001.csv`, ... , `file-999.csv` のファイルを持つテーブルを作成します。

``` sql
CREATE TABLE big_table (name String, value UInt32)
    ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/my_folder/file-{000..999}.csv', 'CSV');
```

**ワイルドカードを使用した例 2**

S3にはCSVフォーマットの以下のURIを持ついくつかのファイルがあるとします：

- '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'

これら6つのファイルを構成するテーブルを作成する方法は以下の通りです：

1. ファイルの接尾辞の範囲を指定します：

``` sql
CREATE TABLE table_with_range (name String, value UInt32)
    ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/some_file_{1..3}', 'CSV');
```

2. `some_file_` プレフィックスを持つすべてのファイルを取得します（両方のフォルダーにそのようなプレフィックスの余分なファイルがないことを確認してください）：

``` sql
CREATE TABLE table_with_question_mark (name String, value UInt32)
    ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/some_file_?', 'CSV');
```

3. 両方のフォルダ内のすべてのファイルを取得します（すべてのファイルがクエリで説明されているフォーマットとスキーマを満たす必要があります）：

``` sql
CREATE TABLE table_with_asterisk (name String, value UInt32)
    ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/*', 'CSV');
```

## ストレージ設定 {#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に関連した設定 {#settings}

以下の設定はクエリ実行前に設定できるか、設定ファイルに配置できます。

- `s3_max_single_part_upload_size` — S3への単一パートアップロードを使用したオブジェクトをアップロードする際の最大サイズ。デフォルト値は `32Mb`。
- `s3_min_upload_part_size` — [S3マルチパートアップロード](https://docs.aws.amazon.com/AmazonS3/latest/dev/uploadobjusingmpu.html)中にアップロードするパートの最小サイズ。デフォルト値は `16Mb`。
- `s3_max_redirects` — 許可されるS3リダイレクトホップの最大数。デフォルト値は `10`。
- `s3_single_read_retries` — 単一の読み取り中の試行最大数。デフォルト値は `4`。
- `s3_max_put_rps` — スロットリング前の1秒あたりの最大PUTリクエスト数。デフォルト値は `0` (無制限)。
- `s3_max_put_burst` — 秒単位のリクエスト制限に達する前に同時に発行できる最大リクエスト数。デフォルトでは (`0`値) `s3_max_put_rps` に等しい。
- `s3_max_get_rps` — スロットリング前の1秒あたりの最大GETリクエスト数。デフォルト値は `0` (無制限)。
- `s3_max_get_burst` — 秒単位のGETリクエスト制限に達する前に同時に発行できる最大リクエスト数。デフォルトでは (`0`値) `s3_max_get_rps` に等しい。
- `s3_upload_part_size_multiply_factor` - S3に一度に書き込みされた後に `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` を参照してください。デフォルト設定で、アップロードされるファイルは `8G`未満の場合は `320Mb`以上を消費しません。消費はより大きなファイルにはさらに大きくなります。

セキュリティの考慮点: 任意のS3 URLを指定可能な悪意のあるユーザーがいた場合、`s3_max_redirects` をゼロに設定して [SSRF](https://en.wikipedia.org/wiki/Server-side_request_forgery) 攻撃を回避する必要があります。または、サーバー構成で `remote_host_filter` を指定する必要があります。

## エンドポイントベースの設定 {#endpoint-settings}

以下の設定は、特定のエンドポイント（URLの正確なプレフィックスと一致する）に対して構成ファイルで指定できます：

- `endpoint` — エンドポイントのプレフィックスを指定します。必須です。
- `access_key_id` と `secret_access_key` — 特定のエンドポイントに使用するクレデンシャルを指定します。任意です。
- `use_environment_credentials` — `true` に設定されている場合、S3クライアントは環境変数と [Amazon EC2](https://en.wikipedia.org/wiki/Amazon_Elastic_Compute_Cloud) メタデータからクレデンシャルを取得しようとします。任意です。デフォルト値は `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` — 指定された場合、SSE-C暗号化でS3オブジェクトにアクセスするために必要なヘッダーがセットされます。任意です。
- `server_side_encryption_kms_key_id` - 指定された場合、[SSE-KMS暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html)された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` - 特定のエンドポイントに対してクエリ単位ではなく使用するスロットリング設定（上記説明参照）。任意です。

**例:**

``` xml
<s3>
    <endpoint-name>
        <endpoint>https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/</endpoint>
        <!-- <access_key_id>ACCESS_KEY_ID</access_key_id> -->
        <!-- <secret_access_key>SECRET_ACCESS_KEY</secret_access_key> -->
        <!-- <region>us-west-1</region> -->
        <!-- <use_environment_credentials>false</use_environment_credentials> -->
        <!-- <use_insecure_imds_request>false</use_insecure_imds_request> -->
        <!-- <expiration_window_seconds>120</expiration_window_seconds> -->
        <!-- <no_sign_request>false</no_sign_request> -->
        <!-- <header>Authorization: Bearer SOME-TOKEN</header> -->
        <!-- <server_side_encryption_customer_key_base64>BASE64-ENCODED-KEY</server_side_encryption_customer_key_base64> -->
        <!-- <server_side_encryption_kms_key_id>KMS_KEY_ID</server_side_encryption_kms_key_id> -->
        <!-- <server_side_encryption_kms_encryption_context>KMS_ENCRYPTION_CONTEXT</server_side_encryption_kms_encryption_context> -->
        <!-- <server_side_encryption_kms_bucket_key_enabled>true</server_side_encryption_kms_bucket_key_enabled> -->
        <!-- <max_single_read_retries>4</max_single_read_retries> -->
    </endpoint-name>
</s3>
```

## アーカイブの操作

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

- '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がインストールされているローカルファイルシステムからのみ読み取ることができます。
:::


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

ClickHouseはさまざまな種類のソースからクレデンシャルを取得しようとします。
時として、このことが、パブリックでアクセスできる一部のバケットにアクセスする際に問題を引き起こし、クライアントが `403` エラーコードを返すことがあります。
この問題は、`NOSIGN` キーワードを使用して、クライアントがすべてのクレデンシャルを無視し、リクエストにサインをしないようにすることで回避できます。

``` sql
CREATE TABLE big_table (name String, value UInt32)
    ENGINE = S3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv', NOSIGN, 'CSVWithNames');
```

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

s3 関数のパフォーマンス最適化に関する詳細は[詳細ガイド](/docs/ja/integrations/s3/performance)をご覧ください。

## 関連情報

- [s3 テーブル関数](../../../sql-reference/table-functions/s3.md)