> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> [s3](/reference/functions/table-functions/url) テーブル関数と同様に、ファイルに対して `SELECT` したりファイルへ `INSERT` したりできるテーブル形式インターフェイスを提供するテーブルエンジンです。ローカルファイルを扱う場合は `file()` を使用し、S3、GCS、MinIO などのオブジェクトストレージ内のバケットを扱う場合は `s3()` を使用します。

# file テーブル関数

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Not supported in ClickHouse Cloud
        </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Experimental feature. <u><a href="/docs/beta-and-experimental-features#experimental-features">Learn more.</a></u>
        </div>;
};

[s3](/ja/reference/functions/table-functions/url) テーブル関数と同様に、ファイルに対して `SELECT` したりファイルへ `INSERT` したりできるテーブル形式インターフェイスを提供するテーブルエンジンです。ローカルファイルを扱う場合は `file()` を使用し、S3、GCS、MinIO などのオブジェクトストレージ内のバケットを扱う場合は `s3()` を使用します。

`file` 関数は、`SELECT` クエリおよび `INSERT` クエリで使用でき、ファイルの読み取りや書き込みを行えます。

<div id="syntax">
  ## 構文
</div>

```sql theme={null}
file([path_to_archive ::] path [,format] [,structure] [,compression])
```

`SELECT` クエリでは、`path` に `Array(String)` を返す式を指定することもできます。

```sql theme={null}
file(['file1.csv', 'file2.csv'], 'CSV', 'column1 UInt32, column2 UInt32')
```

<div id="arguments">
  ## 引数
</div>

| Parameter         | Description                                                                                                                                                                                                                                                                 |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path`            | [user\_files\_path](/ja/reference/settings/server-settings/settings#user_files_path) からのファイルへの相対パス、または `SELECT` クエリで使用するパスの `Array(String)` です。読み取り専用モードでは、次の [グロブ](#globs-in-path) をサポートします: `*`, `?`, `{abc,def}` (`'abc'` と `'def'` は文字列) および `{N..M}` (`N` と `M` は数値) 。 |
| `path_to_archive` | zip/tar/7z アーカイブへの相対パスです。`path` と同じ グロブ をサポートします。                                                                                                                                                                                                                           |
| `format`          | ファイルの [フォーマット](/ja/reference/formats) です。                                                                                                                                                                                                                                   |
| `structure`       | テーブル構造です。形式: `'column1_name column1_type, column2_name column2_type, ...'`。                                                                                                                                                                                                 |
| `compression`     | `SELECT` クエリで使用する場合は既存の圧縮タイプ、`INSERT` クエリで使用する場合は目的の圧縮タイプです。サポートされる圧縮タイプは `gz`, `br`, `xz`, `zst`, `lz4`, `bz2` です。                                                                                                                                                         |

<Tip>
  `structure` 引数を省略すると、ClickHouse はフォーマット自体からスキーマを推論します。
  フォーマットごとに、デフォルトのカラム名と型は異なります。
  特定のフォーマットのスキーマを確認するには、[`format`](/ja/reference/functions/table-functions/format) テーブル関数に対して [`DESC`](/ja/reference/statements/describe-table) を使用します。

  たとえば:

  ```sql theme={null}
  DESC format(LineAsString, 'Hello\nWorld')
  ```

  ```response theme={null}
  ┌─name─┬─type───┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
  │ line │ String │              │                    │         │                  │                │
  └──────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
  ```
</Tip>

<div id="returned_value">
  ## 戻り値
</div>

ファイル内のデータを読み書きするためのテーブルです。

<div id="examples-for-writing-to-a-file">
  ## File への書き込み例
</div>

<div id="write-to-a-tsv-file">
  ### TSVファイルに書き込む
</div>

```sql theme={null}
INSERT INTO TABLE FUNCTION
file('test.tsv', 'TSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
VALUES (1, 2, 3), (3, 2, 1), (1, 3, 2)
```

その結果、データはファイル `test.tsv` に書き込まれます。

```bash theme={null}
# cat /var/lib/clickhouse/user_files/test.tsv
1    2    3
3    2    1
1    3    2
```

<div id="partitioned-write-to-multiple-tsv-files">
  ### 複数のTSVファイルへのパーティション別書き込み
</div>

`file()` 型のテーブル関数にデータを挿入する際に `PARTITION BY` 式を指定すると、パーティションごとに別々のファイルが作成されます。データをファイルごとに分割することで、読み取り処理のパフォーマンス向上に役立ちます。

```sql theme={null}
INSERT INTO TABLE FUNCTION
file('test_{_partition_id}.tsv', 'TSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
PARTITION BY column3
VALUES (1, 2, 3), (3, 2, 1), (1, 3, 2)
```

その結果、データは `test_1.tsv`、`test_2.tsv`、`test_3.tsv` の3つのファイルに書き込まれます。

```bash theme={null}
# cat /var/lib/clickhouse/user_files/test_1.tsv
3    2    1

# cat /var/lib/clickhouse/user_files/test_2.tsv
1    3    2

# cat /var/lib/clickhouse/user_files/test_3.tsv
1    2    3
```

<div id="examples-for-reading-from-a-file">
  ## ファイルから読み込む例
</div>

<div id="select-from-a-csv-file">
  ### CSVファイルからSELECT
</div>

まず、サーバー設定で `user_files_path` を設定し、`test.csv` ファイルを用意します:

```bash theme={null}
$ grep user_files_path /etc/clickhouse-server/config.xml
    <user_files_path>/var/lib/clickhouse/user_files/</user_files_path>

$ cat /var/lib/clickhouse/user_files/test.csv
    1,2,3
    3,2,1
    78,43,45
```

次に、`test.csv` からテーブルにデータを読み込み、先頭の2行を取得します:

```sql theme={null}
SELECT * FROM
file('test.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
LIMIT 2;
```

```text theme={null}
┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘
```

<div id="inserting-data-from-a-file-into-a-table">
  ### ファイルからテーブルへデータを挿入する
</div>

```sql theme={null}
INSERT INTO FUNCTION
file('test.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
VALUES (1, 2, 3), (3, 2, 1);
```

```sql theme={null}
SELECT * FROM
file('test.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32');
```

```text theme={null}
┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘
```

`archive1.zip` または `archive2.zip` に含まれる `table.csv` からデータを読み取る:

```sql theme={null}
SELECT * FROM file('user_files/archives/archive{1..2}.zip :: table.csv');
```

<div id="globs-in-path">
  ## パス内のグロブ
</div>

パスではグロブを使用できます。ファイルは、接尾辞やプレフィックスだけでなく、パスパターン全体に一致する必要があります。例外が 1 つあり、パスが既存の
ディレクトリを指していてグロブを使用していない場合は、`*` が暗黙的にパスに追加されるため、
ディレクトリ内のすべてのファイルが選択されます。

* `*` — 空文字列を含み、`/` を除く任意の長さの文字列を表します。
* `?` — 任意の 1 文字を表します。
* `{some_string,another_string,yet_another_one}` — 文字列 `'some_string'`、`'another_string'`、`'yet_another_one'` のいずれかに置き換えられます。これらの文字列には `/` 記号を含めることができます。
* `{N..M}` — `>= N` かつ `<= M` の任意の数を表します。
* `**` - フォルダ内のすべてのファイルを再帰的に表します。

`{}` を使った構文は、[remote](/ja/reference/functions/table-functions/remote) および [hdfs](/ja/reference/functions/table-functions/hdfs) テーブル関数と似ています。

<div id="examples">
  ## 例
</div>

**例**

次の相対パスを持つファイルがあるとします。

* `some_dir/some_file_1`
* `some_dir/some_file_2`
* `some_dir/some_file_3`
* `another_dir/some_file_1`
* `another_dir/some_file_2`
* `another_dir/some_file_3`

すべてのファイルに含まれる行数の合計を取得するクエリ:

```sql theme={null}
SELECT count(*) FROM file('{some,another}_dir/some_file_{1..3}', 'TSV', 'name String, value UInt32');
```

同じことを実現できる別のパス式:

```sql theme={null}
SELECT count(*) FROM file('{some,another}_dir/*', 'TSV', 'name String, value UInt32');
```

暗黙の `*` を使用して、`some_dir` の総行数をクエリします。

```sql theme={null}
SELECT count(*) FROM file('some_dir', 'TSV', 'name String, value UInt32');
```

<Note>
  ファイルの一覧に先頭ゼロ付きの数値範囲が含まれる場合は、各桁ごとに波かっこを使った構文を使用するか、`?` を使用してください。
</Note>

**例**

`file000`、`file001`、...、`file999` という名前のファイルの行数の合計をクエリします:

```sql theme={null}
SELECT count(*) FROM file('big_dir/file{0..9}{0..9}{0..9}', 'CSV', 'name String, value UInt32');
```

**例**

`big_dir/` ディレクトリ内のすべてのファイルを再帰的に対象として、合計行数をクエリします:

```sql theme={null}
SELECT count(*) FROM file('big_dir/**', 'CSV', 'name String, value UInt32');
```

**例**

ディレクトリ `big_dir/` 内の任意のフォルダにある `file002` ファイルすべてを再帰的に対象にして、合計行数をクエリします:

```sql theme={null}
SELECT count(*) FROM file('big_dir/**/file002', 'CSV', 'name String, value UInt32');
```

<div id="virtual-columns">
  ## 仮想カラム
</div>

* `_path` — ファイルのパス。型: `LowCardinality(String)`.
* `_file` — ファイル名。型: `LowCardinality(String)`.
* `_size` — ファイルサイズ (バイト単位) 。型: `Nullable(UInt64)`. ファイルサイズが不明な場合、値は `NULL` です。
* `_time` — ファイルの最終更新時刻。型: `Nullable(DateTime)`. 時刻が不明な場合、値は `NULL` です。

<div id="hive-style-partitioning">
  ## use\_hive\_partitioning 設定
</div>

`use_hive_partitioning` 設定が 1 に設定されている場合、ClickHouse はパス (`/name=value/`) 内の Hive スタイルのパーティション化を検出し、クエリでパーティションカラムを仮想カラムとして使用できるようになります。これらの仮想カラムは、パーティション化されたパス内の名前と同じ名前になります。

**例**

Hive スタイルのパーティション化で作成された仮想カラムを使用する

```sql theme={null}
SELECT * FROM file('data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;
```

<div id="settings">
  ## 設定
</div>

| Setting                                                                                                                         | Description                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [engine\_file\_empty\_if\_not\_exists](/ja/reference/settings/session-settings#engine_file_empty_if_not_exists)                 | 存在しないファイルを空データとして扱えるようにします。デフォルトでは無効です。                                                                                                                       |
| [engine\_file\_truncate\_on\_insert](/ja/reference/settings/session-settings#engine_file_truncate_on_insert)                    | ファイルへの insert の前に、そのファイルを切り詰められるようにします。デフォルトでは無効です。                                                                                                           |
| [engine\_file\_allow\_create\_multiple\_files](/ja/reference/settings/session-settings#engine_file_allow_create_multiple_files) | フォーマットに接尾辞がある場合、insert のたびに新しいファイルを作成できるようにします。デフォルトでは無効です。                                                                                                   |
| [engine\_file\_skip\_empty\_files](/ja/reference/settings/session-settings#engine_file_skip_empty_files)                        | 読み取り時に空のファイルをスキップできるようにします。デフォルトでは無効です。                                                                                                                       |
| [storage\_file\_read\_method](/ja/reference/settings/session-settings#engine_file_empty_if_not_exists)                          | ストレージファイルからデータを読み取る method です。`read`、`pread`、`mmap` のいずれかを指定します (`clickhouse-local` のみ) 。デフォルト値: `clickhouse-server` では `pread`、`clickhouse-local` では `mmap`。 |

<div id="related">
  ## 関連
</div>

* [仮想カラム](/ja/reference/engines/table-engines#table_engines-virtual_columns)
* [処理後にファイル名を変更する](/ja/reference/settings/session-settings#rename_files_after_processing)