Спецификация двоичного кодирования типов данных

Данная спецификация описывает двоичный формат, который может быть использован для двоичного кодирования и декодирования типов данных 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> (см. двоичное кодирование вида интервала)
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.

Вид интервала	Двоичное кодирование
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>
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>
Negative infinity	0xFE
Positive infinity	0xFF