Spécification d'encodage binaire des types de données

Cette spécification décrit le format binaire pouvant être utilisé pour l'encodage et le décodage binaires des types de données ClickHouse. Ce format est utilisé dans la sérialisation binaire de la colonne Dynamic et peut être utilisé dans les formats d'entrée/sortie RowBinaryWithNamesAndTypes et Native via les paramètres correspondants.

Le tableau ci-dessous décrit la représentation de chaque type de données au format binaire. L'encodage de chaque type de données se compose d'1 octet indiquant le type, ainsi que d'éventuelles informations supplémentaires. var_uint dans l'encodage binaire signifie que la taille est encodée à l'aide de la compression Variable-Length Quantity.

Type de données ClickHouse	Encodage binaire
`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>` (voir encodage binaire du type d’intervalle)
`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>` (voir encodage binaire des paramètres de fonction d’agrégation)
`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>`
`Type personnalisé` (`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>` (voir encodage binaire des paramètres de fonction d’agrégation)
`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>`

Pour le type JSON, l’octet uint8_serialization_version indique la version de la sérialisation. À l’heure actuelle, cette version est toujours égale à 0, mais elle pourra changer à l’avenir si de nouveaux arguments sont introduits pour le type JSON.

Pour le type QBit, l’encodage 0x37 n’est utilisé que lorsque stride diffère de la dimension N. Lorsque stride == N (y compris lorsque le troisième argument est écrit explicitement, comme dans QBit(Float32, 4, 4)), le type est ramené à la forme canonique à deux arguments QBit(T, N) et encodé en 0x36 comme ci-dessus, de sorte que son encodage binaire reste identique octet pour octet à celui d’un QBit sans stride.

Encodage binaire du type d'intervalle

Le tableau ci-dessous décrit l'encodage des différents types d'intervalle du type de données Interval.

Type d'intervalle	Encodage binaire
`Nanosecond`	`0x00`
`Microsecond`	`0x01`
`Millisecond`	`0x02`
`Second`	`0x03`
`Minute`	`0x04`
`Hour`	`0x05`
`Day`	`0x06`
`Week`	`0x07`
`Month`	`0x08`
`Quarter`	`0x09`
`Year`	`0x1A`

Encodage binaire des paramètres d’une fonction d’agrégation

Le tableau ci-dessous décrit l’encodage des paramètres de AggregateFunction et SimpleAggregateFunction. L’encodage d’un paramètre se compose d’un octet indiquant son type, suivi de la valeur elle-même.

Type de paramètre	Encodage binaire
`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>`
`Moins l’infini`	`0xFE`
`Plus l’infini`	`0xFF`