` — `IntervalSecond`, `IntervalMinute`, `IntervalHour`, `IntervalDay`, `IntervalWeek`, `IntervalMonth`, `IntervalQuarter`, `IntervalYear`, `IntervalNanosecond` など。すべての単位で wire エンコーディングは共通で、値は符号付き 8 バイトのリトルエンディアン Int64 として表現されます。単位は型文字列に**のみ**含まれ、wire バイト列にも、単なる整数で表されるテキスト形式にも影響しません。すべての単位は 1 つのデコーダーパスで処理できます。
`IntervalDay` の値 `5`:
```text theme={null}
05 00 00 00 00 00 00 00 Int64 LE = 5
```
#### UUID
値ごとに16バイトです。wire形式のエンコーディングは、標準的な16バイトのビッグエンディアン表現**ではありません**。8バイトごとの各半分について、それぞれ独立にバイト順が反転されます。
論理モデルは、標準的なテキスト形式 `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` で表される128ビットの識別子で、バイトは慣例的にビッグエンディアンで記述されます。wireモデルでは、この標準的な16バイトを2つの8バイト単位に分割し、それぞれをリトルエンディアンで書き込みます。
* wireバイト 0..7 = 標準バイト 0..7 を逆順にしたもの。
* wireバイト 8..15 = 標準バイト 8..15 を逆順にしたもの。
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
```
nil UUID (すべて 0) は、どちらの表現でも同じです。
#### IPv4 と IPv6
相互に関連していますが、エンコード方式が異なる 2 つのアドレス型です。
`IPv4` は 4 バイトで、正規の 32 ビットアドレス (`a.b.c.d` から得られる値 `(a << 24) | (b << 16) | (c << 8) | d`) を保持するリトルエンディアンの UInt32 としてエンコードされます。wire 上のバイト列は、ネットワークバイトオーダーのバイト列を逆順にしたものです。
`192.168.1.10` (正規の 32 ビット値 `0xC0A8010A`) :
```text theme={null}
0A 01 A8 C0 Little-endian UInt32
```
`IPv6` は 16 バイトで、**ネットワークバイトオーダーでそのまま**、スワップせずに書き込まれます。バイト順は `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
```
この非対称性は意図的なものです。IPv4 は算術演算や効率的な範囲クエリのために `u32` として格納される一方、IPv6 は大半のネットワーキング API で一般的なネットワークバイトオーダーのレイアウトを維持します。
#### Enum8 と Enum16
それぞれ `Int8` および `Int16` とワイヤ形式で互換性があります。1 行あたり 1 バイトまたは 2 バイトで、16 ビットのバリアントは 2 の補数のリトルエンディアンです。各バリアントの完全な対応関係は型文字列に含まれます:
```text theme={null}
Enum8('active' = 1, 'inactive' = 2, 'banned' = -1)
Enum16('a' = 1, 'b' = 30000)
```
デコーダーは `(...)` のパラメータ接尾辞を取り除き、`Int8` / `Int16` として処理することがあります。wire上のバイト列は単なる整数インデックスです。ラベルを扱うクライアントは、型文字列から `'name' = value` の map を解析して取り出し、カラムと一緒に保持します。整数だけではラベルを復元できません。テキスト指向の出力では、インデックスではなくラベル (`active`) が表示され、enum が複合型の中にネストされている場合はシングルクォート付き (`'active'`) で表示されます。map は整数カラムからは復元できないため、`Array(Enum8(...))` や `Map(Enum16(...), V)` のようなネストされた enum では保持しておく必要があります。
`Enum8('active' = 1, 'inactive' = 2)` のカラム `[active, inactive, active]`:
```text theme={null}
01 02 01
```
`Enum16(...)` の値 `30000`:
```text theme={null}
30 75 Int16 LE = 30000
```
#### Decimal(P, S)
10 のべき乗でスケーリングされた符号付き整数です。整数のバイト幅は **精度** `P` によって暗黙的に決まり、**スケール** `S` は負の **指数** (小数点以下の桁数) です。どちらも型文字列に含まれます。
| 精度 (P) | 基になる整数 | バイト |
| ----------- | ------ | --- |
| 1 ≤ P ≤ 9 | Int32 | 4 |
| 10 ≤ P ≤ 18 | Int64 | 8 |
| 19 ≤ P ≤ 38 | Int128 | 16 |
| 39 ≤ P ≤ 76 | Int256 | 32 |
wire エンコーディングでは、基になる整数がリトルエンディアンの 2 の補数で表現され、論理的な 10 進値は `wire_integer × 10^(-S)` になります。
ClickHouse は、型の宣言方法にかかわらず、常に `Decimal(P, S)` を出力します。`Decimal32(S)`、`Decimal64(S)` なども、wire 上ではすべて `Decimal(P, S)` に正規化されます (`P` には、その幅で自然な最大値である 9、18、38、76 が設定されます) 。`Decimal(P, S)` のみを認識するデコーダーであれば、サーバーが出力するあらゆる表記を扱えます。
`Decimal(9, 4)` の値 `123.4567` → 基になる整数 `1234567`:
```text theme={null}
87 D6 12 00 Int32 LE = 1234567
```
`Decimal(18, 1)` の値 `-1.5` → 内部整数 `-15`:
```text theme={null}
F1 FF FF FF FF FF FF FF Int64 LE = -15
```
`Decimal(38, 4)`の値 `123.4567` (合計16バイト) :
```text theme={null}
87 D6 12 00 00 00 00 00 00 00 00 00 00 00 00 00
```
#### Nothing
`Nothing` 型は値を一切持ちません。実際には、`Nullable(Nothing)` の内部型としてのみ現れます。つまり、取り得る有効な値が「値が存在しないこと」だけである `SELECT NULL` のような式に対して、server が返す型です。概念的にはユニット型に相当します。
wire 上では、これは**1行あたり正確に1バイトのプレースホルダー**を占有します。server は ASCII 文字 `'0'` (`0x30`) を出力しますが、デシリアライザーはそのバイトを無視します。内容は未定義であり、デコーダーは特定の値に依存してはいけません。書き込まれるバイト数は `num_rows × 1` なので、カラムヘッダーの `num_rows` によって読み取るべき量が完全に決まります。
この 1 行 1 バイトという方式により、Block の不変条件は保たれます。すべてのカラムの長さは `num_rows` から導き出せるため、デコーダーは各 cell の長さプレフィックスなしで前方にスキャンできます。外側の `Nullable` は常にすべての位置を NULL として報告するため、プレースホルダーが参照されることはありません。
3 行 (すべて NULL) の `Nullable(Nothing)` カラム:
```text theme={null}
01 01 01 null map: 1, 1, 1 (three NULLs)
30 30 30 Nothing placeholder bytes (one per row)
```
null-map のプレフィックスは標準的な `Nullable` のフレーミングです ([Nullable](#nullable) を参照) 。内側の 3 バイトは `Nothing` のペイロードで、デコーダーはこれを読み飛ばします。
### 可変長型
各値には、ワイヤ形式でそれぞれの長さが含まれます。
#### String
文字列型: `String`。`String` カラムは、長さプレフィックス付きのバイト列が `num_rows` 個並んだものです:
```text theme={null}
[VarUInt: byte_length] [byte_length bytes: raw value]
[VarUInt: byte_length] [byte_length bytes: raw value]
...
```
長さプレフィックス以外に行同士を区切るものはなく、行レベルの状態もありません。空文字列は単一の `0x00` バイトです。ClickHouse の `String` はテキスト指向ではなく、バイト指向です。つまり、UTF-8 の妥当性は保証されず、値には埋め込み NUL を含む任意のバイトを含めることができます。UTF-8文字列型を対象とするデコーダでは、読み取り時に妥当性を検証するか、生のバイト列を呼び出し元に渡します。カラムが消費する総バイト数は、すべての行についての `Σ (varuint_size(len_i) + len_i)` です。
3 つの文字列 `["ab", "", "c"]` からなるカラム (合計 6 バイト) :
```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)
型文字列は `FixedString(N)` で、`N` は正の整数です (例: `FixedString(16)`) 。このカラムは長さプレフィックスや区切りを持たず、サイズは常に `N × num_rows` raw bytes です。デコーダーは型文字列から `N` を解析し、1行あたりそのバイト数を読み取ります。
SQL が `N` バイトより短い値を insert した場合 (例: `CAST('abc' AS FixedString(5))`) 、server は宣言された長さになるまで右側を NUL バイト (`0x00`) で埋めます。これらのパディングバイトは格納される値の一部であり、そのまま wire 上に送信されます。トリミングは client 側で対処します。`String` と同様に、`FixedString(N)` はテキストというよりバイト配列に近く、通常は固定幅の識別子、アドレスバイト、または hash ダイジェストに使用されます。
2 つの `FixedString(3)` の値 `["abc", "de\0"]` (合計 6 バイト) :
```text theme={null}
61 62 63 row 0: 3 bytes, "abc"
64 65 00 row 1: 3 bytes, "de" + NUL padding
```
比較する 2 つの文字列型:
| プロパティ | `String` | `FixedString(N)` |
| ---------------- | ----------------- | ---------------------- |
| 1 行あたりの長さプレフィックス | あり (`VarUInt`) | なし |
| 行サイズ | 可変 | 常に `N` バイト |
| カラムの合計バイト数 | 可変 | `N × num_rows` |
| NUL バイトのパディング | 該当なし | server により右側が埋められる |
| UTF-8 を想定 | 通常は想定される (強制ではない) | なし (raw bytes として扱われる) |
| 型パラメータ | None | 整数 `N` が必須 |
### 複合型
複合型は1つ以上の内部型を包み、共通の wire モデル、つまり **1つのカラムにつき複数のストリーム** を共有します。1つの論理カラムは、独立して読み取られる2つ以上のバイト列としてエンコードされ、それらを連結した形になります。
これらには、共通する3つの構造的な性質があります。
* **スキーマごとに形状が固定される。** 構造はデコード時に型文字列だけで完全に決まります。`Array(UInt32)` は常に同じストリームレイアウトを持ち、block が変わっても変わりません。
* **独自のバージョンプレフィックスを持たない。** 複合ラッパー自体はバージョンバイトを追加せず、そのフレーミング (offsets、null-map、要素ストリーム) は ClickHouse の releases をまたいでも安定しています。これは *wrapper* 自体にのみ当てはまります。内部のバージョン付き型については、以下のプレフィックスフェーズの注記を参照してください。
* **独自の block 間 state を持たない。** ラッパーのフレーミングは block ごとに完全に self-describing です。block 間 state に関する問題は、ラッパーではなく内部のバージョン付き型に起因します。
複合型は再帰的です。内部型自体が複合型であることもあります。
**データストリームの前にあるプレフィックスフェーズ。** カラムの読み取りは、次の順序で2段階に分かれます。まず **state prefix フェーズ**、次に **data-stream 段階** です。複合ラッパー自体は独自のプレフィックスバイトを持ちませんが、自身のデータストリームを書き込む前に、内部のシリアライゼーションにプレフィックスフェーズを *委譲* します。`SerializationArray` は array offsets が書き込まれる前に内部型のプレフィックスフェーズを実行し、`Tuple`、`Map`、`Nested`、`Nullable` も要素のシリアライゼーションを通じて同様に動作します (`Nullable` は null map の前に内部プレフィックスを実行します) 。
そのため、複合型が [versioned/stateful type](#versioned-types) (`LowCardinality`、`Variant`、`Dynamic`、`JSON`) を包む場合、その内部型の version/state prefix が *最初に* 出力され、ラッパーの offsets や要素 ペイロード より前に置かれます。たとえば、`Array(LowCardinality(String))` のレイアウトは `[LowCardinality state prefix]` → `[array offsets]` → `[flattened LowCardinality element payload]` であり、offsets-first にはなりません。
内部プレフィックスフェーズを実行する前に offsets を読み取るデコーダーは、`LowCardinality`、`Variant`、`Dynamic`、または `JSON` を含む複合型では同期がずれます。すべての内部型が通常のリーフ型、または別の非バージョン付き複合型である場合、プレフィックスフェーズはバイトを出力せず、以下の offsets-first の説明がそのまま当てはまります。
#### Nullable(T)
型文字列: `Nullable(InnerType)`。例: `Nullable(UInt32)`、`Nullable(String)`、`Nullable(FixedString(16))`、`Nullable(DateTime('UTC'))`。
他の複合型と同様に、`Nullable` は null マップを書き込む前に、[プレフィックスフェーズ](#composite-types) を内部のシリアライゼーションに委譲します。内部型がバージョン付きの場合は、内部の state prefix が**最初に**出力されます。したがって、`Nullable(Tuple(LowCardinality(String)))` は null マップではなく、`LowCardinality` の state prefix で始まります。内部型がリーフ型またはその他の非バージョン型である場合、プレフィックスフェーズ ではバイトは出力されません。
ワイヤレイアウト は、内部のプレフィックスフェーズ (内部型がバージョン付きでない限り空) に続いて、2 つの stream を連結したものです。先頭は null マップです:
```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
```
null-map は `num_rows` バイトちょうどで、各行に 1 バイトずつ対応します。
| Byte value | Meaning |
| --------------------------- | -------------------------------------------- |
| `0x00` | この行には値があります。 |
| non-zero (canonical `0x01`) | 値は NULL です。values ストリーム内の対応するバイトはプレースホルダーです。 |
values ストリームには、NULL の位置を含む **すべての** `num_rows` 行について、内部型の標準エンコーディングが格納されます。デコーダーはストリームを先に進めるため、NULL の位置にあるプレースホルダーバイトも読み取る必要がありますが、個々の値を解釈する前に null-map を参照しなければなりません。送信側は NULL の位置に任意のバイトを書き込めるため、デコーダーは特定のプレースホルダー値を前提にしてはいけません。
内部型ファミリーごとのプレースホルダー値:
| Inner type family | Placeholder at null position |
| ----------------------------------------------- | ---------------------------- |
| Fixed-width (UInt/Int/Float/DateTime/UUID/etc.) | 型の幅ぶん、ゼロで初期化されたバイト |
| `String` | 空文字列 — `0x00` バイト 1 つ |
| `FixedString(N)` | `N` 個のゼロバイト |
| `Array(T)` | 空の配列 — offsets は 0 だけ進む |
| `Tuple(T1, T2, ...)` | 各要素はそれぞれ自身のプレースホルダーを使う |
`Nullable(T)` は `Array`、`Tuple`、`Map`、`Nested` の中に現れることがあります — `Array(Nullable(T))` や `Tuple(Nullable(T1), T2)` は一般的です。NULL 許容性はそれ自体とは組み合わせられません。`Nullable(Nullable(T))` は server によって拒否されます。
3 行 `[5, NULL, 9]` を持つ `Nullable(UInt8)` (合計 6 バイト) :
```text theme={null}
00 01 00 null-map: present, null, present
05 00 09 values: 5, placeholder, 9
```
3 行からなる `["hello", NULL, "world"]` を持つ `Nullable(String)` (合計 15 バイト) :
```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)
型文字列: `Array(InnerType)`。例: `Array(UInt32)`、`Array(String)`、`Array(Nullable(UInt32))`、`Array(Array(UInt8))`。
ワイヤレイアウトは、内側の[プレフィックス フェーズ](#composite-types) (内側の型がバージョン付きでない限り空) の後に、2 つの連結された stream が続く構成で、最初に offsets が来ます:
```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
```
offsets ストリームは、`num_rows` 個の little-endian UInt64 値で正確に構成され、各値はその行の要素までを書き込んだ時点での values ストリーム内の**累積終端位置**を表します。
* 行 `N` の要素開始索引 = `offsets[N - 1]` (`N == 0` の場合は `0`) 。
* 行 `N` の要素終了索引 (exclusive) = `offsets[N]`。
* 行 `N` の要素数 = `offsets[N] - offsets[N - 1]`。
したがって、`offsets[num_rows - 1]` は全行にわたる要素の総数を表し、values ストリームにはその数だけの内部値が末尾まで連結された形で格納されます。
offsets は**単調非減少**であり、連続する offsets が同じであれば空の行を意味します。また、デコーダーは単調でない offsets を破損データとして拒否する必要があります。空のカラム (`num_rows == 0`) は 0 バイトを書き込みます — offsets ストリームも values ストリームも存在しません。内部型には、他の複合型を含む任意の型を指定できます。`Array(Array(T))`、`Array(Tuple(...))`、`Array(Nullable(T))` はいずれも有効です。
行が `[[10, 20, 30], [], [40, 50]]` の `Array(UInt32)` (合計 44 バイト) :
```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
```
各オフセットは、共有の値ストリーム内で各行に対応するスライスの累積的な*終端位置*を表します。始点は 1 つ前のオフセット (行 0 の場合は `0`) です。連続するオフセットが同じ場合、その行は空です:
```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)` で、行 `[["a", "bb"], []]` の場合 (合計20バイト) :
```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))` で、行が `[[[1,2]], [], [[3], [4,5]]]` の場合、同じ形状が入れ子になっています。
* 外側の offsets: `[1, 1, 3]` — 行 0 には内側の配列が 1 つ、行 1 には 0 個、行 2 には 2 つあります。
* 中間の `Array(UInt32)` は、offsets `[2, 3, 5]` を持つ 3 行にデコードされます。
* 最も内側の `UInt32` は、5 つの値 `[1, 2, 3, 4, 5]` にデコードされます。
合計で、24 (外側のオフセット) + 24 (内側のオフセット) + 20 (値) = 68バイトです。
#### Tuple(T1, T2, ...)
型文字列: `Tuple(T1, T2, ..., Tn)`。例: `Tuple(UInt32, String)`、`Tuple(Int32)`、`Tuple(Array(UInt32), String)`、`Tuple(UInt8, Tuple(Int32, String))`。ClickHouse は `Tuple(a UInt32, b String)` による**名前付きTuple**もサポートしています。名前はメタデータにすぎず、ワイヤ形式には影響しません。
ワイヤ上のワイヤレイアウトは、要素の [プレフィックスフェーズ](#composite-types) (各バージョン付き要素は、その状態プレフィックスを宣言順に持ち、バージョンなし要素では空) に続き、宣言順で要素型ごとに 1 つずつ連結された *N* 個のストリームです:
```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
```
各ストリームは、正確に `num_rows` 個の値をエンコードします。長さのプレフィックスはなく、offsets ストリームもなく、ストリーム間の区切りもありません。空のカラム (`num_rows == 0`) では、各ストリームに 0 バイトが書き込まれます。要素型には、他の複合型を含む任意の型を使用できます — `Tuple(Tuple(...), ...)`、`Tuple(Array(...), ...)`、`Tuple(Nullable(T1), T2)` はいずれも有効です。
要素数 0 のタプル `Tuple()` も有効です — これは `SELECT tuple()` や `CAST(x AS Tuple())` のような式から生成されます。要素ストリームを持たないため、代わりに [Nothing](#nothing) と同様にシリアライズされます。つまり、**各行につき 1 バイトのプレースホルダー (`0x30`、ASCII `'0'`) ** が書き込まれ、デシリアライザーはこれを破棄します。行数は、`Nothing` の場合とまったく同じく、block header から取得されます。
3 行の `(1,4), (2,5), (3,6)` を持つ `Tuple(UInt8, UInt8)`:
```text theme={null}
Element 0 stream (3 × UInt8 = 3 bytes):
01 02 03
Element 1 stream (3 × UInt8 = 3 bytes):
04 05 06
```
レイアウトは**行優先**ではありません。raw bytes を読み戻すと、要素 0 では `[1, 2, 3]`、要素 1 では `[4, 5, 6]` になります。
`Tuple(UInt32, String)`、2行 `(10, "a")`, `(20, "bb")` (合計 13 バイト) :
```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)
型文字列: `Map(KeyType, ValueType)`。例: `Map(String, UInt32)`、`Map(String, Array(UInt32))`、`Map(UInt8, Tuple(Int32, String))`、`Map(Array(String), Int8)`。ワイヤ形式では、どちらの型にも制限はなく、`K` と `V` はどちらも、複合型を含む任意のサポート対象型を使用できます。 (許可されるキー型に関する ClickHouse の SQL レベルの規則はリリースによって異なるため、対象のサーバーバージョンに対応する SQL ドキュメントを参照してください。)
ワイヤレイアウトは `Array(Tuple(K, V))` とバイト単位で同一であるため、最初に内側の [プレフィックスフェーズ](#composite-types) から始まります (`K` または `V` がバージョン付きでない限り空です) :
```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
```
ここで `total_pairs = offsets[num_rows - 1]` (`num_rows == 0` の場合は `0`) です。offsets ストリームは [Array](#array) と同じセマンティクスを持ちます。キーは値と位置ごとに対応しており、ペア `i` は `(keys[i], values[i])` です。
ClickHouse における Map カラムのインメモリ表現はタプルの配列ですが、型システム上では SQL で扱いやすいように独立した型として表されます (`m['key']`、`mapKeys`、`mapValues`) 。ワイヤ形式はこの保存表現をそのままシリアライズしたものなので、`Map` と `Array(Tuple(K, V))` はバイト単位で完全に同一です。
offsets は単調非減少で、キーと値の両方のストリームにはちょうど `total_pairs` 個の値が含まれます。空のカラムは 0 バイトを書き込みます。1 つの行の中では通常キーは一意ですが、これはセマンティクス上の規則であり、ワイヤ形式で強制されるものではありません。ワイヤ形式では重複したキーもそのまま保持して往復でき、サーバー側のセマンティクスで重複が解決されるのは、Map 対応の関数がその行を処理するときだけです。
2 行 `{1:10, 2:20}`、`{3:30}` を持つ `Map(UInt8, UInt8)` (合計 22 バイト) :
```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
```
キーと値は交互に格納されるのではなく、別々のストリームとして保存されます。ペア `i` は `keys[i]` と `values[i]` を一緒に読み出すことで再構築されます。
1 行 `{'a':1, 'b':2}` を持つ `Map(String, UInt32)` (合計 20 バイト) :
```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, ...)
`Nested` の wire 表現は、サーバー側の `flatten_nested` 設定によって決まり、2 つの異なるケースがあります。
```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))"]
```
**ケース A: `flatten_nested = 1` (サーバーのデフォルト) 。** テーブルがデフォルト設定で作成されている場合、`Nested` は**wire type ではありません**。サーバーはこのカラムを、**ドット付きの名前** (`outer.field1`、`outer.field2` など) を持つ N 本の並列な `Array(T_i)` カラムとして保存し、表示します。フォーマット層では新しい点はなく、ドット付きの各カラムは通常の [Array](#array) です:
```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)
```
**ケース B: `flatten_nested = 0`。** テーブルが `flatten_nested = 0` で作成されている場合、このカラムは wire 上では型文字列 `Nested(name1 T1, name2 T2, ...)` を持つ単一のカラムとして表れ、その型文字列に続くレイアウトは **`Array(Tuple(T1, T2, ..., Tn))` とバイト単位で完全に同一** です。これには内側の [プレフィックスフェーズ](#composite-types) も含まれるため、バージョン付きの各フィールド `T_i` は、offsets より前にまずその state プレフィックスを出力します。以下の例ではバージョン付きでないフィールドを使用しているため、プレフィックスフェーズは空です:
```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
```
唯一の違いは、型文字列の記述です。`Nested` はフィールド名 (`a`, `b`) を保持しますが、`Array(Tuple)` ではそれらは名前付きスロットとしては保持されません。
Case B の型文字列は、(name, type) の組をカンマ区切りで並べたリストです。最初の空白で名前とその型が区切られますが、型自体にはさらに空白、カンマ、括弧が含まれる場合があるため、パースには `Tuple` で使用するのと同じ、ネストの深さを考慮した分割処理が必要です。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 ┘
```
ここで `total_elements = offsets[num_rows - 1]` です (`num_rows == 0` の場合は `0`) 。オフセットは単調非減少で、各フィールドストリームにはちょうど `total_elements` 個の値が含まれます。サーバーは INSERT 時に、1 つの行内ではすべてのフィールドの要素数が同じであることを検証します。空のカラムは 0 バイトを書き込みます。
2 行 `[(10,'x'),(20,'y')]` および `[(30,'z')]` を持つ `Nested(a UInt8, b String)` (型文字列の後に 25 バイト) :
```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"
```
### 型の別名
いくつかの型は単なる別名です。server はカラムヘッダーでは別名を送りますが、その後に続くバイト列は実体となる型のものです。デコーダーは別名をその型に対応付け、その codec を再利用します。新しいワイヤ形式が導入されるわけではありません。
地理型は、ネストした配列やタプルの別名です。
| 型文字列 | 基底ワイヤ型 |
| ---------------------------- | ------------------------- |
| `Point` | `Tuple(Float64, Float64)` |
| `Ring`, `LineString` | `Array(Point)` |
| `Polygon`, `MultiLineString` | `Array(Ring)` |
| `MultiPolygon` | `Array(Polygon)` |
したがって、`Point` カラムは `Tuple(Float64, Float64)` とまったく同じようにデコードされ (表示は `(1,2)`) 、`Ring` は `Array(Tuple(Float64, Float64))` (`[(0,0),(1,1)]`) としてデコードされます。以降も同様に、階層に沿って上位の型へと続きます。
`Geometry` も別名ですが、ネストした配列ではなく [`Variant`](#variant) の別名です。その payload は、上記 6 つの geo types の variant です。カラムヘッダーには型文字列 `Geometry` だけが含まれ、variant の内容までは**示されません**。そのため、デコーダーは自分でこれを展開する必要があります。ほかの `Variant` と同様に、discriminator は geo の別名の正規名を名前順にソートした順序に従います。`0` = `LineString`、`1` = `MultiLineString`、`2` = `MultiPolygon`、`3` = `Point`、`4` = `Polygon`、`5` = `Ring` です。選択された各値は、その後、上記の geo の別名に従ってデコードされます (`NULL` の場合は `Variant` の `NULL` discriminator `255` を使用します) 。
`SimpleAggregateFunction(func, T)` は、その値型 `T` の別名です。これはすでに確定済みの aggregate 値を格納するため、ワイヤ形式も表示も `T` と完全に同一です (`SimpleAggregateFunction(sum, UInt64)` は `UInt64` としてデコードされます) 。このように別名として扱われるのは単一値型の形式だけで、基底型自体は複合型である場合もあります。
関連する 2 つの型は**別名ではありません**。これらは有効な `Native` カラム型です。たとえば client は `-State` combinator や distributed aggregation から `AggregateFunction` カラムを受け取ることがあります。ただし、どちらもこのページの範囲外となる専用の payload を持ちます。
* `AggregateFunction(func, ...)` は *中間* aggregation state を保持します (確定済みの値ではありません) 。そのバイナリ layout は aggregate function とバージョンに固有です。
* `QBit(T, N)` は、vector-search workloads 向けに bit planes を転置したベクトルを格納します。
### バージョン付き型
バージョン付き型は、後続するエンコーディングのどの Variant が続くかを示す、ワイヤ上のシリアライゼーション バージョン プレフィックスを持ちます。これらは (複合型と同様に) 複数のストリームを使用する場合もあります。`Native` wire では、プレフィックスと任意の Dictionary はブロックごとに付与されます。つまり、これらの型はブロックをまたぐ state を保持しません (下の[ブロックごとのプレフィックスに関する注記](#serialization-version-concept)を参照) 。ブロック間のシリアライゼーション state が存在するのは、MergeTree の on-disk stream 内だけです。
これらの型は、固定 shape の複合型よりもかなり複雑なため、単純な分析クエリを対象とする client であれば後回しにできます。
#### シリアル化バージョン: 概念
**シリアル化バージョン**は、型ごと・カラムごとに定義される wire 上のバージョン番号で、送信側がその型のどのエンコーディング方式を使っているかを示します。これはカラムの state prefix の先頭にある最初の情報であるため、デコーダーはまずこれを読み取り、残りのカラムに対して適切なパーサーに処理を振り分けます。
これは protocol version とは別のものです。
| Dimension | Protocol version | Serialization version (this section) |
| ----------------- | ----------------------- | ------------------------------------ |
| Scope | 接続全体 | 型ごと・カラムごと |
| Negotiated | はい、handshake 時に行われる | いいえ — 送信側が書き込み、receiver が読み取る |
| Controls | どのパケットレベルの feature が有効か | 1 つの型のどの wire variant か |
| Mandatory to read | はい | はい、各 versioned column について |
ほとんどの versioned type では、他の state-prefix データの直前に、little-endian の UInt64 としてバージョンが書き込まれますが、一部では VarUInt または UInt8 が使われます。デコーダーは最初にバージョンを読み取り、未知の値は拒否します。より大きいバージョン値は、デコーダーが理解できない新しい送信側フォーマットを意味し、これを誤ってパースすると、それ以降のすべてのバイトが壊れてしまいます。
state prefix は、**行数が 0 より大きいすべての block の先頭**で、その block のペイロード の直前に出力されます。
Native writer と reader は、block をまたいでシリアル化状態を**保持しません**。`NativeWriter` は毎回新しい serialize state を作成し、書き込む空でない各 column block に対して state prefix を書き込みます。`NativeReader` も毎回新しい deserialize state を作成し、読み取る空でない各 block ごとにそれを読み込みます (どちらも `rows == 0` の場合は prefix 全体を完全に省略します) 。
したがって、header block (rows = 0) と empty block では何も出力されず、デコーダーは空でない各 block の先頭で state prefix をあらためて読み取る必要があります。prefix を 1 回しか読まず、後続の block をペイロード だけだとみなすデコーダーは、次の block の prefix をデータとして読んでしまい、同期がずれます:
```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
```
#### シリアル化バージョンのリファレンス
| 型 | フィールド幅 | 値 | Name | 意味 |
| ------------------------------------------------------------------------------- | --------- | --- | -------------------------------------- | ----------------------------------------------------------------------------- |
| **Object** (JSON のベース) | UInt64 LE | `0` | `V1` | 元のエンコーディングです。`max_dynamic_paths` パラメータと dynamic path のリストを含みます。 |
| | | `1` | `STRING` | ネイティブフォーマットの互換性モード — JSON テキストを含む単一の `String` カラムとして Object を転送します。 |
| | | `2` | `V2` | `max_dynamic_paths` パラメータを除いた V1 のレイアウトです。 |
| | | `3` | `FLATTENED` | ネイティブフォーマットの互換性モード — flattened path 表現です。 |
| | | `4` | `V3` | V2 に、shared data のシリアル化バージョン用サブフィールドと statistics フラグを追加したものです。 |
| **Object shared data** (Object `V3` で使用されるサブストリーム) | VarUInt | `0` | `MAP` | shared data を `Map(String, String)` としてエンコードしたものです。 |
| | | `1` | `MAP_WITH_BUCKETS` | `MAP` と同じですが、スキャン効率のために N 個の bucket に分割されます。 |
| | | `2` | `ADVANCED` | path / mark / メタデータごとに個別の stream を持つ compact granule フォーマットです。 |
| **Dynamic** | UInt64 LE | `1` | `V1` | 元のエンコーディングです。`max_dynamic_types` と実行時の Variant 型のリストを含みます。 |
| | | `2` | `V2` | `max_dynamic_types` パラメータを除いた V1 です。 |
| | | `3` | `FLATTENED` | ネイティブフォーマットの互換性モードです。 |
| | | `4` | `V3` | V2 に、バイナリエンコードされた variant type names と empty-statistics のサポートを追加したものです。 |
| **Variant** discriminator モード | UInt64 LE | `0` | `BASIC` | 各行の discriminator をそのまま書き込みます。 |
| | | `1` | `COMPACT` | granule 内のすべての行で discriminator が 1 つだけ共有されている場合、単一の値と granule マーカーのみが書き込まれます。 |
| **Variant** granule フォーマット (mode が `COMPACT` の場合) | UInt8 | `0` | `PLAIN` | granule は異なる discriminator を持ちます。 |
| | | `1` | `COMPACT` | granule はすべての行に対して 1 つの discriminator を持ちます。 |
| **LowCardinality** key のシリアル化 | Int64 | `1` | `sharedDictionariesWithAdditionalKeys` | 現在定義されている唯一のバージョンです。 |
| **JSON-as-String** フォールバック (`output_format_native_write_json_as_string` が有効な場合) | UInt64 LE | `1` | `JSONStringSerializationVersion` | JSON カラムは、このプレフィックスが付いた `String` カラムとして到着します。 |
この表について、いくつか補足があります。
* **値は連番ではありません。** `Dynamic` では `1`、`2`、`3`、`4` が使われており、`V3` は `4`、`FLATTENED` は `3` です。数値が大きいほど新しいとは限りません。
* **ネイティブフォーマット専用の値があります。** `Object::STRING`、`Object::FLATTENED`、`Dynamic::FLATTENED` は、Object/Dynamic を完全には実装していない client との native プロトコル互換性のために存在します。これらは MergeTree のオンディスクストレージには現れません。
* **`V3` は主にオンディスク向けです。** native TCP プロトコルを利用する client では、通常 `V3` (値 `4`) ではなく `FLATTENED` (値 `3`) が見えます。
#### LowCardinality(T)
最も単純なバージョン付き型です。`N` 個の内部の値からなるカラムを、重複のない値の小さな Dictionary と、その Dictionary への `N` 個のインデックスに置き換えます。
型文字列: `LowCardinality(InnerType)`。例: `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
```
状態プレフィックス (Int64 LE = 1) は、定義されている唯一のバージョン `sharedDictionariesWithAdditionalKeys` です。その他の値は予約されています。
ブロックごとのメタデータ UInt64 はビットフィールドです。
| Bit range | Meaning |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 0..7 | キー型コード: `0` = UInt8、`1` = UInt16、`2` = UInt32、`3` = UInt64。`dict_size` 件のエントリに索引付けできる最小の型が選択されます。 |
| 8 (`0x100`) | `NeedGlobalDictionaryBit` — ブロック間で共有される単一の辞書。**`Native` フォーマットでは絶対に設定しません**: Native writer は `low_cardinality_max_dictionary_size = 0` を使用し、Native reader はこのビットを拒否します (`native_format` は `INCORRECT_DATA` — "cannot use global dictionary" を発生させます) 。これは wire ではなく、MergeTree のオンディスクストリームに属します。 |
| 9 (`0x200`) | `HasAdditionalKeysBit` — ブロックに追加の辞書キーが含まれる場合に設定されます (索引の前に書き込まれます) 。空でない `Native` ブロックでは常に設定されます。 |
| 10 (`0x400`) | `NeedUpdateDictionary` — ブロックに辞書の更新が含まれる場合に設定されます。空でない `Native` ブロックでは、各ブロックがそれぞれ自己完結した辞書を持つため、常に設定されます。 |
一般的なクエリ応答で、各カラムにつき単一の data block がある場合、メタデータは `0x600` (HasAdditionalKeys + NeedUpdateDictionary) です。
dict の値は、内部型 T を使ってエンコードされた `dict_size` 個の値です。辞書では特殊な値のために先頭のスロットが予約されます。非 Nullable のカラムでは 1 つ予約され (`dict[0]` には内部型のデフォルト値 (たとえば `String` なら `""`) が入る) 、実際の異なる値は `dict[1]` から始まります。
`LowCardinality(Nullable(T))` では、dict は引き続き通常の T としてエンコードされます (null-map ストリームはありません) が、予約されるスロットは **2 つ** です。`dict[0]` は NULL マーカー、`dict[1]` は内部型のデフォルト値 (たとえば `String` なら `""`) で、実際の異なる値は `dict[2]` から始まります。NULL 行のキーは `dict[0]` を指し、そのスロットは wire 上では内部型のデフォルトのバイト列として書き込まれます。
キーは dict への索引です。各索引のサイズは `1 << key_type_code` バイト (1、2、4、または 8) で、値 `N` は `dict[keys[N]]` として復元されます。
`keys_count` は、**現在の再帰レベル** における `LowCardinality` の値の数であり、必ずしもブロックの行数とは限りません。最上位の `LowCardinality` カラムでは両者は一致します。しかし、`LowCardinality` が複合型の内部にある場合、この数は複合型が下位に渡すフラット化された値の個数になります。たとえば、3 行に合計 5 要素を持つ `Array(LowCardinality(String))` では、`keys_count` は `3` ではなく `5` です。`Map(K, LowCardinality(V))` ではペアの総数になり、以下同様です。デコーダーはブロックの行数を前提にせず、このフィールドから `keys_count` を取得しなければなりません。このフラット化された個数が 0 の場合 — たとえば、配列がすべて空のブロック — `LowCardinality` の data phase では**何も書き込まれません**。存在するのは状態プレフィックス ([composite prefix phase](#composite-types) で出力される) だけで、その後にメタデータ、辞書、`keys_count` は続きません。
行数が 0 より大きいすべてのブロックでは、先頭で状態プレフィックスが読み取られます — ヘッダーブロック (rows = 0) と空ブロックは何も出力しません。ブロック内では、`keys_count` は行数と等しく、`dict_size` は dict ストリーム内の値の数と等しく、各 key は `1 << key_type_code` バイトに収まります。
`Native` フォーマットでは、各ブロックは **自己完結したブロックローカルな Dictionary** を送信します — ブロックをまたいで共有される Dictionary state はありません。Native writer は `low_cardinality_max_dictionary_size = 0` を設定するため、`SerializationLowCardinality` が共有 Dictionary を構築することはありません。つまり、空でない各ブロックは、その key を `NeedGlobalDictionaryBit` を設定せずに (メタデータ `0x600`) 、ブロックローカルな追加 key として書き込み、`native_format` が true の場合、Native reader は `NeedGlobalDictionaryBit` を拒否します。したがって、デコーダーはブロックごとに Dictionary をリセットし、そのブロックに含まれる `dict_size` 件のエントリを読み取る必要があります。前のブロックの Dictionary を引き継ぐと、次のブロックの key を誤って読み取ることになります。 (ブロックをまたいで LC Dictionary を永続化するのは Native wire layout ではなく、MergeTree のオンディスク上の事項です。)
値 `['a', 'b', 'a', 'c', 'b']` を持つ `LowCardinality(String)`:
```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
```
復元結果: `dict[1], dict[2], dict[1], dict[3], dict[2]` = `["a", "b", "a", "c", "b"]`。
値 `['a', NULL, '', 'b']` を持つ `LowCardinality(Nullable(String))` では、予約済みの 2 つのスロット、つまり NULL 用の `dict[0]` と空文字列のデフォルト値用の `dict[1]` の両方が示されます:
```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
```
再構成後: `dict[2]` = `"a"`, `dict[0]` = `NULL`, `dict[1]` = `""`, `dict[3]` = `"b"`、すなわち `["a", NULL, "", "b"]` です。`dict[0]` と `dict[1]` はどちらもワイヤ上では空のバイト列です。`NULL` かどうかはバイト列ではなく、キーがスロット `0` を指していることによって決まります。
#### JSON (Tier 1: String フォールバック)
ClickHouse の `JSON` 型には複数の wire エンコーディングがあります ([シリアル化バージョンのリファレンス](#serialization-version-reference)を参照) 。Tier 1 は最も単純で、クエリごとの設定 `output_format_native_write_json_as_string = 1` が有効な場合、サーバーは各 JSON 値をシリアル化されたテキストに変換し、state-prefix マーカー付きの `String` としてカラムを出力します。
型文字列: `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]
```
この String フォールバックでは、状態プレフィックスの値は `1` です。その他の値は、異なる `JSON`/`Object` エンコーディングを表します: `0` = V1、`2` = V2 (native TCP プロトコルでのデフォルト) 、`3` = FLATTENED、`4` = V3 ([シリアル化バージョンのリファレンス](#serialization-version-reference)を参照) 。ここで `1` 以外の値を見たデコーダーは、String フォールバックを見ているのではありません。プレフィックスは、行数が 0 より大きいすべてのブロックの先頭で読み取られ、values ストリームは `num_rows` 行分の標準的な [String](#string-type) カラムです。
`JSON` 値 `'{"a":1}'` (1 行) :
```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}
```
値は `{"a":1}` のようなコンパクトな JSON テキストとして出力され、整数は整数のまま保持されます。このテキストは単なる `String` の値であるため、client は JSON をそのまま受け取るだけで、個々のパスやそれぞれの ClickHouse の型を復元することはできません。パスごとの忠実な型付けには、以下の Tier 2 エンコーディングが必要です。
#### Variant(T1, T2, ...)
判別付きユニオンです。各行には、variant type のうちいずれか1つの値、または NULL が格納されます。各行には型を選択する 1 バイトの**グローバル 判別子**があり、その後、型ごとの値は variant type ごとに1つの連続した領域として密に格納されます。
型文字列: `Variant(T1, T2, ...)`。サーバーは順序を正規化し (variant type は名前順にソートされます) 、受信する型文字列にはすでに**グローバル 判別子 順**で型が並んでいます。判別子 `0` は最初に列挙された型を選択し、`1` は2番目の型を選択します。以下同様です。`255` (`NULL_DISCRIMINATOR`) は、その行が NULL であることを意味します。Variant の要素が `Nullable` になることはありません。NULL は 判別子 が表現します。例: `Variant(String, UInt64)`、`Variant(Array(UInt8), String)`。
状態プレフィックス には、`UInt64 LE` の 判別子 モードが含まれます。`0` = BASIC (各行の 判別子 をそのまま書き込む) 、`1` = COMPACT (granule 単位のランレングスエンコーディング) です。サーバーはデフォルトでネイティブプロトコルでは BASIC を使用します (`use_compact_variant_discriminators_serialization = false`) 。ここで規定されているのは BASIC のみです。
```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
```
再構築するには、型ごとに進行中のカウンターを保持しながら、判別子 を左から右へ順にたどります。判別子 `d` (≠ 255) を持つ行 `r` は、variant 型 `d` の value run の index `counter[d]` にある値を取り、その後 `counter[d]` をインクリメントします。判別子 `255` の行は NULL で、どの run からも値を消費しないため、型ごとのカウンターの合計は非 NULL の行数に等しくなります。
状態プレフィックス (mode `UInt64`) は、行数が 0 より大きいすべての block の先頭で読み取られます。header と空の block は何も出力しません。各非 NULL の 判別子 は variant 型の数より小さく、variant 型 `i` はちょうど `count[i]` 行分デコードされます。
要素自体が stateful な (`LowCardinality`, `Variant`, `Dynamic`, `JSON`) Variant 要素は、mode `UInt64` の後、要素ごとの state-prefix フェーズでそれぞれ独自の 状態プレフィックス を出力します。リーフ型と通常の複合型 (リーフ型の `Array`, `Tuple`, `Map`) の 状態プレフィックス は空で、自由に組み合わせられます。
値が `[42, 'hi', NULL]` の `Variant(String, UInt64)` (canonical order では `String` が `UInt64` より前にソートされるため、判別子 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
```
再構成後: 行 0 = UInt64 run\[0] = `42`; 行 1 = String run\[0] = `"hi"`; 行 2 = NULL。
判別子ストリームが索引であり、各非 NULL の判別子は対応する型の dense run から次の値を取り出します。一方、`255` (NULL) は何も消費しません。この同じたどり方で [Dynamic](#dynamic) も再構成できますが、異なるのは NULL のエンコード方法だけです:
```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
値の型が実行時に判明するカラムです。各行には、実行時に決定される型集合のいずれか 1 つの値、または NULL が入ります。`Variant` とは異なり、型集合はカラムの型文字列には**含まれず**、状態プレフィックス に格納されます。
型文字列: `Dynamic` または `Dynamic(max_types=N)`。`max_types` パラメータは、このカラムが追跡する異なる型の数の上限を定めますが、以下のワイヤ形式には影響しません。
`Dynamic` には 4 つのエンコーディングがあります — `V1 = 1`、`V2 = 2`、`FLATTENED = 3`、`V3 = 4`。server がどれを出力するかは、チャネルとクエリ設定によって決まります。
* `clickhouse-client` および HTTP `FORMAT Native` では、writer の revision は `0` です (`client_protocol_version` で引き上げない限り) 。そのため、デフォルトは **V1** になります。
* native TCP プロトコルでは、ネゴシエートされた revision におけるデフォルトは **V2** です。`Native` writer では statistics は無効のままのため、デフォルトの `V2` payload には variant ごとの statistics は含まれません。型リストの後には、ネストされた `Variant` prefix と data がそのまま続きます。 (variant ごとの statistics は MergeTree の on-disk に関するものであり、Native wire の一部ではありません。)
* クエリ設定 `output_format_native_use_flattened_dynamic_and_json_serialization = 1` を指定すると、この両方を上書きし、revision に関係なく **FLATTENED (version 3)** を出力します。
**適用範囲**
このページでは **`FLATTENED`** レイアウトのみを規定します。フラットではない `V1`/`V2`/`V3` の binary layout は内部表現 / on-disk 表現 (binary エンコードされた型リスト、variant ごとの statistics) であり、ここでは**規定しません**。このページを使って `Dynamic` をデコードしたい client は、`output_format_native_use_flattened_dynamic_and_json_serialization = 1` を設定して `FLATTENED` を要求する必要があります。以下のレイアウトはその設定を前提としています。version byte は prefix の先頭にあるため、decoder は実際に受信したエンコーディングを検出し、`FLATTENED` のみを実装している場合は `V1`/`V2`/`V3` を拒否できます。
その設定で選択される **FLATTENED (version 3)** レイアウト:
```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
```
判別子の幅は、`num_types` 個の型に NULL スロットを加えたものを表せる最小の符号なし整数です。`num_types ≤ 255` の場合は `UInt8`、それ以降は `UInt16`、`UInt32`、`UInt64` になります。NULL は判別子の値 `num_types` そのもので、NULL が固定値 `255` である `Variant` とは異なります。復元は `Variant` と同じ密な走査で行います。型ごとのカウンターを保持し、判別子 `d` (≠ `num_types`) を持つ行 `r` は、型 `d` の並びから `counter[d]` 番目の値を取ります。
状態プレフィックス (バージョン + 型リスト) は、行数が 0 より大きいすべてのブロックの先頭で読み取られます。ヘッダーと空のブロックは何も出力しません。
シリアライゼーションが状態を持つ実行時の型 (`LowCardinality`、`Variant`、`Dynamic`、`JSON`) は、型名リストの後にネストされた状態プレフィックスを持ちます。
実行時の型リストは通常、`Variant` の正規化に従います。通常の variant スロットは `DataTypeVariant` の順序 (型名順) で書き込まれるため、wire 上の順序は挿入順とは一致しません。ただし、常に全体がソートされている**わけではありません**。共有 variant にあふれた型 (たとえば `Dynamic(max_types=N)` の場合) は、通常のスロットの後に最初に現れた順で追加されるため、リストの tail では型名順が崩れることがあります。したがって、デコーダーは転送された型リストを 判別子 の割り当てにおける基準として扱う必要があり、自分で再ソートしてはいけません。行 `[42::UInt64, "hi", NULL]` では、2 つの型は `String` と `UInt64` で、`"String"` は `"UInt64"` より前にソートされるため、判別子 は `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
```
再構成すると、行 0 = UInt64 run\[0] = `42`; 行 1 = String run\[0] = `"hi"`; 行 2 = NULL。型ごとの run は、型リストと同じ wire 上の順序 (`String` が `UInt64` より前) に従います。
#### JSON (Tier 2: FLATTENED Object)
よりリッチな JSON エンコーディングです。すべての値をテキストにフラット化する (Tier 1) のではなく、カラムは JSON パスごとに 1 つのサブカラムに分割されます。これは、フラット化シリアライゼーションのフラグがオン (`output_format_native_use_flattened_dynamic_and_json_serialization = 1`) のまま、Tier 1 へのフォールバックを**要求しない** (`output_format_native_write_json_as_string = 0`) 場合に選択されます。このとき、server はシリアライゼーション **バージョン 3** を出力します。
パスには 2 種類あります。
* **型付きパス** は型文字列で宣言されます。たとえば `JSON(a UInt32, b String)` のように指定し、宣言された型としてデコードされます。ドットを含むパス名は、型文字列内でバッククォートで囲まれます。
* **動的パス** は runtime に検出され、それぞれ [Dynamic](#dynamic) カラムとしてデコードされます。
FLATTENED モードでは **共有データカラムはありません** (このオーバーフロー格納先は、非フラットな V2/V3 Object エンコーディングに属します) 。すべてのパスは、`num_rows` 個の値を持つ完全なカラムです。
```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)
```
2 段階の構造になっている点に注意してください。まず **すべて** のパスの状態プレフィックスが先に現れ、その後に **すべて** のパスデータが続きます。したがって、動的パスの `Dynamic` プレフィックス (プレフィックスフェーズ) は、そのデータ (データフェーズ) とは分かれています。状態プレフィックスは、行数が 0 より大きいすべてのブロックの先頭で読み取られ、各パスカラム (型付きまたは動的) にはちょうど `num_rows` 個の値が格納されます。行 `r` のオブジェクトは、各パスのインデックス `r` にある値を読み取って組み立てられます。その行で `Dynamic` の判別子が NULL の動的パスは、キーを持ちません。
`JSON` 値 `{"a": 42, "b": "hi"}` (1 行で、両方のパスが動的) の例を示します。JSON の整数は `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 非フラット (V2/V3)
非フラット化 `Object` エンコーディング (`V1`/`V2`/`V3`) は、MergeTree のオンディスクストレージで使用され、flattened フラグがオフのときにサーバーが wire 上に出力する形式です。`clickhouse-client` / HTTP `FORMAT Native` (revision `0`) では `V1`、native TCP プロトコルでは `V2` が使われます。これらは shared-data カラムを含み、このページでは**定義していません**。また、Native wire 上ではパスごとの統計情報を**含まない**点に注意してください。`NativeWriter` は統計情報を無効のままにするため、`Object` structure prefix には統計情報セクションがなく、その後のバイト列には typed/dynamic/shared-data prefixes と data がそのまま続きます。統計情報が現れるのは、それを有効にしている MergeTree のオンディスクパスだけです。このページを使って `JSON` カラムをデコードするには、client は文書化されている tiers のいずれかを選択する必要があります。[String fallback](#json-tier-1-string-fallback) を使う場合は `output_format_native_write_json_as_string = 1` を設定し、[FLATTENED Object](#json-tier-2-flattened-object) レイアウトを使う場合は `output_format_native_use_flattened_dynamic_and_json_serialization = 1` (かつ `output_format_native_write_json_as_string = 0`) を設定します。
## 圧縮フレーム
ClickHouse では、`Native` ストリームのカラムデータを内部フレームフォーマットで圧縮できます。以下の[フレームレイアウト](#frame-format)は**トランスポート非依存**で、同じフレームが native TCP プロトコルでも HTTP 上でも使われます。ただし、圧縮の要求方法と、フレームの外側を構成するものはトランスポートによって異なります。
* **Native TCP プロトコル。** 圧縮は、[Query packet](/ja/reference/interfaces/specs/NativeProtocol#query) の `compression` flag により、クエリ単位でオプトインして有効化します。有効な場合、各 `Data`、`Totals`、`Extremes`、`Log`、`ProfileEvents` packet のボディ、つまり `table_name` string より後ろのバイト列が、このフレームフォーマットでラップされます。packet のエンベロープ自体、packet-type code、および `table_name` string は**圧縮されません**。server はそれらを生のストリームに書き込みます。`NativeWriter` が出力するものはすべて圧縮ストリームに入るため、`BlockInfo` prefix は次元やカラムとともにフレーム内の先頭に配置されます。したがって、client は `BlockInfo` を読み取る前にフレームを展開する必要があります。
* **HTTP。** `SELECT ... FORMAT Native&compress=1` は、`FORMAT Native` のバイトストリーム全体を同じフレームでラップします (server は同じ内部 `CompressedWriteBuffer` を使用します) 。また、`?decompress=1` は `Native` の*入力*ボディで同じフレームを想定し、対応する `CompressedReadBuffer` を通じてそれらをデコードします。この経路には TCP packet type、`table_name`、packet envelope はありません。圧縮された payload 全体は、単にフレーム化された `Native` block です (`BlockInfo` prefix は、ネゴシエートされた revision が `0` より大きい場合にのみ存在し、これは上記の非圧縮レイアウトとまったく同じです) 。この内部 `compress`/`decompress` フレーミングは、HTTP トランスポート圧縮 (`Content-Encoding: gzip`/`zstd`、`enable_http_compression` により有効化) とは別物です。後者は HTTP レイヤーでレスポンスをラップするものであり、以下のフレームフォーマットとは異なります。
したがって、非圧縮の `FORMAT Native` レイアウトしか実装していない client でも、圧縮された HTTP `Native` レスポンスを読み取ったり、`decompress=1` の request body を送信したりするには、このフレームレイヤーに対応する必要があります。
### フレームの形式
```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
```
フレーム全体のサイズは `16 + compressed_size` = `16 + 9 + body_size` = `25 + body_size` です。ここで 2 つの対象範囲に注意してください。checksum は 9 バイトのヘッダーとボディを対象としますが、`compressed_size` はヘッダーとボディを数える一方、checksum 自体は **含みません**。
```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
```
### メソッドのバイト値
| Byte | Method | ボディのエンコーディング |
| ------ | ------ | ----------------------------------------------------------------------- |
| `0x02` | NONE | ボディは生のバイト列です (圧縮なし) 。フレーム自体は引き続き出力され、receiver がチェックサムを検証します。 |
| `0x82` | LZ4 | ボディは **LZ4 block format** です。*LZ4 frame format* ではありません。マジックナンバーもありません。 |
| `0x90` | ZSTD | ボディは生の zstd 単一フレームのストリームです (標準の zstd マジックナンバーはボディの一部です) 。 |
### チェックサム
ClickHouse は CityHash v1.0.2 (旧来のバリアント) を使用しており、最新の Google CityHash は**使用していません**。この 2 つは異なる出力を生成します。
チェックサムは、9 バイトのヘッダー (method + compressed\_size + uncompressed\_size) と N バイトのボディ、つまりチェックサムから frame の末尾までのすべてのデータに対して計算されます。16 バイトの CityHash128 出力では、最初の 8 バイトが下位 половина (LE) 、次の 8 バイトが上位半分 (LE) です。デコーダーは受信したヘッダーとボディに対して CityHash128 を再計算し、その結果を先頭の 16 バイトと比較します。一致しない場合はデータ破損と見なされ、デコーダーは失敗します。
### ブロックごとの境界
Block の compressed payload は、必ずしも単一の フレーム ではなく、**1 つ以上の フレーム からなる stream** です。送信側はシリアライズされた block を `CompressedWriteBuffer` を通じて書き込み、内部 buffer がいっぱいになるたび (約 1 MB、`DBMS_DEFAULT_BUFFER_SIZE`) に フレーム を出力し、block が flush されると最後の フレーム を出力します。したがって、小さい block は 1 つの フレーム ですが、大きい block は連続する複数の フレーム になります。
この不変条件が成り立つのは一方向だけです。送信側は各 block の末尾で compressed buffer を flush するため、**すべての block の終端は フレーム 境界と一致します**。ただし、その逆は成り立ちません。block の途中で buffer がいっぱいになったときに出力される中間の フレーム 境界は、block の*途中*にあり、block 境界ではありません。したがって、デコーダーは block の終端を見つける際に、block 自身の次元 (`num_columns`/`num_rows`) を使う必要があり、各 フレーム が 1 つの完全な block だと仮定してはいけません。
受信側は フレーム を stream として処理します。16 + 9 bytes を読み取り、続いて `compressed_size - 9` bytes のボディを正確に読み取り、それを正確に `uncompressed_size` bytes に展開して、その bytes を block デコーダーに渡します。デコーダーが現在の フレーム に収まっている以上のデータを必要とする場合は、次の フレーム を取得します。送信側は block ごとに flush するため、block のデコードが完全に終わると frame buffer は空になり、次の block は新しい フレーム から始まります。
native TCP プロトコルでは、packet envelope (packet-type VarUInt と `table_name` 文字列) は compressed payload の外側にある **raw** stream に書き込まれ、フレーム 化されるのは block body (BlockInfo + columns) だけです。HTTP の `compress`/`decompress` パスにはこのような envelope はなく、stream 全体が フレーム 化された blocks になります。
### ネゴシエーション
native TCP プロトコルでは、圧縮は接続単位ではなくクエリ単位です。Query パケットの `compression: bool` フィールドで、そのクエリに対してのみ圧縮を要求します。サーバーはこの要求に従い、クエリの存続期間中、圧縮された `Data`/`Totals`/`Extremes`/`Log`/`ProfileEvents` のボディを出力します (`Log`/`ProfileEvents` は v54481+ のみ) 。また、クライアントから*送信される* Data ブロック (external table、空のデータ終端マーカー、INSERT の行) についても、同じ形式でフレーム化されていることを前提とします。同じ connection 上の後続のクエリでは、設定が異なる場合があります。
HTTP では Query パケットが存在しないため、`compress=1` クエリパラメータでそのリクエストのフレーム化された出力を指定し、`decompress=1` で request body がフレーム化されていることを宣言します。`compress=1` の出力は、`network_compression_method` ではなくサーバーのデフォルト codec (`LZ4`) で書き込まれます。一方、`decompress=1` の reader は各フレームの method byte から codec を読み取るため、入力では任意の codec を受け付けます。
圧縮が有効な場合、サーバーは複数の行を含む blocks に対して、カラムを並列 block マーシャリング / `ColumnBLOB` パス (`PARALLEL_BLOCK_MARSHALLING`、v54478) に流すこともあります。INSERT data を圧縮する実装では、ストリームの同期ずれを避けるため、このパスを処理できるようにするか、明示的に無効化する必要があります。
## 用語集
**ブロック** — Native format におけるデータ交換の単位。列指向で格納された行からなる、自己記述型の chunk です。[block and column structure](#block-and-column-structure) を参照してください。
**BlockInfo** — TCP Data-packet path で ブロック の前に置かれるメタデータヘッダーです (connection revision が 0 より大きい場合に常に書き込まれます) 。revision に応じて制御され、field ID でタグ付けされたフィールドの列で構成されます。`Native` 出力フォーマットでは省略されます。これは revision `0` でシリアライズされるためです。[BlockInfo](#blockinfo) を参照してください。
**Column body** — Column header (name、type、has\_custom\_serialization byte) に続く、実際の値を保持する Column のバイト列です。レイアウトは type ごとに異なります。[column wire layout](#column-wire-layout) を参照してください。
**Composite type** — 1 つ以上の inner type から構成される type で、各カラムにつき複数の stream としてエンコードされます。ワイヤ形式は stable で、バージョンはありません。[composite types](#composite-types) を参照してください。
**Dictionary (LowCardinality)** — `LowCardinality(T)` カラムが整数インデックスを通じて参照する、一意な値の配列です。[LowCardinality](#lowcardinality) を参照してください。
**Empty block** — `num_columns = 0` かつ `num_rows = 0` の ブロック です。番兵として使われ、client-side の入力終端マーカーであると同時に、server-side の stream 境界マーカーでもあります。[block variants](#block-variants) を参照してください。
**Header block** — `num_columns > 0` かつ `num_rows = 0` の ブロック で、クエリ応答の最初の Data packet として server から送信されます。結果のスキーマを通知します。[block variants](#block-variants) を参照してください。
**Inner type** — composite が内包する type です。`Array(UInt32)` の inner type は `UInt32`、`Nullable(T)` の inner type は `T` です。
**Offsets stream** — `Array`、`Map`、`Nested` が行ごとの要素境界を区切るために使う、累積終端位置を表す UInt64 配列です。[Array](#array) を参照してください。
**Placeholder value** — `Nullable(T)` カラムの values stream で、null の位置に書き込まれるバイト列です。デコーダーは stream を進めるためにこれを読み取りますが、内容は無視します。[Nullable](#nullable) を参照してください。
**Result block** — 実際のクエリ結果の行を含む、`num_rows > 0` の ブロック です。[block variants](#block-variants) を参照してください。
**Schema block** — header block の同義語で、INSERT phase を説明する際に使われます。この場合、schema block は期待されるカラム形状を client に伝えます。
**Serialization version** — versioned type が、後続するエンコーディングのどの variant が使われるかを示すために用いる、type ごとの on-wire バージョン番号です。protocol version とは異なります。[serialization version: concept](#serialization-version-concept) を参照してください。
**State prefix** — versioned type のブロックごとのペイロードに先行するバイト列です。シリアル化バージョンと、 (LowCardinality の場合は) ブロック単位の dictionary メタデータを保持します。行数が 0 より大きいすべての block の先頭で出力され、block をまたいで保持されることはありません。
**Stream** — カラム body 内の連続したバイト列で、1 つの論理的な下位要素 (null-map、offsets array、values stream) をエンコードします。multi-stream type は、各カラムにつき 2 つ以上の stream を連結します。