` — `IntervalSecond`, `IntervalMinute`, `IntervalHour`, `IntervalDay`, `IntervalWeek`, `IntervalMonth`, `IntervalQuarter`, `IntervalYear`, `IntervalNanosecond`, etc. Toutes les unités partagent le même encodage binaire : le nombre est représenté par un Int64 signé de 8 octets en little-endian. L'unité n'existe **que** dans la chaîne de type — elle ne modifie ni les octets sur le wire ni la forme textuelle, qui est l'entier brut. Un seul chemin de décodage gère toutes les unités.
Valeur `IntervalDay` `5` :
```text theme={null}
05 00 00 00 00 00 00 00 Int64 LE = 5
```
#### UUID
16 octets par valeur. L’encodage binaire **n’est pas** constitué des 16 octets canoniques en big-endian : chaque moitié de 8 octets est inversée indépendamment, octet par octet.
Le modèle logique est un identifiant de 128 bits sous forme textuelle canonique `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, où les octets sont conventionnellement écrits en big-endian. Le modèle sur le fil prend ces 16 octets canoniques, les divise en deux moitiés de 8 octets et écrit chaque moitié en little-endian :
* Octets sur le fil 0..7 = octets canoniques 0..7 inversés.
* Octets sur le fil 8..15 = octets canoniques 8..15 inversés.
UUID `550e8400-e29b-41d4-a716-446655440000` :
```text theme={null}
Canonical bytes (16): 55 0E 84 00 E2 9B 41 D4 A7 16 44 66 55 44 00 00
Wire bytes:
D4 41 9B E2 00 84 0E 55 high half byte-reversed
00 00 44 55 66 44 16 A7 low half byte-reversed
```
L’UUID nul (entièrement composé de zéros) s’écrit de la même façon dans les deux représentations.
#### IPv4 et IPv6
Deux types d’adresses apparentés, mais encodés différemment.
`IPv4` occupe 4 octets et est encodé sous forme d’un UInt32 little-endian contenant l’adresse canonique sur 32 bits (la valeur `(a << 24) | (b << 16) | (c << 8) | d` dérivée de `a.b.c.d`). Les octets sur le wire correspondent aux octets en ordre réseau, mais inversés.
`192.168.1.10` (valeur canonique sur 32 bits `0xC0A8010A`) :
```text theme={null}
0A 01 A8 C0 Little-endian UInt32
```
`IPv6` fait 16 octets, écrits **tels quels en ordre des octets réseau** sans swap — dans le même ordre d’octets que `inet_pton(AF_INET6, ...)`.
`2001:db8::1`:
```text theme={null}
20 01 0D B8 00 00 00 00 network bytes 0..7
00 00 00 00 00 00 00 01 network bytes 8..15
```
L'asymétrie est délibérée : IPv4 est stocké sous forme de `u32` pour les opérations arithmétiques et les requêtes compactes sur des plages, tandis qu'IPv6 conserve la disposition en ordre réseau courante dans la plupart des API réseau.
#### Enum8 and Enum16
Compatibles au niveau binaire avec `Int8` et `Int16` respectivement : 1 ou 2 octets par ligne, complément à deux en little-endian pour la variante sur 16 bits. La correspondance complète des variantes se trouve dans la chaîne de type :
```text theme={null}
Enum8('active' = 1, 'inactive' = 2, 'banned' = -1)
Enum16('a' = 1, 'b' = 30000)
```
Un décodeur peut supprimer le suffixe de paramètre `(...)` et traiter le type comme `Int8` / `Int16` — les octets transmis ne contiennent que l’index entier. Un client qui expose le libellé analyse la correspondance `'name' = value` à partir de la chaîne de type et la conserve avec la colonne : l’entier seul ne permet pas de retrouver le libellé. Une sortie textuelle affiche le libellé (`active`) plutôt que l’index, entre apostrophes (`'active'`) lorsque l’enum est imbriqué dans un type composite. Comme cette correspondance ne peut pas être reconstituée à partir de la colonne entière, elle doit être conservée pour les enums imbriqués tels que `Array(Enum8(...))` ou `Map(Enum16(...), V)`.
Une colonne `Enum8('active' = 1, 'inactive' = 2)` `[active, inactive, active]` :
```text theme={null}
01 02 01
```
Une valeur `30000` de `Enum16(...)` :
```text theme={null}
30 75 Int16 LE = 30000
```
#### Decimal(P, S)
Un entier signé mis à l’échelle par une puissance de 10. La taille en octets de l’entier est implicitement déterminée par la **précision** `P` ; l’**échelle** `S` correspond à l’exposant négatif (le nombre de chiffres après le séparateur décimal). Les deux figurent dans la chaîne de type.
| Précision (P) | Entier sous-jacent | Octets |
| ------------- | ------------------ | ------ |
| 1 ≤ P ≤ 9 | Int32 | 4 |
| 10 ≤ P ≤ 18 | Int64 | 8 |
| 19 ≤ P ≤ 38 | Int128 | 16 |
| 39 ≤ P ≤ 76 | Int256 | 32 |
L’encodage wire est l’entier sous-jacent en complément à deux little-endian, et la valeur décimale logique est `wire_integer × 10^(-S)`.
ClickHouse émet toujours `Decimal(P, S)`, quelle que soit la façon dont le type a été déclaré. `Decimal32(S)`, `Decimal64(S)`, etc. sont tous normalisés en `Decimal(P, S)` sur le wire (avec `P` fixé au maximum naturel pour cette largeur : 9, 18, 38, 76). Un décodeur qui reconnaît uniquement `Decimal(P, S)` couvre toutes les variantes émises par le serveur.
Valeur `123.4567` de `Decimal(9, 4)` → entier sous-jacent `1234567` :
```text theme={null}
87 D6 12 00 Int32 LE = 1234567
```
`Decimal(18, 1)` avec la valeur `-1.5` → entier sous-jacent `-15` :
```text theme={null}
F1 FF FF FF FF FF FF FF Int64 LE = -15
```
`Decimal(38, 4)` valeur `123.4567` (16 octets au total) :
```text theme={null}
87 D6 12 00 00 00 00 00 00 00 00 00 00 00 00 00
```
#### Nothing
Le type `Nothing` ne contient aucune valeur. En pratique, il n’apparaît que comme type interne de `Nullable(Nothing)` — c’est ce que le serveur renvoie pour une expression comme `SELECT NULL`, dont la seule valeur possible est l’absence de valeur. Conceptuellement, il s’agit d’un type unitaire.
Dans le format binaire transmis, il occupe exactement **un octet de remplissage par ligne**. Le serveur émet le caractère ASCII `'0'` (`0x30`), mais le désérialiseur ignore ces octets — leur contenu n’est pas défini et les décodeurs ne doivent supposer aucune valeur particulière. Le nombre d’octets écrits est `num_rows × 1`, donc le `num_rows` de l’en-tête de colonne détermine entièrement la quantité à lire.
Cet octet par ligne préserve l’invariant du Block : chaque colonne a une longueur déductible de `num_rows`, ce qui permet aux décodeurs d’avancer sans préfixe de longueur pour chaque cellule. Le `Nullable` englobant indique toujours NULL pour chaque position, de sorte que ces octets de remplissage ne sont jamais examinés.
Une colonne `Nullable(Nothing)` avec 3 lignes (toutes NULL) :
```text theme={null}
01 01 01 null map: 1, 1, 1 (three NULLs)
30 30 30 Nothing placeholder bytes (one per row)
```
Le préfixe de la null-map correspond à l'encodage standard de `Nullable` (voir [Nullable](#nullable)) ; les trois octets internes forment le `payload` de `Nothing`, que le décodeur saute.
### Types à longueur variable
Chaque valeur inclut sa propre longueur dans le format binaire transmis.
#### String
Type de chaîne : `String`. Une colonne `String` est une séquence de `num_rows` séquences d’octets préfixées par leur longueur :
```text theme={null}
[VarUInt: byte_length] [byte_length bytes: raw value]
[VarUInt: byte_length] [byte_length bytes: raw value]
...
```
Il n’y a pas de séparateurs entre les lignes au-delà des préfixes de longueur, et il n’existe pas d’état row-level. Une chaîne vide correspond à un seul octet `0x00`. Le type ClickHouse `String` est orienté octets plutôt que texte : la validité de l’UTF-8 n’est pas vérifiée, et une valeur peut contenir n’importe quels octets, y compris un NUL incorporé. Un décodeur visant un type de chaîne UTF-8 valide soit les données à la lecture, soit expose les raw bytes à l’appelant. Le nombre total d’octets consommés par la colonne est `Σ (varuint_size(len_i) + len_i)` sur l’ensemble des lignes.
Une colonne de 3 chaînes `["ab", "", "c"]` (6 octets au total) :
```text theme={null}
02 61 62 row 0: length 2, "ab"
00 row 1: length 0, empty
01 63 row 2: length 1, "c"
```
#### FixedString(N)
Chaîne de type : `FixedString(N)`, où `N` est un entier positif (par exemple, `FixedString(16)`). La colonne contient exactement `N × num_rows` octets bruts, sans préfixe de longueur ni séparateur. Un décodeur analyse `N` à partir de la chaîne de type et consomme ce nombre d’octets par ligne.
Lorsqu’une instruction SQL insère une valeur plus courte que `N` octets (par exemple, `CAST('abc' AS FixedString(5))`), le serveur la complète à droite avec des octets NUL (`0x00`) jusqu’à la longueur déclarée. Ces octets de remplissage font partie de la valeur stockée et sont transmis tels quels sur le réseau ; leur suppression relève du client. Comme `String`, `FixedString(N)` s’apparente davantage à un tableau d’octets qu’à du texte : il est généralement utilisé pour des identifiants à largeur fixe, des octets d’adresse ou des condensats de hachage.
Deux valeurs `FixedString(3)` `["abc", "de\0"]` (6 octets au total) :
```text theme={null}
61 62 63 row 0: 3 bytes, "abc"
64 65 00 row 1: 3 bytes, "de" + NUL padding
```
Comparaison des deux types de chaînes :
| Propriété | `String` | `FixedString(N)` |
| ----------------------------------- | ------------------------- | ----------------------------------- |
| Préfixe de longueur par ligne | Oui (VarUInt) | Non |
| Taille d’une ligne | Variable | Exactement `N` octets |
| Nombre total d’octets de la colonne | Variable | `N × num_rows` |
| Remplissage par octets NUL | s.o. | Complété à droite par le serveur |
| UTF-8 attendu | Généralement (non imposé) | Non (traité comme des octets bruts) |
| Paramètre de type | None | Entier `N` obligatoire |
### Types composites
Les types composites encapsulent un ou plusieurs types internes et partagent un modèle binaire commun sur le wire : **plusieurs flux par colonne**. Une même colonne logique est encodée sous la forme de deux séquences d’octets ou plus, lues indépendamment puis concaténées.
Ils partagent trois propriétés structurelles :
* **Forme fixe par schéma.** La structure est entièrement déterminée par la chaîne de type au moment du décodage. `Array(UInt32)` a toujours la même organisation de flux, d’un bloc à l’autre.
* **Aucun préfixe de version propre.** Le wrapper composite lui-même n’ajoute aucun octet de version ; son encapsulation (offsets, null-map, flux d’éléments) reste stable d’une version de ClickHouse à l’autre. Cela s’applique uniquement au *wrapper* — voir la note ci-dessous sur la phase de préfixe pour les types internes versionnés.
* **Aucun état inter-blocs propre.** L’encapsulation du wrapper est entièrement auto-descriptive pour chaque bloc ; toute problématique d’état inter-blocs provient d’un type interne versionné, et non du wrapper.
Les composites sont récursifs — un type interne peut lui-même être un composite.
**Phase de préfixe avant les flux de données.** La lecture d’une colonne se déroule en deux phases, dans cet ordre : une **phase de préfixe d’état**, puis la **phase des flux de données**. Un wrapper composite n’a pas d’octets de préfixe qui lui soient propres, mais il *délègue* la phase de préfixe à sa sérialisation interne avant d’écrire le moindre de ses propres flux de données : `SerializationArray` exécute la phase de préfixe de son type interne avant d’écrire les offsets du tableau, et `Tuple`, `Map`, `Nested` et `Nullable` font de même via leurs sérialisations d’éléments (`Nullable` exécute le préfixe interne avant sa null map).
Ainsi, lorsqu’un composite encapsule un [type versionné/avec état](#versioned-types) (`LowCardinality`, `Variant`, `Dynamic`, `JSON`), le préfixe de version/d’état de ce type interne est émis *en premier*, avant les offsets du wrapper et le payload des éléments. Par exemple, `Array(LowCardinality(String))` se présente ainsi : `[LowCardinality state prefix]` → `[array offsets]` → `[flattened LowCardinality element payload]`, et non avec les offsets en premier.
Un décodeur qui lit les offsets avant d’exécuter la phase de préfixe interne se désynchronisera sur tout composite contenant `LowCardinality`, `Variant`, `Dynamic` ou `JSON`. Lorsque tous les types internes sont soit des types feuilles simples, soit d’autres composites non versionnés, la phase de préfixe n’émet aucun octet et la description « offsets d’abord » ci-dessous s’applique telle quelle.
#### Nullable(T)
Chaîne de type : `Nullable(InnerType)`. Exemples : `Nullable(UInt32)`, `Nullable(String)`, `Nullable(FixedString(16))`, `Nullable(DateTime('UTC'))`.
Comme les autres types composites, `Nullable` délègue la [phase de préfixe](#composite-types) à sa sérialisation interne avant d’écrire la null-map : lorsque le type interne est versionné, son préfixe d’état est émis **en premier**. Ainsi, `Nullable(Tuple(LowCardinality(String)))` commence par le préfixe d’état de `LowCardinality`, et non par la null-map. Lorsque le type interne est un type feuille ou un autre type non versionné, la phase de préfixe n’émet aucun octet.
La disposition sur le wire correspond à la phase de préfixe interne (vide sauf si le type interne est versionné), suivie de deux flux concaténés, en commençant par la null-map :
```text theme={null}
[inner type's state prefix] empty for leaf/non-versioned inners; emitted first when the inner is versioned
[null-map stream] num_rows × UInt8
[values stream] inner type's encoding for num_rows values
```
La null-map comporte exactement `num_rows` octets, un par ligne :
| Valeur d’octet | Signification |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `0x00` | Une valeur est présente sur cette ligne. |
| non nulle (canonique `0x01`) | La valeur est NULL. Les octets correspondants dans le flux de valeurs sont une valeur de remplissage. |
Le flux de valeurs contient l’encodage standard du type interne pour **l’ensemble des** `num_rows` lignes, y compris aux positions nulles. Un décodeur doit tout de même lire les octets de remplissage aux positions nulles pour avancer dans le flux, mais il doit consulter la null-map avant d’interpréter une quelconque valeur individuelle. Les émetteurs peuvent écrire n’importe quels octets aux positions nulles ; les décodeurs ne doivent donc pas s’appuyer sur une valeur de remplissage spécifique.
Valeurs de remplissage par famille de types internes :
| Famille de types internes | Valeur de remplissage à la position nulle |
| ----------------------------------------------- | ------------------------------------------------------ |
| Fixed-width (UInt/Int/Float/DateTime/UUID/etc.) | Octets initialisés à zéro sur toute la largeur du type |
| `String` | Chaîne vide — un seul octet `0x00` |
| `FixedString(N)` | `N` octets à zéro |
| `Array(T)` | Tableau vide — les offsets n’avancent pas |
| `Tuple(T1, T2, ...)` | Chaque élément utilise sa propre valeur de remplissage |
`Nullable(T)` peut apparaître dans `Array`, `Tuple`, `Map` et `Nested` — `Array(Nullable(T))` et `Tuple(Nullable(T1), T2)` sont courants. La nullabilité ne se compose pas avec elle-même : `Nullable(Nullable(T))` est rejeté par le serveur.
Un `Nullable(UInt8)` avec trois lignes `[5, NULL, 9]` (6 octets au total) :
```text theme={null}
00 01 00 null-map: present, null, present
05 00 09 values: 5, placeholder, 9
```
Un `Nullable(String)` comportant trois lignes `["hello", NULL, "world"]` (15 octets au total) :
```text theme={null}
00 01 00 null-map
05 'h' 'e' 'l' 'l' 'o' row 0: "hello"
00 row 1: placeholder (empty string)
05 'w' 'o' 'r' 'l' 'd' row 2: "world"
```
#### Array(T)
Chaîne de type : `Array(InnerType)`. Exemples : `Array(UInt32)`, `Array(String)`, `Array(Nullable(UInt32))`, `Array(Array(UInt8))`.
La disposition sur le wire correspond à la [phase de préfixe](#composite-types) interne (vide sauf si le type interne est versionné), suivie de deux flux concaténés, avec les offsets en premier :
```text theme={null}
[inner type's state prefix] empty for leaf/non-versioned inners; emitted first when the inner is versioned
[offsets stream] num_rows × UInt64 LE
[values stream] inner type's encoding for offsets[num_rows - 1] values
```
Le flux d’offsets est composé exactement de `num_rows` valeurs UInt64 en little-endian, chacune représentant la **position de fin cumulée** dans le flux de valeurs après les éléments de cette ligne :
* L’indice de début des éléments pour la ligne `N` = `offsets[N - 1]` (ou `0` lorsque `N == 0`).
* L’indice de fin des éléments (exclusif) pour la ligne `N` = `offsets[N]`.
* Le nombre d’éléments de la ligne `N` = `offsets[N] - offsets[N - 1]`.
`offsets[num_rows - 1]` correspond donc au nombre total d’éléments sur l’ensemble des lignes, et le flux de valeurs contient ce nombre de valeurs internes concaténées bout à bout.
Les offsets sont **monotones non décroissants** ; des offsets consécutifs identiques indiquent une ligne vide, et un décodeur doit rejeter les offsets non monotones comme corrompus. Une colonne vide (`num_rows == 0`) écrit zéro octet — aucun flux d’offsets ni flux de valeurs. Les types internes peuvent être de tout type, y compris d’autres types composites : `Array(Array(T))`, `Array(Tuple(...))` et `Array(Nullable(T))` sont tous valides.
`Array(UInt32)` avec les lignes `[[10, 20, 30], [], [40, 50]]` (44 octets au total) :
```text theme={null}
Offsets (3 × UInt64 LE = 24 bytes):
03 00 00 00 00 00 00 00 offsets[0] = 3
03 00 00 00 00 00 00 00 offsets[1] = 3 (empty row)
05 00 00 00 00 00 00 00 offsets[2] = 5
Values (5 × UInt32 LE = 20 bytes):
0A 00 00 00 10
14 00 00 00 20
1E 00 00 00 30
28 00 00 00 40
32 00 00 00 50
```
Chaque offset correspond à la *fin* cumulée de la portion du flux partagé des valeurs associée à une ligne ; le début est l’offset précédent (ou `0` pour la ligne 0). Deux offsets consécutifs identiques correspondent à une ligne vide :
```mermaid theme={null}
flowchart LR
subgraph V["values stream: [10, 20, 30, 40, 50]"]
direction LR
v0["10"] --- v1["20"] --- v2["30"] --- v3["40"] --- v4["50"]
end
r0["row 0"] -->|"[0 .. offsets[0]=3)"| v0
r1["row 1"] -.->|"[3 .. offsets[1]=3) empty"| V
r2["row 2"] -->|"[offsets[1]=3 .. offsets[2]=5)"| v3
```
`Array(String)` avec les lignes `[["a", "bb"], []]` (20 octets au total) :
```text theme={null}
Offsets (2 × UInt64 LE = 16 bytes):
02 00 00 00 00 00 00 00 offsets[0] = 2
02 00 00 00 00 00 00 00 offsets[1] = 2 (empty row)
Values (2 strings, 4 bytes total):
01 'a' row's first string: "a"
02 'b' 'b' row's second string: "bb"
```
`Array(Array(UInt32))` avec les lignes `[[[1,2]], [], [[3], [4,5]]]` présente la même structure imbriquée :
* Offsets externes : `[1, 1, 3]` — la ligne 0 contient 1 tableau interne, la ligne 1 n’en contient aucun, la ligne 2 en contient 2.
* Le `Array(UInt32)` intermédiaire décode 3 lignes avec les offsets `[2, 3, 5]`.
* Le `UInt32` le plus interne décode 5 valeurs : `[1, 2, 3, 4, 5]`.
Cela donne 24 (offsets externes) + 24 (offsets intermédiaires) + 20 (valeurs) = 68 octets.
#### Tuple(T1, T2, ...)
Chaîne de type : `Tuple(T1, T2, ..., Tn)`. Exemples : `Tuple(UInt32, String)`, `Tuple(Int32)`, `Tuple(Array(UInt32), String)`, `Tuple(UInt8, Tuple(Int32, String))`. ClickHouse prend également en charge les **tuples nommés** via `Tuple(a UInt32, b String)` ; les noms ne sont que des métadonnées et n’affectent pas le wire format.
La disposition sur le wire correspond à la [phase de préfixe](#composite-types) des éléments (chaque élément versionné apporte son préfixe d’état, dans l’ordre de déclaration ; elle est vide pour les éléments non versionnés), suivie de *N* flux concaténés, un par type d’élément, dans l’ordre de déclaration :
```text theme={null}
[element state prefixes] in declaration order; empty unless an element type is versioned
[stream for T1] inner T1's encoding for num_rows values
[stream for T2] inner T2's encoding for num_rows values
...
[stream for Tn] inner Tn's encoding for num_rows values
```
Chaque flux encode exactement `num_rows` valeurs. Il n’y a pas de préfixe de longueur, pas de flux d’offsets, ni de séparateurs entre les flux. Une colonne vide (`num_rows == 0`) écrit zéro octet par flux. Les types d’éléments peuvent être de tout type, y compris d’autres types composites — `Tuple(Tuple(...), ...)`, `Tuple(Array(...), ...)` et `Tuple(Nullable(T1), T2)` sont tous valides.
Le tuple sans élément `Tuple()` est lui aussi valide — il résulte d’expressions comme `SELECT tuple()` ou `CAST(x AS Tuple())`. Comme il n’a pas de flux d’éléments, il se sérialise comme [Nothing](#nothing) : **un octet factice (`0x30`, ASCII `'0'`) par ligne**, que le désérialiseur ignore. Le nombre de lignes provient de l’en-tête du block, exactement comme pour `Nothing`.
`Tuple(UInt8, UInt8)` avec 3 lignes `(1,4), (2,5), (3,6)` :
```text theme={null}
Element 0 stream (3 × UInt8 = 3 bytes):
01 02 03
Element 1 stream (3 × UInt8 = 3 bytes):
04 05 06
```
La disposition n’est **pas** organisée par lignes : la relecture des octets bruts renvoie `[1, 2, 3]` pour l’élément 0 et `[4, 5, 6]` pour l’élément 1.
`Tuple(UInt32, String)` avec 2 lignes `(10, "a")`, `(20, "bb")` (13 octets au total) :
```text theme={null}
Element 0 stream (2 × UInt32 LE = 8 bytes):
0A 00 00 00 10
14 00 00 00 20
Element 1 stream (2 strings, 5 bytes total):
01 'a' "a"
02 'b' 'b' "bb"
```
#### Map(K, V)
Chaîne de type : `Map(KeyType, ValueType)`. Exemples : `Map(String, UInt32)`, `Map(String, Array(UInt32))`, `Map(UInt8, Tuple(Int32, String))`, `Map(Array(String), Int8)`. Le format wire n’impose aucune restriction à l’un ou l’autre type : `K` et `V` peuvent tous deux être de n’importe quel type pris en charge, y compris des types composites. (Les règles de ClickHouse au niveau SQL concernant les types de clé acceptés ont varié selon les versions ; consultez la documentation SQL correspondant à la version ciblée du serveur.)
La disposition sur le wire est identique, octet pour octet, à `Array(Tuple(K, V))` ; elle commence donc par la [phase de préfixe](#composite-types) interne (vide, sauf si `K` ou `V` est versionné) :
```text theme={null}
[K/V state prefixes] from the inner Tuple's prefix phase; empty unless K or V is versioned
[offsets stream] num_rows × UInt64 LE ← from Array
[keys stream] K's encoding for total_pairs values ┐ from Tuple's
[values stream] V's encoding for total_pairs values ┘ per-element streams
```
où `total_pairs = offsets[num_rows - 1]` (ou `0` lorsque `num_rows == 0`). Le flux d’offsets a la même sémantique que [Array](#array). Les clés sont alignées positionnellement avec les valeurs : la paire `i` est `(keys[i], values[i])`.
La représentation en mémoire d’une colonne Map dans ClickHouse est un tableau de tuples ; le système de types l’expose comme un type distinct pour plus d’ergonomie en SQL (`m['key']`, `mapKeys`, `mapValues`). Le format wire est une sérialisation directe de ce stockage ; `Map` et `Array(Tuple(K, V))` sont donc interchangeables octet pour octet.
Les offsets sont monotones et non décroissants, et les flux de clés et de valeurs contiennent tous deux exactement `total_pairs` valeurs. Une colonne vide n’écrit aucun octet. Au sein d’une même ligne, les clés sont généralement uniques, mais il s’agit d’une règle sémantique, non imposée par le format wire : le format wire permet de préserver des clés dupliquées à l’aller comme au retour, et la sémantique côté serveur ne résout les doublons que lorsqu’une fonction compatible avec Map consomme la ligne.
`Map(UInt8, UInt8)` avec 2 lignes `{1:10, 2:20}`, `{3:30}` (22 octets au total) :
```text theme={null}
Offsets (2 × UInt64 LE = 16 bytes):
02 00 00 00 00 00 00 00 offsets[0] = 2
03 00 00 00 00 00 00 00 offsets[1] = 3
Keys (3 × UInt8 = 3 bytes):
01 02 03 keys: 1, 2, 3
Values (3 × UInt8 = 3 bytes):
0A 14 1E values: 10, 20, 30
```
Les clés et les valeurs sont stockées dans des flux distincts, et non entrelacés — la paire `i` est reconstituée en lisant ensemble `keys[i]` et `values[i]`.
`Map(String, UInt32)` avec 1 ligne `{'a':1, 'b':2}` (20 octets au total) :
```text theme={null}
Offsets (1 × UInt64 LE = 8 bytes):
02 00 00 00 00 00 00 00 offsets[0] = 2
Keys (2 strings, 4 bytes total):
01 'a' "a"
01 'b' "b"
Values (2 × UInt32 LE = 8 bytes):
01 00 00 00 1
02 00 00 00 2
```
#### Nested(name1 T1, name2 T2, ...)
La représentation sur le wire de `Nested` dépend du paramètre `flatten_nested` côté serveur, ce qui donne lieu à deux cas distincts.
```mermaid theme={null}
flowchart TD
N["column declared Nested(a T1, b T2, ...)"]
N --> Q{"flatten_nested?"}
Q -->|"= 1 (server default)"| A["N parallel Array(T_i) columns
with dotted names (n.a, n.b)
— no Nested wire type"]
Q -->|"= 0"| B["one column, type string Nested(...)
laid out byte-identically to
Array(Tuple(T1, ..., Tn))"]
```
**Cas A : `flatten_nested = 1` (valeur par défaut du serveur).** Lorsque la table a été créée avec les paramètres par défaut, `Nested` **n'est pas un type wire**. Le serveur stocke et présente la colonne sous la forme de N colonnes `Array(T_i)` parallèles avec des **noms en notation pointée** (`outer.field1`, `outer.field2`, etc.). Au niveau du format, il n'y a rien de nouveau — chaque colonne en notation pointée est un [Array](#array) classique :
```text theme={null}
DESCRIBE TABLE t -- t has column n Nested(a UInt8, b String)
id UInt8
n.a Array(UInt8)
n.b Array(String)
```
**Cas B : `flatten_nested = 0`.** Lorsque la table a été créée avec `flatten_nested = 0`, la colonne apparaît dans la représentation binaire comme une seule colonne avec la chaîne de type `Nested(name1 T1, name2 T2, ...)`, et sa structure après la chaîne de type est **strictement identique, octet pour octet, à `Array(Tuple(T1, T2, ..., Tn))`** — y compris la [phase de préfixe](#composite-types) interne, de sorte que tout champ versionné `T_i` émet d'abord son préfixe d'état, avant les offsets. L'exemple ci-dessous utilise des champs non versionnés ; la phase de préfixe est donc vide :
```text theme={null}
Nested(a UInt8, b String) bytes (after type string):
02 00 00 00 00 00 00 00 offsets[0] = 2
03 00 00 00 00 00 00 00 offsets[1] = 3
0A 14 1E UInt8 stream
01 'x' 01 'y' 01 'z' String stream
Array(Tuple(a UInt8, b String)) bytes (after type string):
02 00 00 00 00 00 00 00 offsets[0] = 2
03 00 00 00 00 00 00 00 offsets[1] = 3
0A 14 1E UInt8 stream
01 'x' 01 'y' 01 'z' String stream
```
La seule différence réside dans la chaîne de type : `Nested` préserve les noms de champ (`a`, `b`), alors que `Array(Tuple)` ne les conserve pas sous forme de positions nommées.
La chaîne de type du cas B est une liste de paires (nom, type) séparées par des virgules. Le premier espace sépare un nom de son type ; le type lui-même peut contenir d'autres espaces, virgules et parenthèses. L'analyse nécessite donc le même découpeur tenant compte de la profondeur que celui utilisé pour `Tuple`. La représentation sur le wire :
```text theme={null}
[offsets stream] num_rows × UInt64 LE ← from Array
[field1 stream] T1's encoding for total_elements values ┐ from Tuple's
[field2 stream] T2's encoding for total_elements values │ per-element
... │ streams
[fieldn stream] Tn's encoding for total_elements values ┘
```
où `total_elements = offsets[num_rows - 1]` (ou `0` lorsque `num_rows == 0`). Les offsets sont monotones et non décroissants, et chaque flux de champ contient exactement `total_elements` valeurs. Le serveur impose lors de `INSERT` que, dans une même ligne, tous les champs contiennent le même nombre d’éléments. Une colonne vide n’écrit aucun octet.
`Nested(a UInt8, b String)` avec 2 lignes `[(10,'x'),(20,'y')]` et `[(30,'z')]` (25 octets après la chaîne de type) :
```text theme={null}
Offsets (2 × UInt64 LE = 16 bytes):
02 00 00 00 00 00 00 00 offsets[0] = 2
03 00 00 00 00 00 00 00 offsets[1] = 3
Field 'a' stream (3 × UInt8 = 3 bytes):
0A 14 1E 10, 20, 30
Field 'b' stream (3 strings, 6 bytes):
01 'x' 01 'y' 01 'z' "x", "y", "z"
```
### Alias de type
Plusieurs types sont de simples alias : le serveur envoie le nom de l'alias dans l'en-tête de colonne, mais les octets qui suivent sont ceux d'un type sous-jacent. Un décodeur associe l'alias à ce type et réutilise son codec — aucun nouveau format wire n'entre en jeu.
Les types géographiques sont des alias de tableaux et de tuples imbriqués :
| Chaîne de type | Type wire sous-jacent |
| ---------------------------- | ------------------------- |
| `Point` | `Tuple(Float64, Float64)` |
| `Ring`, `LineString` | `Array(Point)` |
| `Polygon`, `MultiLineString` | `Array(Ring)` |
| `MultiPolygon` | `Array(Polygon)` |
Ainsi, une colonne `Point` est décodée exactement comme `Tuple(Float64, Float64)` (affichée sous la forme `(1,2)`), un `Ring` comme `Array(Tuple(Float64, Float64))` (`[(0,0),(1,1)]`), et ainsi de suite dans la hiérarchie.
`Geometry` est également un alias, mais d'un [`Variant`](#variant) plutôt que d'un tableau imbriqué : son payload est la variante des six types geo ci-dessus. L'en-tête de colonne ne contient que la chaîne de type `Geometry` — il **ne détaille pas** la variante — donc un décodeur doit l'étendre lui-même. Comme pour tout `Variant`, les discriminants suivent l'ordre canonique des alias geo triés par nom : `0` = `LineString`, `1` = `MultiLineString`, `2` = `MultiPolygon`, `3` = `Point`, `4` = `Polygon`, `5` = `Ring`. Chaque valeur sélectionnée est ensuite décodée via l'alias geo correspondant ci-dessus (`NULL` utilise le discriminant `NULL` `255` de `Variant`).
`SimpleAggregateFunction(func, T)` est un alias de son type de valeur `T`. Il stocke une valeur d'agrégation déjà finalisée, donc sa représentation wire et son affichage sont exactement ceux de `T` (`SimpleAggregateFunction(sum, UInt64)` est décodé comme `UInt64`). Seule la forme à type de valeur unique est un alias de cette manière ; le type sous-jacent peut lui-même être composite.
Deux types apparentés ne sont **pas** des alias. Ce sont des column types `Native` valides — un client peut recevoir une colonne `AggregateFunction` depuis un combinator `-State` ou une agrégation distribuée, par exemple — mais chacun transporte son propre payload spécialisé, qui sort du cadre de cette page :
* `AggregateFunction(func, ...)` contient un état d'aggregation *intermédiaire* (et non une valeur finalisée) ; sa disposition binaire est spécifique à l'aggregate function et à la version.
* `QBit(T, N)` stocke un vecteur dont les bit planes sont transposés pour des workloads de recherche vectorielle.
### Types versionnés
Les types versionnés comportent un préfixe de version de sérialisation on-wire qui indique quelle variante de l’encodage suit. Ils peuvent aussi utiliser plusieurs flux (comme les composites). Avec le format `Native`, le préfixe et tout dictionnaire sont définis par bloc — ces types ne conservent aucun état d’un bloc à l’autre (voir [la note sur le préfixe par bloc](#serialization-version-concept) ci-dessous) ; un état de sérialisation entre les blocs n’existe que dans le flux sur disque de MergeTree.
Ces types sont nettement plus complexes que les composites à structure fixe, et un client visant de simples requêtes analytiques peut en remettre la prise en charge à plus tard.
#### Version de sérialisation : concept
Une **version de sérialisation** est un numéro de version on-wire, propre à chaque type et à chaque colonne, qui indique quelle variante de l’encodage d’un type l’expéditeur utilise. C’est le premier élément du préfixe d’état de la colonne ; le décodeur le lit donc en premier et l’aiguille vers le parseur approprié pour le reste de la colonne.
Elle est distincte de la version du protocole :
| Dimension | Version du protocole | Version de sérialisation (cette section) |
| ------------------- | ---------------------------------------------------------- | ------------------------------------------ |
| Portée | À l’échelle de la connexion | Par type, par colonne |
| Négociée | Oui, lors du handshake | Non — l’expéditeur écrit, le récepteur lit |
| Contrôle | Quelles fonctionnalités au niveau des paquets sont actives | Quelle variante on-wire d’un type |
| Lecture obligatoire | Oui | Oui, pour chaque colonne versionnée |
La plupart des types versionnés écrivent la version sous forme de UInt64 little-endian, immédiatement avant toute autre donnée du préfixe d’état ; quelques-uns utilisent VarUInt ou UInt8. Le décodeur lit d’abord la version et rejette les valeurs inconnues — une version plus élevée implique un format d’expéditeur plus récent que le décodeur ne comprend pas, et une mauvaise analyse corrompt chaque octet suivant.
Le préfixe d’état est émis au début de **chaque bloc dont le nombre de lignes est supérieur à zéro**, immédiatement avant le payload de ce bloc.
Le writer et le reader Native ne conservent **pas** l’état de sérialisation d’un bloc à l’autre : `NativeWriter` crée un nouvel état de sérialisation et écrit un préfixe d’état pour chaque bloc de colonne non vide qu’il écrit, et `NativeReader` crée un nouvel état de désérialisation et le lit pour chaque bloc non vide qu’il lit (tous deux omettent entièrement le préfixe lorsque `rows == 0`).
Les header blocks (`rows = 0`) et les blocs vides n’émettent donc rien, et un décodeur doit relire le préfixe d’état au début de chaque bloc non vide. Un décodeur qui ne lit le préfixe qu’une seule fois et traite les blocs suivants comme ne contenant que le payload lira le préfixe du bloc suivant comme des données et se désynchronisera :
```mermaid theme={null}
sequenceDiagram
participant S as Server (writer)
participant C as Client (decoder)
S->>C: Header block (num_rows = 0)
Note right of C: no state prefix
S->>C: First block with rows > 0
Note right of C: read state prefix,
then block payload
S->>C: Next block with rows > 0
Note right of C: read state prefix again,
then block payload
S->>C: Empty block (end marker)
Note right of C: no state prefix
```
#### Référence des versions de sérialisation
| Type | Largeur du champ | Valeur | Nom | Signification |
| -------------------------------------------------------------------------------------------- | ---------------- | ------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Object** (base du JSON) | UInt64 LE | `0` | `V1` | Encodage d'origine. Inclut le paramètre `max_dynamic_paths` et une liste de chemins dynamiques. |
| | | `1` | `STRING` | Mode de compatibilité du format natif — `Object` est transmis sous la forme d'une seule colonne `String` contenant du texte JSON. |
| | | `2` | `V2` | Disposition V1 sans le paramètre `max_dynamic_paths`. |
| | | `3` | `FLATTENED` | Mode de compatibilité du format natif — représentation aplatie des chemins. |
| | | `4` | `V3` | V2 avec, en plus, un sous-champ de version de sérialisation des données partagées et un indicateur de statistiques. |
| **Données partagées d'Object** (sous-flux utilisé dans Object `V3`) | VarUInt | `0` | `MAP` | Données partagées encodées sous la forme de `Map(String, String)`. |
| | | `1` | `MAP_WITH_BUCKETS` | Identique à `MAP`, mais réparti en N buckets pour améliorer l'efficacité du scan. |
| | | `2` | `ADVANCED` | Format de granule compact avec des flux séparés pour les chemins / marks / métadonnées. |
| **Dynamic** | UInt64 LE | `1` | `V1` | Encodage d'origine. Inclut `max_dynamic_types` et une liste de types Variant au runtime. |
| | | `2` | `V2` | V1 sans le paramètre `max_dynamic_types`. |
| | | `3` | `FLATTENED` | Mode de compatibilité du format natif. |
| | | `4` | `V3` | V2 avec, en plus, des noms de types Variant encodés en binaire et la prise en charge de statistiques vides. |
| **Variant** mode des discriminateurs | UInt64 LE | `0` | `BASIC` | Le discriminateur de chaque ligne est écrit littéralement. |
| | | `1` | `COMPACT` | Si toutes les lignes d'une granule partagent le même discriminateur, seule une valeur unique + un marqueur de granule sont écrits. |
| **Variant** format de granule (lorsque le mode est `COMPACT`) | UInt8 | `0` | `PLAIN` | La granule contient des discriminateurs hétérogènes. |
| | | `1` | `COMPACT` | La granule a un seul discriminateur pour toutes les lignes. |
| **LowCardinality** sérialisation des clés | Int64 | `1` | `sharedDictionariesWithAdditionalKeys` | Seule version actuellement définie. |
| **JSON-as-String** fallback (lorsque `output_format_native_write_json_as_string` est activé) | UInt64 LE | `1` | `JSONStringSerializationVersion` | La colonne JSON arrive sous la forme d'une colonne `String` précédée de ce préfixe. |
Quelques points à noter à propos du tableau :
* **Les valeurs ne sont pas contiguës.** `Dynamic` utilise `1`, `2`, `3`, `4`, avec `V3` à `4` et `FLATTENED` à `3`. Un nombre plus élevé n'est pas nécessairement plus récent.
* **Certaines valeurs sont propres au format natif.** `Object::STRING`, `Object::FLATTENED` et `Dynamic::FLATTENED` existent pour assurer la compatibilité du protocole natif avec les clients qui n'implémentent pas entièrement Object/Dynamic. Elles n'apparaissent pas dans le stockage sur disque de MergeTree.
* **`V3` est principalement utilisé sur disque.** Les clients qui utilisent le protocole TCP natif voient généralement `FLATTENED` (valeur `3`) plutôt que `V3` (valeur `4`).
#### LowCardinality(T)
Le type versionné le plus simple. Il remplace une colonne de `N` valeurs sous-jacentes par un petit dictionnaire de valeurs uniques, ainsi que `N` indices dans ce dictionnaire.
Chaîne de type : `LowCardinality(InnerType)`. Exemples : `LowCardinality(String)`, `LowCardinality(FixedString(4))`, `LowCardinality(Nullable(String))`.
```text theme={null}
[per block with rows > 0]:
[8 bytes: Int64 LE state prefix = 1] ← repeated at the start of every non-empty block
[8 bytes: UInt64 LE metadata] ← key type code (low byte) + flag bits
[8 bytes: UInt64 LE dict_size] ← number of dict entries (incl. placeholder slot)
[N bytes: dict values] ← inner type's encoding for dict_size values
[8 bytes: UInt64 LE keys_count] ← number of values at this recursive level (see below)
[K bytes: keys] ← (1 << key_type_code) bytes per key
```
Le préfixe d’état (Int64 LE = 1) est l’unique version définie, `sharedDictionariesWithAdditionalKeys` ; toutes les autres valeurs sont réservées.
Les métadonnées UInt64 par bloc forment un champ de bits :
| Bit range | Meaning |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0..7 | Code du type de clé : `0` = UInt8, `1` = UInt16, `2` = UInt32, `3` = UInt64. Le plus petit type capable d’indexer `dict_size` entrées est choisi. |
| 8 (`0x100`) | `NeedGlobalDictionaryBit` — un dictionnaire unique partagé entre les blocs. **Jamais défini dans le format `Native`** : le writer Native utilise `low_cardinality_max_dictionary_size = 0`, et le reader Native rejette ce bit (`native_format` lève `INCORRECT_DATA` — "cannot use global dictionary"). Il appartient au flux sur disque de MergeTree, pas au flux binaire. |
| 9 (`0x200`) | `HasAdditionalKeysBit` — défini lorsque le bloc transporte des clés de dictionnaire supplémentaires (écrites avant les index). Toujours défini pour un bloc `Native` non vide. |
| 10 (`0x400`) | `NeedUpdateDictionary` — défini lorsque le bloc transporte une mise à jour du dictionnaire. Toujours défini pour un bloc `Native` non vide, puisque chaque bloc transporte son propre dictionnaire autonome. |
Pour une réponse de query typique avec un seul bloc de données par colonne, les métadonnées valent `0x600` (HasAdditionalKeys + NeedUpdateDictionary).
Les valeurs du dict sont `dict_size` valeurs encodées à l’aide du type interne T. Le dictionnaire réserve des emplacements initiaux pour des valeurs spéciales : une colonne non nullable en réserve un (`dict[0]` contient la valeur par défaut du type interne, par exemple `""` pour `String`), et les véritables valeurs distinctes commencent à `dict[1]`.
Pour `LowCardinality(Nullable(T))`, le dict est toujours encodé comme un T simple (sans flux null-map), mais **deux** emplacements sont réservés : `dict[0]` est le marqueur NULL et `dict[1]` est la valeur par défaut du type interne (par exemple `""` pour `String`) ; les véritables valeurs distinctes commencent à `dict[2]`. La clé d’une ligne NULL pointe vers `dict[0]`, et cet emplacement est écrit dans le flux binaire sous la forme des octets par défaut du type interne.
Les clés sont des index dans le dict ; chaque index occupe `1 << key_type_code` octets (1, 2, 4 ou 8), et la valeur `N` est reconstruite comme `dict[keys[N]]`.
`keys_count` est le nombre de valeurs `LowCardinality` au **niveau récursif courant**, et pas nécessairement le nombre de lignes du bloc. Pour une colonne `LowCardinality` de niveau supérieur, les deux coïncident. Mais lorsque `LowCardinality` se trouve dans un type composite, le compte correspond au nombre de valeurs aplaties transmis par le type composite : pour `Array(LowCardinality(String))` avec trois lignes contenant cinq éléments au total, `keys_count` vaut `5`, pas `3` ; pour `Map(K, LowCardinality(V))`, c’est le nombre total de paires, et ainsi de suite. Un décodeur doit prendre `keys_count` dans ce champ au lieu de supposer qu’il s’agit du nombre de lignes du bloc. Lorsque ce compte aplati est nul — par exemple, pour un bloc dont les tableaux sont tous vides — la phase de données `LowCardinality` n’écrit **rien du tout** : seul le préfixe d’état (émis dans la [phase de préfixe des types composites](#composite-types)) est présent, sans métadonnées, dictionnaire ni `keys_count` à la suite.
Le préfixe d’état est lu au début de chaque bloc dont le nombre de lignes est supérieur à zéro — les blocs d’en-tête (rows = 0) et les blocs vides n’émettent rien. Dans un bloc, `keys_count` est égal au nombre de lignes, `dict_size` est égal au nombre de valeurs dans le flux du dictionnaire, et chaque clé tient dans `1 << key_type_code` octets.
Dans le format `Native`, chaque bloc transporte un **dictionnaire autonome, local au bloc** — il n’existe aucun état de dictionnaire entre les blocs. Le writer Native définit `low_cardinality_max_dictionary_size = 0`, donc `SerializationLowCardinality` ne construit jamais de dictionnaire partagé : chaque bloc non vide écrit ses clés comme des additional keys locales au bloc avec `NeedGlobalDictionaryBit` non défini (metadata `0x600`), et le reader Native rejette `NeedGlobalDictionaryBit` lorsque `native_format` vaut true. Un décodeur doit donc réinitialiser le dictionnaire à chaque bloc et lire les entrées `dict_size` présentes dans ce bloc ; conserver un dictionnaire du bloc précédent entraînerait une mauvaise lecture des clés du bloc suivant. (La persistance d’un dictionnaire LC entre les blocs relève du stockage sur disque de MergeTree, et non du wire layout Native.)
`LowCardinality(String)` avec les valeurs `['a', 'b', 'a', 'c', 'b']` :
```text theme={null}
01 00 00 00 00 00 00 00 state prefix Int64 = 1
00 06 00 00 00 00 00 00 metadata UInt64 = 0x600
04 00 00 00 00 00 00 00 dict_size = 4
00 dict[0] = "" (placeholder)
01 'a' dict[1] = "a"
01 'b' dict[2] = "b"
01 'c' dict[3] = "c"
05 00 00 00 00 00 00 00 keys_count = 5
01 02 01 03 02 keys (UInt8): 1, 2, 1, 3, 2
```
Reconstitué : `dict[1], dict[2], dict[1], dict[3], dict[2]` = `["a", "b", "a", "c", "b"]`.
`LowCardinality(Nullable(String))` avec les valeurs `['a', NULL, '', 'b']` montre les deux emplacements réservés — `dict[0]` pour NULL et `dict[1]` pour la chaîne vide par défaut :
```text theme={null}
01 00 00 00 00 00 00 00 state prefix Int64 = 1
00 06 00 00 00 00 00 00 metadata UInt64 = 0x600
04 00 00 00 00 00 00 00 dict_size = 4
00 dict[0] = "" → NULL marker
00 dict[1] = "" → inner default value
01 'a' dict[2] = "a"
01 'b' dict[3] = "b"
04 00 00 00 00 00 00 00 keys_count = 4
02 00 01 03 keys (UInt8): 2, 0, 1, 3
```
Reconstitué : `dict[2]` = `"a"`, `dict[0]` = `NULL`, `dict[1]` = `""`, `dict[3]` = `"b"`, c.-à-d. `["a", NULL, "", "b"]`. `dict[0]` et `dict[1]` correspondent tous deux à des octets vides dans la représentation binaire transmise ; le fait d’être `NULL` vient de la clé qui pointe vers l’emplacement `0`, et non des octets eux-mêmes.
#### JSON (Tier 1 : String fallback)
Le type `JSON` de ClickHouse possède plusieurs encodages binaires (voir [la référence sur la version de sérialisation](#serialization-version-reference)). Le Tier 1 est le plus simple : lorsque le paramètre par requête `output_format_native_write_json_as_string = 1` est défini, le serveur convertit chaque valeur JSON en son texte sérialisé et émet la colonne sous forme de `String` avec un marqueur de préfixe d’état.
Chaîne de type : `JSON`.
```text theme={null}
[8 bytes: Int64 LE state prefix = 1] ← JSONStringSerializationVersion
[per block with rows > 0]:
[N bytes: String column encoding for num_rows JSON text values]
```
La valeur du préfixe d’état est `1` pour ce String fallback. Les autres valeurs indiquent différents encodages `JSON`/`Object` : `0` = V1, `2` = V2 (la valeur par défaut sur le protocole TCP natif), `3` = FLATTENED, `4` = V3 (voir [la référence sur la version de sérialisation](#serialization-version-reference)). Un décodeur qui rencontre ici une valeur autre que `1` n’est pas en train de lire le String fallback. Le préfixe est lu au début de chaque bloc avec lignes > 0, et le flux de valeurs est une colonne [String](#string-type) standard de `num_rows` lignes.
Valeur `JSON` `'{"a":1}'` (une ligne) :
```text theme={null}
01 00 00 00 00 00 00 00 state prefix Int64 = 1
07 7B 22 61 22 3A 31 7D String: 7 bytes {"a":1}
```
La valeur est émise sous la forme de son texte JSON compact — `{"a":1}`, l’entier étant conservé comme entier. Le texte n’est qu’une valeur `String`, donc le client reçoit le JSON comme un contenu opaque en transit, mais ne retrouve pas les chemins individuels ni leurs types ClickHouse ; pour conserver un typage fidèle par chemin, l’encodage de niveau 2 ci-dessous est nécessaire.
#### Variant(T1, T2, ...)
Une union discriminée : chaque ligne contient une valeur d’un seul des types de variante, ou NULL. Chaque ligne porte un **discriminateur global** d’un octet qui sélectionne son type, puis les valeurs de chaque type sont stockées de manière dense, en une séquence contiguë par type de variante.
Chaîne de type : `Variant(T1, T2, ...)`. Le serveur met l’ordre sous forme canonique (les types de variante sont triés par nom), de sorte que la chaîne de type reçue énumère déjà les types dans l’**ordre des discriminateurs globaux** : le discriminateur `0` sélectionne le premier type indiqué, `1` le deuxième, et ainsi de suite. `255` (`NULL_DISCRIMINATOR`) signifie que la ligne vaut NULL. Les éléments Variant ne sont jamais `Nullable` — NULL est géré par le discriminateur. Exemples : `Variant(String, UInt64)`, `Variant(Array(UInt8), String)`.
Le préfixe d’état contient un mode de discriminateurs `UInt64 LE` : `0` = BASIC (le discriminateur de chaque ligne est écrit littéralement), `1` = COMPACT (encodage des granules par longueur de séquence). Le serveur utilise BASIC sur le protocole natif par défaut (`use_compact_variant_discriminators_serialization = false`) ; seul BASIC est spécifié ici.
```text theme={null}
[per block with rows > 0]:
[8 bytes: UInt64 LE discriminators mode = 0] ← state prefix, repeated at the start of every non-empty block;
followed by each variant element's own state prefix
(empty for leaf types)
[num_rows bytes: UInt8 discriminators] ← one global discriminator per row; 255 = NULL
[for each variant type i, in declared order]:
[values for the rows whose discriminator == i] ← dense encoding in type i; count = #rows selecting i
```
Pour reconstruire, parcourez les discriminateurs de gauche à droite en maintenant un compteur courant pour chaque type. La ligne `r` avec le discriminateur `d` (≠ 255) prend la valeur à l’index `counter[d]` dans la séquence de valeurs du type de variante `d`, puis `counter[d]` est incrémenté. Les lignes dont le discriminateur vaut `255` sont `NULL` et ne consomment aucune valeur d’aucune séquence, de sorte que la somme des compteurs par type est égale au nombre de lignes non-`NULL`.
Le préfixe d’état (le mode `UInt64`) est lu au début de chaque bloc contenant des lignes > 0 ; l’en-tête et les blocs vides n’émettent rien. Chaque discriminateur non-`NULL` est inférieur au nombre de types de variante, et le type de variante `i` est décodé pour exactement `count[i]` lignes.
Les éléments de `Variant` qui conservent eux-mêmes un état (`LowCardinality`, `Variant`, `Dynamic`, `JSON`) émettent leur propre préfixe d’état dans la phase de préfixe d’état par élément, après le mode `UInt64`. Les types feuilles et les composites simples (`Array`, `Tuple`, `Map` de types feuilles) ont des préfixes d’état vides et se composent librement.
`Variant(String, UInt64)` avec les valeurs `[42, 'hi', NULL]` (l’ordre canonique place `String` avant `UInt64`, donc discriminateur 0 = String, 1 = UInt64) :
```text theme={null}
00 00 00 00 00 00 00 00 state prefix: UInt64 discriminators mode = 0 (BASIC)
01 00 FF discriminators (3 rows): 1 (UInt64), 0 (String), 255 (NULL)
02 68 69 String run (1 value): len=2 "hi"
2A 00 00 00 00 00 00 00 UInt64 run (1 value): 42
```
Reconstruction : ligne 0 = UInt64 run\[0] = `42`; ligne 1 = String run\[0] = `"hi"`; ligne 2 = NULL.
Le flux de discriminateurs constitue l’index ; chaque discriminateur non-NULL prend la valeur suivante dans la séquence dense de son type, tandis que `255` (NULL) ne consomme rien. Ce même parcours reconstruit [Dynamic](#dynamic), qui ne diffère que par la façon dont NULL est encodé :
```mermaid theme={null}
flowchart LR
subgraph D["discriminators (one per row)"]
direction TB
d0["row 0 → 1"]
d1["row 1 → 0"]
d2["row 2 → 255"]
end
subgraph SR["String run (discriminator 0)"]
s0["[0] = hi"]
end
subgraph UR["UInt64 run (discriminator 1)"]
u0["[0] = 42"]
end
d0 -->|"counter[1] = 0"| u0
d1 -->|"counter[0] = 0"| s0
d2 -.->|"255 = NULL,
no value consumed"| X["(skip)"]
```
#### Dynamic
Colonne dont le type de valeur est déterminé à l’exécution : chaque ligne contient une valeur d’un ensemble de types déterminé à l’exécution, ou `NULL`. Contrairement à `Variant`, l’ensemble des types **n’apparaît pas** dans la type string de la colonne — il est porté par le state prefix.
Type string : `Dynamic` ou `Dynamic(max_types=N)`. Le paramètre `max_types` limite le nombre de types distincts suivis par la colonne, mais n’affecte pas le wire format ci-dessous.
`Dynamic` a quatre encodages : `V1 = 1`, `V2 = 2`, `FLATTENED = 3`, `V3 = 4`. Celui émis par le server dépend du canal et des query settings :
* Avec `clickhouse-client` et HTTP `FORMAT Native`, la revision du writer est `0` (sauf si elle est augmentée avec `client_protocol_version`), donc l’encodage par défaut est **V1**.
* Avec le native TCP protocol à la revision négociée, l’encodage par défaut est **V2**. Le writer `Native` laisse les statistics désactivées ; une payload `V2` par défaut ne contient donc aucune statistique par variante — après la liste des types viennent directement le préfixe `Variant` imbriqué et les données. (Les statistiques par variante relèvent du stockage sur disk de MergeTree, et ne font pas partie du Native wire.)
* Le query setting `output_format_native_use_flattened_dynamic_and_json_serialization = 1` remplace ces deux comportements et émet **FLATTENED (version 3)** quelle que soit la revision.
**Portée**
Cette page spécifie uniquement le layout **`FLATTENED`**. Les layouts binaires non aplatis `V1`/`V2`/`V3` correspondent à la représentation interne/sur disque (listes de types encodées en binaire, statistiques par variante) et **ne** sont **pas** spécifiés ici. Un client qui veut décoder `Dynamic` à l’aide de cette page doit demander `FLATTENED` en définissant `output_format_native_use_flattened_dynamic_and_json_serialization = 1` ; le layout ci-dessous suppose ce réglage. Comme l’octet de version se trouve en tête du préfixe, un decoder peut détecter l’encodage réellement reçu et rejeter `V1`/`V2`/`V3` s’il n’implémente que `FLATTENED`.
Le layout **FLATTENED (version 3)** sélectionné par ce réglage :
```text theme={null}
[per block with rows > 0]:
[8 bytes: UInt64 LE version = 3] ← state prefix, repeated at the start of every non-empty block
[VarUInt num_types] ← number of runtime types
[num_types × type] ← type names, in wire order; each a String, or a binary
type encoding when output_format_native_encode_types_in_binary_format = 1
[per type: its own state prefix] ← empty for leaf types; + indexes-type prefix (empty, integer)
[num_rows × discriminator] ← width by num_types (UInt8 if ≤ 255, else UInt16/32/64);
NULL discriminator = num_types (one past the last type)
[for each type i, in wire order]:
[values for the rows whose discriminator == i] ← dense encoding in type i
```
La largeur du discriminant correspond au plus petit entier non signé pouvant indexer `num_types` types plus l’emplacement NULL — `UInt8` pour `num_types ≤ 255`, puis `UInt16`, `UInt32`, `UInt64`. NULL est la valeur de discriminant `num_types` elle-même, ce qui diffère de `Variant`, où NULL est la valeur fixe `255`. La reconstruction suit le même parcours dense que `Variant` : conservez un compteur par type, et la ligne `r` dont le discriminant est `d` (≠ `num_types`) prend la valeur `counter[d]` dans la série du type `d`.
Le préfixe d’état (version + liste des types) est lu au début de chaque bloc contenant des lignes > 0 ; l’en-tête et les blocs vides n’émettent rien.
Les types d’exécution dont la sérialisation conserve un état (`LowCardinality`, `Variant`, `Dynamic`, `JSON`) comportent des préfixes d’état imbriqués après la liste des noms de types.
La liste des types au runtime suit normalement la canonicalisation de `Variant` — les slots de variant ordinaires sont écrits dans l’ordre `DataTypeVariant` (nom de type), de sorte que l’ordre de transmission ne suit pas l’ordre d’insertion. Elle n’est cependant **pas toujours** triée globalement : les types qui ont débordé dans le variant partagé (par exemple avec `Dynamic(max_types=N)`) sont ajoutés après les slots ordinaires dans l’ordre de première apparition, de sorte que la fin de la liste peut ne plus respecter l’ordre des noms de type. Un décodeur doit donc traiter la liste de types transmise comme faisant autorité pour l’attribution du discriminateur et ne doit pas la retrier lui-même. Pour les lignes `[42::UInt64, "hi", NULL]`, les deux types sont `String` et `UInt64`, et `"String"` se trie avant `"UInt64"` ; les discriminateurs sont donc `0` = String, `1` = UInt64, `2` = NULL :
```text theme={null}
03 00 00 00 00 00 00 00 state prefix: UInt64 version = 3 (FLATTENED)
02 VarUInt num_types = 2
06 53 74 72 69 6E 67 type[0] = "String"
06 55 49 6E 74 36 34 type[1] = "UInt64"
01 00 02 discriminators (3 rows): 1 (UInt64), 0 (String), 2 (NULL)
02 68 69 String run (type[0], 1 value): len=2 "hi"
2A 00 00 00 00 00 00 00 UInt64 run (type[1], 1 value): 42
```
Reconstitué : ligne 0 = UInt64 run\[0] = `42`; ligne 1 = String run\[0] = `"hi"`; ligne 2 = NULL. Les séquences par type suivent le même ordre de transmission que la liste des types (`String` avant `UInt64`).
#### JSON (Tier 2 : Object FLATTENED)
L’encodage JSON le plus riche : au lieu de ramener chaque valeur à du texte (Tier 1), la colonne est scindée en une sous-colonne par chemin JSON. Ce mode est sélectionné si l’on **ne** demande **pas** le mécanisme de repli Tier 1 (`output_format_native_write_json_as_string = 0`) tout en activant l’indicateur de sérialisation aplatie (`output_format_native_use_flattened_dynamic_and_json_serialization = 1`) ; le server émet alors la **version 3** de sérialisation.
Il existe deux types de chemins :
* Les **chemins typés** sont déclarés dans la chaîne de type, par exemple `JSON(a UInt32, b String)`, et décodés selon leur type déclaré. Un nom de chemin contenant des points est placé entre accents graves dans la chaîne de type.
* Les **chemins dynamiques** sont découverts à l’exécution et chacun est décodé comme une colonne [Dynamic](#dynamic).
En mode FLATTENED, il n’y a **pas de colonne de données partagées** (cette zone de débordement appartient aux encodages Object non plats V2/V3). Chaque chemin est une colonne complète de `num_rows` valeurs.
```text theme={null}
[per block with rows > 0]:
-- prefix phase (repeated at the start of every non-empty block):
[8 bytes: UInt64 LE version = 3] ← state prefix
[VarUInt num_dynamic_paths]
[num_dynamic_paths × String] ← dynamic path names, in wire order
[per typed path: its column's state prefix] ← empty for leaf types
[per dynamic path: a Dynamic state prefix] ← version + type list (see Dynamic)
-- data phase:
[for each typed path: its column's data] ← num_rows values in the declared type
[for each dynamic path: its Dynamic data] ← num_rows values (discriminators + runs)
```
Notez la structure en deux phases : **tous** les préfixes d’état des chemins apparaissent d’abord, puis **toutes** les données des chemins. Le préfixe `Dynamic` d’un chemin dynamique (dans la phase de préfixe) est donc séparé de ses données (dans la phase de données). Le préfixe d’état est lu au début de chaque bloc avec un nombre de lignes > 0, et chaque colonne de chemin (typée ou dynamique) contient exactement `num_rows` valeurs. L’objet de la ligne `r` est reconstitué en lisant la valeur de chaque chemin à l’index `r` ; un chemin dynamique dont le discriminateur `Dynamic` vaut NULL pour cette ligne n’apporte aucune clé.
Valeur `JSON` `{"a": 42, "b": "hi"}` (une ligne, les deux chemins étant dynamiques). Un entier JSON est inféré comme `Int64` :
```text theme={null}
03 00 00 00 00 00 00 00 version = 3 (Object)
02 num_dynamic_paths = 2
01 61 path "a"
01 62 path "b"
03 00 00 00 00 00 00 00 01 05 49 6E 74 36 34 "a" Dynamic prefix: version 3, 1 type, "Int64"
03 00 00 00 00 00 00 00 01 06 53 74 72 69 6E 67 "b" Dynamic prefix: version 3, 1 type, "String"
00 2A 00 00 00 00 00 00 00 "a" data: discriminator 0, Int64 42
00 02 68 69 "b" data: discriminator 0, String "hi"
```
#### JSON non aplati (V2/V3)
Les encodages `Object` non aplatis (`V1`/`V2`/`V3`) sont utilisés par le stockage sur disque de MergeTree et correspondent à ce que le serveur émet sur le wire lorsque l’indicateur flattened est désactivé — `V1` via `clickhouse-client` / HTTP `FORMAT Native` (revision `0`), `V2` via le native TCP protocol. Ils incluent une colonne de données partagées et ne sont **pas** spécifiés sur cette page. Notez qu’ils n’incluent **pas** de statistiques par chemin sur le wire Native : `NativeWriter` laisse les statistiques désactivées, de sorte que le préfixe de structure `Object` ne contient pas de section de statistiques, et les octets qui suivent sont directement les préfixes typed/dynamic/données partagées et les données. Les statistiques n’apparaissent que sur les chemins sur disque de MergeTree où elles sont activées. Pour décoder une colonne `JSON` à l’aide de cette page, un client doit sélectionner l’un des tiers documentés : définissez `output_format_native_write_json_as_string = 1` pour le [String fallback](#json-tier-1-string-fallback), ou `output_format_native_use_flattened_dynamic_and_json_serialization = 1` (avec `output_format_native_write_json_as_string = 0`) pour la disposition [FLATTENED Object](#json-tier-2-flattened-object).
## Trame de compression
ClickHouse peut compresser les données de colonnes d’un flux `Native` à l’aide d’un format de trame interne. La [structure de la trame](#frame-format) ci-dessous est **indépendante du transport** — les mêmes trames apparaissent aussi bien avec le protocole TCP natif que sur HTTP — mais la façon dont la compression est demandée, ainsi que ce qui entoure les trames, diffère selon le transport.
* **Protocole TCP natif.** La compression s’active explicitement pour chaque requête via le flag `compression` dans le [Query packet](/fr/reference/interfaces/specs/NativeProtocol#query). Lorsqu’elle est active, le body de chaque paquet `Data`, `Totals`, `Extremes`, `Log` et `ProfileEvents` — les octets après la chaîne `table_name` — est encapsulé dans le format de trame. L’enveloppe du paquet elle-même, le code de type du paquet et la chaîne `table_name` ne sont **pas** compressés ; le server les écrit dans le flux brut. Tout ce que `NativeWriter` émet entre dans le flux compressé ; le préfixe `BlockInfo` est donc le premier élément à l’intérieur de la trame, avec les dimensions et les colonnes. Un client doit donc décompresser la trame avant de pouvoir lire `BlockInfo`.
* **HTTP.** `SELECT ... FORMAT Native&compress=1` encapsule l’intégralité du flux d’octets `FORMAT Native` dans les mêmes trames (le server utilise le même `CompressedWriteBuffer` interne), et `?decompress=1` attend les mêmes trames dans un body d’entrée `Native`, qu’il décode via le `CompressedReadBuffer` correspondant. Sur ce chemin, il n’y a ni type de paquet TCP, ni `table_name`, ni enveloppe de paquet : toute la payload compressée n’est constituée que de blocks `Native` encapsulés (un préfixe `BlockInfo` n’est présent que si la revision négociée est supérieure à `0`, exactement comme dans la structure non compressée ci-dessus). Cette encapsulation interne `compress`/`decompress` se distingue de la compression du transport HTTP (`Content-Encoding: gzip`/`zstd`, activée par `enable_http_compression`), qui encapsule la réponse au niveau HTTP et ne correspond pas au format de trame ci-dessous.
Ainsi, un client qui n’implémente que la structure non compressée `FORMAT Native` doit quand même ajouter cette couche de trame pour lire une réponse HTTP `Native` compressée ou pour envoyer un body de requête `decompress=1`.
### Format de la trame
```text theme={null}
[16 bytes: CityHash128 checksum over the 9-byte header + compressed body]
[1 byte: method] ← 0x82 = LZ4, 0x90 = ZSTD, 0x02 = NONE
[4 bytes: compressed_size LE u32] ← INCLUDES the 9-byte header, EXCLUDES the 16-byte checksum
[4 bytes: uncompressed_size LE u32]
[N bytes: compressed body] ← N = compressed_size - 9
```
La taille totale de la trame est `16 + compressed_size` = `16 + 9 + body_size` = `25 + body_size`. Notez bien la distinction suivante : la somme de contrôle couvre l’en-tête de 9 octets ainsi que le corps, tandis que `compressed_size` inclut l’en-tête et le corps, mais **pas** la somme de contrôle elle-même :
```mermaid theme={null}
flowchart LR
CK["checksum
16 B
CityHash128"]
subgraph SPAN["counted by compressed_size (9 + N)"]
direction LR
M["method
1 B"]
CS["compressed_size
4 B LE"]
US["uncompressed_size
4 B LE"]
BODY["compressed body
N = compressed_size − 9 B"]
M --> CS --> US --> BODY
end
CK --> M
```
### Valeurs d’octet de méthode
| Octet | Méthode | Encodage du corps |
| ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `0x02` | NONE | Le corps contient les octets bruts (sans compression). La trame est quand même émise ; le receiver vérifie la somme de contrôle. |
| `0x82` | LZ4 | Le corps utilise le **format de bloc LZ4** — *et non* le format de trame LZ4. Aucun nombre magique. |
| `0x90` | ZSTD | Le corps est un flux zstd brut à une seule trame (le nombre magique zstd standard fait partie du corps). |
### Somme de contrôle
ClickHouse utilise CityHash v1.0.2 (la variante historique), **et non** la version moderne de Google CityHash ; les deux produisent des résultats différents.
La somme de contrôle est calculée sur les 9 octets d’en-tête (method + compressed\_size + uncompressed\_size) plus les N octets du corps — c’est-à-dire tout ce qui se trouve entre la somme de contrôle et la fin de la trame. Dans la sortie de 16 octets de CityHash128, les 8 premiers octets correspondent à la moitié basse (LE) et les 8 suivants à la moitié haute (LE). Un décodeur recalcule CityHash128 sur l’en-tête et le corps reçus, puis compare le résultat aux 16 octets de tête ; en cas de non-correspondance, les données sont corrompues et le décodeur échoue.
### Limites par bloc
La charge utile compressée d’un Block est un **flux d’une ou plusieurs trames**, et pas nécessairement d’une seule trame. L’émetteur écrit le bloc sérialisé via un `CompressedWriteBuffer`, qui émet une trame chaque fois que son tampon interne se remplit (≈ 1 MB, `DBMS_DEFAULT_BUFFER_SIZE`), puis une trame finale lorsque le bloc est vidé. Ainsi, un petit bloc tient dans une seule trame ; un grand bloc s’étend sur plusieurs trames consécutives.
L’invariant ne vaut que dans un seul sens : puisque l’émetteur vide le tampon compressé à la fin de chaque bloc, **chaque fin de bloc coïncide avec une limite de trame** — mais l’inverse n’est pas vrai. Une limite de trame intermédiaire, émise lorsque le tampon s’est rempli au milieu d’un bloc, tombe au *milieu* d’un bloc et ne constitue pas une limite de bloc. Un décodeur doit donc utiliser les dimensions propres au bloc (`num_columns`/`num_rows`) pour déterminer où se termine un bloc ; il ne doit pas supposer que chaque trame correspond à un bloc complet.
Un récepteur lit les trames en flux : lire 16 + 9 octets, lire exactement `compressed_size - 9` octets de corps, décompresser en exactement `uncompressed_size` octets, puis fournir ces octets au décodeur de bloc ; lorsque le décodeur a besoin de plus de données que n’en contient la trame courante, il récupère la trame suivante. Comme l’émetteur vide le tampon pour chaque bloc, une fois un bloc entièrement décodé, le tampon de trame est vide et le bloc suivant commence sur une nouvelle trame.
Sur le protocole TCP natif, l’enveloppe de paquet — le VarUInt du type de paquet et la chaîne `table_name` — est écrite dans le flux **brut**, hors de la charge utile compressée ; seul le corps du bloc (BlockInfo + colonnes) est découpé en trames. Le chemin HTTP `compress`/`decompress` n’a pas une telle enveloppe : l’ensemble du flux est constitué de blocs découpés en trames.
### Négociation
Avec le protocole TCP natif, la compression s’applique par requête, et non par connexion. Le champ `compression: bool` du paquet Query l’active pour cette requête uniquement. Le serveur respecte cette demande et émet des corps `Data`/`Totals`/`Extremes`/`Log`/`ProfileEvents` compressés pendant toute la durée de vie de la requête (`Log`/`ProfileEvents` uniquement à partir de v54481+). Il attend également que les blocs de Data *envoyés* par le client — tables externes, marqueur vide de fin de données et lignes INSERT — soient encapsulés de la même façon. Les requêtes suivantes sur la même connexion peuvent utiliser un réglage différent.
En HTTP, il n’y a pas de paquet Query : le paramètre de requête `compress=1` sélectionne une sortie encapsulée pour cette requête, et `decompress=1` indique que le corps de la requête est encapsulé. La sortie `compress=1` est écrite avec le codec par défaut du serveur (`LZ4`) plutôt qu’avec `network_compression_method` ; le lecteur `decompress=1` détermine le codec à partir de l’octet de méthode de chaque trame, de sorte que n’importe quel codec est accepté en entrée.
Lorsque la compression est activée, le serveur peut également faire passer les colonnes par le chemin parallèle de sérialisation des blocs / `ColumnBLOB` (`PARALLEL_BLOCK_MARSHALLING`, v54478) pour les blocs de plus d’une ligne. Une implémentation qui compresse les données INSERT doit être capable de gérer ce chemin (ou de le désactiver explicitement) afin d’éviter une désynchronisation du flux.
## Glossaire
**Bloc** — l’unité d’échange de données du format Native. Un bloc auto-descriptif de lignes stockées en format colonnaire. Voir [structure des blocks et des colonnes](#block-and-column-structure).
**BlockInfo** — l’en-tête de métadonnées qui précède un Bloc sur le chemin des paquets TCP Data (écrit chaque fois que la révision de la connexion est supérieure à zéro). Une séquence de champs, conditionnés par la révision et balisés par un ID de champ. Omis par le format de sortie `Native`, qui sérialise à la révision `0`. Voir [BlockInfo](#blockinfo).
**Corps de colonne** — les octets d’une Column qui contiennent les valeurs proprement dites, après l’en-tête de colonne (nom, type, octet has\_custom\_serialization). L’agencement dépend du type. Voir [organisation on-wire des colonnes](#column-wire-layout).
**Type composite** — un type construit à partir d’un ou de plusieurs types internes, encodé sous forme de plusieurs flux par colonne. Le wire format est stable et non versionné. Voir [types composites](#composite-types).
**Dictionnaire (LowCardinality)** — le tableau de valeurs uniques auquel une colonne `LowCardinality(T)` fait référence via des indices entiers. Voir [LowCardinality](#lowcardinality).
**Bloc vide** — un Bloc avec `num_columns = 0` et `num_rows = 0`. Utilisé comme sentinelle : un marqueur client-side de fin d’entrée et un marqueur server-side de limite de flux. Voir [variantes de bloc](#block-variants).
**Bloc d’en-tête** — un Bloc avec `num_columns > 0` et `num_rows = 0`, envoyé par le server comme premier paquet Data d’une réponse à une query. Il annonce le schéma du résultat. Voir [variantes de bloc](#block-variants).
**Type interne** — le type qu’un type composite encapsule. `Array(UInt32)` a pour type interne `UInt32` ; le type interne de `Nullable(T)` est `T`.
**Flux d’offsets** — le tableau UInt64 des positions de fin cumulées que `Array`, `Map` et `Nested` utilisent pour délimiter les frontières des éléments ligne par ligne. Voir [Array](#array).
**Valeur d’espace réservé** — les octets écrits aux positions nulles dans le flux de valeurs d’une colonne `Nullable(T)`. Le décodeur les lit pour faire avancer le flux, mais ignore leur contenu. Voir [Nullable](#nullable).
**Bloc de résultat** — un Bloc avec `num_rows > 0` contenant les lignes réelles du résultat de la requête. Voir [variantes de bloc](#block-variants).
**Bloc de schéma** — synonyme de bloc d’en-tête, utilisé lors de la description de la phase INSERT, où le bloc de schéma indique au client les structures de colonnes attendues.
**Version de sérialisation** — un numéro de version on-wire par type, que les types versionnés utilisent pour déclarer quelle variante de l’encodage suit. À distinguer de la version du protocole. Voir [version de sérialisation : concept](#serialization-version-concept).
**Préfixe d’état** — les octets qui précèdent la payload par bloc d’un type versionné. Transporte la version de sérialisation et (pour LowCardinality) les métadonnées du dictionnaire par bloc. Émis au début de chaque bloc avec rows > 0 ; non conservé d’un bloc à l’autre.
**Stream** — une séquence contiguë d’octets dans le corps d’une colonne, encodant un sous-composant logique (une null-map, un tableau d’offsets, un flux de valeurs). Les types à plusieurs flux concatènent deux flux ou plus par colonne.