メインコンテンツへスキップ
メインコンテンツへスキップ

file テーブル関数

s3 テーブル関数と同様に、ファイルに対する SELECT や INSERT をテーブルと同じように扱えるインターフェイスを提供するテーブルエンジンです。ローカルファイルを扱う場合は file() を使用し、S3、GCS、MinIO などのオブジェクトストレージ内のバケットを扱う場合は s3 のテーブル関数 s3() を使用します。

file 関数は、SELECT および INSERT クエリで使用して、ファイルからの読み取りやファイルへの書き込みを行うことができます。

構文​

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

引数​

パラメータ説明
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 です。

戻り値​

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

ファイルへの書き込み例​

TSV ファイルへの書き込み​

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 \{#cat-varlibclickhouseuser_filestesttsv}
1    2    3
3    2    1
1    3    2

複数の TSV ファイルへのパーティション分割書き込み​

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 \{#cat-varlibclickhouseuser_filestest_1tsv}
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

ファイルから読み込む例​

CSV ファイルからの SELECT​

まず、サーバー設定で 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 │
└─────────┴─────────┴─────────┘

ファイルからテーブルにデータを挿入する​

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

パス内のグロブ​

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

  • * — / 以外の任意の長さ（空文字列を含む）の文字列を表します。
  • ? — 任意の 1 文字を表します。
  • {some_string,another_string,yet_another_one} — 文字列 'some_string', 'another_string', 'yet_another_one' のいずれかに置き換えられます。これらの文字列には / 記号を含めることができます。
  • {N..M} — >= N かつ <= M の任意の数値を表します。
  • ** — ディレクトリ配下のすべてのファイルを再帰的に表します。

{} を用いる構文は、remote および hdfs テーブル関数と同様です。

例​

例

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

  • 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');
注記

ファイル一覧に先頭ゼロ付きの番号範囲が含まれている場合は、各桁を個別に中かっこで指定する構文を使うか、? を使用してください。

例

file000、file001、...、file999 という名前のファイルに含まれる行数の合計をクエリします。

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

例

big_dir/ ディレクトリ配下のすべてのファイルに対して、再帰的に行数の合計をクエリします。

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

例

ディレクトリ big_dir/ 以下のすべてのフォルダに含まれる file002 ファイルの全行数を、再帰的にクエリします。

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

仮想カラム​

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

use_hive_partitioning 設定​

use_hive_partitioning 設定を 1 にすると、ClickHouse はパス（/name=value/）内の Hive スタイルのパーティショニングを検出し、クエリ内でパーティション列を仮想列として使用できるようにします。これらの仮想列は、パーティションを表すパス内の名前と同じ名前を持ちますが、先頭に _ が付きます。

例

Hive スタイルのパーティショニングで作成された仮想列を使用する。

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

設定​

SettingDescription
engine_file_empty_if_not_exists存在しないファイルから空の結果セットを SELECT できるようにします。デフォルトでは無効です。
engine_file_truncate_on_insertINSERT の前にファイルの内容を切り詰められるようにします。デフォルトでは無効です。
engine_file_allow_create_multiple_filesフォーマットにサフィックスがある場合、INSERT ごとに新しいファイルを作成できるようにします。デフォルトでは無効です。
engine_file_skip_empty_files読み取り時に空のファイルをスキップできるようにします。デフォルトでは無効です。
storage_file_read_methodストレージファイルからデータを読み取る方法です。read、pread、mmap のいずれかです（mmap は clickhouse-local のみ）。デフォルト値: clickhouse-server では pread、clickhouse-local では mmap。