File テーブルエンジン

File テーブルエンジンは、サポートされているファイルフォーマット（TabSeparated、Native など）のいずれかを使用して、データをファイルに保存します。

File テーブルエンジンは、サポートされているファイルフォーマット (TabSeparated、Native など) のいずれかを使用して、データをファイルに保存します。

使用例:

• ClickHouse からファイルへデータをエクスポートする。
• データをあるフォーマットから別のフォーマットに変換する。
• ディスク上のファイルを編集して、ClickHouse 内のデータを更新する。

このエンジンは現在 ClickHouse Cloud では利用できません。代わりに、S3 table function を使用してください。

​

ClickHouse Server での利用

File(Format)

Format パラメータでは、利用可能なファイルフォーマットのいずれか 1 つを指定します。SELECT クエリを実行するには、そのフォーマットが入力をサポートしている必要があり、INSERT クエリを実行するには、出力をサポートしている必要があります。利用可能なフォーマットは フォーマット セクションに一覧があります。

ClickHouse では、File に対してファイルシステム上のパスを指定できません。代わりに、サーバー設定の path setting で定義されたフォルダーが使用されます。

File(Format) を使用してテーブルを作成すると、そのフォルダー内に空のサブディレクトリが作成されます。そのテーブルにデータが書き込まれると、そのサブディレクトリ内の data.Format ファイルに保存されます。

このサブフォルダーとファイルはサーバーのファイルシステム上で手動で作成し、その後、対応する名前のテーブル情報に ATTACH できます。これにより、そのファイルのデータをクエリできます。

この機能を使用する際は注意してください。ClickHouse は、このようなファイルに対する外部からの変更を追跡しません。ClickHouse 経由の書き込みと ClickHouse 外部での書き込みを同時に行った場合の結果は未定義です。

​

例

1. file_engine_table テーブルを作成します:

CREATE TABLE file_engine_table (name String, value UInt32) ENGINE=File(TabSeparated)

デフォルトでは、ClickHouse は /var/lib/clickhouse/data/default/file_engine_table フォルダーを作成します。

2. /var/lib/clickhouse/data/default/file_engine_table/data.TabSeparated を手動で作成し、次の内容を書き込みます:

$ cat data.TabSeparated
one 1
two 2

3. データにクエリを実行します:

SELECT * FROM file_engine_table

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

​

ClickHouse-localでの使用

clickhouse-local では、Fileエンジンは Format に加えてファイルパスも受け付けます。デフォルトの入出力ストリームは、0 または stdin、1 または stdout のような数値名または人間が読める名前で指定できます。追加のエンジンパラメーターまたはファイル拡張子 (gz、br、xz) に基づいて、圧縮ファイルの読み書きも可能です。

例:

$ echo -e "1,2\n3,4" | clickhouse-local -q "CREATE TABLE table (a Int64, b Int64) ENGINE = File(CSV, stdin); SELECT a, b FROM table; DROP TABLE table"

​

実装の詳細

• 複数の SELECT クエリは同時実行できますが、INSERT クエリは互いの完了を待機します。
• INSERT クエリで新しいファイルを作成できます。
• ファイルが存在する場合、INSERT はそのファイルに新しいデータを追記します。
• サポートしていません:
  • ALTER
  • SELECT ... SAMPLE
  • インデックス
  • レプリケーション

​

PARTITION BY

PARTITION BY — 省略可能です。データをパーティションキーで分割することで、別々のファイルを作成できます。ほとんどの場合、パーティションキーは必要ありません。必要な場合でも、通常は月単位より細かいパーティションキーは不要です。パーティション化でクエリが高速化されることはありません (ORDER BY 式とは異なります) 。細かすぎる粒度でパーティション化するのは避けてください。クライアント識別子や名前でデータをパーティション化しないでください (代わりに、クライアント識別子または名前を ORDER BY 式の先頭カラムにしてください) 。

月単位でパーティション化するには、toYYYYMM(date_column) 式を使用します。ここで、date_column は Date 型の日付カラムです。この場合のパーティション名のフォーマットは "YYYYMM" です。

​

仮想カラム

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

​

設定

• engine_file_empty_if_not_exists - 存在しないファイルから空のデータを選択できるようにします。デフォルトでは無効です。
• engine_file_truncate_on_insert - ファイルに insert する前に、そのファイルを切り詰められるようにします。デフォルトでは無効です。
• engine_file_allow_create_multiple_files - フォーマットに接尾辞がある場合、insert のたびに新しいファイルを作成できるようにします。デフォルトでは無効です。
• engine_file_skip_empty_files - 読み取り時に空のファイルをスキップできるようにします。デフォルトでは無効です。
• storage_file_read_method - ストレージファイルからデータを読み取る方法です。次のいずれかを指定します: read、pread、mmap。mmap メソッドは clickhouse-server には適用されません (clickhouse-local 向けです) 。デフォルト値: clickhouse-server では pread、clickhouse-local では mmap。