ネイティブプロトコル

ネイティブプロトコルは、ClickHouseのクライアントとサーバーがTCP上で使用する、バイナリの接続指向プロトコルです。このプロトコルでは、SQLクエリ、結果データ、INSERTのペイロード、実行テレメトリー、エラー信号がやり取りされます。コマンドラインクライアントや、C++および大半のサードパーティ製ネイティブドライバーを支えるプロトコルでもあります。

このページでは、プロトコルそのもの、つまりパケットのフレーミング、接続の状態遷移、バージョンネゴシエーション、そしてBlock以外のすべてのメッセージのボディを扱います。Data系パケット内のバイト列 (Block本体、そのカラム、型ごとのエンコーディング) については別のトピックであり、Native Format仕様で説明されています。

いくつかの性質は全体を通して共通しています。このプロトコルはバイナリであり、位置依存です。BlockInfo内を除いてフィールドタグは存在しないため、1バイトでもずれると、それ以降のすべてが同期しなくなります。また、これはステートフルなプロトコルであり、各TCP接続は一度に1つのクエリだけを処理します。多重化はありません。固定幅整数はリトルエンディアンです。

wire 上のすべてのメッセージは VarUInt のパケットタイプコードで始まり、その後に、そのコードとネゴシエートされたプロトコルバージョンに応じて構造が決まるボディが続きます。

接続は 3 つのフェーズで進行します。最初に一回限りのハンドシェイクがあり、その後に任意回数の Ping または Query のやり取りが続き、最後に切断されます:

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: TCP connect

    rect rgb(220, 235, 255)
        Note over C,S: Handshake
        C->>S: ClientHello (name, version, db, user, password)
        S->>C: ServerHello (server_name, version, [timezone, display_name, ...])
        Note over C,S: negotiated_version = min(client, server)
        opt negotiated_version ≥ 54458
            C->>S: Addendum (quota_key)
        end
    end

    rect rgb(220, 245, 225)
        Note over C,S: Query phase
        C->>S: Query packet (ClientInfo, settings, params, SQL)
        C->>S: External-table Data packets (0 or more)
        C->>S: Empty Data marker — the "go" signal
        loop until EndOfStream or Exception
            S->>C: Data / Progress / Log / ProfileInfo / Totals / ...
        end
        S->>C: EndOfStream
    end

ネイティブTCPプロトコルでは、SQL 内の FORMAT 句に関係なく、表形式のデータは常に Nativeフォーマットで運ばれます。RowBinary、CSV、JSON などへの再フォーマットはクライアント側の役割であり、Nativeブロックをデコードした後に行われます。 (HTTPインターフェイスはこれとは別のコードパスで、FORMAT 句を実際に尊重します。HTTP はここでの対象外です。)

TLS はプロトコルの下位にあるトランスポート層で動作します。有効にすると TCP ストリーム全体が暗号化され、TLS を使用するかどうかにかかわらず、プロトコルメッセージ自体はバイト単位でまったく同一です。

認証は、ハンドシェイク時の ClientHello メッセージで行われます。user フィールドと password フィールドは平文の文字列として送信されるため、転送中の認証情報を保護するのはトランスポート層の暗号化 (TLS) です。

空の user フィールドは、サーバーで設定されているデフォルトのセッションユーザー、つまり default_session_user サーバー設定 (デフォルト値は default) として解釈されます。この値は、protocols セクションでリスナーごとにオーバーライドされる場合があります。サーバーのデフォルトのセッションユーザーが空に設定されている場合、またはサーバーのバージョンが 26.8 より前の場合、空の user フィールドは例外として拒否されます。clickhouse-client は空のユーザー名を送信しないことに注意してください。クライアント側で default に置き換えます。

SSH チャレンジレスポンス認証は、プロトコルバージョン 54466 以降で利用できます。詳しくは、SSH チャレンジレスポンス認証 を参照してください。

分散クエリ実行では、サーバー同士は共有シークレットを知っていることを証明することで相互認証を行います。この際、シークレット自体が wire 上に送られることはありません。各 Query は、salt、nonce、設定されたシークレット、およびクエリから計算される 32 バイトの SHA-256 auth_hash を Query のフィールド 4 に含み、受信側のサーバーはこれを再計算して照合します。これは INTERSERVER_SECRET 機能 (v54441) によって有効化されます。外部クライアントは、ここには常に空文字列を送信します。サーバー間認証を参照してください。

client と server はどちらも、ハンドシェイク時に対応する最大の プロトコルバージョン を通知します。交渉後のバージョン は、その 2 つのうち小さい方です。

negotiated_version = min(client_version, server_version)

その後の各メッセージでは、ネゴシエートされたバージョンに基づいて、wire 上にどのフィールドが含まれるかが決まります。

機能は、それが導入されたプロトコルバージョンによって識別され、ネゴシエートされたバージョンがその番号以上の場合に有効になります。

送受信どちらの方向でも、通信上のすべてのメッセージは同じ外側の構造を持ちます：

[VarUInt: packet_type_code]    always encoded as VarUInt
[message body]                 format depends on packet_type_code

完全なパケット型の一覧は、packet type referenceにあります。

パケット型は固定幅のバイトではなく、VarUInt です。値が128未満の場合、VarUInt でも同じ1バイトになりますが、将来パケット型が128以上になっても互換性を保てるよう、実装では VarUInt エンコーディングを使用する必要があります。

message referenceでは、各パケットのボディ、つまりパケット型コードの後に続くバイト列のみを記載しています。フィールド番号は、最初のボディフィールドを1として始まります。

CHUNKED_PROTOCOL 機能の使用がネゴシエートされると (ハンドシェイクを参照) 、wire 上のすべてのパケットはチャンク化フレーミングで包まれます。この包み方は方向ごとです。つまり、client→server と server→client は個別にネゴシエートされるため、異なるモード (チャンク化または非フレーム) になる場合があります。

パケットごとの wire レイアウト:

<chunk>...   one or more chunks; their payloads concatenated form the whole packet
[u32 LE = 0] zero-size terminator marking end of packet

chunkごとのWireレイアウト:

[u32 LE: chunk_size]   chunk_size in [1, UINT32_MAX]
[chunk_size bytes]     packet bytes (see note below)

パケット型 VarUInt は chunk 化されたストリームの内側にあります。つまり、フレーミングの前に別個のバイトとして送られるのではなく、パケットペイロードの先頭バイト (最初の chunk の先頭バイト) です。各パケットの chunk ペイロードは、packet envelope の完全な [VarUInt packet_type_code][message body] 全体です。パケット型を chunk 化されたストリームの外側に置くクライアントは、その型バイトを u32 の chunk サイズの先頭バイトとして相手に読ませてしまい、接続の同期が崩れます。

書き込み側のバッファがパケット途中でいっぱいになると、1 つのパケットが複数の chunk に分割されることがあります。分割位置はどこでもあり得るため、パケット型の VarUInt の途中で分割されることもあります。読み取り側は chunk ペイロードを連結し、末尾の 4 バイトのゼロを透過的なパケット境界として扱います。つまり、それ自体は消費しますが、パケットボディを読む側には見せません。

ボディを持たないパケットも引き続きラップされます。Ping や Pong のような 1 バイトのパケットは、chunk 化がネゴシエートされると [u32 size = 1][0x04][u32 0] になります。このページの他の箇所で「wire 上では単一バイト」と説明しているものは、いずれも chunk 化前の形式を指します。

ネゴシエーション。 ServerHello と Addendum はそれぞれ、方向ごとに 1 つずつ、合計 2 つの String フィールドを持ち、その値は {"chunked", "notchunked", "chunked_optional", "notchunked_optional"} から取られます。

• chunked / notchunked は厳格です。その側はそのモードを厳密に要求します。
• _optional バリアントは柔軟で、相手側が選んだどちらのモードも受け入れます。

各方向で合意される値は、ペアごとに次のように計算されます。

クライアント側では、クライアントの SEND 設定がサーバーの RECV 設定とネゴシエートされ、逆方向も同様です。

タイミング。 ネゴシエーション文字列はフレーム化されていない wire 上を流れます: ClientHello → ServerHello (server prefs) → Addendum (client のネゴシエート済みの値) 。フレーミングへの切り替えは、Addendum が flush された後に送信されるすべてのバイトに適用されます。Addendum 自体、ClientHello、ServerHello は常にフレーム化されません。

接続は常に、HANDSHAKE、READY、READING_RESPONSE、または終了済みの4つの状態のいずれか1つにあります。プロトコルは多重化を行わないため、前のレスポンスを読み切る前にクライアントが新しいリクエストを送信すると、転送中のバイト列が交錯してストリームが破損します。

stateDiagram-v2
    [*] --> HANDSHAKE: TCP connect

    HANDSHAKE --> READY: handshake ok
    READY --> READING_RESPONSE: send Query
    READING_RESPONSE --> READY: EndOfStream / Exception
    READY --> READY: Ping / Pong

    HANDSHAKE --> Terminated: handshake error
    READING_RESPONSE --> Terminated: protocol violation / I/O error
    READY --> Terminated: close
    Terminated --> [*]

正常系の流れはそのまま下に進みます — HANDSHAKE → READY → READING_RESPONSE → READY — Ping/Pong の自己ループがあり、すべての失敗エッジは単一の Terminated シンクに集約されます。

認証を行い、プロトコルバージョンをネゴシエートします。これは各接続で、他のどの処理よりも前に、必ず一度だけ発生します。

TCP接続は確立された直後で、まだメッセージは一切やり取りされていません。流れは次のとおりです。

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: ClientHello
    alt success
        S->>C: ServerHello
    else error
        S->>C: Exception — connection terminates
    end
    Note over C,S: negotiated_version = min(client, server)
    opt negotiated_version ≥ 54458
        C->>S: Addendum
    end

1. クライアントは、サポートする最大のプロトコルバージョンを指定して ClientHello を送信します。

2. クライアントは応答を読み取り、パケットタイプに応じて次のように処理を振り分けます。

   Packet type	Action
   Hello (0)	ServerHello をデコードします。negotiated_version = min(client_ver, server_ver) を計算します。ステップ 3 に進みます。
   Exception (2)	Exception をデコードします。エラーとして返し、接続を終了します。
   anything else	プロトコル違反です。接続を終了します。

3. negotiated_version ≥ 54458 (ADDENDUM 機能) の場合、クライアントは Addendum を送信します。この判断は、クライアントが宣言したバージョンではなく、ネゴシエートされたバージョンに基づきます。

成功すると接続は READY に移行し、何らかのエラーが発生した場合は終了します。

TCP keepalive とは独立した、アプリケーションレベルの生存確認です。Ping/Pong の往復が成功すれば、TCP接続が双方向で生きており、サーバーが応答可能であることを確認できます。Ping はステートレスで、どのクエリとも相関付けられていないため、連続する複数の Ping は互いに独立しています。

READY からのフローは次のとおりです。

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: Ping (0x04)
    alt responsive
        S->>C: Pong (0x04)
    else error
        S->>C: Exception
    end

1. クライアントは Ping を送信します。

2. クライアントはレスポンスを読み取ります。

   Packet type	Action
   Pong (4)	応答可能であることを確認し、READY に戻ります。
   Exception (2)	Exception をデコードし、エラーとして返します。
   anything else	プロトコル違反。

クライアントは SQL ステートメントを送信し、サーバーは結果ブロックと実行テレメトリーをストリームで返します。レスポンスは一連のパケットで構成され、最後は必ず 1 つの EndOfStream または Exception で終わります。

READY から始まるフローは次のとおりです。

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: Query message
    C->>S: External-table Data packets (0 or more)
    C->>S: Empty Data marker — end-of-client-data (required)
    S->>C: Data — header block (N cols, 0 rows)
    loop until EndOfStream or Exception
        S->>C: Progress / Log (interleaved)
        S->>C: Data — result block (N cols, M rows)
        S->>C: Totals / Extremes (aggregation queries)
        S->>C: ProfileInfo / ProfileEvents (profiling)
    end
    S->>C: Data — empty block (boundary marker)
    S->>C: Progress — final updates
    S->>C: EndOfStream — authoritative end of query

いずれかの時点でエラーが発生した場合、サーバーは EndOfStream の代わりに Exception を送信し、それによってクエリは終了します。

1. クライアントは一意の query_id (通常は UUID) を付けて Query を送信します。

2. クライアントは任意の 外部テーブル を送信し、その後に空の Data マーカーを送信します。空の Data パケットは table_name = "", num_columns = 0, num_rows = 0 です。サーバーは、このマーカーを受信するまでクエリの実行を開始しません。

3. クライアントは READING_RESPONSE に移行し、書き込みバッファを flush します。

4. クライアントは応答パケットをループで読み取り、type ごとに処理を振り分けます。

   Packet type	Action
   Data (1)	block をデコードします。最初の Data はスキーマヘッダーで、それ以降は結果 block (蓄積対象) です。空の block は境界マーカーです。num_rows == 0 はクエリ終了ではありません。
   Progress (3)	実行メトリクス。各パケットは前回からの増分なので、ローカルで累積します。
   EndOfStream (5)	クエリ完了。ループを抜けて READY に戻ります。
   ProfileInfo (6)	実行後の profiling データ。
   Totals (7)	aggregation の totals block (Data と同じワイヤ形式) 。
   Extremes (8)	最小値/最大値の block (Data と同じワイヤ形式) 。
   Log (10)	server log の 1 行。
   TableColumns (11)	カラムのデフォルト値に関するメタデータ。
   ProfileEvents (14)	パフォーマンス counters。
   Exception (2)	デコードして error として返します。ループを抜けて READY に戻ります。
   anything else	クエリ phase 中に現れるのは想定外です。connection を終了します。

EndOfStream または処理済みの Exception を受け取ると、connection は READY に戻ります。プロトコル違反または I/O error が発生した場合は終了します。

INSERT フェーズは、クエリフェーズに 2 回の追加のやり取りを加えたものです。クライアントが INSERT ステートメントを送信すると、サーバーはターゲットテーブルを示す スキーマブロック を返します。続いてクライアントは行を含む Data packets をストリーミングし、その後に空の Data マーカーを送信します。最後に、サーバーは EndOfStream または Exception を返して終了します。

READY から開始する場合、SQL は INSERT INTO <table> [(<cols>)] VALUES 形式の INSERT です。行データは Data packets を通じて送られるため、インラインの VALUES (...) リテラルは含みません。フローは次のとおりです。

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: Query packet (INSERT body)
    C->>S: External-table Data packets (0 or more)
    Note over C,S: No empty Data marker here —<br/>it would end the row stream before it starts
    opt metadata before schema
        S->>C: TableColumns / Progress / ...
    end
    S->>C: Data packet — schema block (columns, 0 rows)
    Note over C,S: Schema block is the contract:<br/>rows sent next must match these column shapes
    loop one or more blocks
        C->>S: Data packet (rows N)
    end
    C->>S: Data packet — empty block (0 rows), end-of-input terminator
    loop until EndOfStream or Exception
        S->>C: Progress / ProfileInfo / Log / ProfileEvents
    end
    opt async_insert = 1 and negotiated_version ≥ 54484
        S->>C: trailing Progress, then insert ProfileEvents
    end
    S->>C: EndOfStream

1. クライアントは、body を INSERT SQL に設定した Query を送信します。
2. クライアントは、外部テーブル (INSERT ではまれ) もあれば送信します。クエリフェーズ とは異なり、ここでは空の Data マーカーは送信しません。INSERT の Query パケットは後続のデータを伴って送信されるため、データ終端を示す空の block は手順 5 まで送られません。これをスキーマ block より前に送ると、server はそれを行ストリームの終端として読み取り、行が 1 つもないまま INSERT を完了し、その後に到着する最初の実データの行パケットを、場違いなトップレベルパケットとして parse してしまいます。
3. クライアントは、スキーマ Data パケットを読み取るまで、メタデータ パケット (TableColumns、Progress、ProfileInfo、Log、ProfileEvents) を順に受信します。これは 0 行ですが、完全なカラム構造 (名前と型) を持つ Block です。スキーマ block は契約です。次にクライアントが送信する行は、これらのカラムの shape に一致している必要があります。
4. クライアントは data block を送信します。各 block について、VarUInt(ClientPacket::Data = 2)、次に空の external-table 名として String("")、その後に Block を書き込みます。カラム型は、スキーマ block のカラムと位置で一致している必要があります。
5. クライアントは入力終端を送信します。これは空の Block (0 カラム、0 行) を持つ Data パケットです。
6. クライアントは、EndOfStream (成功) または Exception (失敗) に達するまでレスポンスストリームを順に受信します。

非同期 INSERT (v54484+). クエリに async_insert = 1 が含まれている場合、server は行をキューに入れ、バッチの一部として flush します。ネゴシエートされた バージョン が 54484 以上 (PROGRESS_IN_ASYNC_INSERT) では、flush が完了すると server は追加の Progress パケットを送信し、その直後にその insert の ProfileEvents、続いて EndOfStream を送信します。54484 未満では、server はこの末尾の Progress を送信しません。このパケットは通常の Progress です。server は書き込み件数を反映する前にクエリ パイプラインをリセットするため、実際にはこの増分には経過時間しか含まれず、書き込まれた行数とバイト数の統計は付随する ProfileEvents を通じてクライアントに渡されます。手順 6 ですでに Progress の割り込み受信に対応しているクライアントであれば、追加の 1 パケットを受け取れるようにするだけで十分です。

接続は、EndOfStream または処理済みの Exception を受け取ると READY に戻ります。プロトコル違反や I/O エラーが発生した場合、接続は終了します。

フィールドは wire 順で記載しています。Type カラムでは次を使用します。

• VarUInt — 可変長の符号なし整数 (VarUIntを参照) 。
• String — VarUInt プレフィックス付きのバイト列 (Stringを参照) 。
• UInt8、Int32 など — 固定幅の little-endian 整数。
• Bool — 1 バイトで、0x00 または 0x01 です。

Role カラムは、各フィールドを誰が使用するかを示します。

• client — 外部クライアントが設定します。
• inter-server — サーバー間通信でのみ意味があります。外部クライアントはデフォルト値を書き込みます。
• universal — 両方で使用されます。

これらの表で記載しているのは、各パケットのパケット種別コードに続くボディのみです。

クライアント → サーバー。TCP接続の確立後に送信される最初のメッセージです。

Server → Client。認証に成功した場合の ClientHello への応答です。

Rule — password_complexity_rules の要素:

このリストはサーバー運用者のパスワードポリシー設定を反映したもので、あくまで参考情報です。サーバーはハンドシェイク中にこれらのルールを強制しません。パスワードの変更または設定機能を提供するクライアントは、準拠していないパスワードをサーバーに送信する前に、これらのルールを使ってエラーを示すことができます。

クライアント → サーバー。ADDENDUM (v54458) によって有効化され、ハンドシェイクのやり取りが完了した直後に送信されます。これは独立したパケットタイプではなく、各フィールドはパケットタイプを示すバイト接頭辞なしで、生のまま wire に載せられます。

チャンク化フレーミング への切り替えは、この Addendum が flush された後 に適用されます。つまり、Addendum 自体はフレーム化されません。

クライアント → サーバー。ボディはありません。パケットは、チャンク化フレーミング の前では 1 バイトの 0x04 のみです。chunking がネゴシエートされると、このバイトは chunk の 1 バイトのペイロードになります (チャンク化フレーミング を参照) 。

サーバー → クライアント。ボディはありません。パケットは、チャンク化フレーミングの前は 1 バイトの 0x04 のみです。チャンク化がネゴシエートされると、このバイトは chunk の 1 バイトのペイロードになります (chunked framingを参照) 。

サーバー → クライアント。いずれかのフェーズでサーバーがエラーに遭遇した場合に送信されます。

クライアント → サーバー。

クライアント → サーバー。Query のボディ (フィールド 2) に埋め込まれます。CLIENT_INFO (v54032) で制御されます。 (ClientInfo 内の一部のフィールドは、以下の各フィールドの注記にあるとおり、以降のバージョンで制御されます。)

OpenTelemetry エンコーディング (フィールド 16) :

[UInt8: has_trace]              0 = no trace data follows, 1 = trace data follows
If has_trace == 1:
  [16 bytes: trace_id]          byte-swapped per-8-bytes
  [8 bytes:  span_id]           byte-swapped
  [String:   trace_state]       W3C trace state
  [UInt8:    trace_flags]       W3C trace flags

Query のフィールド 4 (auth_hash) は、通信上でやり取りされる共有クラスターシークレット ではありません。生のシークレットを送信すると、認証に失敗するだけでなく、シークレット自体も漏えいしてしまいます。代わりに、inter-server クライアントとして動作するサーバーは、ソルト付き SHA-256 ハッシュを使ってシークレットを知っていることを証明します。

1. inter-server モードに入ります。 接続するサーバーは、ClientHello 内でそのことを通知します。user フィールドには inter-server マーカーが入り、password は空です。続いて、同じ ClientHello パケットの一部として、user/password フィールドの直後に 2 つの文字列、つまりクラスター名と新たに生成した 32 バイトの salt (ランダムな値の encodeSHA256) を追加します。サーバーは ServerHello を送信する前にこの 2 つの文字列を読み取るため、クライアントはそれらを先に書き込む必要があります。先に ServerHello を待つとデッドロックになります。サーバーがそれらの読み取りで待機しているためです。
2. nonce を取得します。 INTERSERVER_SECRET_V2 (v54462) がネゴシエートされると、ServerHello には 8 バイトの UInt64 nonce が含まれます。
3. ハッシュを計算します。 InitialQuery ではないすべての Query パケットについて、クライアントはフィールド 4 に encodeSHA256(salt + nonce + cluster_secret + query + query_id + initial_user + external_roles + current_roles) を書き込みます。これは 32 バイトのダイジェストです。 (nonce は 10 進文字列形式で、v54462 以上がネゴシエートされた場合にのみ含まれます。external_roles は INTERSERVER_EXTERNALLY_GRANTED_ROLES (v54472) がネゴシエートされた場合にのみ追加されます。current_roles は、プレゼンスバイトを含まない [VarUInt count][String]*count のシリアル化されたロール名リストであり、INTERSERVER_CURRENT_ROLES (v54488) がネゴシエートされ、リストが存在する場合にのみ追加されます。) InitialQuery の場合、またはクラスターシークレットが設定されていない場合、クライアントは代わりに空文字列を書き込みます。
4. 検証します。 サーバーはフィールド 4 を最大 32 バイトで読み取り、自身が保持するクラスターシークレットのコピーを使って同じ連結内容を再計算します。ダイジェストが一致しない場合、接続は拒否されます。

外部 (inter-server ではない) クライアントはこのモードに入ることはなく、常に空の auth_hash を送信します。

Query ボディの設定リスト (Query パケットのフィールド 3) にインラインでエンコードされます。このリストは、ネゴシエーションされたバージョンに関係なく常に存在し、空の key を持つ Setting、つまり後続に flags も value も続かない単一の VarUInt 0 で終端されます。setting ごとのエンコードだけが、SETTINGS_SERIALIZED_AS_STRINGS (v54429) を境に、ネゴシエーション済みバージョンに応じて変わります。

v54429+ (STRINGS_WITH_FLAGS) — 各 setting は、ここに示す 3 つ組です。

key が空の場合、フィールド 2 と 3 は存在しません。

Pre-54429 (BINARY) — 各 setting は [String key][type-specific binary value] です。flags フィールドは書き込まれず、値は 10 進数やテキスト文字列ではなく、setting 固有のネイティブなバイナリ形式 (たとえば固定幅整数や長さプレフィックス付き文字列) でエンコードされます。リストは引き続き空の key で終端されます。ネゴシエーションされたバージョンが 54429 未満のクライアントは、上記の 3 つ組ではなく、このバイナリ形式を読み書きしなければなりません。 (ただし、ユーザー定義の custom setting は例外で、どちらのエンコーディングでも常に flags と文字列値を持ちます。)

flags フィールドには次が格納されます。

• 0x01 — Important: この setting はクエリ結果に影響するため、古い peer によって黙って無視されてはなりません。
• 0x02 — Custom: ユーザー定義の custom setting。
• 0x0c — 独立したフラグではなく 2-bit tier フィールドです: 0x00 = Production、0x04 = 廃止された、0x08 = Experimental、0x0c = ベータ。2 ビットすべて (flags & 0x0c) を読んでください。単純に flags & 0x04 で判定すると、ベータ (0x0c) を廃止されたものと誤分類してしまいます。
• 0x80 — HotReload (再起動なしでの config 再読み込み。flags enum で定義されており、主に 協調 settings で見られます) 。

SELECT {x:UInt64} のようなパラメータ化クエリで使用するクエリパラメータです。Custom フラグ (0x02) が設定された Setting と同じ形式でエンコードされ、同様に空の key で終端されます。

双方向で使用されます。結果ブロック、INSERT データ、外部テーブル、データ終端マーカーを運びます。

ワイヤ形式は対称で、どちらの方向でも Block の前に table_name プレフィックスが含まれます。異なるのは パケットタイプ byte のみです。

[VarUInt: packet_type]     1 (server→client) or 2 (client→server)
[String:  table_name]      External table name; empty in most cases
[Block]                    See the Native Format spec for the Block layout

データ終端マーカーは、table_name に関係なく、Block が空、つまり 0 カラムかつ 0 行のパケットです。サーバーは、デコードされたブロックが空 (block.empty()) の場合にのみ、クライアントの Data パケットを終端として扱います。table_name = "" でブロックが空でないパケットは、終端ではなく通常の行パケットです。したがって、INSERT の行ストリームは、空でない Data ブロックが連続し、その最後にストリームを終了する 1 つの空の Data ブロックが続く形になります。

ブロックの各種バリアントとその意味については、Block variants を参照してください。

サーバー → クライアント。クエリの実行中に定期的に送信されます。すべてのフィールドは VarUInt で、各パケットに含まれるのは直前の Progress パケット以降の増分であり、累計値ではありません。送信前に、サーバーは counters を読み取ってアトミックに 0 にリセットし、elapsed_ns は前回送信からの経過時間の差分として計算します。したがってクライアントは、連続して届くパケットをローカルで必ず加算していく必要があります。パケットを絶対値として扱うと、複数のパケットが到着した時点で進捗表示が後戻りしたり、過少計上されたりします。

Server → Client。各クエリにつき1回、実行の終盤に送信されます。

サーバー → クライアント。WITH TOTALS を指定したクエリに対して送信されます。ワイヤ形式は Data と同一で、table_name 文字列 (常に空) の後に Block が続きます。異なるのはパケットタイプのバイトだけです。

[VarUInt: 7]                packet type
[String:  table_name]       always empty
[Block]                     see the Native Format spec

サーバー → クライアント。extremes 設定が有効な場合に送信されます。ワイヤ形式は Data と同一です。ブロックにはちょうど 2 行が含まれます。行 0 には各カラムの最小値が、行 1 には最大値が入ります。

[VarUInt: 8]                packet type
[String:  table_name]       always empty
[Block]                     num_rows = 2

サーバー → クライアント。クエリにアクティブなログキューがある場合に送信されます (send_logs_level 設定。詳細はログストリーミングを参照) 。

Data と同じエンベロープおよびボディのフォーマットです。この block は固定の num_columns = 8 と、あらかじめ定義されたスキーマを持ちます。各ログ行は 8 つのカラムすべてにまたがる 1 行で、1 つの Log パケットに複数の行が含まれる場合があります。

[VarUInt: 10]               packet type
[String:  table_name]       always empty
[Block]                     num_columns = 8, num_rows = number of log lines

以下の 8 つのカラム (この順序どおり) :

サーバー → クライアント。クエリごとのパフォーマンスカウンターを格納します。

エンベロープとボディのフォーマットは Data と同じです。ブロックは固定の num_columns = 6 を持ち、スキーマは事前定義されています。各イベントは 1 行です。

[VarUInt: 14]               packet type
[String:  table_name]       always empty
[Block]                     num_columns = 6, num_rows = number of events

6つのカラム:

Server → Client。COLUMN_DEFAULTS_METADATA (v54410) によって制御されます。サーバーは、カラムのデフォルト値に関するメタデータを渡すために、INSERT のスキーマブロックの前にこれを送信します。ただし、ネゴシエートされたバージョンが 54410 以上 かつ input_format_defaults_for_omitted_fields 設定が有効な場合に限られます。54410 未満ではこのパケットは一切送信されないため、古い client はこれを待ってはなりません — スキーマ Data block が直接続きます。v54410+ の client は、どちらの順序にも対応できるようにしておく必要があります。つまり、オプションの TableColumns があり、その後にスキーマブロックが続く場合です。

Server → Client。TIMEZONE_UPDATES (v54464) で有効になります。送信されるのは厳密に 1 か所だけで、input table function の初期化時です (INSERT INTO <table> SELECT ... FROM input('<structure>') 形式のクエリで、client から行をストリーミングします) 。server は入力スキーマの Data block (INSERT phase を参照) を送信した直後に、クエリコンテキストにおける現在の session_timezone を含む TimezoneUpdate を送出します。これにより、client はこれから送信する行を同じ timezone で parse できます。server は、クエリの途中で任意に実行された SET session_timezone の変更に対してこのパケットを送出することはなく、後続の結果 block をどのような timezone でフォーマットすべきかを client に伝えるために送出することもありません。

このパケットは 1 回だけ到着し、入力スキーマ block の直後、client が行 block の送信を開始する前に届きます。TimezoneUpdate を無視するデコーダーでも、wire の整合性を保つために末尾の String は必ず消費しなければなりません。

SSH_AUTHENTICATION (v54466) で有効になり、明示的に有効化した場合にのみ使用されます。ClientHello が user = " SSH KEY AUTHENTICATION " + <real_user> (先頭と末尾のスペースを含む) および password = "" を送信すると、接続は SSH フローに入ります。サーバーはこのプレフィックスを読み取り、取り除いて実際のユーザー名を復元し、チャレンジレスポンス方式に切り替えます。

このフローはパスワード認証の代わりに実行され、チャレンジレスポンスのやり取りは ServerHello より前に行われます。サーバーは認証が成功するまで Hello 応答を保留します。

1. Client は、SSH マーカープレフィックスと空の password を含む ClientHello を送信します。

2. Client は SSHChallengeRequest (パケット 11) を送信します。サーバーはまだ ServerHello を送信しておらず、先に認証を処理するため、このパケットを待ってここでブロックします。

3. サーバーは、ランダムなバイト列を含む SSHChallenge (パケット 18) を返します。

4. Client は署名対象の文字列を構築し、生の challenge ではなくその文字列に署名してから、署名を含む SSHChallengeResponse (パケット 12) を送信します。署名対象のメッセージは、次の 4 つの部分をこの厳密な順序で、区切り文字なしにバイト単位で連結したものです。

   to_sign = decimal(protocol_version) + default_database + user + challenge

   Part	Source
   decimal(protocol_version)	Client のプロトコルバージョンを 10 進 ASCII 文字列 で表したもの (例: "54466") — バージョン番号を文字列として表したものであり、VarUInt や固定幅整数ではありません。サーバーは ClientHello で受信したものと同じプロトコルバージョンを使って検証します。
   default_database	ClientHello の database フィールド (ない場合は空文字列) 。
   user	" SSH KEY AUTHENTICATION " のマーカープレフィックスを取り除いた実際のユーザー名 — サーバーがプレフィックスを除去して復元する名前と同じです。
   challenge	SSHChallenge パケット内の生の challenge バイト列。

5. サーバーは、ユーザーに登録された公開鍵に対して署名を検証し、同じ decimal(protocol_version) + default_database + user + challenge 文字列を再構築します。成功すると ServerHello を送信します。これはパスワードフローと同じ応答で、その後ハンドシェイクは通常どおり継続します (Addendum など) 。失敗した場合は Exception を返して接続を終了します。生の challenge バイト列だけに署名した Client は認証に失敗します。

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: ClientHello (SSH marker user, empty password)
    C->>S: SSHChallengeRequest (11)
    Note over C,S: Server has NOT sent ServerHello yet —<br/>it authenticates first and blocks here
    S->>C: SSHChallenge (18) — random bytes to sign
    C->>S: SSHChallengeResponse (12) — signature over version+db+user+challenge
    alt signature verifies
        S->>C: ServerHello — handshake continues normally
    else verification fails
        S->>C: Exception — connection terminates
    end

SSH 認証を使用しない外部 client では、パケット 11、12、18 が現れることはありません。ユーザーが username のプレフィックスで明示的に有効化しない限り、これらが wire 上に出ることはありません。

Client → Server、サーバー間専用。parallel_replicas_protocol_version ≥ 8 の場合に有効です (VERSIONED_PARALLEL_REPLICAS_PROTOCOL を参照) 。外部クライアントがこのパケットを送信することはありません。

ネゴシエートされた parallel-replicas のバージョンが ≥ 8 の場合、フォロワーの MergeTreeAllRangesAnnouncement (パケットタイプ 15、server→client 方向) に対するイニシエーターのリクエスト/レスポンスサイクルは次のように変わります。

1. フォロワーは自身の read pipeline を開き、MergeTreeAllRangesAnnouncement をイニシエーターに送信します。
2. announcement の mode が Default 以外の場合のみ (WithOrder = 1 または ReverseOrder = 2。いずれも順序付き並列読み取り に使用) 、イニシエーターは MergeTreeAllRangesAnnouncementResponse を返します。mode = Default = 0 の場合、イニシエーターは何も返さず、フォロワーも待機しません。Default モードでは、各 MergeTreeReadTaskRequest ごとに範囲が割り当てられるため、事前のパーツ一覧は不要です。
3. フォロワーは、最初の MergeTreeReadTaskRequest (server パケット 16 — follower→initiator に送信され、イニシエーターは MergeTreeReadTaskResponse (client パケット 10) で応答) を発行する前に、必要な場合はレスポンスを待機します。返されたパーツ一覧を使って、#split_i stream が所有するパーツだけを対象に source の構築を正確に絞り込みます。

バージョン 8 未満では、mode に関係なく announcement は fire-and-forget であり、フォロワーはローカルで認識しているすべてのパーツに対して source を構築します (従来の動作) 。

このセクションでは、ネイティブプロトコル接続の挙動を左右する調整項目について説明します。

• トランスポート層の設定 — TCP ソケットのオプションとタイムアウトで、TCP 接続自体の動作に影響します。
• アプリケーション層の設定 — Query パケットの設定リストで渡されるクエリごとの調整項目で、サーバーが通信上で送信する内容やそのフレーミング方法に影響します。
• 対象外の設定 — プロトコル設定と混同されがちですが、実際には SQL の実行やストレージを制御する設定です。

以下のデフォルト値は最近のサーバーリリースに基づいていますが、バージョンやデプロイ環境によって異なる場合があります。

タイムアウトは次のように入れ子になります:

tcp_keep_alive_timeout (290s)
      < receive_timeout (300s)
      < idle_connection_timeout (3600s)
      < tcp_close_connection_after_queries_seconds (0 = unlimited by default)

OS の keepalive が最初に働き、カーネルレベルで切断されたピアを暗黙のうちに検出できる場合があります。次の防御策は、アプリケーションの受信タイムアウトです。最後の手段として、アイドルタイムアウトが長時間使われていない接続を回収します。

定期的にクエリを発行する接続は、無期限に維持できます。1 時間後に回収されるのはアイドル接続のみで、デフォルトでは接続の最大寿命は設定されていません。

これらの設定は、クエリごとに Query パケットの設定リスト に含まれて送信されます。これにより、サーバーがワイヤ形式で送信する内容や、そのフレーミング方法が変わります。

Query パケット (フィールド 6) の compression フラグは、圧縮のオン/オフを切り替えます。これらの設定では、オンのときに使用するコーデックを選択します。

send_logs_level を "none" 以外に設定すると、サーバーはクエリ実行中に Log パケットを出力します。

これは目標となる最小値であり、厳密な最大値ではありません。クエリの処理の進みが十分に速くない場合、サーバーは Progress パケットの送信頻度をさらに下げることがあります。

これらの設定はプロトコルレベルの設定と誤解されることがありますが、ワイヤ上の挙動ではなく、SQL の実行、ストレージ、または CPU 使用量を制御するものです。プロトコル実装側でこれらを特別に扱う必要はありません。

• max_threads — クエリ実行時の並列度。
• max_memory_usage — クエリごとのメモリ上限。
• max_block_size, preferred_block_size_bytes — クエリ処理中の内部的な block サイズを指定します。ワイヤ上の block はこれらとは独立しています。
• compile_expressions — JIT コンパイル。CPU にのみ影響します。
• async_insert_max_data_size — server-side の queue バッファ。
• input_format_* と output_format_* のすべての設定 (input_format_native_* / output_format_native_* ファミリーは除く) — native 以外のものは、別のフォーマット (たとえば HTTP 経由) を選択または調整するためのものであり、ネイティブプロトコルの Data block は変更しません。

例外は *_native_* 設定です。これらはネイティブ TCP の Data block 内のバイト列を変更するため、プロトコル実装ではそれを考慮する必要があります。output_format_native_encode_types_in_binary_format は column の type フィールドをテキスト文字列からバイナリの型エンコーディングに切り替え、output_format_native_write_json_as_string は JSON カラムを String として出力し、output_format_native_use_flattened_dynamic_and_json_serialization は FLATTENED Dynamic/JSON レイアウトを選択します。これらはパケットのエンベロープではなく block のボディに影響するため、Native Format の仕様で規定されています。詳しくは、column wire layout と versioned types を参照してください。

キャンセル — 実行中のクエリを中止する、クライアント起点のパケット (type 3) です。このページでは詳しく規定していません。

クライアントデータ終端マーカー — 入力ストリームを閉じるためにクライアントが送信する空の Data パケット (0 カラム、0 行) です。その位置はクエリの種類によって異なります。

• 通常のクエリ (SELECT など) : Query パケットと外部テーブル用の Data パケット群の後に送信し、「外部データはこれ以上ない」ことを示します。その後、サーバーが実行を開始します。
• INSERT: クライアントはスキーマ前のマーカーを送信しません。最初にサーバーがスキーマブロックを送信し、次にクライアントが行の Data ブロックをストリーミングし、最後に行ストリームを終了するための空の Data パケットを送信します。スキーマブロックの前に空マーカーを送ると、行がそこで終了したものとして即座に解釈され、データが失われます。

Feature — 特定のプロトコルバージョンで導入されたワイヤ形式の変更です。交渉済みバージョンがその feature のバージョン以上であれば有効になります。versioning and feature gates を参照してください。

Inter-server — サーバー間の distributed queries でのみ意味を持つフィールド用のロールラベルです。外部クライアントはデフォルト値 (通常は空文字列、0、または false) を書き込みます。

交渉済みバージョン — min(client_version, server_version) です。handshake 中に計算されます。これにより、connection の存続期間中にどの features が有効かが決まります。

Packet — ワイヤメッセージです。先頭に VarUInt のパケット type code があり、その後に type に応じたフォーマットのボディが続きます。packet envelope を参照してください。

Packet type code — パケット先頭の VarUInt で、そのフォーマットを識別します。現在は 0–18 の値が割り当てられています。packet type reference を参照してください。

レスポンスストリーム — クエリ実行中にサーバーが出力するパケット列です。長さは未定で、終端は EndOfStream (成功) または Exception (失敗) のどちらか 1 つだけです。query phase を参照してください。

スキーマブロック — INSERT phase 中にサーバーが送信する header block (カラムはあるが 0 行の Block) で、クライアントがデータを送信する前に、想定されるカラム shape を通知するものです。

設定リスト — Query ボディ内の (key, flags, value) tuple の並びで、空の key で終端します。クエリごとのアプリケーション層 configuration を保持します。Setting を参照してください。

Stage — Query パケット内の VarUInt フィールド (field 5) で、サーバーがクエリをどこまで実行するかを制御します。外部クライアントは通常 2 (Complete) を送信し、distributed queries やシリアライズ済みのクエリプランではより大きい値を使用します。wire 値の完全な一覧は Query の field 5 を参照してください。

Terminator — ストリームを終了するパケットです。Query のレスポンスは EndOfStream (成功) または Exception (失敗) で終わります。クライアントの入力ストリームは空の Data マーカーで終わります。