数据类型二进制编码规范
本规范描述了用于 ClickHouse 数据类型二进制编码和解码的二进制格式。该格式用于Dynamic 列的 二进制序列化，并且可以在 RowBinaryWithNamesAndTypes 和 Native 输入/输出格式下使用，前提是在相应的设置下。
下表描述了每种数据类型如何在二进制格式中表示。每种数据类型编码都包含 1 个字节，用于指示类型以及一些可选的附加信息。二进制编码中的var_uint 表示大小使用可变长度量压缩进行编码。
| ClickHouse 数据类型 | 二进制编码 |
|---|---|
无 | 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> (参见 时间间隔类型二进制编码) |
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> (参见 聚合函数参数二进制编码) |
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> |
自定义类型 (Ring, Polygon, 等) | 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> (参见 聚合函数参数二进制编码) |
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>... |
对于类型JSON，字节uint8_serialization_version 指示序列化版本。目前版本始终为 0，但如果将来为JSON 类型引入了新参数，则可能会发生更改。
时间间隔类型二进制编码
下表描述了Interval 数据类型的不同时间间隔类型是如何编码的。
| 时间间隔类型 | 二进制编码 |
|---|---|
纳秒 | 0x00 |
微秒 | 0x01 |
毫秒 | 0x02 |
秒 | 0x03 |
分钟 | 0x04 |
小时 | 0x05 |
天 | 0x06 |
周 | 0x07 |
月 | 0x08 |
季度 | 0x09 |
年 | 0x1A |
聚合函数参数二进制编码
下表描述了AggregateFunction 和 SimpleAggregateFunction 的参数是如何编码的。参数的编码包含 1 个字节，用于指示参数类型和值本身。
| 参数类型 | 二进制编码 |
|---|---|
Null | 0x00 |
UInt64 | 0x01<var_uint_value> |
Int64 | 0x02<var_int_value> |
UInt128 | 0x03<uint128_little_endian_value> |
Int128 | 0x04<int128_little_endian_value> |
UInt128 | 0x05<uint128_little_endian_value> |
Int128 | 0x06<int128_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> |
负无穷大 | 0xFE |
正无穷大 | 0xFF |