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

ClickHouse は、一般的なテキスト形式およびバイナリ形式のほとんどをサポートしています。これにより、運用中のほぼあらゆるデータパイプラインに容易に統合し、ClickHouse の利点を活用できます。

入力フォーマット

入力フォーマットは次の用途に使用されます:

• INSERT ステートメントに渡されたデータのパース
• File、URL、HDFS などのファイルをバックエンドに持つテーブルに対する SELECT クエリの実行
• 辞書の読み取り

ClickHouse にデータを効率的にインジェストするには、適切な入力フォーマットの選択が重要です。70 を超えるフォーマットがサポートされているため、どのフォーマットを選ぶかによって、挿入速度、CPU・メモリ使用量、およびシステム全体の効率が大きく変わります。これらの選択肢を検討しやすくするため、フォーマットごとにインジェスト性能をベンチマークし、次のような主なポイントが明らかになりました:

• Native フォーマットは最も効率的な入力フォーマットであり、最高の圧縮率、最小のリソース使用量、およびサーバー側処理のオーバーヘッドの最小化を実現します。
• 圧縮は不可欠です - LZ4 は CPU コストをほとんど増やさずにデータサイズを削減し、ZSTD は追加の CPU 使用量と引き換えにより高い圧縮率を提供します。
• 事前のソートの影響は中程度であり、ClickHouse 自体がすでに効率的なソートを行います。
• バッチ処理は効率を大きく改善します - バッチサイズを大きくすることで挿入時のオーバーヘッドが減り、スループットが向上します。

結果とベストプラクティスの詳細については、 完全版の ベンチマーク分析 を参照してください。 テスト結果の全体像は、FastFormats のオンラインダッシュボードで確認できます。

出力形式

出力としてサポートされている形式は、次の用途に使用されます:

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

フォーマットの概要

サポートされているフォーマットは以下のとおりです。

フォーマット	入力	出力
TabSeparated	✔	✔
TabSeparatedRaw	✔	✔
TabSeparatedWithNames	✔	✔
TabSeparatedWithNamesAndTypes	✔	✔
TabSeparatedRawWithNames	✔	✔
TabSeparatedRawWithNamesAndTypes	✔	✔
Template	✔	✔
TemplateIgnoreSpaces	✔	✗
CSV	✔	✔
CSVWithNames	✔	✔
CSVWithNamesAndTypes	✔	✔
CustomSeparated	✔	✔
CustomSeparatedWithNames	✔	✔
CustomSeparatedWithNamesAndTypes	✔	✔
SQLInsert	✗	✔
値	✔	✔
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	✔	✔
Null	✗	✔
Hash	✗	✔
XML	✗	✔
CapnProto	✔	✔
LineAsString	✔	✔
LineAsStringWithNames	✔	✔
LineAsStringWithNamesAndTypes	✔	✔
正規表現（Regexp）	✔	✗
RawBLOB	✔	✔
MsgPack	✔	✔
MySQLDump	✔	✗
DWARF	✔	✗
Markdown	✗	✔
フォーム	✔	✗

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

フォーマットスキーマ

フォーマットスキーマを格納したファイル名は、設定 format_schema で指定します。 この設定は、Cap'n Proto または Protobuf のいずれかのフォーマットを使用する場合に必須です。 フォーマットスキーマは、コロンで区切られた「ファイル名」と、そのファイル内のメッセージ型の名前の組み合わせです。 例: schemafile.proto:MessageType。 ファイルがそのフォーマットの標準拡張子（たとえば Protobuf の .proto）を持つ場合は、拡張子を省略でき、その場合フォーマットスキーマは schemafile:MessageType のようになります。

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

HTTP インターフェイス経由でデータを入力または出力する場合、フォーマットスキーマで指定するファイル名は、 サーバー設定の 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 は、次の行の先頭を見つけるために、最後の列の後の区切り文字と行間の区切り文字を使用するため、少なくとも一方が空でない場合にのみエラーをスキップできます。