file テーブル関数

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

file 関数は、ファイルを読み書きするために SELECT および INSERT クエリで使用できます。

構文

パラメータ

• path — user_files_path からのファイルへの相対パス。以下の グロブ を読み取り専用モードでサポートします: *, ?, {abc,def}（'abc' と 'def' が文字列）、および {N..M}（N と M が数字）。
• path_to_archive - zip/tar/7z アーカイブへの相対パス。path と同じグロブをサポートします。
• format — ファイルの フォーマット。
• structure — テーブルの構造。形式: 'column1_name column1_type, column2_name column2_type, ...'。
• compression — SELECT クエリで使用する場合の既存の圧縮タイプ、または INSERT クエリで使用する場合の希望する圧縮タイプ。サポートされている圧縮タイプは gz, br, xz, zst, lz4, および bz2 です。

戻り値

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

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

TSV ファイルへの書き込み

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

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

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

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

ファイルからの読み込みの例

CSV ファイルからの SELECT

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

次に、test.csv からデータをテーブルに読み込み、その最初の2行を選択します。

ファイルからテーブルへのデータ挿入

archive1.zip または archive2.zip にある table.csv からのデータを読み込みます。

パスのグロブ

パスはグロビングを使用できます。ファイルは全体のパスパターンに一致する必要があり、サフィックスやプレフィックスだけには一致できません。パスが既存のディレクトリを指し、グロブを使用しない場合、すべてのファイルが選択されるように、* が暗黙的にパスに追加されます。

• * — / を除く任意の文字を表し、空文字列を含みます。
• ? — 任意の単一の文字を表します。
• {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

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

同じことを達成する別のパス表現:

暗黙的な * を使って some_dir 内の総行数をクエリします。

注記

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

例

ファイル名 file000、file001、...、file999 の全ファイルの行数をクエリします。

例

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

例

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

仮想カラム

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

Hive スタイルのパーティショニング

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

例

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

設定

• 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 - ストレージファイルからのデータ読み取り方法。選択肢: read, pread, mmap (clickhouse-local のみ)。デフォルト値: clickhouse-server 用に pread、clickhouse-local 用に mmap。

関連情報

• 仮想カラム
• 処理後のファイル名変更