入出力データのフォーマット

ClickHouse でサポートされている入出力データフォーマットの概要

ClickHouse は、広く知られているテキストおよびバイナリのデータフォーマットの大半をサポートしています。これにより、ほぼあらゆる データパイプラインに容易に組み込むことができ、ClickHouse の利点を活用できます。

​

入力フォーマット

入力フォーマットは、次の用途で使用されます。

• INSERT ステートメントに渡されるデータのパース
• File、URL、HDFS などのファイルベースのテーブルに対する SELECT クエリの実行
• ディクショナリの読み取り

ClickHouse で効率的にデータをインジェストするには、適切な入力フォーマットを選ぶことが非常に重要です。70 を超える対応フォーマットがあるため、 最も高性能な選択肢を選ぶことで、insert 速度、CPU とメモリの使用量、システム全体の 効率に大きな影響を与えます。こうした選択に役立てるため、各フォーマットのインジェスト性能をベンチマークし、次の重要な知見を得ました。

• Native フォーマットは最も効率的な入力フォーマットです。最も高い圧縮率、 最小限のリソース使用量、そしてサーバー側の処理オーバーヘッドの最小化を実現します。
• 圧縮は不可欠です - LZ4 は最小限の CPU コストでデータサイズを削減し、ZSTD は追加の CPU 使用量を 伴う代わりに、より高い圧縮率を提供します。
• 事前ソートの影響は中程度です。ClickHouse 自体がすでに効率的にソートを行うためです。
• バッチ化は効率を大幅に向上させます - バッチが大きいほど insert のオーバーヘッドが減り、スループットが向上します。

結果とベストプラクティスを詳しく知りたい場合は、 完全版の ベンチマーク分析 を参照してください。 完全なテスト結果については、FastFormats のオンラインダッシュボードをご覧ください。

​

出力フォーマット

出力に対応しているフォーマットは、次の用途で使用されます。

• SELECTクエリの結果の整形
• ファイルベースのテーブルに対する INSERT 操作の実行

​

フォーマットの概要

対応フォーマットは以下のとおりです。

フォーマット	入力	出力
TabSeparated	✔	✔
TabSeparatedRaw	✔	✔
TabSeparatedWithNames	✔	✔
TabSeparatedWithNamesAndTypes	✔	✔
TabSeparatedRawWithNames	✔	✔
TabSeparatedRawWithNamesAndTypes	✔	✔
Template	✔	✔
TemplateIgnoreSpaces	✔	✗
CSV	✔	✔
CSVWithNames	✔	✔
CSVWithNamesAndTypes	✔	✔
CustomSeparated	✔	✔
CustomSeparatedWithNames	✔	✔
CustomSeparatedWithNamesAndTypes	✔	✔
SQLInsert	✗	✔
Values	✔	✔
Vertical	✗	✔
JSON	✔	✔
JSONAsString	✔	✗
JSONAsObject	✔	✗
JSONStrings	✔	✔
JSONColumns	✔	✔
JSONColumnsWithMetadata	✔	✔
JSONCompact	✔	✔
JSONCompactStrings	✗	✔
JSONCompactColumns	✔	✔
JSONEachRow	✔	✔
PrettyJSONEachRow	✗	✔
JSONEachRowWithProgress	✗	✔
JSONStringsEachRow	✔	✔
JSONStringsEachRowWithProgress	✗	✔
JSONCompactEachRow	✔	✔
JSONCompactEachRowWithNames	✔	✔
JSONCompactEachRowWithNamesAndTypes	✔	✔
JSONCompactEachRowWithProgress	✗	✔
JSONCompactStringsEachRow	✔	✔
JSONCompactStringsEachRowWithNames	✔	✔
JSONCompactStringsEachRowWithNamesAndTypes	✔	✔
JSONCompactStringsEachRowWithProgress	✗	✔
JSONObjectEachRow	✔	✔
BSONEachRow	✔	✔
TSKV	✔	✔
Pretty	✗	✔
PrettyNoEscapes	✗	✔
PrettyMonoBlock	✗	✔
PrettyNoEscapesMonoBlock	✗	✔
PrettyCompact	✗	✔
PrettyCompactNoEscapes	✗	✔
PrettyCompactMonoBlock	✗	✔
PrettyCompactNoEscapesMonoBlock	✗	✔
PrettySpace	✗	✔
PrettySpaceNoEscapes	✗	✔
PrettySpaceMonoBlock	✗	✔
PrettySpaceNoEscapesMonoBlock	✗	✔
Prometheus	✗	✔
Protobuf	✔	✔
ProtobufSingle	✔	✔
ProtobufList	✔	✔
Avro	✔	✔
AvroConfluent	✔	✔
Parquet	✔	✔
ParquetMetadata	✔	✗
Arrow	✔	✔
ArrowStream	✔	✔
ORC	✔	✔
One	✔	✗
Npy	✔	✔
RowBinary	✔	✔
RowBinaryWithNames	✔	✔
RowBinaryWithNamesAndTypes	✔	✔
RowBinaryWithDefaults	✔	✗
Native	✔	✔
Buffers	✔	✔
Null	✗	✔
Hash	✗	✔
XML	✗	✔
CapnProto	✔	✔
LineAsString	✔	✔
LineAsStringWithNames	✔	✔
LineAsStringWithNamesAndTypes	✔	✔
Regexp	✔	✗
RawBLOB	✔	✔
MsgPack	✔	✔
MySQLDump	✔	✗
DWARF	✔	✗
Markdown	✗	✔
Form	✔	✗

一部のフォーマットの処理パラメータは、ClickHouseの設定で制御できます。詳しくは、Settings セクションを参照してください。

​

フォーマットスキーマ

フォーマットスキーマを含むファイル名は、設定 format_schema で指定します。 この設定は、Cap'n Proto または Protobuf フォーマットを使用する場合に必要です。 フォーマットスキーマは、ファイル名とそのファイル内のメッセージ型名をコロンで区切って組み合わせたものです。 たとえば、schemafile.proto:MessageType のようになります。 ファイルがそのフォーマットの標準拡張子 (たとえば Protobuf の場合は .proto) を持つ場合、 その拡張子は省略でき、この場合のフォーマットスキーマは schemafile:MessageType のようになります。

client を対話型モードで使用してデータを入力または出力する場合、フォーマットスキーマで指定するファイル名には、 絶対パス、またはクライアント上の現在のディレクトリからの相対パスを指定できます。 batch mode でクライアントを使用する場合は、セキュリティ上の理由により、スキーマへのパスは相対パスでなければなりません。

HTTP interface 経由でデータを入力または出力する場合、フォーマットスキーマで指定するファイル名は、 サーバー設定の format_schema_path で指定されたディレクトリに配置する必要があります。

​

エラーのスキップ

CSV、TabSeparated、TSKV、JSONEachRow、Template、CustomSeparated、Protobuf などの一部のフォーマットでは、パースエラーが発生しても不正な行をスキップし、次の行の先頭からパースを続行できます。input_format_allow_errors_num と input_format_allow_errors_ratio の設定を参照してください。 制限事項:

• JSONEachRow では、パースエラーが発生すると改行 (または EOF) までのすべてのデータがスキップされるため、エラーを正しくカウントするには、行が \n で区切られている必要があります。
• Template と CustomSeparated では、次の行の先頭を見つけるために、最後のカラムの後の区切り文字と行間の区切り文字を使用します。そのため、エラーのスキップが機能するのは、その少なくとも一方が空でない場合だけです。