メインコンテンツまでスキップ
メインコンテンツまでスキップ

file Table Function

ファイルからSELECTおよびINSERTするためのテーブルのようなインターフェースを提供するテーブルエンジンで、s3テーブル関数に似ています。ローカルファイルを扱う際はfile()を、S3、GCS、またはMinIOのようなオブジェクトストレージ内のバケットを扱う際はs3()を使用します。

file関数は、ファイルから読み取ったり書き込んだりするために、SELECTおよびINSERTクエリで使用できます。

Syntax​

file([path_to_archive ::] path [,format] [,structure] [,compression])

Arguments​

パラメーター説明
pathuser_files_pathからのファイルへの相対パス。読み取り専用モードで次のグロブがサポートされています：*、?、{abc,def}（ここで'abc'および'def'は文字列）および{N..M}（ここでNおよびMは数値）。
path_to_archivezip/tar/7zアーカイブへの相対パス。pathと同様のグロブがサポートされています。
formatファイルのフォーマット。
structureテーブルの構造。フォーマット：'column1_name column1_type, column2_name column2_type, ...'。
compressionSELECTクエリで使用される既存の圧縮タイプ、またはINSERTクエリで使用される際の希望する圧縮タイプ。サポートされている圧縮タイプはgz、br、xz、zst、lz4、およびbz2です。

Returned value​

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

Examples for Writing to a File​

Write to a TSV file​

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に書き込まれます：


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

Partitioned write to multiple TSV files​

file()タイプのテーブル関数にデータを挿入する際にPARTITION BY式を指定すると、各パーティションに対して別のファイルが作成されます。データを別々のファイルに分割すると、読み取り操作のパフォーマンスが向上します。

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)

結果として、データは3つのファイルに書き込まれます：test_1.tsv、test_2.tsv、およびtest_3.tsv。


# 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

Examples for Reading from a File​

SELECT from a CSV file​

まず、サーバー設定でuser_files_pathを設定し、test.csvファイルを準備します：

$ 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行を選択します：

SELECT * FROM
file('test.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
LIMIT 2;

┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

Inserting data from a file into a table​

INSERT INTO FUNCTION
file('test.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
VALUES (1, 2, 3), (3, 2, 1);

SELECT * FROM
file('test.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32');

┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

archive1.zipまたは/およびarchive2.zipにあるtable.csvからデータを読み取ります：

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

Globs in path​

パスはグロビングを使用できます。ファイルは全体のパスパターンと一致しなければなりません。サフィックスやプレフィックスのみではありません。1つだけ例外があり、パスが存在するディレクトリを参照しており、グロブを使用しない場合、*が暗黙的にパスに追加され、ディレクトリ内のすべてのファイルが選択されます。

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

{}を含む構造は、remoteおよびhdfsテーブル関数に似ています。

Examples​

Example

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

  • 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

すべてのファイルの総行数をクエリします：

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

同じ結果を得る別のパス表現：

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

暗黙的*を使用してsome_dirの総行数をクエリします：

SELECT count(*) FROM file('some_dir', 'TSV', 'name String, value UInt32');
注記

ファイルリストに先頭ゼロの数字範囲が含まれている場合は、各桁に対してブレースを使用するか、?を使用してください。

Example

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

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

Example

ディレクトリbig_dir/内のすべてのファイルの総行数を再帰的にクエリします：

SELECT count(*) FROM file('big_dir/**', 'CSV', 'name String, value UInt32');

Example

ディレクトリbig_dir/内の任意のフォルダにあるfile002という名前のすべてのファイルの総行数を再帰的にクエリします：

SELECT count(*) FROM file('big_dir/**/file002', 'CSV', 'name String, value UInt32');

Virtual Columns​

  • _path — ファイルへのパス。タイプ：LowCardinality(String)。
  • _file — ファイルの名前。タイプ：LowCardinality(String)。
  • _size — ファイルのサイズ（バイト単位）。タイプ：Nullable(UInt64)。ファイルサイズが不明な場合、値はNULLです。
  • _time — ファイルの最終更新時刻。タイプ：Nullable(DateTime)。時間が不明な場合、値はNULLです。

Hive-style partitioning​

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

Example

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

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

Settings​

設定説明
engine_file_empty_if_not_exists存在しないファイルから空のデータを選択することを許可します。デフォルトでは無効です。
engine_file_truncate_on_insert挿入の前にファイルを切り捨てることを許可します。デフォルトでは無効です。
engine_file_allow_create_multiple_filesフォーマットがサフィックスを持つ場合に、各挿入ごとに新しいファイルを作成することを許可します。デフォルトでは無効です。
engine_file_skip_empty_files読み取り中に空のファイルをスキップすることを許可します。デフォルトでは無効です。
storage_file_read_methodストレージファイルからデータを読み取る方法の設定の1つ：read、pread、mmap（clickhouse-local専用）。デフォルト値：preadはclickhouse-serverのため、mmapはclickhouse-localのため。