数据类型二进制编码规范

本规范说明了可用于对 ClickHouse 数据类型进行二进制编码和解码的二进制格式。该格式用于 Dynamic 列的二进制序列化，也可在相应设置下用于输入/输出格式 RowBinaryWithNamesAndTypes 和 Native。

下表说明了每种数据类型在二进制格式中的表示方式。每种数据类型的编码由 1 个字节组成，用于标识类型，以及一些可选的附加信息。二进制编码中的 var_uint 表示其大小使用可变长度数量压缩进行编码。

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 的二进制编码)
`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>`
`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>` (参见聚合函数参数的二进制编码)
`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 类型，仅当 stride 与维度 N 不同时，才会使用 0x37 编码。当 stride == N 时 (包括显式写出第三个参数的情况，例如 QBit(Float32, 4, 4)) ，该类型会被规范化为双参数形式 QBit(T, N)，并按上文所述编码为 0x36，因此其二进制编码在字节级别上与不带 stride 的 QBit 完全一致。

时间间隔类型的二进制编码

下表说明了 Interval 数据类型中不同时间间隔类型的二进制编码方式。

时间间隔类型	二进制编码
`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 个字节的参数类型标识以及参数值本身组成。

参数类型	二进制编码
`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>`
`负无穷`	`0xFE`
`正无穷`	`0xFF`