Set up docs MCPこの仕様では、ClickHouseのデータ型のバイナリエンコーディングおよびデコーディングに使用できるバイナリフォーマットについて説明します。このフォーマットは、Dynamic カラムのバイナリシリアライゼーションで使用され、対応する設定により、入出力フォーマット RowBinaryWithNamesAndTypes および Native でも使用できます。
以下の表では、各データ型がバイナリフォーマットでどのように表現されるかを示します。各データ型のエンコーディングは、型を示す1バイトと、任意の追加情報で構成されます。
バイナリエンコーディングにおける var_uint は、サイズが Variable-Length Quantity 圧縮を使ってエンコードされることを意味します。
| ClickHouseのデータ型 | バイナリ符号化 |
|---|---|
Nothing |
0x00 |
UInt8 |
0x01 |
UInt16 |
0x02 |
UInt32 |
0x03 |
UInt64 |
0x04 |
UInt128 |
0x05 |
UInt256 |
0x06 |
Int8 |
0x07 |
Int16 |
0x08 |
Int32 |
0x09 |
Int64 |
0x0A |
Int128 |
0x0B |
Int256 |
0x0C |
Float32 |
0x0D |
Float64 |
0x0E |
Date |
0x0F |
Date32 |
0x10 |
DateTime |
0x11 |
DateTime(time_zone) |
0x12<var_uint_time_zone_name_size><time_zone_name_data> |
DateTime64(P) |
0x13<uint8_precision> |
DateTime64(P, time_zone) |
0x14<uint8_precision><var_uint_time_zone_name_size><time_zone_name_data> |
String |
0x15 |
FixedString(N) |
0x16<var_uint_size> |
Enum8 |
0x17<var_uint_number_of_elements><var_uint_name_size_1><name_data_1><int8_value_1>...<var_uint_name_size_N><name_data_N><int8_value_N> |
Enum16 |
0x18<var_uint_number_of_elements><var_uint_name_size_1><name_data_1><int16_little_endian_value_1>...><var_uint_name_size_N><name_data_N><int16_little_endian_value_N> |
Decimal32(P, S) |
0x19<uint8_precision><uint8_scale> |
Decimal64(P, S) |
0x1A<uint8_precision><uint8_scale> |
Decimal128(P, S) |
0x1B<uint8_precision><uint8_scale> |
Decimal256(P, S) |
0x1C<uint8_precision><uint8_scale> |
UUID |
0x1D |
Array(T) |
0x1E<nested_type_encoding> |
Tuple(T1, ..., TN) |
0x1F<var_uint_number_of_elements><nested_type_encoding_1>...<nested_type_encoding_N> |
Tuple(name1 T1, ..., nameN TN) |
0x20<var_uint_number_of_elements><var_uint_name_size_1><name_data_1><nested_type_encoding_1>...<var_uint_name_size_N><name_data_N><nested_type_encoding_N> |
Set |
0x21 |
Interval |
0x22<interval_kind> (interval kind binary encodingを参照) |
Nullable(T) |
0x23<nested_type_encoding> |
Function |
0x24<var_uint_number_of_arguments><argument_type_encoding_1>...<argument_type_encoding_N><return_type_encoding> |
AggregateFunction(function_name(param_1, ..., param_N), arg_T1, ..., arg_TN) |
0x25<var_uint_version><var_uint_function_name_size><function_name_data><var_uint_number_of_parameters><param_1>...<param_N><var_uint_number_of_arguments><argument_type_encoding_1>...<argument_type_encoding_N> (aggregate function parameter binary encodingを参照) |
LowCardinality(T) |
0x26<nested_type_encoding> |
Map(K, V) |
0x27<key_type_encoding><value_type_encoding> |
IPv4 |
0x28 |
IPv6 |
0x29 |
Variant(T1, ..., TN) |
0x2A<var_uint_number_of_variants><variant_type_encoding_1>...<variant_type_encoding_N> |
Dynamic(max_types=N) |
0x2B<uint8_max_types> |
Custom type (Ring, Polygon, etc) |
0x2C<var_uint_type_name_size><type_name_data> |
Bool |
0x2D |
SimpleAggregateFunction(function_name(param_1, ..., param_N), arg_T1, ..., arg_TN) |
0x2E<var_uint_function_name_size><function_name_data><var_uint_number_of_parameters><param_1>...<param_N><var_uint_number_of_arguments><argument_type_encoding_1>...<argument_type_encoding_N> (aggregate function parameter binary encodingを参照) |
Nested(name1 T1, ..., nameN TN) |
0x2F<var_uint_number_of_elements><var_uint_name_size_1><name_data_1><nested_type_encoding_1>...<var_uint_name_size_N><name_data_N><nested_type_encoding_N> |
JSON(max_dynamic_paths=N, max_dynamic_types=M, path Type, SKIP skip_path, SKIP REGEXP skip_path_regexp) |
0x30<uint8_serialization_version><var_int_max_dynamic_paths><uint8_max_dynamic_types><var_uint_number_of_typed_paths><var_uint_path_name_size_1><path_name_data_1><encoded_type_1>...<var_uint_number_of_skip_paths><var_uint_skip_path_size_1><skip_path_data_1>...<var_uint_number_of_skip_path_regexps><var_uint_skip_path_regexp_size_1><skip_path_data_regexp_1>... |
BFloat16 |
0x31 |
Time |
0x32 |
Time64(P) |
0x34<uint8_precision> |
QBit(T, N) |
0x36<element_type_encoding><var_uint_dimension> |
QBit(T, N, stride) |
0x37<element_type_encoding><var_uint_dimension><var_uint_stride> |
型 JSON では、uint8_serialization_version というバイト値がシリアライゼーションのバージョンを示します。現時点ではこのバージョンは常に 0 ですが、将来的に JSON 型に新しい引数が導入された場合は変更される可能性があります。
型 QBit では、0x37 エンコーディングは stride が次元 N と異なる場合にのみ使用されます。stride == N の場合 (QBit(Float32, 4, 4) のように第 3 引数が明示的に記述されている場合も含む) 、この型は 2 引数形式の QBit(T, N) に正規化され、上記の 0x36 としてエンコードされるため、そのバイナリエンコーディングはストライドなしの QBit とバイト単位で完全に同一のままです。
Interval kind のバイナリエンコーディング
以下の表は、Interval データ型の各 interval kind がどのようにエンコードされるかを示しています。
| Interval kind | バイナリエンコーディング |
|---|---|
Nanosecond |
0x00 |
Microsecond |
0x01 |
Millisecond |
0x02 |
Second |
0x03 |
Minute |
0x04 |
Hour |
0x05 |
Day |
0x06 |
Week |
0x07 |
Month |
0x08 |
Quarter |
0x09 |
Year |
0x1A |
集約関数パラメータのバイナリエンコーディング
以下の表は、AggregateFunction および SimpleAggregateFunction のパラメータがどのようにエンコードされるかを示しています。
パラメータのエンコーディングは、パラメータの型を示す 1 バイトと、その値自体で構成されます。
| Parameter type | Binary encoding |
|---|---|
Null |
0x00 |
UInt64 |
0x01<var_uint_value> |
Int64 |
0x02<var_int_value> |
UInt128 |
0x03<uint128_little_endian_value> |
Int128 |
0x04<int128_little_endian_value> |
UInt256 |
0x05<uint256_little_endian_value> |
Int256 |
0x06<int256_little_endian_value> |
Float64 |
0x07<float64_little_endian_value> |
Decimal32 |
0x08<var_uint_scale><int32_little_endian_value> |
Decimal64 |
0x09<var_uint_scale><int64_little_endian_value> |
Decimal128 |
0x0A<var_uint_scale><int128_little_endian_value> |
Decimal256 |
0x0B<var_uint_scale><int256_little_endian_value> |
String |
0x0C<var_uint_size><data> |
Array |
0x0D<var_uint_size><value_encoding_1>...<value_encoding_N> |
Tuple |
0x0E<var_uint_size><value_encoding_1>...<value_encoding_N> |
Map |
0x0F<var_uint_size><key_encoding_1><value_encoding_1>...<key_encoding_N><value_encoding_N> |
IPv4 |
0x10<uint32_little_endian_value> |
IPv6 |
0x11<uint128_little_endian_value> |
UUID |
0x12<uuid_value> |
Bool |
0x13<bool_value> |
Object |
0x14<var_uint_size><var_uint_key_size_1><key_data_1><value_encoding_1>...<var_uint_key_size_N><key_data_N><value_encoding_N> |
AggregateFunctionState |
0x15<var_uint_name_size><name_data><var_uint_data_size><data> |
Negative infinity |
0xFE |
Positive infinity |
0xFF |