ClickHouse/docs/ja/interfaces/formats.md

slug	sidebar_position	sidebar_label	title
/ja/interfaces/formats	21	すべてのフォーマットを表示…	入出力データのフォーマット

ClickHouseは様々なフォーマットでデータを受け入れることができ、返すことができます。入力をサポートするフォーマットは、INSERTに提供するデータの解析、FileやURL、HDFSにバックアップされたテーブルからのSELECTの実行、もしくはDictionaryの読み込みに使用できます。出力をサポートするフォーマットは、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	✔	✔
JSONCompactStringsEachRow	✔	✔
JSONCompactStringsEachRowWithNames	✔	✔
JSONCompactStringsEachRowWithNamesAndTypes	✔	✔
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	✗	✔
XML	✗	✔
CapnProto	✔	✔
LineAsString	✔	✔
Regexp	✔	✗
RawBLOB	✔	✔
MsgPack	✔	✔
MySQLDump	✔	✗
DWARF	✔	✗
Markdown	✗	✔
Form	✔	✗

ClickHouse設定により、いくつかのフォーマット処理パラメータを制御することができます。詳細については、設定 セクションを参照してください。

TabSeparated

TabSeparatedフォーマットでは、データは行ごとに書き込まれます。各行の値はタブで区切られ、最後の値には改行が必須です。ユニックス形式の改行が必要です。最後の行も改行を含める必要があります。値はテキスト形式で書かれ、囲み文字はありません。特別な文字はエスケープされます。

このフォーマットはTSVという名前でも利用できます。

TabSeparatedフォーマットは、カスタムプログラムやスクリプトを使用してデータを処理するのに便利です。HTTPインターフェイスや、コマンドラインクライアントのバッチモードでデフォルトで使用されます。このフォーマットを使用して、異なるDBMS間でデータを転送することもできます。例えば、MySQLからダンプを取得し、それをClickHouseにアップロードすることができます。

TabSeparatedフォーマットは、総計値（WITH TOTALSを使用時）や極値（extremesを1に設定時）の出力をサポートしています。この場合、総計値と極値はメインデータの後に出力されます。メイン結果、総計値、極値は、空行で分けられます。例：

SELECT EventDate, count() AS c FROM test.hits GROUP BY EventDate WITH TOTALS ORDER BY EventDate FORMAT TabSeparated

2014-03-17    1406958
2014-03-18    1383658
2014-03-19    1405797
2014-03-20    1353623
2014-03-21    1245779
2014-03-22    1031592
2014-03-23    1046491

1970-01-01    8873898

2014-03-17    1031592
2014-03-23    1406958

データフォーマティング

整数は10進法で書かれます。数値の先頭には「+」記号を含めることができます（解析時に無視され、フォーマット時には記録されません）。非負の数値には負符号をつけることはできません。解析時には空の文字列を0と解釈することが許され、また（符号付きタイプの場合）マイナス記号だけの文字列を0と解釈します。該当するデータタイプに収まらない数字は、エラーメッセージなしに別の数として解析されることがあります。

浮動小数点数は10進法で書かれます。小数点は小数の区切り記号として使われます。指数表記や inf, +inf, -inf, nan がサポートされています。浮動小数点数のエントリは、小数点で始まるか終わることがあります。 フォーマット時に、浮動小数点数の精度が失われる場合があります。 解析時には、機械で表現可能な最も近い数値を必ずしも読まなければならないわけではありません。

日付はYYYY-MM-DD形式で書かれ、任意の文字を区切り文字として解析されます。 日時付きの日付は、YYYY-MM-DD hh:mm:ss形式で書かれ、任意の文字を区切り文字として解析されます。 これは、クライアントまたはサーバーが起動したときのシステムタイムゾーンで行われます（データをフォーマットする側に依存します）。夏時間の時は指定されません。したがって、ダンプに夏時間中の時間が含まれていると、ダンプがデータと一致しないことがあり、解析時には2つの時間のうち1つが選ばれます。 読み取り操作中に、不正な日付や日時付きの日付は、自然なオーバーフローまたはnullの日付や時間として解析され、エラーメッセージはされません。

例外として、日時の解析が10進数桁が10個だけから成るUnixタイムスタンプ形式でもサポートされています。結果はタイムゾーンに依存しません。YYYY-MM-DD hh:mm:ssと NNNNNNNNNN の形式は自動的に区別されます。

文字列は、バックスラッシュでエスケープされた特殊文字と共に出力されます。出力には以下のエスケープシーケンスを使用します: \b, \f, \r, \n, \t, \0, \', \\. 解析もまた、シーケンス \a, \v, \xHH (16進エスケープシーケンス）および任意の\cシーケンスをサポートし、ここでcは任意の文字です（これらのシーケンスはcに変換されます）。したがって、データの読み取りは、改行が\nまたは \、または改行として書かれる形式をサポートします。例えば、単語間のスペースの代わりに改行を使用したHello world文字列は、以下のどのバリエーションでも解析できます：

Hello\nworld

Hello\
world

2番目のバリアントは、MySQLがタブ分割されたダンプを書き込むときに使用するためサポートされています。

TabSeparatedフォーマットでデータを渡すときにエスケープする必要がある文字の最小セット：タブ、改行（LF）、およびバックスラッシュ。

ごく少数の記号のみがエスケープされます。出力時にあなたのターミナルを損ねる文字列値に簡単に行き当たることがあります。

配列は四角い括弧で囲まれたコンマ区切りの値リストとして書かれます。配列内の番号アイテムは通常通り書式が設定されます。Date と DateTime 型はシングルクォートで囲まれます。文字列は上記と同じエスケープルールでシングルクォートで囲まれます。

NULLはformat_tsv_null_representation設定（デフォルト値は\N）に従ってフォーマットされます。

入力データにおいて、ENUMの値は名前またはidとして表現できます。まず、入力値をENUM名にマッチしようとします。失敗した場合でかつ入力値が数字である場合、その数字をENUM idにマッチさせようとします。 入力データがENUM idのみを含む場合、ENUM解析を最適化するために、input_format_tsv_enum_as_number設定を有効化することをお勧めします。

Nested構造の各要素は配列として表現されます。

例えば：

CREATE TABLE nestedt
(
    `id` UInt8,
    `aux` Nested(
        a UInt8,
        b String
    )
)
ENGINE = TinyLog

INSERT INTO nestedt Values ( 1, [1], ['a'])

SELECT * FROM nestedt FORMAT TSV

1  [1]    ['a']

TabSeparatedフォーマット設定

• format_tsv_null_representation - TSVフォーマットでのNULLのカスタム表現。デフォルト値 - \N。
• input_format_tsv_empty_as_default - TSV入力の空フィールドをデフォルト値として扱います。デフォルト値 - false。複雑なデフォルト式の場合、input_format_defaults_for_omitted_fieldsも有効にする必要があります。
• input_format_tsv_enum_as_number - TSV形式で挿入されたenum値をenumインデックスとして扱います。デフォルト値 - false。
• input_format_tsv_use_best_effort_in_schema_inference - TSV形式でスキーマを推測するためにいくつかの調整とヒューリスティックを使用します。無効化されると、すべてのフィールドは文字列として推測されます。デフォルト値 - true。
• output_format_tsv_crlf_end_of_line - TSV出力形式で行末を\r\nにする場合はtrueに設定。デフォルト値 - false。
• input_format_tsv_crlf_end_of_line - TSV入力形式で行末を\r\nにする場合はtrueに設定。デフォルト値 - false。
• input_format_tsv_skip_first_lines - データの最初の行を指定された数だけスキップします。デフォルト値 - 0。
• input_format_tsv_detect_header - TSV形式で名前とタイプを含むヘッダーを自動的に検出します。デフォルト値 - true。
• input_format_tsv_skip_trailing_empty_lines - データの末尾の空行をスキップします。デフォルト値 - false。
• input_format_tsv_allow_variable_number_of_columns - TSV形式でカラム数を変動可能にします。余分なカラムを無視し、欠落したカラムはデフォルト値を使用。デフォルト値 - false。

TabSeparatedRaw

TabSeparatedフォーマットと異なり、行はエスケープなしで書き込まれる。 このフォーマットでの解析では、各フィールドにタブや改行を含むことは許可されていません。

このフォーマットはTSVRaw、Rawという名前でも利用できます。

TabSeparatedWithNames

TabSeparatedフォーマットと異なり、カラム名が最初の行に書かれます。

解析中、最初の行はカラム名を含むことを期待されています。カラム名を使用して位置を決定したり、正確性を確認することができます。

:::note 設定 input_format_with_names_use_header が1に設定されている場合、 入力データのカラムは名前でテーブルのカラムにマッピングされ、不明な名前のカラムは、設定 input_format_skip_unknown_fields が1に設定されている場合にスキップされます。 それ以外の場合、最初の行はスキップされます。 :::

このフォーマットはTSVWithNamesという名前でも利用できます。

TabSeparatedWithNamesAndTypes

TabSeparatedフォーマットと異なり、カラム名は最初の行に書かれ、カラムタイプは2行目に書かれます。

:::note 設定 input_format_with_names_use_header が1に設定されている場合、 入力データのカラムは名前でテーブルのカラムにマッピングされ、不明な名前のカラムは、設定 input_format_skip_unknown_fields が1に設定されている場合にスキップされます。 それ以外の場合、最初の行はスキップされます。 設定 input_format_with_types_use_header が1に設定されている場合、 入力データのタイプは対応するテーブルのカラムタイプと比較されます。それ以外の場合、2行目はスキップされます。 :::

このフォーマットはTSVWithNamesAndTypesという名前でも利用できます。

TabSeparatedRawWithNames

TabSeparatedWithNamesフォーマットと異なり、行はエスケープなしで書かれます。 このフォーマットでの解析では、各フィールドにタブや改行を含むことは許可されていません。

このフォーマットはTSVRawWithNames、RawWithNamesという名前でも利用できます。

TabSeparatedRawWithNamesAndTypes

TabSeparatedWithNamesAndTypesフォーマットと異なり、行はエスケープなしで書かれます。 このフォーマットでの解析では、各フィールドにタブや改行を含むことは許可されていません。

このフォーマットはTSVRawWithNamesAndNames、RawWithNamesAndNamesという名前でも利用できます。

Template

このフォーマットは、指定されたエスケープルールを持つ値のプレースホルダーを使用して、カスタムフォーマット文字列を指定できることを可能にします。

設定はformat_template_resultset、format_template_row（format_template_row_format）、format_template_rows_between_delimiterと、その他のいくつかの形式の設定（例：JSONエスケープ使用時のoutput_format_json_quote_64bit_integers）。

設定format_template_rowは、次のシンタックスを持つ行に対するフォーマット文字列を含むファイルのパスを指定します：

delimiter_1${column_1:serializeAs_1}delimiter_2${column_2:serializeAs_2} ... delimiter_N、

ここでdelimiter_iは値間のデリミタ（$シンボルは $$でエスケープ可能）、 column_iは選択または挿入される値のカラム名またはインデックス（空の場合、そのカラムはスキップされる）、 serializeAs_iはカラム値のエスケープルールを意味します。サポートされるエスケープルールは以下の通りです：

• CSV, JSON, XML（同じ名前のフォーマットに類似）
• Escaped（TSVに類似）
• Quoted（Valuesに類似）
• Raw（エスケープなし、TSVRawに類似）
• None（エスケープルールなし、詳細は後述）

エスケープルールが省略された場合、Noneが利用されます。XMLは出力にのみ適しています。

したがって、次のフォーマット文字列：

  `Search phrase: ${SearchPhrase:Quoted}, count: ${c:Escaped}, ad price: $$${price:JSON};`

では、SearchPhrase、c、priceカラムの値が Quoted、Escaped、JSON としてエスケープされ、Search phrase:、, count:、, ad price: $、;のデリミタ間に（選択/挿入フォーマット時に）出力されます。例えば：

Search phrase: 'bathroom interior design', count: 2166, ad price: $3;

クラスタ内のすべてのノードにテンプレートフォーマットの出力設定を配置することが挑戦的または可能でない場合や、フォーマットが簡単な場合は、format_template_row_formatを使用して、ファイルのパスではなく、クエリ内で直接テンプレート文字列を設定できます。

設定format_template_rows_between_delimiterは、行間のデリミタを指定し、最後の行以外のすべての行の後に印刷される（もしくは期待される）（デフォルトは\n）設定です。

設定format_template_resultsetは、結果セットのフォーマット文字列を含むファイルのパスを指定します。設定format_template_resultset_formatは、結果セットのテンプレート文字列をクエリ内で直接設定することも可能にします。結果セットのフォーマット文字列には、行用のフォーマット文字列と同じシンタックスがあります。プレフィックス、サフィックス、追加情報の方法を指定することができます。カラム名の代わりに次のプレースホルダーを含む：

• dataは、format_template_rowフォーマットでデータを持つ行で、format_template_rows_between_delimiterで分割されます。このプレースホルダーはフォーマット文字列で最初のプレースホルダーでなければなりません。
• totalsは、format_template_rowフォーマットの合計値の行です（WITH TOTALS使用時）
• minは、format_template_rowフォーマットの最小値の行です（極限が1に設定されているとき）
• maxは、format_template_rowフォーマットの最大値の行です（極限が1に設定されているとき）
• rowsは、出力行の総数
• rows_before_limitは、LIMITなしの場合でも少なくともある行数。クエリにLIMITが含まれる場合のみ出力します。GROUP BYが含まれる場合、LIMITがなければ、rows_before_limit_at_leastは正確な行数です。
• timeは、リクエストの実行時間（秒）
• rows_readは、読み取られた行の数
• bytes_readは、読み取られたバイト数（非圧縮）

プレースホルダーdata、totals、min、およびmaxには、エス케ープルールが指定されてはなりません（またはNoneが明示的に指定される必要があります）。残りのプレースホルダーには、任意のエスケープルールが指定できます。 format_template_resultset設定が空の文字列の場合、${data}がデフォルト値として使用されます。 挿入クエリに対するフォーマットでは、プレフィックスやサフィックスがあれば、一部のカラムやフィールドをスキップできるようにしています（例を参照）。

選択例：

SELECT SearchPhrase, count() AS c FROM test.hits GROUP BY SearchPhrase ORDER BY c DESC LIMIT 5 FORMAT Template SETTINGS
format_template_resultset = '/some/path/resultset.format', format_template_row = '/some/path/row.format', format_template_rows_between_delimiter = '\n    '

/some/path/resultset.format：

<!DOCTYPE HTML>
<html> <head> <title>Search phrases</title> </head>
 <body>
  <table border="1"> <caption>Search phrases</caption>
    <tr> <th>Search phrase</th> <th>Count</th> </tr>
    ${data}
  </table>
  <table border="1"> <caption>Max</caption>
    ${max}
  </table>
  <b>Processed ${rows_read:XML} rows in ${time:XML} sec</b>
 </body>
</html>

/some/path/row.format：

<tr> <td>${0:XML}</td> <td>${1:XML}</td> </tr>

結果：

<!DOCTYPE HTML>
<html> <head> <title>Search phrases</title> </head>
 <body>
  <table border="1"> <caption>Search phrases</caption>
    <tr> <th>Search phrase</th> <th>Count</th> </tr>
    <tr> <td>bathroom interior design</td> <td>2166</td> </tr>
    <tr> <td>clickhouse</td> <td>1655</td> </tr>
    <tr> <td>spring 2014 fashion</td> <td>1549</td> </tr>
    <tr> <td>freeform photos</td> <td>1480</td> </tr>
  </table>
  <table border="1"> <caption>Max</caption>
    <tr> <td></td> <td>8873898</td> </tr>
  </table>
  <b>Processed 3095973 rows in 0.1569913 sec</b>
 </body>
</html>

挿入例：

Some header
Page views: 5, User id: 4324182021466249494, Useless field: hello, Duration: 146, Sign: -1
Page views: 6, User id: 4324182021466249494, Useless field: world, Duration: 185, Sign: 1
Total rows: 2

INSERT INTO UserActivity SETTINGS
format_template_resultset = '/some/path/resultset.format', format_template_row = '/some/path/row.format'
FORMAT Template

/some/path/resultset.format：

Some header\n${data}\nTotal rows: ${:CSV}\n

/some/path/row.format：

Page views: ${PageViews:CSV}, User id: ${UserID:CSV}, Useless field: ${:CSV}, Duration: ${Duration:CSV}, Sign: ${Sign:CSV}

PageViews、UserID、Duration、およびSignはテーブル内のカラム名です。行内のUseless fieldの後やサフィックスの\nTotal rows:の後の値は無視されます。 入力データのすべてのデリミタは、指定されたフォーマット文字列のデリミタと厳密に等しい必要があります。

TemplateIgnoreSpaces

このフォーマットは入力専用です。 Templateに似ていますが、入力ストリームのデリミタと値の間の空白文字をスキップします。ただし、フォーマット文字列に空白文字が含まれている場合、これらの文字は、入力ストリームで期待されます。また、いくつかのデリミタを別々に分けるために、空のプレースホルダー（${}または${:None}）を指定することも許可します。このようなプレースホルダーは、空白文字をスキップするだけに使用されます。そのため、すべての行でのカラム値の順序が同じ場合、JSONを読み取ることができます。例えば、JSONフォーマットの例から出力されたデータを挿入するための形式として、以下のリクエストが使用されることがあります：

INSERT INTO table_name SETTINGS
format_template_resultset = '/some/path/resultset.format', format_template_row = '/some/path/row.format', format_template_rows_between_delimiter = ','
FORMAT TemplateIgnoreSpaces

/some/path/resultset.format：

{${}"meta"${}:${:JSON},${}"data"${}:${}[${data}]${},${}"totals"${}:${:JSON},${}"extremes"${}:${:JSON},${}"rows"${}:${:JSON},${}"rows_before_limit_at_least"${}:${:JSON}${}}

/some/path/row.format：

{${}"SearchPhrase"${}:${}${phrase:JSON}${},${}"c"${}:${}${cnt:JSON}${}}

TSKV

TabSeparatedに似ていますが、値を名前=value形式で出力します。名前はTabSeparatedフォーマットと同様にエスケープされ、=`記号もエスケープされます。

SearchPhrase=   count()=8267016
SearchPhrase=bathroom interior design    count()=2166
SearchPhrase=clickhouse     count()=1655
SearchPhrase=2014 spring fashion    count()=1549
SearchPhrase=freeform photos       count()=1480
SearchPhrase=angelina jolie    count()=1245
SearchPhrase=omsk       count()=1112
SearchPhrase=photos of dog breeds    count()=1091
SearchPhrase=curtain designs        count()=1064
SearchPhrase=baku       count()=1000

NULLは\Nとしてフォーマットされます。

SELECT * FROM t_null FORMAT TSKV

x=1    y=\N

小さなカラムが多数ある場合、このフォーマットは非効率的ですし、通常使用する理由はありません。それにもかかわらず、効率においてJSONEachRowに劣ることはありません。

データの出力と解析の両方がこのフォーマットでサポートされています。解析中は、異なるカラムの値の順序は任意です。一部の値が省略されていることが許可されており、それらはデフォルト値と同等と見なされます。この場合、零や空白行がデフォルト値として使用されます。テーブルに指定されうる複雑な値はデフォルトとしてサポートされていません。

解析がtskvという追加フィールドの存在を許可します。このフィールドは実際には無視されます。

インポート中に、不明な名前のカラムは、設定input_format_skip_unknown_fieldsが1に設定されている場合、スキップされます。

CSV

コンマ区切り値形式（RFC）。

書式設定時、行は二重引用符で囲まれます。文字列内の二重引用符は、二重引用符列として出力されます。他のエスケープ文字に関するルールはありません。日付と日時は二重引用符で囲まれます。数値は引用符なしで出力されます。値はデリミタ文字で分割され、デフォルトは,です。デリミタ文字は設定format_csv_delimiterで定義されます。行の区切りにはUnixの改行（LF）が使用されます。配列は、最初にTabSeparated形式で文字列としてシリアライズした後、結果の文字列を二重引用符で囲んで出力します。CSV形式では、タプルは別のカラムとしてシリアライズされます（故に、タプル内部のネストは失われます）。

$ clickhouse-client --format_csv_delimiter="|" --query="INSERT INTO test.csv FORMAT CSV" < data.csv

*デフォルトでは、デリミタは,です。詳細についてはformat_csv_delimiter設定を参照してください。

解析時、すべての値は引用符ありまたは引用符なしで解析できます。ダブル引用符およびシングル引用符の両方がサポートされています。行も引用符なしで配置することができ、それを区切り文字または改行（CRまたはLF）まで解析します。RFCに違反して、引用符なしの行解析中に、先頭および末尾のスペースおよびタブは無視されます。改行の種類に関しては、Unix（LF）、Windows（CR LF）、およびMac OS Classic（CR LF）がすべてサポートされています。

NULLは設定format_csv_null_representation（デフォルト値は\N）に従ってフォーマットされます。

入力データにおいて、ENUMの値は名前またはidとして表現できます。最初に入力値をENUM名に合わせようとし、失敗し、値が数値である場合、ENUM idに合わせようとします。 入力データがENUM idのみを含む場合、ENUM解析を最適化するために、input_format_csv_enum_as_number設定を有効化することをお勧めします。

CSV形式は、TabSeparatedと同様に、合計や極値の出力をサポートしています。

CSVフォーマット設定

• format_csv_delimiter - CSVデータでデリミタと見なされる文字。デフォルト値 - ,。
• format_csv_allow_single_quotes - シングルクォート内の文字列を許可。デフォルト値 - true。
• format_csv_allow_double_quotes - ダブルクォート内の文字列を許可。デフォルト値 - true。
• format_csv_null_representation - CSVフォーマット内のNULLのカスタム表現。デフォルト値 - \N。
• input_format_csv_empty_as_default - CSV入力の空フィールドをデフォルト値として扱う。デフォルト値 - true。複雑なデフォルト式の場合、input_format_defaults_for_omitted_fieldsも有効にする必要があります。
• input_format_csv_enum_as_number - CSV形式で挿入されたenum値をenumインデックスとして扱います。デフォルト値 - false。
• input_format_csv_use_best_effort_in_schema_inference - CSV形式でスキーマを推測するためのいくつかの調整やヒューリスティックを使用します。無効化されると、すべてのフィールドは文字列として推測されます。デフォルト値 - true。
• input_format_csv_arrays_as_nested_csv - CSVからArrayを読み取る際に、それの要素がネストされたCSVとしてシリアライズされ、それから文字列に入れられると仮定します。デフォルト値 - false。
• output_format_csv_crlf_end_of_line - trueに設定されている場合、CSV出力形式の行の終了は\r\nとなり、\nではありません。デフォルト値 - false。
• input_format_csv_skip_first_lines - データの最初に指定された数の行をスキップします。デフォルト値 - 0。
• input_format_csv_detect_header - CSV形式で名前とタイプを含むヘッダーを自動的に検出します。デフォルト値 - true。
• input_format_csv_skip_trailing_empty_lines - データの末尾の空行をスキップします。デフォルト値 - false。
• input_format_csv_trim_whitespaces - 非引用されたCSV文字列内のスペースやタブをトリムします。デフォルト値 - true。
• input_format_csv_allow_whitespace_or_tab_as_delimiter - CSV文字列内でのフィールドデリミタとしてホワイトスペースやタブを使用できるようにします。デフォルト値 - false。
• input_format_csv_allow_variable_number_of_columns - CSV形式でカラム数を変動可能にし、余分なカラムは無視し、欠落したカラムにはデフォルト値を使用。デフォルト値 - false。
• input_format_csv_use_default_on_bad_values - CSVフィールドの不正な値のデシリアライズが失敗したとき、カラムにデフォルト値を設定できるようにします。デフォルト値 - false。
• input_format_csv_try_infer_numbers_from_strings - スキーマ推測中に文字列フィールドから数値を推測しようとします。デフォルト値 - false。

CSVWithNames

カラム名でヘッダー行も出力します。TabSeparatedWithNamesに似ています。

:::note 設定 input_format_with_names_use_header が1に設定されている場合、 入力データのカラムは名前でテーブルのカラムにマッピングされ、不明な名前のカラムは、設定 input_format_skip_unknown_fields が1に設定されている場合にスキップされます。 それ以外の場合、最初の行はスキップされます。 :::

CSVWithNamesAndTypes

カラム名とタイプと共に2つのヘッダー行を書き込みます。これはTabSeparatedWithNamesAndTypesに似ています。

:::note 設定 input_format_with_names_use_header が1に設定されている場合、 入力データのカラムは名前でテーブルのカラムにマッピングされ、不明な名前のカラムは、設定 input_format_skip_unknown_fields が1に設定されている場合にスキップされます。 それ以外の場合、最初の行はスキップされます。 設定 input_format_with_types_use_header が1に設定されている場合、 入力データのタイプは対応するテーブルのカラムタイプと比較されます。それ以外の場合、2行目はスキップされます。 :::

CustomSeparated

Templateに似ていますが、すべてのカラムの名前とタイプを印刷もしくは読み取り、エスケープルールはformat_custom_escaping_rule設定、デリミタはformat_custom_field_delimiter、format_custom_row_before_delimiter、format_custom_row_after_delimiter、format_custom_row_between_delimiter、format_custom_result_before_delimiterおよびformat_custom_result_after_delimiterから取得しますが、フォーマット文字列からは取得しません。

追加設定：

• input_format_custom_detect_header - ヘッダを自動的に検出することを有効にします。デフォルト値 - true。
• input_format_custom_skip_trailing_empty_lines - ファイル末尾の空行をスキップします。デフォルト値 - false。
• input_format_custom_allow_variable_number_of_columns - カスタムセパレーテッド形式でカラム数を変動可能にし、余分なカラムは無視し、欠落したカラムにはデフォルト値を使用。デフォルト値 - false。

また、TemplateIgnoreSpacesに類似するCustomSeparatedIgnoreSpacesフォーマットもあります。

CustomSeparatedWithNames

カラム名でヘッダー行も出力します。TabSeparatedWithNamesに似ています。

:::note 設定 input_format_with_names_use_header が1に設定されている場合、 入力データのカラムは名前でテーブルのカラムにマッピングされ、不明な名前のカラムは、設定 input_format_skip_unknown_fields が1に設定されている場合にスキップされます。 それ以外の場合、最初の行はスキップされます。 :::

CustomSeparatedWithNamesAndTypes

カラム名とタイプと共に2つのヘッダー行を書き込みます。これはTabSeparatedWithNamesAndTypesに似ています。

:::note 設定 input_format_with_names_use_header が1に設定されている場合、 入力データのカラムは名前でテーブルのカラムにマッピングされ、不明な名前のカラムは、設定 input_format_skip_unknown_fields が1に設定されている場合にスキップされます。 それ以外の場合、最初の行はスキップされます。 設定 input_format_with_types_use_header が1に設定されている場合、入力データのタイプは対応するテーブルのカラムタイプと比較されます。それ以外の場合、2行目はスキップされます。 :::

SQLInsert

データをINSERT INTO table (columns...) VALUES (...), (...) ...;ステートメントのシーケンスとして出力します。

例：

SELECT number AS x, number + 1 AS y, 'Hello' AS z FROM numbers(10) FORMAT SQLInsert SETTINGS output_format_sql_insert_max_batch_size = 2

INSERT INTO table (x, y, z) VALUES (0, 1, 'Hello'), (1, 2, 'Hello');
INSERT INTO table (x, y, z) VALUES (2, 3, 'Hello'), (3, 4, 'Hello');
INSERT INTO table (x, y, z) VALUES (4, 5, 'Hello'), (5, 6, 'Hello');
INSERT INTO table (x, y, z) VALUES (6, 7, 'Hello'), (7, 8, 'Hello');
INSERT INTO table (x, y, z) VALUES (8, 9, 'Hello'), (9, 10, 'Hello');

この形式で出力されたデータを読み取るには、MySQLDump入力形式を使用できます。

SQLInsertフォーマット設定

• output_format_sql_insert_max_batch_size - 1つのINSERTステートメント内の最大行数。デフォルト値 - 65505。
• output_format_sql_insert_table_name - 出力INSERTクエリのテーブル名。デフォルト値 - 'table'。
• output_format_sql_insert_include_column_names - INSERTクエリにカラム名を含めます。デフォルト値 - true。
• output_format_sql_insert_use_replace - INSERTの代わりにREPLACEステートメントを使用します。デフォルト値 - false。
• output_format_sql_insert_quote_names - カラム名を"`"文字で引用します。デフォルト値 - true。

JSON

データをJSON形式で出力します。データテーブル以外にも、カラム名とタイプのほか、出力された行の総数、LIMITがなければ出力可能だった行数などの追加情報も出力されます。例：

SELECT SearchPhrase, count() AS c FROM test.hits GROUP BY SearchPhrase WITH TOTALS ORDER BY c DESC LIMIT 5 FORMAT JSON

{
        "meta":
        [
                {
                        "name": "num",
                        "type": "Int32"
                },
                {
                        "name": "str",
                        "type": "String"
                },
                {
                        "name": "arr",
                        "type": "Array(UInt8)"
                }
        ],

        "data":
        [
                {
                        "num": 42,
                        "str": "hello",
                        "arr": [0,1]
                },
                {
                        "num": 43,
                        "str": "hello",
                        "arr": [0,1,2]
                },
                {
                        "num": 44,
                        "str": "hello",
                        "arr": [0,1,2,3]
                }
        ],

        "rows": 3,

        "rows_before_limit_at_least": 3,

        "statistics":
        {
                "elapsed": 0.001137687,
                "rows_read": 3,
                "bytes_read": 24
        }
}

このJSONはJavaScriptと互換性があります。これを保証するために、いくつかの文字はさらにエスケープされています：スラッシュ / は \/ としてエスケープされます。ブラウザの問題を引き起こすU+2028とU+2029の特殊な改行は、\uXXXXとしてエスケープされます。ASCII制御文字はエスケープされます：バックスペース、フォームフィード、ラインフィード、キャリッジリターン、および水平タブは \b, \f, \n, \r, \t として、00-1F範囲にある残りのバイトは \uXXXX シーケンスとして置き換えます。無効なUTF-8シーケンスは置き換え文字に変更されるので、出力テキストは有効なUTF-8シーケンスで構成されます。JavaScriptとの互換性のため、Int64 および UInt64 の整数はデフォルトで引用符で囲まれています。引用符を除去するには、設定パラメータoutput_format_json_quote_64bit_integersを0に設定します。

rows – 出力行の総数。

rows_before_limit_at_least – LIMITがなければ最低限残っていた行数。クエリにLIMITが含まれる場合のみ出力されます。 クエリにGROUP BYが含まれる場合、rows_before_limit_at_leastはLIMITがない場合の正確な行数です。

totals – 合計値（WITH TOTALSを使用時）。

extremes – 極値（extremesが1に設定時）。

ClickHouseはNULLをサポートしており、JSON出力でnullとして表示されます。出力で+nan、-nan、+inf、および-infを有効にするには、出力形式の引数を変更してくださいoutput_format_json_quote_denormalsを1に設定します。

関連項目

• JSONEachRowフォーマット
• output_format_json_array_of_rows設定

JSON入力形式では、設定input_format_json_validate_types_from_metadataが1に設定されている場合、入力データのメタデータから検証されたタイプが、対応するテーブルのカラムのタイプと比較されます。

JSONStrings

JSONと異なり、データフィールドが文字列として出力され、型つきJSON値ではありません。

例：

{
        "meta":
        [
                {
                        "name": "num",
                        "type": "Int32"
                },
                {
                        "name": "str",
                        "type": "String"
                },
                {
                        "name": "arr",
                        "type": "Array(UInt8)"
                }
        ],

        "data":
        [
                {
                        "num": "42",
                        "str": "hello",
                        "arr": "[0,1]"
                },
                {
                        "num": "43",
                        "str": "hello",
                        "arr": "[0,1,2]"
                },
                {
                        "num": "44",
                        "str": "hello",
                        "arr": "[0,1,2,3]"
                }
        ],

        "rows": 3,

        "rows_before_limit_at_least": 3,

        "statistics":
        {
                "elapsed": 0.001403233,
                "rows_read": 3,
                "bytes_read": 24
        }
}

JSONColumns

:::tip JSONColumns*形式の出力は、ClickHouseフィールド名とそのフィールドのテーブルの各行の内容を提供します。視覚的には、データが左90度回転したように見えます。 :::

このフォーマットでは、すべてのデータが1つのJSONオブジェクトとして表現されます。 JSONColumns出力形式はすべてのデータをメモリにバッファリングして、単一ブロックとして出力するため、高メモリ消費につながる可能性があります。

例：

{
	"num": [42, 43, 44],
	"str": ["hello", "hello", "hello"],
	"arr": [[0,1], [0,1,2], [0,1,2,3]]
}

インポート中、設定input_format_skip_unknown_fieldsが1に設定されていると、不明な名前のカラムはスキップされます。 ブロックに存在しないカラムは、デフォルト値で満たされます（ここでinput_format_defaults_for_omitted_fields設定を使用できます）

JSONColumnsWithMetadata

JSONColumns形式と異なり、いくつかのメタデータや統計情報（JSON形式と類似）も含んでいます。 出力形式はすべてのデータをメモリにバッファリングして、単一ブロックとして出力するため、高メモリ消費につながる可能性があります。

例：

{
        "meta":
        [
                {
                        "name": "num",
                        "type": "Int32"
                },
                {
                        "name": "str",
                        "type": "String"
                },

                {
                        "name": "arr",
                        "type": "Array(UInt8)"
                }
        ],

        "data":
        {
                "num": [42, 43, 44],
                "str": ["hello", "hello", "hello"],
                "arr": [[0,1], [0,1,2], [0,1,2,3]]
        },

        "rows": 3,

        "rows_before_limit_at_least": 3,

        "statistics":
        {
                "elapsed": 0.000272376,
                "rows_read": 3,
                "bytes_read": 24
        }
}

JSONColumnsWithMetadata入力形式において、input_format_json_validate_types_from_metadataの設定が1に設定されている場合は、入力データのメタデータからの型をテーブルの対応するカラムの型と比較します。

JSONAsString

この形式では、単一のJSONオブジェクトを単一の値として解釈します。入力に複数のJSONオブジェクト（カンマで区切られる）がある場合、それらは別々の行として解釈されます。入力データが角括弧で囲まれている場合、それはJSONの配列として解釈されます。

この形式は、String型の単一フィールドのテーブルに対してのみ解析できます。残りのカラムはDEFAULTまたはMATERIALIZEDとして設定するか、省略する必要があります。全体のJSONオブジェクトを文字列として収集した後に、JSON関数を使用して処理できます。

例

クエリ:

DROP TABLE IF EXISTS json_as_string;
CREATE TABLE json_as_string (json String) ENGINE = Memory;
INSERT INTO json_as_string (json) FORMAT JSONAsString {"foo":{"bar":{"x":"y"},"baz":1}},{},{"any json stucture":1}
SELECT * FROM json_as_string;

結果:

┌─json──────────────────────────────┐
│ {"foo":{"bar":{"x":"y"},"baz":1}} │
│ {}                                │
│ {"any json stucture":1}           │
└───────────────────────────────────┘

複数のJSONオブジェクトからなる配列

クエリ:

CREATE TABLE json_square_brackets (field String) ENGINE = Memory;
INSERT INTO json_square_brackets FORMAT JSONAsString [{"id": 1, "name": "name1"}, {"id": 2, "name": "name2"}];

SELECT * FROM json_square_brackets;

結果:

┌─field──────────────────────┐
│ {"id": 1, "name": "name1"} │
│ {"id": 2, "name": "name2"} │
└────────────────────────────┘

JSONAsObject

この形式では、単一のJSONオブジェクトを単一のJSON値として解釈します。入力に複数のJSONオブジェクト（カンマで区切られる）がある場合、それらは別々の行として解釈されます。入力データが角括弧で囲まれている場合、それはJSONの配列として解釈されます。

この形式は、JSON型の単一フィールドのテーブルに対してのみ解析できます。残りのカラムはDEFAULTまたはMATERIALIZEDとして設定する必要があります。

例

クエリ:

SET allow_experimental_json_type = 1;
CREATE TABLE json_as_object (json JSON) ENGINE = Memory;
INSERT INTO json_as_object (json) FORMAT JSONAsObject {"foo":{"bar":{"x":"y"},"baz":1}},{},{"any json stucture":1}
SELECT * FROM json_as_object FORMAT JSONEachRow;

結果:

{"json":{"foo":{"bar":{"x":"y"},"baz":"1"}}}
{"json":{}}
{"json":{"any json stucture":"1"}}

複数のJSONオブジェクトからなる配列

クエリ:

SET allow_experimental_json_type = 1;
CREATE TABLE json_square_brackets (field JSON) ENGINE = Memory;
INSERT INTO json_square_brackets FORMAT JSONAsObject [{"id": 1, "name": "name1"}, {"id": 2, "name": "name2"}];
SELECT * FROM json_square_brackets FORMAT JSONEachRow;

結果:

{"field":{"id":"1","name":"name1"}}
{"field":{"id":"2","name":"name2"}}

デフォルト値を持つカラム

SET allow_experimental_json_type = 1;
CREATE TABLE json_as_object (json JSON, time DateTime MATERIALIZED now()) ENGINE = Memory;
INSERT INTO json_as_object (json) FORMAT JSONAsObject {"foo":{"bar":{"x":"y"},"baz":1}};
INSERT INTO json_as_object (json) FORMAT JSONAsObject {};
INSERT INTO json_as_object (json) FORMAT JSONAsObject {"any json stucture":1}
SELECT time, json FROM json_as_object FORMAT JSONEachRow

{"time":"2024-09-16 12:18:10","json":{}}
{"time":"2024-09-16 12:18:13","json":{"any json stucture":"1"}}
{"time":"2024-09-16 12:18:08","json":{"foo":{"bar":{"x":"y"},"baz":"1"}}}

JSONCompact

データ行をオブジェクトではなく配列で出力する点でJSONとは異なります。

例:

{
    "meta":
    [
        {
            "name": "num",
            "type": "Int32"
        },
        {
            "name": "str",
            "type": "String"
        },
        {
            "name": "arr",
            "type": "Array(UInt8)"
        }
    ],

    "data":
    [
        [42, "hello", [0,1]],
        [43, "hello", [0,1,2]],
        [44, "hello", [0,1,2,3]]
    ],

    "rows": 3,

    "rows_before_limit_at_least": 3,

    "statistics":
    {
        "elapsed": 0.001222069,
        "rows_read": 3,
        "bytes_read": 24
    }
}

JSONCompactStrings

データ行をオブジェクトではなく配列で出力する点でJSONStringsとは異なります。

例:

{
    "meta":
    [
        {
            "name": "num",
            "type": "Int32"
        },
        {
            "name": "str",
            "type": "String"
        },
        {
            "name": "arr",
            "type": "Array(UInt8)"
        }
    ],

    "data":
    [
        ["42", "hello", "[0,1]"],
        ["43", "hello", "[0,1,2]"],
        ["44", "hello", "[0,1,2,3]"]
    ],

    "rows": 3,

    "rows_before_limit_at_least": 3,

    "statistics":
    {
        "elapsed": 0.001572097,
        "rows_read": 3,
        "bytes_read": 24
    }
}

JSONCompactColumns

この形式では、すべてのデータが単一のJSON配列として表現されます。 JSONCompactColumns出力形式は、すべてのデータをメモリにバッファーして単一のブロックとして出力するため、高メモリ消費につながる可能性があります。

例:

[
    [42, 43, 44],
    ["hello", "hello", "hello"],
    [[0,1], [0,1,2], [0,1,2,3]]
]

ブロックに存在しないカラムはデフォルト値で埋められます（ここでinput_format_defaults_for_omitted_fields設定を使用できます）。

JSONEachRow

この形式では、ClickHouseは各行を区切り、新しい行ごとに区切られたJSONオブジェクトとして出力します。

例:

{"num":42,"str":"hello","arr":[0,1]}
{"num":43,"str":"hello","arr":[0,1,2]}
{"num":44,"str":"hello","arr":[0,1,2,3]}

データをインポートすると、input_format_skip_unknown_fieldsが1に設定されている場合に、名前の知られていないカラムはスキップされます。

PrettyJSONEachRow

JSONEachRowと異なる点は、JSONが改行デリミタと4つのスペースのインデントで整形されて出力される点です。出力専用に適しています。

例:

{
    "num": "42",
    "str": "hello",
    "arr": [
        "0",
        "1"
    ],
    "tuple": {
        "num": 42,
        "str": "world"
    }
}
{
    "num": "43",
    "str": "hello",
    "arr": [
        "0",
        "1",
        "2"
    ],
    "tuple": {
        "num": 43,
        "str": "world"
    }
}

JSONStringsEachRow

JSONEachRowと異なる点は、データフィールドが文字列として出力され、型付きJSON値としてではないことです。

例:

{"num":"42","str":"hello","arr":"[0,1]"}
{"num":"43","str":"hello","arr":"[0,1,2]"}
{"num":"44","str":"hello","arr":"[0,1,2,3]"}

JSONCompactEachRow

JSONEachRowとは異なる点は、データ行がオブジェクトではなく配列で出力されることです。

例:

[42, "hello", [0,1]]
[43, "hello", [0,1,2]]
[44, "hello", [0,1,2,3]]

JSONCompactStringsEachRow

JSONCompactEachRowと異なる点は、データフィールドが文字列として出力され、型付きJSON値としてではないことです。

例:

["42", "hello", "[0,1]"]
["43", "hello", "[0,1,2]"]
["44", "hello", "[0,1,2,3]"]

JSONEachRowWithProgress

JSONStringsEachRowWithProgress

JSONEachRow/JSONStringsEachRowと異なる点は、ClickHouseが進捗情報もJSON値として提供することです。

{"row":{"num":42,"str":"hello","arr":[0,1]}}
{"row":{"num":43,"str":"hello","arr":[0,1,2]}}
{"row":{"num":44,"str":"hello","arr":[0,1,2,3]}}
{"progress":{"read_rows":"3","read_bytes":"24","written_rows":"0","written_bytes":"0","total_rows_to_read":"3"}}

JSONCompactEachRowWithNames

JSONCompactEachRow形式と異なる点は、カラム名を含むヘッダー行も出力されることです。TabSeparatedWithNames形式に似ています。

:::note settings-formats-input_format_with_names_use_headerの設定が1に設定されている場合、 入力データのカラムは名前でテーブルのカラムにマッピングされます。未知の名前のカラムは、input_format_skip_unknown_fieldsの設定が1に設定されている場合、スキップされます。 それ以外の場合は、最初の行がスキップされます。 :::

JSONCompactEachRowWithNamesAndTypes

JSONCompactEachRow形式と異なる点は、カラム名と型を含む2つのヘッダー行も出力されることです。TabSeparatedWithNamesAndTypes形式に似ています。

:::note settings-formats-input_format_with_names_use_headerの設定が1に設定されている場合、 入力データのカラムは名前でテーブルのカラムにマッピングされます。未知の名前のカラムは、input_format_skip_unknown_fieldsの設定が1に設定されている場合、スキップされます。 それ以外の場合は、最初の行がスキップされます。 settings-formats-input_format_with_types_use_headerの設定が1に設定されている場合、 入力データの型はテーブルの対応するカラムの型と比較されます。そうでない場合、2番目の行はスキップされます。 :::

JSONCompactStringsEachRowWithNames

JSONCompactStringsEachRowとは異なる点は、カラム名を含むヘッダー行も出力されることです。TabSeparatedWithNames形式に似ています。

:::note settings-formats-input_format_with_names_use_headerの設定が1に設定されている場合、 入力データのカラムは名前でテーブルのカラムにマッピングされます。未知の名前のカラムは、input_format_skip_unknown_fieldsの設定が1に設定されている場合、スキップされます。 それ以外の場合は、最初の行がスキップされます。 :::

JSONCompactStringsEachRowWithNamesAndTypes

JSONCompactStringsEachRowとは異なる点は、カラム名と型を含む2つのヘッダー行も出力されることです。TabSeparatedWithNamesAndTypes形式に似ています。

:::note settings-formats-input_format_with_names_use_headerの設定が1に設定されている場合、 入力データのカラムは名前でテーブルのカラムにマッピングされます。未知の名前のカラムは、input_format_skip_unknown_fieldsの設定が1に設定されている場合、スキップされます。 それ以外の場合は、最初の行がスキップされます。 settings-formats-input_format_with_types_use_headerの設定が1に設定されている場合、 入力データの型はテーブルの対応するカラムの型と比較されます。そうでない場合、2番目の行はスキップされます。 :::

["num", "str", "arr"]
["Int32", "String", "Array(UInt8)"]
[42, "hello", [0,1]]
[43, "hello", [0,1,2]]
[44, "hello", [0,1,2,3]]

JSONObjectEachRow

この形式では、すべてのデータが単一のJSONオブジェクトとして表現され、各行がこのオブジェクトの個別のフィールドとして表され、JSONEachRow形式に似ています。

例:

{
    "row_1": {"num": 42, "str": "hello", "arr":  [0,1]},
    "row_2": {"num": 43, "str": "hello", "arr":  [0,1,2]},
    "row_3": {"num": 44, "str": "hello", "arr":  [0,1,2,3]}
}

オブジェクト名をカラム値として使用するには、特別な設定format_json_object_each_row_column_for_object_nameを使用できます。この設定の値は、結果のオブジェクトで行のJSONキーとして使用されるカラムの名前に設定されます。

例:

出力の場合:

テーブルtestを次のように仮定します。2つのカラムがあります:

┌─object_name─┬─number─┐
│ first_obj   │      1 │
│ second_obj  │      2 │
│ third_obj   │      3 │
└─────────────┴────────┘

JSONObjectEachRow形式で出力し、format_json_object_each_row_column_for_object_name設定を使用しましょう:

select * from test settings format_json_object_each_row_column_for_object_name='object_name'

出力:

{
    "first_obj": {"number": 1},
    "second_obj": {"number": 2},
    "third_obj": {"number": 3}
}

入力の場合:

前の例からの出力をdata.jsonというファイルに保存したと仮定します:

select * from file('data.json', JSONObjectEachRow, 'object_name String, number UInt64') settings format_json_object_each_row_column_for_object_name='object_name'

┌─object_name─┬─number─┐
│ first_obj   │      1 │
│ second_obj  │      2 │
│ third_obj   │      3 │
└─────────────┴────────┘

スキーマ推論でも動作します:

desc file('data.json', JSONObjectEachRow) settings format_json_object_each_row_column_for_object_name='object_name'

┌─name────────┬─type────────────┐
│ object_name │ String          │
│ number      │ Nullable(Int64) │
└─────────────┴─────────────────┘

データの挿入

INSERT INTO UserActivity FORMAT JSONEachRow {"PageViews":5, "UserID":"4324182021466249494", "Duration":146,"Sign":-1} {"UserID":"4324182021466249494","PageViews":6,"Duration":185,"Sign":1}

ClickHouseは以下を許可します:

• オブジェクト内のキーと値のペアの順序は任意です。
• 一部の値の省略。

ClickHouseは要素間の空白やオブジェクト後のカンマを無視します。すべてのオブジェクトを1行で渡すことができます。行区切りは必要ありません。

省略された値の処理

ClickHouseは、省略された値を対応するデータ型のデフォルト値で補います。

DEFAULT exprが指定されている場合、ClickHouseは、input_format_defaults_for_omitted_fields設定に応じて異なる置換ルールを使用します。

次のテーブルを考慮してください:

CREATE TABLE IF NOT EXISTS example_table
(
    x UInt32,
    a DEFAULT x * 2
) ENGINE = Memory;

• input_format_defaults_for_omitted_fields = 0の場合、xとaのデフォルト値はともに0（UInt32データ型のデフォルト値）です。
• input_format_defaults_for_omitted_fields = 1の場合、xのデフォルト値は0ですが、aのデフォルト値はx * 2です。

:::note input_format_defaults_for_omitted_fields = 1でデータを挿入すると、input_format_defaults_for_omitted_fields = 0での挿入に比べて、ClickHouseはより多くの計算資源を消費します。 :::

データの選択

UserActivityテーブルを例として考慮しましょう:

┌──────────────UserID─┬─PageViews─┬─Duration─┬─Sign─┐
│ 4324182021466249494 │         5 │      146 │   -1 │
│ 4324182021466249494 │         6 │      185 │    1 │
└─────────────────────┴───────────┴──────────┴──────┘

クエリSELECT * FROM UserActivity FORMAT JSONEachRowは以下を返します:

{"UserID":"4324182021466249494","PageViews":5,"Duration":146,"Sign":-1}
{"UserID":"4324182021466249494","PageViews":6,"Duration":185,"Sign":1}

JSON形式と異なり、無効なUTF-8シーケンスの置換はありません。値はJSONと同じようにエスケープされます。

:::info 任意のバイトセットは文字列に出力できます。データが情報を失うことなくJSONとしてフォーマット可能であると確信している場合は、JSONEachRow形式を使用してください。 :::

ネスト構造の使用

Nestedデータ型カラムを持つテーブルがある場合、同じ構造のJSONデータを挿入できます。input_format_import_nested_json設定を有効にしてください。

例として、次のテーブルを考慮してください:

CREATE TABLE json_each_row_nested (n Nested (s String, i Int32) ) ENGINE = Memory

Nestedデータ型の説明で示すように、ClickHouseはネストされた構造の各要素を別々のカラムとして扱います（我々のテーブルではn.sとn.i）。次のようにデータを挿入できます:

INSERT INTO json_each_row_nested FORMAT JSONEachRow {"n.s": ["abc", "def"], "n.i": [1, 23]}

データを階層型JSONオブジェクトとして挿入するには、input_format_import_nested_json=1に設定します。

{
    "n": {
        "s": ["abc", "def"],
        "i": [1, 23]
    }
}

この設定なしでは、ClickHouseは例外を投げます。

SELECT name, value FROM system.settings WHERE name = 'input_format_import_nested_json'

┌─name────────────────────────────┬─value─┐
│ input_format_import_nested_json │ 0     │
└─────────────────────────────────┴───────┘

INSERT INTO json_each_row_nested FORMAT JSONEachRow {"n": {"s": ["abc", "def"], "i": [1, 23]}}

Code: 117. DB::Exception: Unknown field found while parsing JSONEachRow format: n: (at row 1)

SET input_format_import_nested_json=1
INSERT INTO json_each_row_nested FORMAT JSONEachRow {"n": {"s": ["abc", "def"], "i": [1, 23]}}
SELECT * FROM json_each_row_nested

┌─n.s───────────┬─n.i────┐
│ ['abc','def'] │ [1,23] │
└───────────────┴────────┘

JSON形式の設定

• input_format_import_nested_json - ネストされたJSONデータをネストされたテーブルにマップします（これはJSONEachRow形式で機能します）。デフォルト値 - false。
• input_format_json_read_bools_as_numbers - JSON入力形式でブール値を数値として解析します。デフォルト値 - true。
• input_format_json_read_bools_as_strings - JSON入力形式でブール値を文字列として解析します。デフォルト値 - true。
• input_format_json_read_numbers_as_strings - JSON入力形式で数値を文字列として解析します。デフォルト値 - true。
• input_format_json_read_arrays_as_strings - JSON入力形式で配列を文字列として解析します。デフォルト値 - true。
• input_format_json_read_objects_as_strings - JSON入力形式でオブジェクトを文字列として解析します。デフォルト値 - true。
• input_format_json_named_tuples_as_objects - 名前付きタプルカラムをJSONオブジェクトとして解析します。デフォルト値 - true。
• input_format_json_try_infer_numbers_from_strings - スキーマ推論中に文字列フィールドから数値を推測しようとします。デフォルト値 - false。
• input_format_json_try_infer_named_tuples_from_objects - スキーマ推論中にJSONオブジェクトから名前付きタプルを推測しようとします。デフォルト値 - true。
• input_format_json_infer_incomplete_types_as_strings - JSON入力形式でスキーマ推論中にNullまたは空のオブジェクト/配列のみを含むKeysにString型を使用します。デフォルト値 - true。
• input_format_json_defaults_for_missing_elements_in_named_tuple - 名前付きタプル解析中に、JSONオブジェクト内で欠けている要素に対してデフォルト値を挿入します。デフォルト値 - true。
• input_format_json_ignore_unknown_keys_in_named_tuple - 名前付きタプルのjsonオブジェクト内で未知のキーを無視します。デフォルト値 - false。
• input_format_json_compact_allow_variable_number_of_columns - JSONCompact/JSONCompactEachRow形式で変動するカラム数を許可し、余分なカラムを無視し、欠けているカラムにデフォルト値を使用します。デフォルト値 - false。
• input_format_json_throw_on_bad_escape_sequence - JSON文字列に誤ったエスケープシーケンスが含まれている場合に例外をスローします。無効化された場合、誤ったエスケープシーケンスはデータ内でそのまま残ります。デフォルト値 - true。
• input_format_json_empty_as_default - JSON入力で空のフィールドをデフォルト値として処理します。デフォルト値 - false。複雑なデフォルト式の場合は、input_format_defaults_for_omitted_fieldsも有効にする必要があります。
• output_format_json_quote_64bit_integers - JSON出力形式で64ビット整数の引用を制御します。デフォルト値 - true。
• output_format_json_quote_64bit_floats - JSON出力形式で64ビット浮動小数点数の引用を制御します。デフォルト値 - false。
• output_format_json_quote_denormals - JSON出力形式での+nan、-nan、+inf、-inf の出力を有効にします。デフォルト値 - false。
• output_format_json_quote_decimals - JSON出力形式での小数の引用を制御します。デフォルト値 - false。
• output_format_json_escape_forward_slashes - JSON出力形式での文字列出力のスラッシュのエスケープを制御します。デフォルト値 - true。
• output_format_json_named_tuples_as_objects - 名前付きタプルカラムをJSONオブジェクトとしてシリアライズします。デフォルト値 - true。
• output_format_json_array_of_rows - JSONEachRow(Compact)形式で全行のJSON配列を出力します。デフォルト値 - false。
• output_format_json_validate_utf8 - JSON出力形式でのUTF-8シーケンスの検証を有効にします（それはJSON/JSONCompact/JSONColumnsWithMetadata形式に影響しません、それらは常にutf8を検証します）。デフォルト値 - false。

BSONEachRow

この形式では、ClickHouseはデータを区分なしでBSONドキュメントのシーケンスとしてフォーマット/解析します。 各行は単一のドキュメントとしてフォーマットされ、各カラムはカラム名をキーとして単一のBSONドキュメントフィールドとしてフォーマットされます。

出力のために、ClickHouseのタイプとBSONタイプの対応関係は次の通りです：

ClickHouseのタイプ	BSONタイプ
Bool	\x08 boolean
Int8/UInt8/Enum8	\x10 int32
Int16/UInt16/Enum16	\x10 int32
Int32	\x10 int32
UInt32	\x12 int64
Int64/UInt64	\x12 int64
Float32/Float64	\x01 double
Date/Date32	\x10 int32
DateTime	\x12 int64
DateTime64	\x09 datetime
Decimal32	\x10 int32
Decimal64	\x12 int64
Decimal128	\x05 binary, \x00 binary subtype, size = 16
Decimal256	\x05 binary, \x00 binary subtype, size = 32
Int128/UInt128	\x05 binary, \x00 binary subtype, size = 16
Int256/UInt256	\x05 binary, \x00 binary subtype, size = 32
String/FixedString	\x05 binary, \x00 binary subtype or \x02 string if setting output_format_bson_string_as_string is enabled
UUID	\x05 binary, \x04 uuid subtype, size = 16
Array	\x04 array
Tuple	\x04 array
Named Tuple	\x03 document
Map	\x03 document
IPv4	\x10 int32
IPv6	\x05 binary, \x00 binary subtype

入力のために、BSONタイプとClickHouseのタイプの対応関係は次の通りです:

BSONタイプ	ClickHouseタイプ
\x01 double	Float32/Float64
\x02 string	String/FixedString
\x03 document	Map/Named Tuple
\x04 array	Array/Tuple
\x05 binary, \x00	String/FixedString/IPv6
\x05 binary, \x02 old	String/FixedString
\x05 binary, \x03 old	UUID
\x05 binary, \x04	UUID
\x07 ObjectId	String/FixedString
\x08 boolean	Bool
\x09 datetime	DateTime64
\x0A null value	NULL
\x0D JavaScript code	String/FixedString
\x0E symbol	String/FixedString
\x10 int32	Int32/UInt32/Decimal32/IPv4/Enum8/Enum16
\x12 int64	Int64/UInt64/Decimal64/DateTime64

他のBSONタイプはサポートされていません。また、異なる整数型間の変換を行います（たとえば、BSON int32値をClickHouse UInt8に挿入できます）。 大きな整数および小数（Int128/UInt128/Int256/UInt256/Decimal128/Decimal256）は、\x00バイナリサブタイプを持つBSONバイナリ値から解析できます。この場合、この形式はバイナリデータのサイズが予想値のサイズと等しいことを検証します。

注: この形式は、ビッグエンディアンプラットフォームでは適切に動作しません。

BSON形式の設定

• output_format_bson_string_as_string - Stringカラムに対してBSON Stringタイプを使用します。デフォルト値 - false。
• input_format_bson_skip_fields_with_unsupported_types_in_schema_inference - フォーマットBSONEachRowのスキーマ推論中にサポートされていない型を持つカラムをスキップすることを許可します。デフォルト値 - false。

Native

最も効率的な形式です。データはバイナリ形式でブロックごとに書き込まれ読み取られます。各ブロックについて、行数、カラム数、カラム名と型、そしてこのブロックのカラム部分が次々に記録されます。言い換えれば、この形式は「カラム型」であり、カラムを行に変換しません。これは、サーバー間のインターフェイスで使用される形式であり、コマンドラインクライアントやC++クライアントで使用するためのものです。

この形式を使用して、ClickHouse DBMSでのみ読み取ることができるダンプを迅速に生成することができます。この形式を自分で操作する意味はありません。

Null

何も出力しません。ただし、クエリは処理され、コマンドラインクライアントを使用している場合には、データがクライアントに伝送されます。これは、テスト、特にパフォーマンステストに使用されます。 当然ながら、この形式は出力専用であり、解析には適していません。

Pretty

Unicodeアートテーブルとしてデータを出力し、ANSIエスケープシーケンスを使用して端末内の色を設定します。 テーブルの完全なグリッドが描画され、各行は端末内で2行を占有します。 各結果ブロックは個別のテーブルとして出力されます。これは、結果をバッファリングせずにブロックを出力するために必要です（値の可視幅をすべて事前に計算するためにはバッファリングが必要になります）。

NULLはᴺᵁᴸᴸとして出力されます。

例（PrettyCompact形式で表示）:

SELECT * FROM t_null

┌─x─┬────y─┐
│ 1 │ ᴺᵁᴸᴸ │
└───┴──────┘

行はPretty*形式ではエスケープされません。例はPrettyCompact形式で表示されます:

SELECT 'String with \'quotes\' and \t character' AS Escaping_test

┌─Escaping_test────────────────────────┐
│ String with 'quotes' and      character │
└──────────────────────────────────────┘

端末にあまりにも多くのデータをダンプしないように、最初の10,000行のみが印刷されます。行数が10,000以上の場合、「Showed first 10 000」というメッセージが印刷されます。この形式は、クエリ結果を出力するためにのみ適しており、解析には適していません（テーブルに挿入するためにデータを取得する）。

Pretty形式は、総合値（WITH TOTALSを使用した場合）と極端値（'extremes'が1に設定されている場合）の出力をサポートします。この場合、総合値と極端値はメインデータの後に個別のテーブルで出力されます。例（PrettyCompact形式で表示）:

SELECT EventDate, count() AS c FROM test.hits GROUP BY EventDate WITH TOTALS ORDER BY EventDate FORMAT PrettyCompact

┌──EventDate─┬───────c─┐
│ 2014-03-17 │ 1406958 │
│ 2014-03-18 │ 1383658 │
│ 2014-03-19 │ 1405797 │
│ 2014-03-20 │ 1353623 │
│ 2014-03-21 │ 1245779 │
│ 2014-03-22 │ 1031592 │
│ 2014-03-23 │ 1046491 │
└────────────┴─────────┘

Totals:
┌──EventDate─┬───────c─┐
│ 1970-01-01 │ 8873898 │
└────────────┴─────────┘

Extremes:
┌──EventDate─┬───────c─┐
│ 2014-03-17 │ 1031592 │
│ 2014-03-23 │ 1406958 │
└────────────┴─────────┘

PrettyNoEscapes

Prettyとは異なりANSIエスケープシーケンスは使用されません。これはブラウザでこの形式を表示するのに必要であり、また、「watch」コマンドラインユーティリティを使用する際にも役立ちます。

例:

$ watch -n1 "clickhouse-client --query='SELECT event, value FROM system.events FORMAT PrettyCompactNoEscapes'"

ブラウザで表示するためには、HTTPインターフェイスを使用することができます。

PrettyMonoBlock

Prettyとは異なり、最大10,000行がバッファリングされ、ブロックではなく単一のテーブルとして出力されます。

PrettyNoEscapesMonoBlock

PrettyNoEscapesとは異なり、最大10,000行がバッファリングされ、ブロックではなく単一のテーブルとして出力されます。

PrettyCompact

Prettyとは異なり、行間にグリッドが描画され、結果がよりコンパクトになります。 この形式は、対話モードのコマンドラインクライアントでデフォルトで使用されます。

PrettyCompactNoEscapes

PrettyCompactとは異なり、ANSIエスケープシーケンスは使用されません。これはブラウザでこの形式を表示するのに必要であり、「watch」コマンドラインユーティリティを使用する際にも役立ちます。

PrettyCompactMonoBlock

PrettyCompactとは異なり、最大10,000行がバッファリングされ、ブロックではなく単一のテーブルとして出力されます。

PrettyCompactNoEscapesMonoBlock

PrettyCompactNoEscapesとは異なり、最大10,000行がバッファリングされ、ブロックではなく単一のテーブルとして出力されます。

PrettySpace

PrettyCompactとは異なり、グリッドの代わりにホワイトスペース（スペース文字）が使用されます。

PrettySpaceNoEscapes

PrettySpaceとは異なり、ANSIエスケープシーケンスは使用されません。これはブラウザでこの形式を表示するのに必要であり、「watch」コマンドラインユーティリティを使用する際にも役立ちます。

PrettySpaceMonoBlock

PrettySpaceとは異なり、最大10,000行がバッファリングされ、ブロックではなく単一のテーブルとして出力されます。

PrettySpaceNoEscapesMonoBlock

PrettySpaceNoEscapesとは異なり、最大10,000行がバッファリングされ、ブロックではなく単一のテーブルとして出力されます。

Pretty形式の設定

• output_format_pretty_max_rows - Prettyフォーマットの行のリミット。デフォルト値 - 10000。
• output_format_pretty_max_column_pad_width - Prettyフォーマットでカラム内のすべての値をパッドする最大幅。デフォルト値 - 250。
• output_format_pretty_max_value_width - Prettyフォーマットで表示する最大の値の幅。これを超える場合は切り捨てられます。デフォルト値 - 10000。
• output_format_pretty_color - PrettyフォーマットでANSIエスケープシーケンスを使用して色を塗る。デフォルト値 - true。
• output_format_pretty_grid_charset - グリッドの罫線を印刷するための文字セット。使用可能な文字セット: ASCII, UTF-8。デフォルト値 - UTF-8。
• output_format_pretty_row_numbers - Pretty出力形式で各行の前に行番号を追加する。デフォルト値 - true。
• output_format_pretty_display_footer_column_names - テーブル内に多くの行がある場合、フッターでカラム名を表示する。デフォルト値 - true。
• output_format_pretty_display_footer_column_names_min_rows - フッターが表示される最小行数を設定します。output_format_pretty_display_footer_column_namesが有効な場合に適用されます。デフォルト値 - 50。

RowBinary

データを行ごとにバイナリ形式でフォーマットおよび解析します。行と値は区切りなしで列挙されます。データがバイナリ形式であるため、FORMAT RowBinaryの後の区切り文字は次のように厳密に指定されます：任意の数の空白（スペース' ' - スペース、コード0x20; タブ'\t' - タブ、コード0x09; 改ページ'\f' - 改ページ、コード0x0C）に続いて正確に1つの新しい行シーケンス（Windowsスタイル"\r\n"またはUnixスタイル'\n'）であり、そのすぐ後にバイナリデータがあります。 この形式は、ネイティブ形式よりも効率が悪く、行ベースであるためです。

整数は固定長リトルエンディアン表現を使用します。たとえば、UInt64は8バイトを使用します。 DateTimeはUnixタイムスタンプを値として格納するUInt32として表現されます。 Dateは1970-01-01からの日数を値として格納するUInt16オブジェクトとして表現されます。 Stringは可変長（符号なしLEB128）として表現され、文字列のバイトが続きます。 FixedStringは単にバイトのシーケンスとして表されます。

Arrayは可変長（符号なしLEB128）として表現され、配列の連続する要素が続きます。

NULLサポートのため、各Nullable値の前に1または0を含む追加のバイトが追加されます。1の場合、値はNULLとされ、このバイトは別の値として解釈されます。0の場合、このバイトの後の値はNULLではありません。

RowBinaryWithNames

RowBinaryと類似しますが、ヘッダーが追加されています:

• LEB128でエンコードされたカラム数(N)
• N個のStringがカラム名を指定

:::note settings-formats-input_format_with_names_use_headerの設定が1に設定されている場合、 入力データのカラムは名前でテーブルのカラムにマッピングされます。未知の名前のカラムは、input_format_skip_unknown_fieldsの設定が1に設定されている場合、スキップされます。 それ以外の場合は、最初の行がスキップされます。 :::

RowBinaryWithNamesAndTypes

RowBinaryと類似しますが、ヘッダーが追加されています:

• LEB128でエンコードされたカラム数(N)
• N個のStringがカラム名を指定
• N個のStringがカラム型を指定

:::note settings-formats-input_format_with_names_use_headerの設定が1に設定されている場合、 入力データのカラムは名前でテーブルのカラムにマッピングされます。未知の名前のカラムは、input_format_skip_unknown_fieldsの設定が1に設定されている場合、スキップされます。 それ以外の場合は、最初の行がスキップされます。 settings-formats-input_format_with_types_use_headerの設定が1に設定されている場合、 入力データの型はテーブルの対応するカラムの型と比較されます。そうでない場合、2番目の行はスキップされます。 :::

RowBinaryWithDefaults

RowBinaryと類似しますが、各カラムの前にデフォルト値を使用するかどうかを示す追加のバイトがあります。

例:

:) select * from format('RowBinaryWithDefaults', 'x UInt32 default 42, y UInt32', x'010001000000')

┌──x─┬─y─┐
│ 42 │ 1 │
└────┴───┘

カラムxの場合、唯一の1バイト01がデフォルト値が使用されるべきであることを示し、その後のデータは提供されません。 カラムyの場合、データは00のバイトで始まり、これはカラムに実際の値があることを示し、その後のデータ01000000から読む必要があります。

RowBinary形式の設定

• format_binary_max_string_size - RowBinary形式でのStringに対する最大許容サイズ。デフォルト値 - 1GiB。
• output_format_binary_encode_types_in_binary_format - ヘッダー内での型の名前を持つ文字列の代わりに、バイナリエンコーディングを使用してRowBinaryWithNamesAndTypes出力形式で型を記述します。デフォルト値 - false。
• input_format_binary_encode_types_in_binary_format - RowBinaryWithNamesAndTypes入力形式で型名を文字列としてではなく、バイナリエンコーディングを使用してヘッダー内の型を読み取ることを許可します。デフォルト値 - false.
• output_format_binary_write_json_as_string - RowBinary出力形式でJSONデータ型の値をJSON String値として書き込むことを許可します。デフォルト値 - false.
• input_format_binary_read_json_as_string - RowBinary入力形式でJSONデータ型の値をJSON String値として読み取ることを許可します。デフォルト値 - false.

値

各行を括弧で囲んで出力します。行はカンマで区切られ、最後の行の後にはカンマはありません。括弧内の値もカンマで区切られています。数値は引用符なしの10進形式で出力されます。配列は角括弧で出力されます。文字列、日付、および時間を伴う日付は引用符で出力されます。エスケープルールと解析はTabSeparated形式と似ています。フォーマット中、余分なスペースは挿入されませんが、解析中には許可されスキップされます（配列値内のスペースを除く、これは許可されません）。NULLはNULLとして表現されます。

Values形式でデータを渡す際にエスケープが必要な最小限の文字セット：シングルクオートとバックスラッシュ。

この形式はINSERT INTO t VALUES ...で使用されますが、クエリの結果をフォーマットするために使用することもできます。

値形式の設定

• input_format_values_interpret_expressions - ストリーミングパーサがフィールドを解析できない場合、SQLパーサを実行し、SQL式として解釈しようとします。デフォルト値 - true.
• input_format_values_deduce_templates_of_expressions - ストリーミングパーサがフィールドを解析できない場合、SQLパーサを実行し、SQL式のテンプレートを導出し、テンプレートを使用してすべての行を解析し、すべての行に対して式を解釈しようとします。デフォルト値 - true.
• input_format_values_accurate_types_of_literals - テンプレートを使用して式を解析し解釈する際に、リテラルの実際の型をチェックして、オーバーフローや精度の問題を回避します。デフォルト値 - true.

垂直

各値を指定されたカラム名とともに別の行に出力します。この形式は、各行が多数のカラムで構成されている場合に、1行または数行だけを出力するのに便利です。

NULLはᴺᵁᴸᴸとして出力されます。

例:

SELECT * FROM t_null FORMAT Vertical

Row 1:
──────
x: 1
y: ᴺᵁᴸᴸ

Vertical形式では行はエスケープされません:

SELECT 'string with \'quotes\' and \t with some special \n characters' AS test FORMAT Vertical

Row 1:
──────
test: string with 'quotes' and      with some special
 characters

この形式はクエリ結果の出力にのみ適していますが、テーブルに挿入するデータを解析する（取得する）ためには適していません。

XML

XML形式は出力専用であり、解析には適していません。例:

<?xml version='1.0' encoding='UTF-8' ?>
<result>
        <meta>
                <columns>
                        <column>
                                <name>SearchPhrase</name>
                                <type>String</type>
                        </column>
                        <column>
                                <name>count()</name>
                                <type>UInt64</type>
                        </column>
                </columns>
        </meta>
        <data>
                <row>
                        <SearchPhrase></SearchPhrase>
                        <field>8267016</field>
                </row>
                <row>
                        <SearchPhrase>bathroom interior design</SearchPhrase>
                        <field>2166</field>
                </row>
                <row>
                        <SearchPhrase>clickhouse</SearchPhrase>
                        <field>1655</field>
                </row>
                <row>
                        <SearchPhrase>2014 spring fashion</SearchPhrase>
                        <field>1549</field>
                </row>
                <row>
                        <SearchPhrase>freeform photos</SearchPhrase>
                        <field>1480</field>
                </row>
                <row>
                        <SearchPhrase>angelina jolie</SearchPhrase>
                        <field>1245</field>
                </row>
                <row>
                        <SearchPhrase>omsk</SearchPhrase>
                        <field>1112</field>
                </row>
                <row>
                        <SearchPhrase>photos of dog breeds</SearchPhrase>
                        <field>1091</field>
                </row>
                <row>
                        <SearchPhrase>curtain designs</SearchPhrase>
                        <field>1064</field>
                </row>
                <row>
                        <SearchPhrase>baku</SearchPhrase>
                        <field>1000</field>
                </row>
        </data>
        <rows>10</rows>
        <rows_before_limit_at_least>141137</rows_before_limit_at_least>
</result>

カラム名が受け入れ可能な形式でない場合、単に‘field’が要素名として使用されます。一般に、XML構造はJSON構造に従います。JSONと同様に、無効なUTF-8シーケンスは置換文字<E69687>に変更されるため、出力テキストは有効なUTF-8シーケンスで構成されます。

文字列値内の文字<と&はそれぞれ<と&としてエスケープされます。

配列は<array><elem>Hello</elem><elem>World</elem>...</array>として、タプルは<tuple><elem>Hello</elem><elem>World</elem>...</tuple>として出力されます。

CapnProto

CapnProtoは、Protocol BuffersやThriftに似たバイナリメッセージ形式ですが、JSONやMessagePackとは異なります。

CapnProtoメッセージは厳密に型付けされており、自己記述的ではありません。したがって、外部スキーマの記述が必要です。スキーマはクエリごとにキャッシュされその場で適用されます。

また、Format Schemaも参照してください。

データ型のマッチング

以下の表は、INSERTおよびSELECTクエリにおけるClickHouseのデータ型と対応するサポートされているデータ型を示しています。

CapnProto データ型 (INSERT)	ClickHouse データ型	CapnProto データ型 (SELECT)
UINT8, BOOL	UInt8	UINT8
INT8	Int8	INT8
UINT16	UInt16, Date	UINT16
INT16	Int16	INT16
UINT32	UInt32, DateTime	UINT32
INT32	Int32, Decimal32	INT32
UINT64	UInt64	UINT64
INT64	Int64, DateTime64, Decimal64	INT64
FLOAT32	Float32	FLOAT32
FLOAT64	Float64	FLOAT64
TEXT, DATA	String, FixedString	TEXT, DATA
union(T, Void), union(Void, T)	Nullable(T)	union(T, Void), union(Void, T)
ENUM	Enum(8/16)	ENUM
LIST	Array	LIST
STRUCT	Tuple	STRUCT
UINT32	IPv4	UINT32
DATA	IPv6	DATA
DATA	Int128/UInt128/Int256/UInt256	DATA
DATA	Decimal128/Decimal256	DATA
STRUCT(entries LIST(STRUCT(key Key, value Value)))	Map	STRUCT(entries LIST(STRUCT(key Key, value Value)))

整数型は入力/出力の際に相互に変換可能です。

CapnProto形式でEnumを扱うにはformat_capn_proto_enum_comparising_mode設定を使用してください。

配列はネスト可能であり、Nullable型を引数として持つことができます。TupleとMap型もネストできます。

データの挿入と選択

ファイルからCapnProtoデータをClickHouseテーブルに挿入するには、以下のコマンドを使用します:

$ cat capnproto_messages.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_schema = 'schema:Message' FORMAT CapnProto"

ここで、schema.capnpは以下のようになります:

struct Message {
  SearchPhrase @0 :Text;
  c @1 :Uint64;
}

ClickHouseテーブルからデータを選択し、CapnProto形式でファイルに保存するには、以下のコマンドを使用します:

$ clickhouse-client --query = "SELECT * FROM test.hits FORMAT CapnProto SETTINGS format_schema = 'schema:Message'"

自動生成スキーマの使用

データの外部CapnProtoスキーマがない場合でも、自動生成スキーマを使用してCapnProto形式でデータを入力/出力することができます。例:

SELECT * FROM test.hits format CapnProto SETTINGS format_capn_proto_use_autogenerated_schema=1

この場合、ClickHouseはテーブルの構造に従ってCapnProtoスキーマを自動生成し、このスキーマを使用してCapnProto形式でデータをシリアル化します。

自動生成スキーマでCapnProtoファイルを読み込むこともできます（この場合、ファイルは同じスキーマを使用して作成する必要があります）:

$ cat hits.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_capn_proto_use_autogenerated_schema=1 FORMAT CapnProto"

設定format_capn_proto_use_autogenerated_schemaはデフォルトで有効になっており、format_schemaが設定されていない場合に適用されます。

入力/出力中に自動生成スキーマをファイルに保存することもでき、設定output_format_schemaを使用します。例:

SELECT * FROM test.hits format CapnProto SETTINGS format_capn_proto_use_autogenerated_schema=1, output_format_schema='path/to/schema/schema.capnp'

この場合、自動生成されたCapnProtoスキーマはファイルpath/to/schema/schema.capnpに保存されます。

Prometheus

Prometheusのテキスト形式でメトリックを公開します。

出力テーブルには適切な構造が必要です。 カラムname（String）とvalue（数値）は必須です。 行にはオプションでhelp（String）とtimestamp（数値）を含めることができます。 カラムtype（String）はcounter、gauge、histogram、summary、untypedまたは空です。 各メトリックの値にはいくつかのlabels（Map(String, String)）を持たせることができます。 いくつかの連続した行は、異なるラベルで1つのメトリックに参照される場合があります。テーブルは（例：ORDER BY nameで）メトリック名でソートする必要があります。

[histogram]と[summary]のラベルには特別な要件があります。詳細はPrometheus文書を参照してください。ラベルが{'count':''}および{'sum':''}である行には特別なルールが適用され、それぞれ<metric_name>_countと<metric_name>_sumに変換されます。

例:

┌─name────────────────────────────────┬─type──────┬─help──────────────────────────────────────┬─labels─────────────────────────┬────value─┬─────timestamp─┐
│ http_request_duration_seconds       │ histogram │ A histogram of the request duration.      │ {'le':'0.05'}                  │    24054 │             0 │
│ http_request_duration_seconds       │ histogram │                                           │ {'le':'0.1'}                   │    33444 │             0 │
│ http_request_duration_seconds       │ histogram │                                           │ {'le':'0.2'}                   │   100392 │             0 │
│ http_request_duration_seconds       │ histogram │                                           │ {'le':'0.5'}                   │   129389 │             0 │
│ http_request_duration_seconds       │ histogram │                                           │ {'le':'1'}                     │   133988 │             0 │
│ http_request_duration_seconds       │ histogram │                                           │ {'le':'+Inf'}                  │   144320 │             0 │
│ http_request_duration_seconds       │ histogram │                                           │ {'sum':''}                     │    53423 │             0 │
│ http_requests_total                 │ counter   │ Total number of HTTP requests             │ {'method':'post','code':'200'} │     1027 │ 1395066363000 │
│ http_requests_total                 │ counter   │                                           │ {'method':'post','code':'400'} │        3 │ 1395066363000 │
│ metric_without_timestamp_and_labels │           │                                           │ {}                             │    12.47 │             0 │
│ rpc_duration_seconds                │ summary   │ A summary of the RPC duration in seconds. │ {'quantile':'0.01'}            │     3102 │             0 │
│ rpc_duration_seconds                │ summary   │                                           │ {'quantile':'0.05'}            │     3272 │             0 │
│ rpc_duration_seconds                │ summary   │                                           │ {'quantile':'0.5'}             │     4773 │             0 │
│ rpc_duration_seconds                │ summary   │                                           │ {'quantile':'0.9'}             │     9001 │             0 │
│ rpc_duration_seconds                │ summary   │                                           │ {'quantile':'0.99'}            │    76656 │             0 │
│ rpc_duration_seconds                │ summary   │                                           │ {'count':''}                   │     2693 │             0 │
│ rpc_duration_seconds                │ summary   │                                           │ {'sum':''}                     │ 17560473 │             0 │
│ something_weird                     │           │                                           │ {'problem':'division by zero'} │      inf │      -3982045 │
└─────────────────────────────────────┴───────────┴───────────────────────────────────────────┴────────────────────────────────┴──────────┴───────────────┘

次のようにフォーマットされます:

# HELP http_request_duration_seconds A histogram of the request duration.
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.05"} 24054
http_request_duration_seconds_bucket{le="0.1"} 33444
http_request_duration_seconds_bucket{le="0.5"} 129389
http_request_duration_seconds_bucket{le="1"} 133988
http_request_duration_seconds_bucket{le="+Inf"} 144320
http_request_duration_seconds_sum 53423
http_request_duration_seconds_count 144320

# HELP http_requests_total Total number of HTTP requests
# TYPE http_requests_total counter
http_requests_total{code="200",method="post"} 1027 1395066363000
http_requests_total{code="400",method="post"} 3 1395066363000

metric_without_timestamp_and_labels 12.47

# HELP rpc_duration_seconds A summary of the RPC duration in seconds.
# TYPE rpc_duration_seconds summary
rpc_duration_seconds{quantile="0.01"} 3102
rpc_duration_seconds{quantile="0.05"} 3272
rpc_duration_seconds{quantile="0.5"} 4773
rpc_duration_seconds{quantile="0.9"} 9001
rpc_duration_seconds{quantile="0.99"} 76656
rpc_duration_seconds_sum 17560473
rpc_duration_seconds_count 2693

something_weird{problem="division by zero"} +Inf -3982045

Protobuf

Protobufとは、Protocol Buffers形式です。

この形式は外部フォーマットスキーマが必要です。スキーマはクエリ間でキャッシュされます。 ClickHouseはproto2とproto3の両方のシンタックスをサポートしています。繰り返し/オプション/必須フィールドがサポートされています。

使用例:

SELECT * FROM test.table FORMAT Protobuf SETTINGS format_schema = 'schemafile:MessageType'

cat protobuf_messages.bin | clickhouse-client --query "INSERT INTO test.table SETTINGS format_schema='schemafile:MessageType' FORMAT Protobuf"

ファイルschemafile.protoは以下のようになります:

syntax = "proto3";

message MessageType {
  string name = 1;
  string surname = 2;
  uint32 birthDate = 3;
  repeated string phoneNumbers = 4;
};

テーブルカラムとProtocol Buffersのメッセージ型のフィールドの間の対応を見つけるために、ClickHouseはその名前を比較します。 この比較は大文字と小文字を区別せず、_（アンダースコア）と.（ドット）は等しいとみなされます。 カラムとProtocol Buffersのメッセージのフィールドの型が異なる場合は、必要な変換が適用されます。

ネストされたメッセージがサポートされています。以下のメッセージタイプでフィールド z の場合

message MessageType {
  message XType {
    message YType {
      int32 z;
    };
    repeated YType y;
  };
  XType x;
};

ClickHouseはx.y.z（またはx_y_zやX.y_Zなど）という名前のカラムを探そうとします。 ネストされたメッセージは、ネストされたデータ構造を入力または出力するのに適しています。

プロトコルバッファのスキーマで次のように定義されたデフォルト値

syntax = "proto2";

message MessageType {
  optional int32 result_per_page = 3 [default = 10];
}

は適用されず、テーブルデフォルトが代わりに使用されます。

ClickHouseはlength-delimited形式でプロトコルバッファメッセージを入出力します。 つまり、各メッセージの前に、その長さがvarintとして書かれている必要があります。 また、一般的な言語で長さ区切りのプロトコルバッファメッセージを読み書きする方法も参照してください。

自動生成スキーマの使用

データの外部プロトコルバッファスキーマがない場合でも、自動生成スキーマを使用してプロトコルバッファ形式でデータを入力/出力することができます。例:

SELECT * FROM test.hits format Protobuf SETTINGS format_protobuf_use_autogenerated_schema=1

この場合、ClickHouseはテーブルの構造に従ってプロトコルバッファスキーマを自動生成し、このスキーマを使用してプロトコルバッファ形式でデータをシリアル化します。

自動生成スキーマでプロトコルバッファファイルを読み込むこともできます（この場合、ファイルは同じスキーマを使用して作成する必要があります）:

$ cat hits.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_protobuf_use_autogenerated_schema=1 FORMAT Protobuf"

設定format_protobuf_use_autogenerated_schemaはデフォルトで有効になっており、format_schemaが設定されていない場合に適用されます。

入力/出力中に自動生成スキーマをファイルに保存することもでき、設定output_format_schemaを使用します。例:

SELECT * FROM test.hits format Protobuf SETTINGS format_protobuf_use_autogenerated_schema=1, output_format_schema='path/to/schema/schema.proto'

この場合、自動生成されたプロトコルバッファスキーマはファイルpath/to/schema/schema.capnpに保存されます。

プロトコルバッファキャッシュの削除

format_schema_pathからロードしたプロトコルバッファスキーマをリロードするには、SYSTEM DROP ... FORMAT CACHEステートメントを使用します。

SYSTEM DROP FORMAT SCHEMA CACHE FOR Protobuf

ProtobufSingle

Protobufと同様ですが、長さ区切りがない単一のプロトコルバッファメッセージを保存/解析するためのものです。

ProtobufList

Protobufに似ていますが、行は固定名が「Envelope」であるメッセージ内のサブメッセージのシーケンスとして表現されます。

使用例:

SELECT * FROM test.table FORMAT ProtobufList SETTINGS format_schema = 'schemafile:MessageType'

cat protobuflist_messages.bin | clickhouse-client --query "INSERT INTO test.table FORMAT ProtobufList SETTINGS format_schema='schemafile:MessageType'"

ファイルschemafile.protoは以下のようになります:

syntax = "proto3";
message Envelope {
  message MessageType {
    string name = 1;
    string surname = 2;
    uint32 birthDate = 3;
    repeated string phoneNumbers = 4;
  };
  MessageType row = 1;
};

Avro

Apache Avroは、ApacheのHadoopプロジェクト内で開発された行指向のデータシリアル化フレームワークです。

ClickHouseのAvro形式はAvroデータファイルの読み取りおよび書き込みをサポートしています。

データ型のマッチング

以下の表は、INSERTおよびSELECTクエリにおけるClickHouseのデータ型とのマッチングを示しています。

Avro データ型 INSERT	ClickHouse データ型	Avro データ型 SELECT
boolean, int, long, float, double	Int(8\16\32), UInt(8\16\32)	int
boolean, int, long, float, double	Int64, UInt64	long
boolean, int, long, float, double	Float32	float
boolean, int, long, float, double	Float64	double
bytes, string, fixed, enum	String	bytes または string *
bytes, string, fixed	FixedString(N)	fixed(N)
enum	Enum(8\16)	enum
array(T)	Array(T)	array(T)
map(V, K)	Map(V, K)	map(string, K)
union(null, T), union(T, null)	Nullable(T)	union(null, T)
union(T1, T2, …) **	Variant(T1, T2, …)	union(T1, T2, …) **
null	Nullable(Nothing)	null
int (date) ***	Date, Date32	int (date) ***
long (timestamp-millis) ***	DateTime64(3)	long (timestamp-millis) ***
long (timestamp-micros) ***	DateTime64(6)	long (timestamp-micros) ***
bytes (decimal) ***	DateTime64(N)	bytes (decimal) ***
int	IPv4	int
fixed(16)	IPv6	fixed(16)
bytes (decimal) ***	Decimal(P, S)	bytes (decimal) ***
string (uuid) ***	UUID	string (uuid) ***
fixed(16)	Int128/UInt128	fixed(16)
fixed(32)	Int256/UInt256	fixed(32)
record	Tuple	record

* bytesはデフォルトです。これはoutput_format_avro_string_column_patternによって制御されます。

** Variant型はフィールド値としてnullを暗黙的に受け入れるため、例えばAvro union(T1, T2, null)はVariant(T1, T2)に変換されます。 結果として、ClickHouseからAvroを生成する際には、スキーマ推論中に任意の値が実際にnullかどうか不明なため、union型セットに常にnull型を含める必要があります。

*** Avro論理型

サポートされていないAvro論理データ型：time-millis, time-micros, duration

データ挿入

AvroファイルからClickHouseテーブルにデータを挿入するには:

$ cat file.avro | clickhouse-client --query="INSERT INTO {some_table} FORMAT Avro"

入力Avroファイルのルートスキーマはrecord型でなければなりません。

テーブルカラムとAvroスキーマのフィールドの間の対応を見つけるために、ClickHouseはその名前を比較します。比較は大文字と小文字を区別します。 使用されていないフィールドはスキップされます。

ClickHouseテーブルカラムのデータ型は、挿入されるAvroデータの対応するフィールドの型と異なる可能性があります。データを挿入する際、ClickHouseは上記の表に従ってデータ型を解釈し、その後、ClickHouseテーブルカラムに対応する型にデータをキャストします。

データをインポートする際、スキーマ内でフィールドが見つからず、設定inform_format_avro_allow_missing_fieldsが有効の場合、デフォルト値がエラーの代わりに使用されます。

データ選択

ClickHouseテーブルからAvroファイルにデータを選択するには:

$ clickhouse-client --query="SELECT * FROM {some_table} FORMAT Avro" > file.avro

カラム名は以下を満たす必要があります：

• [A-Za-z_]で始まる
• 次に[A-Za-z0-9_]のみを含む

出力Avroファイルの圧縮と同期インターバルはoutput_format_avro_codecとoutput_format_avro_sync_intervalでそれぞれ設定できます。

データ例

ClickHouseのDESCRIBE機能を使用して、次の例のようなAvroファイルの推論形式をすばやく表示できます。この例にはClickHouse S3パブリックバケット内の公開アクセス可能なAvroファイルのURLが含まれています：

DESCRIBE url('https://clickhouse-public-datasets.s3.eu-central-1.amazonaws.com/hits.avro','Avro);

┌─name───────────────────────┬─type────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ WatchID                    │ Int64           │              │                    │         │                  │                │
│ JavaEnable                 │ Int32           │              │                    │         │                  │                │
│ Title                      │ String          │              │                    │         │                  │                │
│ GoodEvent                  │ Int32           │              │                    │         │                  │                │
│ EventTime                  │ Int32           │              │                    │         │                  │                │
│ EventDate                  │ Date32          │              │                    │         │                  │                │
│ CounterID                  │ Int32           │              │                    │         │                  │                │
│ ClientIP                   │ Int32           │              │                    │         │                  │                │
│ ClientIP6                  │ FixedString(16) │              │                    │         │                  │                │
│ RegionID                   │ Int32           │              │                    │         │                  │                │
...
│ IslandID                   │ FixedString(16) │              │                    │         │                  │                │
│ RequestNum                 │ Int32           │              │                    │         │                  │                │
│ RequestTry                 │ Int32           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

AvroConfluent

AvroConfluentは、KafkaおよびConfluent Schema Registryで一般的に使用されるシングルオブジェクトAvroメッセージのデコードをサポートしています。

各AvroメッセージにはスキーマIDが埋め込まれており、スキーマレジストリの助けを借りて実際のスキーマに解決できます。

スキーマは一度解決されるとキャッシュされます。

スキーマレジストリURLはformat_avro_schema_registry_urlで設定されます。

データ型のマッチング

Avroと同様です。

使用方法

スキーマ解決をすばやく確認するには、kafkacatとclickhouse-localを使用できます：

$ kafkacat -b kafka-broker  -C -t topic1 -o beginning -f '%s' -c 3 | clickhouse-local --input-format AvroConfluent --format_avro_schema_registry_url 'http://schema-registry' -S "field1 Int64, field2 String"  -q 'select * from table'
1 a
2 b
3 c

KafkaでAvroConfluentを使用するには：

CREATE TABLE topic1_stream
(
    field1 String,
    field2 String
)
ENGINE = Kafka()
SETTINGS
kafka_broker_list = 'kafka-broker',
kafka_topic_list = 'topic1',
kafka_group_name = 'group1',
kafka_format = 'AvroConfluent';

-- デバッグ目的の場合、セッションでformat_avro_schema_registry_urlを設定できます。
-- この方法は本番環境では使用できません。
SET format_avro_schema_registry_url = 'http://schema-registry';

SELECT * FROM topic1_stream;

:::note format_avro_schema_registry_urlの設定値は再起動後も維持するためにusers.xmlで設定する必要があります。また、Kafkaテーブルエンジンのformat_avro_schema_registry_url設定を使用することもできます。 :::

Parquet

Apache Parquetは、Hadoopエコシステムで広く使用されている列指向のストレージ形式です。ClickHouseはこの形式の読み取りおよび書き込み操作をサポートしています。

データ型のマッチング

以下の表は、INSERTおよびSELECTクエリにおけるClickHouseのデータ型とのマッチングを示しています。

Parquet データ型 (INSERT)	ClickHouse データ型	Parquet データ型 (SELECT)
BOOL	Bool	BOOL
UINT8, BOOL	UInt8	UINT8
INT8	Int8/Enum8	INT8
UINT16	UInt16	UINT16
INT16	Int16/Enum16	INT16
UINT32	UInt32	UINT32
INT32	Int32	INT32
UINT64	UInt64	UINT64
INT64	Int64	INT64
FLOAT	Float32	FLOAT
DOUBLE	Float64	DOUBLE
DATE	Date32	DATE
TIME (ms)	DateTime	UINT32
TIMESTAMP, TIME (us, ns)	DateTime64	TIMESTAMP
STRING, BINARY	String	BINARY
STRING, BINARY, FIXED_LENGTH_BYTE_ARRAY	FixedString	FIXED_LENGTH_BYTE_ARRAY
DECIMAL	Decimal	DECIMAL
LIST	Array	LIST
STRUCT	Tuple	STRUCT
MAP	Map	MAP
UINT32	IPv4	UINT32
FIXED_LENGTH_BYTE_ARRAY, BINARY	IPv6	FIXED_LENGTH_BYTE_ARRAY
FIXED_LENGTH_BYTE_ARRAY, BINARY	Int128/UInt128/Int256/UInt256	FIXED_LENGTH_BYTE_ARRAY

配列はネスト可能であり、Nullable型を引数として持つことができます。TupleとMap型もネストできます。

サポートされていないParquetデータ型：FIXED_SIZE_BINARY, JSON, UUID, ENUM。

ClickHouseテーブルカラムのデータ型は、挿入されるParquetデータの対応するフィールドのデータ型と異なる可能性があります。データを挿入する際、ClickHouseは上記の表に従ってデータ型を解釈し、その後、キャストを行い、ClickHouseテーブルカラムに設定されたデータ型に変換します。

データの挿入と選択

ファイルからParquetデータをClickHouseテーブルに挿入するには、以下のコマンドを使用します:

$ cat {filename} | clickhouse-client --query="INSERT INTO {some_table} FORMAT Parquet"

ClickHouseテーブルからデータを選択し、それをParquet形式でファイルに保存するには、以下のコマンドを使用します:

$ clickhouse-client --query="SELECT * FROM {some_table} FORMAT Parquet" > {some_file.pq}

Hadoopとのデータ交換には、HDFSテーブルエンジンを使用できます。

Parquet形式の設定

• output_format_parquet_row_group_size - データ出力の際の行グループサイズ（行単位）。デフォルト値 - 1000000.
• output_format_parquet_string_as_string - Parquet String型を使用してStringカラムをBinaryでなく出力します。デフォルト値 - false.
• input_format_parquet_import_nested - Parquet入力形式でネストされたデータをNestedテーブルに挿入することを許可します。デフォルト値 - false.
• input_format_parquet_case_insensitive_column_matching - ParquetカラムとClickHouseカラムの照合を大文字と小文字を区別せずに処理します。デフォルト値 - false.
• input_format_parquet_allow_missing_columns - Parquetデータを読み取る際にカラムが欠損しても許可します。デフォルト値 - false.
• input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference - Parquet形式のスキーマ推論中にサポートされていない型のカラムをスキップすることを許可します。デフォルト値 - false.
• input_format_parquet_local_file_min_bytes_for_seek - Parquet入力形式でシークを実行する際に必要な最小バイト数（ローカル読み取りファイル）を定義します。デフォルト値 - 8192.
• output_format_parquet_fixed_string_as_fixed_byte_array - FixedStringカラムにParquet FIXED_LENGTH_BYTE_ARRAY型を使用します。デフォルト値 - true.
• output_format_parquet_version - 出力形式で使用されるParquetフォーマットのバージョン。デフォルト値 - 2.latest.
• output_format_parquet_compression_method - 出力Parquet形式に使用される圧縮方法。デフォルト値 - lz4.
• input_format_parquet_max_block_size - Parquetリーダーの最大ブロック行サイズ。デフォルト値 - 65409.
• input_format_parquet_prefer_block_bytes - Parquetリーダーが出力する平均ブロックバイト数。デフォルト値 - 16744704.
• output_format_parquet_write_page_index - Parquetファイルにページインデックスを書き込む可能性を追加します。現在はoutput_format_parquet_use_custom_encoderを無効にする必要があります。デフォルト値 - true.

ParquetMetadata {data-format-parquet-metadata}

Parquetファイルメタデータ(https://parquet.apache.org/docs/file-format/metadata/)を読むための特別な形式です。常に以下の構造/内容で1行を出力します:

• num_columns - カラムの数
• num_rows - 合計行数
• num_row_groups - 合計行グループ数
• format_version - parquetフォーマットのバージョン、常に1.0または2.6
• total_uncompressed_size - データの総非圧縮バイトサイズ、すべての行グループのtotal_byte_sizeの合計として計算
• total_compressed_size - データの総圧縮バイトサイズ、すべての行グループのtotal_compressed_sizeの合計として計算
• columns - 次の構造を持つカラムメタデータのリスト:
  • name - カラム名
  • path - カラムパス（ネストされたカラムの場合にはnameと異なる）
  • max_definition_level - 最大定義レベル
  • max_repetition_level - 最大繰り返しレベル
  • physical_type - カラムの物理型
  • logical_type - カラムの論理型
• compression - このカラムで使用されている圧縮
• total_uncompressed_size - 行グループすべてのカラムの total_uncompressed_size を合計して得られる、カラムの総非圧縮バイトサイズ
• total_compressed_size - 行グループすべてのカラムの total_compressed_size を合計して得られる、カラムの総圧縮バイトサイズ
• space_saved - 圧縮によって節約されたスペースの割合（パーセント）、(1 - total_compressed_size/total_uncompressed_size)として計算される
• encodings - このカラムで使用されるエンコーディングのリスト
• row_groups - 次の構造を持つ行グループのメタデータリスト:
  • num_columns - 行グループ内のカラム数
  • num_rows - 行グループ内の行数
  • total_uncompressed_size - 行グループの総非圧縮バイトサイズ
  • total_compressed_size - 行グループの総圧縮バイトサイズ
  • columns - 次の構造を持つカラムチャンクメタデータのリスト:
    • name - カラム名
    • path - カラムパス
    • total_compressed_size - カラムの総圧縮バイトサイズ
    • total_uncompressed_size - 行グループの総非圧縮バイトサイズ
    • have_statistics - カラムチャンクメタデータにカラム統計が含まれるかどうかを示す真偽値
    • statistics - カラムチャンクの統計情報 (have_statistics が false の場合、すべてのフィールドは NULL) 次の構造を持つ:
      • num_values - カラムチャンク内の非 NULL 値の数
      • null_count - カラムチャンク内の NULL 値の数
      • distinct_count - カラムチャンク内の異なる値の数
      • min - カラムチャンクの最小値
      • max - カラムチャンクの最大値

例:

SELECT * FROM file(data.parquet, ParquetMetadata) format PrettyJSONEachRow

{
    "num_columns": "2",
    "num_rows": "100000",
    "num_row_groups": "2",
    "format_version": "2.6",
    "metadata_size": "577",
    "total_uncompressed_size": "282436",
    "total_compressed_size": "26633",
    "columns": [
        {
            "name": "number",
            "path": "number",
            "max_definition_level": "0",
            "max_repetition_level": "0",
            "physical_type": "INT32",
            "logical_type": "Int(bitWidth=16, isSigned=false)",
            "compression": "LZ4",
            "total_uncompressed_size": "133321",
            "total_compressed_size": "13293",
            "space_saved": "90.03%",
            "encodings": [
                "RLE_DICTIONARY",
                "PLAIN",
                "RLE"
            ]
        },
        {
            "name": "concat('Hello', toString(modulo(number, 1000)))",
            "path": "concat('Hello', toString(modulo(number, 1000)))",
            "max_definition_level": "0",
            "max_repetition_level": "0",
            "physical_type": "BYTE_ARRAY",
            "logical_type": "None",
            "compression": "LZ4",
            "total_uncompressed_size": "149115",
            "total_compressed_size": "13340",
            "space_saved": "91.05%",
            "encodings": [
                "RLE_DICTIONARY",
                "PLAIN",
                "RLE"
            ]
        }
    ],
    "row_groups": [
        {
            "num_columns": "2",
            "num_rows": "65409",
            "total_uncompressed_size": "179809",
            "total_compressed_size": "14163",
            "columns": [
                {
                    "name": "number",
                    "path": "number",
                    "total_compressed_size": "7070",
                    "total_uncompressed_size": "85956",
                    "have_statistics": true,
                    "statistics": {
                        "num_values": "65409",
                        "null_count": "0",
                        "distinct_count": null,
                        "min": "0",
                        "max": "999"
                    }
                },
                {
                    "name": "concat('Hello', toString(modulo(number, 1000)))",
                    "path": "concat('Hello', toString(modulo(number, 1000)))",
                    "total_compressed_size": "7093",
                    "total_uncompressed_size": "93853",
                    "have_statistics": true,
                    "statistics": {
                        "num_values": "65409",
                        "null_count": "0",
                        "distinct_count": null,
                        "min": "Hello0",
                        "max": "Hello999"
                    }
                }
            ]
        },
        ...
    ]
}

Arrow

Apache Arrowには2つの組み込みの列指向ストレージフォーマットがあります。ClickHouseはこれらのフォーマットの読み書きをサポートしています。

Arrowは、Apache Arrowの"file mode"フォーマットです。これはインメモリランダムアクセス用に設計されています。

データ型のマッチング

下記の表は、INSERTおよびSELECTクエリにおいてサポートされるデータ型とClickHouse データ型のマッチングの方法を示しています。

Arrow データ型 (INSERT)	ClickHouse データ型	Arrow データ型 (SELECT)
BOOL	Bool	BOOL
UINT8, BOOL	UInt8	UINT8
INT8	Int8/Enum8	INT8
UINT16	UInt16	UINT16
INT16	Int16/Enum16	INT16
UINT32	UInt32	UINT32
INT32	Int32	INT32
UINT64	UInt64	UINT64
INT64	Int64	INT64
FLOAT, HALF_FLOAT	Float32	FLOAT32
DOUBLE	Float64	FLOAT64
DATE32	Date32	UINT16
DATE64	DateTime	UINT32
TIMESTAMP, TIME32, TIME64	DateTime64	UINT32
STRING, BINARY	String	BINARY
STRING, BINARY, FIXED_SIZE_BINARY	FixedString	FIXED_SIZE_BINARY
DECIMAL	Decimal	DECIMAL
DECIMAL256	Decimal256	DECIMAL256
LIST	Array	LIST
STRUCT	Tuple	STRUCT
MAP	Map	MAP
UINT32	IPv4	UINT32
FIXED_SIZE_BINARY, BINARY	IPv6	FIXED_SIZE_BINARY
FIXED_SIZE_BINARY, BINARY	Int128/UInt128/Int256/UInt256	FIXED_SIZE_BINARY

配列はネスト可能であり、引数としてNullable型を持つことができます。TupleとMap型もネスト可能です。

INSERTクエリにはDICTIONARY型がサポートされており、SELECTクエリでは、LowCardinality型をDICTIONARY型として出力することを可能にする設定 output_format_arrow_low_cardinality_as_dictionaryがあります。

サポートされていないArrowデータ型: FIXED_SIZE_BINARY, JSON, UUID, ENUM.

ClickHouseのテーブルカラムのデータ型は、対応するArrowのデータフィールドと一致する必要はありません。データを挿入する際、ClickHouseは上記の表に従ってデータ型を解釈し、その後、ClickHouseのテーブルカラムに設定されたデータ型にキャストします。

データ挿入

ArrowデータをファイルからClickHouseテーブルに挿入するには、次のコマンドを使用します:

$ cat filename.arrow | clickhouse-client --query="INSERT INTO some_table FORMAT Arrow"

データの選択

ClickHouseテーブルからデータを選択し、それをArrowフォーマットのファイルに保存するには、次のコマンドを使用します:

$ clickhouse-client --query="SELECT * FROM {some_table} FORMAT Arrow" > {filename.arrow}

Arrowフォーマットの設定

• output_format_arrow_low_cardinality_as_dictionary - ClickHouse LowCardinality型をDictionary Arrow型として出力することを有効にします。デフォルト値はfalseです。
• output_format_arrow_use_64_bit_indexes_for_dictionary - Dictionaryのインデックスに64ビット整数型を使用します。デフォルト値はfalseです。
• output_format_arrow_use_signed_indexes_for_dictionary - Dictionaryのインデックスに符号付き整数型を使用します。デフォルト値はtrueです。
• output_format_arrow_string_as_string - StringカラムにBinaryではなくArrow String型を使用します。デフォルト値はfalseです。
• input_format_arrow_case_insensitive_column_matching - ArrowカラムとClickHouseカラムのマッチングにおいて大文字小文字を無視します。デフォルト値はfalseです。
• input_format_arrow_allow_missing_columns - Arrowデータを読み取る際に欠落しているカラムを許可します。デフォルト値はfalseです。
• input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference - Arrowフォーマットのスキーマ推論時にサポートされていない型のカラムをスキップすることを許可します。デフォルト値はfalseです。
• output_format_arrow_fixed_string_as_fixed_byte_array - FixedStringカラムにByte/StringではなくArrow FIXED_SIZE_BINARY型を使用します。デフォルト値はtrueです。
• output_format_arrow_compression_method - 出力Arrowフォーマットに使用される圧縮メソッド。デフォルト値はlz4_frameです。

ArrowStream

ArrowStreamはApache Arrowの「stream mode」フォーマットです。これはインメモリストリーム処理用に設計されています。

ORC

Apache ORCはHadoopエコシステムで広く使用されている列指向ストレージフォーマットです。

データ型のマッチング

下記の表は、INSERTおよびSELECTクエリにおいてサポートされるデータ型とClickHouse データ型のマッチングの方法を示しています。

ORC データ型 (INSERT)	ClickHouse データ型	ORC データ型 (SELECT)
Boolean	UInt8	Boolean
Tinyint	Int8/UInt8/Enum8	Tinyint
Smallint	Int16/UInt16/Enum16	Smallint
Int	Int32/UInt32	Int
Bigint	Int64/UInt32	Bigint
Float	Float32	Float
Double	Float64	Double
Decimal	Decimal	Decimal
Date	Date32	Date
Timestamp	DateTime64	Timestamp
String, Char, Varchar, Binary	String	Binary
List	Array	List
Struct	Tuple	Struct
Map	Map	Map
Int	IPv4	Int
Binary	IPv6	Binary
Binary	Int128/UInt128/Int256/UInt256	Binary
Binary	Decimal256	Binary

その他の型はサポートされていません。

配列はネスト可能で、引数としてNullable型を持つことができます。TupleとMap型もネスト可能です。

ClickHouseのテーブルカラムのデータ型は、対応するORCデータフィールドと一致する必要はありません。データを挿入する際、ClickHouseは上記の表に従ってデータ型を解釈し、その後、ClickHouseのテーブルカラムに設定されたデータ型にキャストします。

データ挿入

ORCデータをファイルからClickHouseテーブルに挿入するには、次のコマンドを使用します:

$ cat filename.orc | clickhouse-client --query="INSERT INTO some_table FORMAT ORC"

データの選択

ClickHouseテーブルからデータを選択し、それをORCフォーマットのファイルに保存するには、次のコマンドを使用します:

$ clickhouse-client --query="SELECT * FROM {some_table} FORMAT ORC" > {filename.orc}

Arrowフォーマットの設定

• output_format_arrow_string_as_string - StringカラムにBinaryではなくArrow String型を使用します。デフォルト値はfalseです。
• output_format_orc_compression_method - 出力ORCフォーマットに使用される圧縮メソッド。デフォルト値はnoneです。
• input_format_arrow_case_insensitive_column_matching - ArrowカラムとClickHouseカラムのマッチングにおいて大文字小文字を無視します。デフォルト値はfalseです。
• input_format_arrow_allow_missing_columns - Arrowデータを読み取る際に欠落しているカラムを許可します。デフォルト値はfalseです。
• input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference - Arrowフォーマットのスキーマ推論時にサポートされていない型のカラムをスキップすることを許可します。デフォルト値はfalseです。

Hadoopとデータを交換するには、HDFSテーブルエンジンを使用できます。

One

ファイルからデータを読み取らず、UInt8型、名前dummy、値0を持つカラムを含む行のみを返す特殊な入力フォーマット。 仮想カラム_file/_pathを使用して、実際のデータを読み取らずにすべてのファイルをリストするために使用できます。

例:

クエリ:

SELECT _file FROM file('path/to/files/data*', One);

結果:

┌─_file────┐
│ data.csv │
└──────────┘
┌─_file──────┐
│ data.jsonl │
└────────────┘
┌─_file────┐
│ data.tsv │
└──────────┘
┌─_file────────┐
│ data.parquet │
└──────────────┘

Npy

この機能は、NumPyの.npyファイルからNumPy配列をClickHouseにロードするように設計されています。NumPyファイルフォーマットは、数値データの配列を効率的に保存するためのバイナリフォーマットです。インポート中、ClickHouseは最上位次元を単一カラムを持つ行の配列として扱います。サポートされているNpyデータ型と、それに対応するClickHouseの型は以下の通りです。

Npy データ型 (INSERT)	ClickHouse データ型	Npy データ型 (SELECT)
i1	Int8	i1
i2	Int16	i2
i4	Int32	i4
i8	Int64	i8
u1, b1	UInt8	u1
u2	UInt16	u2
u4	UInt32	u4
u8	UInt64	u8
f2, f4	Float32	f4
f8	Float64	f8
S, U	String	S
	FixedString	S

Pythonを使用して.npy形式で配列を保存する例

import numpy as np
arr = np.array([[[1],[2],[3]],[[4],[5],[6]]])
np.save('example_array.npy', arr)

ClickHouseでNumPyファイルを読む例

クエリ:

SELECT *
FROM file('example_array.npy', Npy)

結果:

┌─array─────────┐
│ [[1],[2],[3]] │
│ [[4],[5],[6]] │
└───────────────┘

データの選択

ClickHouseテーブルからデータを選択し、それをNpyフォーマットのファイルに保存するには、次のコマンドを使用します:

$ clickhouse-client --query="SELECT {column} FROM {some_table} FORMAT Npy" > {filename.npy}

LineAsString

このフォーマットでは、入力データの各行が単一の文字列値として解釈されます。このフォーマットは、型Stringの単一フィールドを持つテーブルのみ解析できます。他のカラムはDEFAULTまたはMATERIALIZEDに設定されるか、省略される必要があります。

例

クエリ:

DROP TABLE IF EXISTS line_as_string;
CREATE TABLE line_as_string (field String) ENGINE = Memory;
INSERT INTO line_as_string FORMAT LineAsString "I love apple", "I love banana", "I love orange";
SELECT * FROM line_as_string;

結果:

┌─field─────────────────────────────────────────────┐
│ "I love apple", "I love banana", "I love orange"; │
└───────────────────────────────────────────────────┘

Regexp

インポートされたデータの各行は、正規表現に従って解析されます。

Regexpフォーマットを使用する際には、以下の設定を利用できます：

• format_regexp — String。re2形式の正規表現を含みます。

• format_regexp_escaping_rule — String。以下のエスケープルールがサポートされています：

  • CSV (類似 CSV)
  • JSON (類似 JSONEachRow)
  • Escaped (類似 TSV)
  • Quoted (類似 Values)
  • Raw (サブパターンを丸ごと抽出、エスケープルールなし、TSVRawに類似)

• format_regexp_skip_unmatched — UInt8。インポートされたデータが format_regexp 式に一致しなかった場合に例外をスローする必要性を定義します。0または1に設定できます。

使用方法

format_regexp設定からの正規表現は、インポートされたデータの各行に適用されます。正規表現のサブパターン数は、インポートされたデータセット内のカラム数と一致しなければなりません。

インポートされたデータの各行は、改行文字 '\n' 又は DOSスタイルの改行 "\r\n" で区切られる必要があります。

各サブパターンの内容は、format_regexp_escaping_rule設定に従って、対応するデータ型のメソッドで解析されます。

正規表現が行に一致せず、format_regexp_skip_unmatchedが1に設定されている場合、その行は静かにスキップされます。それ以外の場合、例外がスローされます。

例

ファイル data.tsvを考えてみましょう:

id: 1 array: [1,2,3] string: str1 date: 2020-01-01
id: 2 array: [1,2,3] string: str2 date: 2020-01-02
id: 3 array: [1,2,3] string: str3 date: 2020-01-03

そしてテーブル:

CREATE TABLE imp_regex_table (id UInt32, array Array(UInt32), string String, date Date) ENGINE = Memory;

インポートコマンド:

$ cat data.tsv | clickhouse-client  --query "INSERT INTO imp_regex_table SETTINGS format_regexp='id: (.+?) array: (.+?) string: (.+?) date: (.+?)', format_regexp_escaping_rule='Escaped', format_regexp_skip_unmatched=0 FORMAT Regexp;"

クエリ:

SELECT * FROM imp_regex_table;

結果:

┌─id─┬─array───┬─string─┬───────date─┐
│  1 │ [1,2,3] │ str1   │ 2020-01-01 │
│  2 │ [1,2,3] │ str2   │ 2020-01-02 │
│  3 │ [1,2,3] │ str3   │ 2020-01-03 │
└────┴─────────┴────────┴────────────┘

フォーマットスキーマ

フォーマットスキーマを含むファイル名は、設定 format_schema で設定されます。 Cap'n Proto および Protobuf のフォーマットが使用されている場合、この設定の設定が必要です。 フォーマットスキーマは、ファイル名とこのファイル内のメッセージタイプの名前をコロンで区切った組み合わせです、 例えば schemafile.proto:MessageType です。 ファイルがフォーマットの標準拡張子（例えば、Protobufの場合は.proto）を持っている場合、その拡張子を省略でき、この場合、フォーマットスキーマは schemafile:MessageType となります。

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

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は、次の行の開始を見つけるために最後のカラム後の区切り文字と行間の区切り文字を使用するため、少なくともどちらか一つが空でない場合にのみエラーのスキップが機能します。

RawBLOB

このフォーマットでは、入力データは単一の値に読み込まれます。型Stringまたは類似の単一フィールドのテーブルのみを解析することができます。 結果は、バイナリ形式で区切りやエスケープなしで出力されます。複数の値が出力される場合、フォーマットは曖昧になり、データを再度読み取ることができなくなります。

以下は、RawBLOBフォーマットとTabSeparatedRawフォーマットの比較です。

RawBLOB:

• データはバイナリフォーマットで出力され、エスケープなし;
• 値間の区切りなし;
• 各値の最後に改行なし。

TabSeparatedRaw:

• データはエスケープなしで出力される;
• 行にはタブで区切られた値が含まれる;
• 各行の最後の値の後には改行がある。

以下はRawBLOBとRowBinaryフォーマットの比較です。

RawBLOB:

• Stringフィールドは長さをプレフィックスに持たずに出力される。

RowBinary:

• Stringフィールドはvarint形式（符号なしLEB128）で長さが表され、その後に文字列のバイトが続く。

RawBLOB入力に空のデータを渡すと、ClickHouseは例外をスローします:

Code: 108. DB::Exception: No data to insert

例

$ clickhouse-client --query "CREATE TABLE {some_table} (a String) ENGINE = Memory;"
$ cat {filename} | clickhouse-client --query="INSERT INTO {some_table} FORMAT RawBLOB"
$ clickhouse-client --query "SELECT * FROM {some_table} FORMAT RawBLOB" | md5sum

結果:

f9725a22f9191e064120d718e26862a9  -

MsgPack

ClickHouseはMessagePackデータファイルの読み書きをサポートしています。

データ型のマッチング

MessagePack データ型 (INSERT)	ClickHouse データ型	MessagePack データ型 (SELECT)
uint N, positive fixint	UIntN	uint N
int N, negative fixint	IntN	int N
bool	UInt8	uint 8
fixstr, str 8, str 16, str 32, bin 8, bin 16, bin 32	String	bin 8, bin 16, bin 32
fixstr, str 8, str 16, str 32, bin 8, bin 16, bin 32	FixedString	bin 8, bin 16, bin 32
float 32	Float32	float 32
float 64	Float64	float 64
uint 16	Date	uint 16
int 32	Date32	int 32
uint 32	DateTime	uint 32
uint 64	DateTime64	uint 64
fixarray, array 16, array 32	Array/Tuple	fixarray, array 16, array 32
fixmap, map 16, map 32	Map	fixmap, map 16, map 32
uint 32	IPv4	uint 32
bin 8	String	bin 8
int 8	Enum8	int 8
bin 8	(U)Int128/(U)Int256	bin 8
int 32	Decimal32	int 32
int 64	Decimal64	int 64
bin 8	Decimal128/Decimal256	bin 8

例:

".msgpk"ファイルへの書き込み:

$ clickhouse-client --query="CREATE TABLE msgpack (array Array(UInt8)) ENGINE = Memory;"
$ clickhouse-client --query="INSERT INTO msgpack VALUES ([0, 1, 2, 3, 42, 253, 254, 255]), ([255, 254, 253, 42, 3, 2, 1, 0])";
$ clickhouse-client --query="SELECT * FROM msgpack FORMAT MsgPack" > tmp_msgpack.msgpk;

MsgPackフォーマットの設定

• input_format_msgpack_number_of_columns - 挿入されたMsgPackデータ内のカラム数。データからの自動スキーマ推論に使用。デフォルト値は0。
• output_format_msgpack_uuid_representation - MsgPackフォーマットでUUIDを出力する方法。デフォルト値はEXT。

MySQLDump

ClickHouseはMySQL ダンプの読み取りをサポートしています。 ダンプ内の1つのテーブルに属するINSERTクエリからすべてのデータを読み取ります。複数のテーブルがある場合、デフォルトでは最初のテーブルからデータを読み取ります。 input_format_mysql_dump_table_name設定を使用して、データを読み取るテーブルの名前を指定できます。 input_format_mysql_dump_map_columns設定が1に設定されており、指定されたテーブルのCREATEクエリまたはINSERTクエリ内のカラム名がダンプに含まれている場合、入力データのカラムはその名前でテーブルのカラムにマップされます、 未知の名前のカラムは、設定input_format_skip_unknown_fieldsが1に設定されている場合、スキップされます。 このフォーマットはスキーマ推論をサポートしています：ダンプが指定されたテーブルのCREATEクエリを含む場合、構造はそこから抽出されます。そうでなければ、スキーマはINSERTクエリのデータから推論されます。

例:

ファイル dump.sql:

/*!40101 SET @saved_cs_client     = @@character_set_client */;
/*!50503 SET character_set_client = utf8mb4 */;
CREATE TABLE `test` (
  `x` int DEFAULT NULL,
  `y` int DEFAULT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
/*!40101 SET character_set_client = @saved_cs_client */;
INSERT INTO `test` VALUES (1,NULL),(2,NULL),(3,NULL),(3,NULL),(4,NULL),(5,NULL),(6,7);
/*!40101 SET @saved_cs_client     = @@character_set_client */;
/*!50503 SET character_set_client = utf8mb4 */;
CREATE TABLE `test 3` (
  `y` int DEFAULT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
/*!40101 SET character_set_client = @saved_cs_client */;
INSERT INTO `test 3` VALUES (1);
/*!40101 SET @saved_cs_client     = @@character_set_client */;
/*!50503 SET character_set_client = utf8mb4 */;
CREATE TABLE `test2` (
  `x` int DEFAULT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
/*!40101 SET character_set_client = @saved_cs_client */;
INSERT INTO `test2` VALUES (1),(2),(3);

クエリ:

DESCRIBE TABLE file(dump.sql, MySQLDump) SETTINGS input_format_mysql_dump_table_name = 'test2'

┌─name─┬─type────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ x    │ Nullable(Int32) │              │                    │         │                  │                │
└──────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

SELECT *
FROM file(dump.sql, MySQLDump)
         SETTINGS input_format_mysql_dump_table_name = 'test2'

┌─x─┐
│ 1 │
│ 2 │
│ 3 │
└───┘

DWARF

ELFファイル（実行ファイル、ライブラリ、オブジェクトファイル）からDWARFデバッグシンボルを解析します。dwarfdumpに似ていますが、はるかに速く（数百MB/秒）、SQLと共に利用できます。.debug_infoセクション内の各デバッグ情報エントリ（DIE）に対して1行を生成します。DIEを終端するためにDWARFエンコーディングが使用する"null"エントリも含まれます。

簡単な背景: .debug_info は ユニット で構成されており、それぞれがコンパイルユニットに対応します。各ユニットは、compile_unit DIEをルートとする DIE のツリーです。各DIEは タグ を持ち、属性 のリストを持ちます。各属性は 名前 と 値（およびその値がどのようにエンコードされているかを指定する form）を持ちます。DIEはソースコードからの内容を表し、そのタグがどのような内容であるかを示しています。例えば、関数は（タグ= subprogram）、クラス/構造体/列挙型（class_type/structure_type/enumeration_type）、変数（variable）、関数の引数（formal_parameter）などです。ツリー構造は対応するソースコードを反映しています。例えば、class_type DIE はクラスのメソッドを表す subprogram DIE を含むことがあります。

以下のカラムを出力します:

• offset - .debug_info セクション内のDIEの位置
• size - エンコードされたDIEのバイト数（属性を含む）
• tag - DIEのタイプ; 通常の "DW_TAG_" プレフィックスは省略されます
• unit_name - このDIEを含むコンパイルユニットの名前
• unit_offset - .debug_info セクション内でこのDIEを含むコンパイルユニットの位置
• 現在のDIEのツリー内の先祖のタグを順に含む配列:
  • ancestor_tags
  • ancestor_offsets - ancestor_tagsと並行する補Offset
• 利便性のために属性配列から重複したいくつかの一般的な属性：
  • name
  • linkage_name - マングルされた完全修飾名; 通常、関数のみがそれを持ちます（すべての関数が持っているわけではありません）
  • decl_file - このエンティティが宣言されたソースコードファイルの名前
  • decl_line - このエンティティが宣言されたソースコード内の行番号
• 属性を説明する並行配列：
  • attr_name - 属性の名前; 通常の "DW_AT_" プレフィックスは省略
  • attr_form - 属性がどのようにエンコードされ、解釈されるか; 通常のDW_FORM_プレフィックスは省略
  • attr_int - 属性の整数値; 属性が数値を持たない場合は0
  • attr_str - 属性の文字列値; 属性が文字列値を持たない場合は空

例：最も多くの関数定義を持つコンパイルユニットを見つける（テンプレートのインスタンス化やインクルードされたヘッダファイルからの関数を含む）：

SELECT
    unit_name,
    count() AS c
FROM file('programs/clickhouse', DWARF)
WHERE tag = 'subprogram' AND NOT has(attr_name, 'declaration')
GROUP BY unit_name
ORDER BY c DESC
LIMIT 3

┌─unit_name──────────────────────────────────────────────────┬─────c─┐
│ ./src/Core/Settings.cpp                                    │ 28939 │
│ ./src/AggregateFunctions/AggregateFunctionSumMap.cpp       │ 23327 │
│ ./src/AggregateFunctions/AggregateFunctionUniqCombined.cpp │ 22649 │
└────────────────────────────────────────────────────────────┴───────┘

3 rows in set. Elapsed: 1.487 sec. Processed 139.76 million rows, 1.12 GB (93.97 million rows/s., 752.77 MB/s.)
Peak memory usage: 271.92 MiB.

Markdown

結果をMarkdownフォーマットを利用してエクスポートし、自分の.mdファイルに貼り付ける準備を整えることができます：

SELECT
    number,
    number * 2
FROM numbers(5)
FORMAT Markdown

| number | multiply(number, 2) |
|-:|-:|
| 0 | 0 |
| 1 | 2 |
| 2 | 4 |
| 3 | 6 |
| 4 | 8 |

Markdownテーブルは自動的に生成され、GithubのようなMarkdown対応プラットフォームで使用することができます。このフォーマットは出力専用です。

Form

Formフォーマットは、データを key1=value1&key2=value2 の形式でフォーマットされた application/x-www-form-urlencoded フォーマットで単一のレコードを読み書きするために使用できます。

例:

ユーザーファイルパスに配置されたファイル data.tmp には、URLエンコードされたデータがあります:

t_page=116&c.e=ls7xfkpm&c.tti.m=raf&rt.start=navigation&rt.bmr=390%2C11%2C10

SELECT * FROM file(data.tmp, Form) FORMAT vertical;

結果:

Row 1:
──────
t_page:   116
c.e:      ls7xfkpm
c.tti.m:  raf
rt.start: navigation
rt.bmr:   390,11,10