原生协议

原生协议是 ClickHouse 客户端和服务器通过 TCP 进行通信时使用的二进制、面向连接的协议。它承载 SQL 查询、结果数据、INSERT 载荷、执行遥测以及错误信号。它也是命令行客户端、C++ 以及大多数第三方原生驱动所使用的底层协议。

本页介绍协议本身：数据包分帧、连接状态机、版本协商，以及每一种非 Block 消息的消息体。Data 家族数据包中的字节 (即 Block、其列以及各类型的编码) 属于另一部分内容，记录在 Native Format 规范中。

该协议始终具有以下几个特性：它是二进制的，并且按位置解析；除 BlockInfo 内部外，没有字段标签，因此只要有一个字节错位，后续所有内容都会失去同步。它是有状态的，并且每个 TCP 连接一次只处理一个查询——不存在多路复用。定长整数采用小端序。

在线上传输的每条消息都以一个 VarUInt 数据包类型编码开头，后面跟着一个消息体，其形态取决于该编码以及协商出的协议版本。

一个连接会经历三个阶段——先进行一次性握手，然后进行任意次数的 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 协议始终以 Native 格式传输表格数据，而不会理会 SQL 中任何 FORMAT 子句。重新格式化为 RowBinary、CSV、JSON 等格式是客户端的工作，这一步会在其解码 Native 块之后完成。 (HTTP interface 则是另一条代码路径，确实会遵循 FORMAT 子句；这里不作讨论。)

TLS 位于传输层，处于协议层之下。启用后，整个 TCP 数据流都会被加密；而无论是否使用 TLS，协议消息在字节级别上都完全一致。

身份验证在握手阶段进行，也就是在 ClientHello 消息中完成。user 和 password 字段会以明文字符串形式传输，因此需要依靠传输层加密 (TLS) 来保护传输中的凭据。

服务器会将空的 user 字段解释为其配置的默认会话用户：即 default_session_user 服务器设置 (其默认值为 default) ，也可能在 protocols 部分中按 listener 被覆盖。如果服务器配置的默认会话用户为空，或者服务器版本早于 26.8，则会以异常拒绝空的 user 字段。请注意，clickhouse-client 从不发送空用户名：它会在客户端将其替换为 default。

从协议版本 54466 开始，支持 SSH 质询-响应身份验证——请参阅 SSH 质询-响应身份验证。

对于分布式查询执行，服务器之间会通过证明自己知晓某个共享密钥来相互进行身份验证，而无需在传输过程中直接发送该密钥。每个 Query 都会在 Query 的字段 4 中携带一个 32 字节的 SHA-256 auth_hash，它根据 salt、nonce、已配置的密钥以及查询内容计算得出，接收服务器会重新计算并进行比对。此功能受 INTERSERVER_SECRET 功能开关 (v54441) 控制。外部客户端在此处始终发送空字符串。请参阅服务器间身份验证。

客户端和服务端都会在握手期间声明其支持的最高协议版本。协商后的版本取两者中较小者：

negotiated_version = min(client_version, server_version)

此后的每条消息都会使用协商出的版本来决定传输时包含哪些字段。

每项功能都以引入它的协议版本作为标识；当协商出的版本大于或等于该版本号时，该功能即处于生效状态。

在线上传输的每条消息，无论哪个方向，其外层结构都相同：

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

完整的数据包类型表见数据包类型参考。

数据包类型是 VarUInt，而不是定宽字节。对于小于 128 的值，VarUInt 产生的仍然是相同的单个字节，但实现必须使用 VarUInt 编码，以确保当未来的数据包类型达到 128 或更大时仍能保持兼容。

消息参考仅说明每个数据包的 包体 —— 即位于数据包类型代码之后的字节。字段编号从 1 开始，包体中的第一个字段编号为 1。

当 CHUNKED_PROTOCOL 功能协商完成后 (参见握手) ，线路上传输的每个数据包都会使用分块帧进行封装。这种封装是按方向分别进行的：client→server 和 server→client 会分别协商，最终可能采用不同的模式 (分块或无帧封装) 。

每个数据包在线路上的布局：

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

每个 chunk 的线格式：

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

VarUInt 数据包类型位于分块流 内部：它是数据包载荷的第一个字节 (即第一个 chunk 的第一个字节) ，而不是在分帧之前单独提前发送的一个字节。每个数据包的 chunk 载荷都是来自数据包封装的完整 [VarUInt packet_type_code][message body]。如果客户端把数据包类型放在分块流之外，对端就会把这个类型字节当作 u32 chunk 大小的第一个字节来读取，导致连接失去同步。

如果写入端的缓冲区在数据包中途写满，单个数据包可以拆分到多个 chunk 中；拆分点可以出现在任何位置，包括数据包类型的 VarUInt 内部。读取端会拼接各个 chunk 载荷，并将末尾的 4 字节零值视为透明的数据包边界——它会将其消费掉，但不会把它暴露给负责读取数据包消息体的逻辑。

没有消息体的数据包仍然会被封装：像 Ping 或 Pong 这样的单字节数据包，在协商启用分块后会变成 [u32 size = 1][0x04][u32 0]。本页其他地方任何“在线路上是单字节”的描述，指的都是分块前的形式。

协商。 ServerHello 和 Addendum 各自携带两个 String 字段，每个方向一个，取值来自 {"chunked", "notchunked", "chunked_optional", "notchunked_optional"}：

• chunked / notchunked 是严格模式：该方向要求必须精确使用该模式。
• _optional 变体是灵活的：它们接受对端选择的任意模式。

每个方向的最终协商值按双方成对计算：

在客户端一侧，客户端的 SEND 偏好会与服务端的 RECV 偏好协商，反之亦然。

时序。 这些协商字符串通过未分帧的线路传输：ClientHello → ServerHello (服务端偏好) → Addendum (客户端的协商结果值) 。分帧模式切换适用于 Addendum 被刷出 之后 发送的每一个字节。Addendum 本身、ClientHello 和 ServerHello 始终不分帧。

在任何时刻，连接都只会处于以下四种状态之一：HANDSHAKE、READY、READING_RESPONSE，或已终止。由于该协议不支持多路复用，如果客户端在尚未读取完上一个响应之前就发送新请求，就会导致传输中的字节交错，从而破坏数据流。

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. 客户端读取响应，并根据数据包类型进行分发处理：

   数据包类型	操作
   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. 客户端读取响应：

   数据包类型	操作
   Pong (4)	确认存活，返回到 READY。
   Exception (2)	解码 Exception，并将其作为错误返回。
   其他任何类型	协议违规。

客户端提交一条 SQL 语句；服务器以流式方式返回结果块和执行遥测信息。响应由一系列数据包组成，并且恰好以一个 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

如果在任意阶段发生错误，服务端会发送 Exception 而不是 EndOfStream，从而终止查询。

1. 客户端发送带有唯一 query_id (通常为 UUID) 的 Query。

2. 客户端发送所有外部表，然后发送空的 Data 标记。空 Data 数据包的字段为 table_name = ""、num_columns = 0、num_rows = 0。服务端在收到此标记之前不会开始执行查询。

3. 客户端进入 READING_RESPONSE，并刷写其写入缓冲区。

4. 客户端在循环中读取响应数据包，并按类型分发处理：

   数据包类型	Action
   Data (1)	解码该块。第一个 Data 是 schema 头；后续的是结果块 (累积) ；空块是边界标记。num_rows == 0 不是 查询结束。
   Progress (3)	执行指标。每个数据包都是相对于前一个数据包的增量——在本地累积。
   EndOfStream (5)	查询完成。退出循环并返回 READY。
   ProfileInfo (6)	执行后的 profiling 数据。
   Totals (7)	aggregation totals 块 (与 Data 相同的传输格式) 。
   Extremes (8)	最小/最大值块 (与 Data 相同的传输格式) 。
   Log (10)	服务端日志行。
   TableColumns (11)	列默认值 metadata。
   ProfileEvents (14)	性能计数器。
   Exception (2)	解码后作为错误返回。退出循环并返回 READY。
   anything else	在查询阶段属于异常情况。终止连接。

收到 EndOfStream 或已处理的 Exception 后，连接会返回 READY。如果发生协议违规或 I/O 错误，连接会被终止。

INSERT 阶段是在查询阶段的基础上增加了两次额外的交互。客户端提交一条 INSERT 语句；服务器返回一个描述目标表的 schema 块；客户端随后以流式方式发送包含这些行的 Data packets，再发送空的 Data 标记；最后，服务器以 EndOfStream 或 Exception 结束。

从 READY 状态开始，SQL 采用如下形式的 INSERT：INSERT INTO <table> [(<cols>)] VALUES —— 不包含内联的 VALUES (...) 字面量，因为行数据是通过 Data packets 传输的。流程如下：

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。
2. 客户端发送所有外部表 (这种情况在 INSERT 中较少见) 。与 查询 phase 不同，这里不会发送空的 Data 标记。INSERT 的 查询 数据包会连同待发送的数据一起发出，因此表示数据结束的空数据块会推迟到步骤 5；如果在 schema 块之前发送它，服务器会将其视为行流结束，从而以 0 行完成 INSERT，随后再把第一个真实的行数据包解析为一个游离的顶层数据包。
3. 客户端持续读取元数据包 (TableColumns、Progress、ProfileInfo、Log、ProfileEvents) ，直到读到 schema Data 数据包——这是一个 0 行但包含完整列结构 (名称和类型) 的 Block。schema 块就是约定：客户端接下来发送的行必须符合这些列的形态。
4. 客户端发送一个或多个数据块。对于每个块，它都会先写入 VarUInt(ClientPacket::Data = 2)，然后写入表示空外部表名称的 String("")，接着写入 Block。列类型必须按位置与 schema 块中的列对齐。
5. 客户端发送输入结束标记：一个带空 Block (0 列、0 行) 的 Data 数据包。
6. 客户端持续读取响应流，直到 EndOfStream (成功) 或 Exception (失败) 。

异步 INSERT (v54484+) 。 当查询带有 async_insert = 1 时，服务器会将这些行放入队列，并作为某个批次的一部分进行刷写。在协商版本 ≥ 54484 (PROGRESS_IN_ASYNC_INSERT) 时，一旦刷写完成，服务器会额外发出一个 Progress 数据包，紧接着发送该次 insert 的 ProfileEvents，然后是 EndOfStream。在 54484 以下，服务器会跳过这个尾部的 Progress。该数据包是一个普通的 Progress；由于服务器在合并写入计数前会重置查询管道，因此其中的增量实际上只包含已用时间，而写入行数和字节统计则通过随附的 ProfileEvents 传递给客户端。对于已经在步骤 6 中处理交错 Progress 的客户端，只需再接受一个额外的数据包即可。

连接在收到 EndOfStream 或已处理的 Exception 后会返回 READY。协议违规和 I/O 错误会终止连接。

各字段按 wire 顺序列出。Type 列使用：

• VarUInt — 可变长度无符号整数 (参见 VarUInt) 。
• String — 以 VarUInt 为前缀的字节序列 (参见 String) 。
• UInt8、Int32 等 — 固定宽度的小端序整数。
• Bool — 单个字节，0x00 或 0x01。

Role 列说明每个字段由谁使用：

• client — 由外部客户端设置。
• inter-server — 仅对服务器之间的通信有意义；外部客户端写入默认值。
• universal — 两者都会使用。

这些表仅记录每个数据包的包体，即位于数据包类型代码之后的部分。

客户端 → 服务器。TCP 连接建立后发送的第一条消息。

服务器 → 客户端。对 ClientHello 在身份验证成功后的响应。

Rule — password_complexity_rules 中的一个元素：

该列表反映 server operator 配置的密码策略，仅起提示作用——server 不会在握手期间强制执行这些规则。提供密码修改/设置功能的客户端可利用这些规则，在将不合规密码发送给 server 之前先提示错误。

客户端 → 服务器，受 ADDENDUM (v54458) 控制。在握手交换完成后立即发送。它不是一种独立的数据包类型——这些字段会以原始形式直接在传输中发送，前面不带数据包类型字节前缀。

分块帧格式的切换会在此附加信息写出后才生效——附加信息本身不带帧封装。

客户端 → 服务器。无消息体——在分块成帧之前，该数据包仅为单个字节 0x04；协商启用分块后，该字节会成为一个块的单字节载荷 (参见 分块成帧) 。

服务器 → 客户端。无消息体——在采用分块帧之前，该数据包仅为单个字节 0x04；协商启用分块传输后，该字节会作为某个分块的单字节载荷 (参见分块成帧) 。

服务器 → 客户端。当服务器在任意阶段发生错误时发送。

客户端 → 服务器。

客户端 → 服务器，嵌入在 查询 体 (字段 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) 不是在线路上传输的共享集群 secret。发送原始密钥不仅会导致身份验证失败，还会泄露密钥。相反，作为服务器间客户端的服务端会使用加盐的 SHA-256 哈希来证明自己知道该密钥：

1. 进入服务器间模式。 发起连接的服务端会在 ClientHello 中表明这一点：user 字段是服务器间标记，password 为空。然后，它会在同一个 ClientHello 数据包中，紧接 user/password 字段之后再附加两个字符串——cluster 名称，以及一个新生成的 32 字节 salt (随机值的 encodeSHA256) 。服务端会在发送 ServerHello 之前读取这两个字符串，因此客户端必须预先写入它们；如果先等待 ServerHello，就会发生死锁，因为服务端会阻塞并等待读取这两个字符串。
2. 获取 nonce。 当协商了 INTERSERVER_SECRET_V2 (v54462) 时，ServerHello 会携带一个 8 字节的 UInt64 nonce。
3. 计算哈希。 对于每个非 InitialQuery 的 Query 数据包，客户端会将 encodeSHA256(salt + nonce + cluster_secret + query + query_id + initial_user + external_roles + current_roles) 写入第 4 个字段——即一个 32 字节摘要。 (nonce 是其十进制字符串形式，仅在协商版本 ≥ v54462 时存在；external_roles 仅在协商了 INTERSERVER_EXTERNALLY_GRANTED_ROLES (v54472) 时附加；current_roles 是序列化的角色名称列表——[VarUInt count][String]*count，不含存在字节——仅在协商了 INTERSERVER_CURRENT_ROLES (v54488) 且该列表存在时附加。) 对于 InitialQuery，或者在未配置集群 secret时，客户端则会写入空字符串。
4. 验证。 服务端会以 32 字节上限读取第 4 个字段，并使用自己持有的集群 secret副本重新计算相同的拼接内容；如果摘要不同，则会拒绝该连接。

外部 (非服务器间) 客户端永远不会进入此模式，并且始终发送空的 auth_hash。

以内联方式编码在 Query body 的 settings 列表中 (Query 数据包的第 3 个字段) 。无论协商出的版本是什么，该列表都始终存在，并以一个 key 为空的 Setting 结尾——即单个 VarUInt 0，后面不再跟任何 flags 或 value。只有单个 setting 的编码方式取决于协商版本，并受 SETTINGS_SERIALIZED_AS_STRINGS (v54429) 控制。

v54429+ (STRINGS_WITH_FLAGS) — 每个 setting 都是如下所示的三元组：

当 key 为空时，字段 2 和 3 不存在。

Pre-54429 (BINARY) — 每个 setting 的编码形式为 [String key][特定类型的二进制值]：不会写入 flags 字段，value 也会按该 setting 的原生二进制形式编码 (例如定宽整数或带长度前缀的字符串) ，而不是编码为十进制/文本字符串。该列表仍以空 key 结尾。以低于 54429 的协商版本为目标的 client，必须读写这种二进制形式，而不是上面的三元组。 (自定义 setting 属于例外：无论哪种编码，它们始终都带有 flags 和字符串 value。)

flags 字段包含：

• 0x01 — Important：该 setting 会影响查询结果，旧版 peer 不得静默忽略它。
• 0x02 — Custom：用户定义的自定义 setting。
• 0x0c — 一个 2 位层级 字段，而非独立 flag：0x00 = Production，0x04 = Obsolete，0x08 = Experimental，0x0c = Beta。应读取完整 2 位 (flags & 0x0c) ——如果简单测试 flags & 0x04，会把 Beta (0x0c) 误判为 Obsolete。
• 0x80 — HotReload (无需重启即可重载 config；在 flags 枚举中定义，主要见于协调 settings) 。

查询参数，用于参数化查询，例如 SELECT {x:UInt64}。其编码方式与设置了 Custom 标志 (0x02) 的 Setting 完全相同，并同样以空 key 作为结束标记。

两个方向均使用此类型。它承载结果块、INSERT 数据、外部表以及数据结束标记。

传输格式是对称的——两个方向都会在块前包含一个 table_name 前缀。只有数据包类型字节不同。

[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

数据结束标记是指 Block 为空的数据包——即 0 列和 0 行——与 table_name 的值无关。只有当解码后的块为空 (block.empty()) 时，服务器才会将客户端的 Data 数据包视为终止符；带有 table_name = "" 且块非空的数据包只是普通的行数据包，并非终止符。因此，INSERT 行流由一系列非空 Data 块组成，最后以一个空的 Data 块结束。

有关块的各种变体及其含义，请参见 块变体。

服务器 → 客户端。在查询执行期间定期发送。所有字段均为 VarUInt，并且每个数据包携带的都是自上一个 Progress 数据包以来的增量，而非累计总数。发送前，服务器会读取其计数器，并以原子方式将其重置为零，同时将 elapsed_ns 计算为自上次发送以来的时间差。因此，客户端必须在本地累加后续收到的数据包，才能得到持续更新的总数——如果把某个数据包当作绝对值，一旦收到多个数据包，进度显示就会回跳或少计。

服务器 → 客户端。每个查询发送一次，通常在执行接近结束时发送。

服务器 → 客户端。对于包含 WITH TOTALS 的查询，会发送此数据包。其传输格式与 Data 完全一致：一个 table_name 字符串 (始终为空) ，后面跟着一个块。不同之处仅在于数据包类型字节。

[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 相同。该块的 num_columns = 8 为固定值，并具有预定义的 schema。每条日志记录对应一行，分布在全部 8 列中；单个日志数据包可携带多行。

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

这 8 列的顺序必须严格如下：

Server → Client。携带每个查询的性能计数器。

其封套和 body 格式与 Data 相同。该块的 num_columns = 6 为固定值，并具有预定义的 schema。每个事件对应一行。

[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) 控制。server 会在 INSERT schema 块之前发送该数据包，用于携带列默认值元数据，但仅当协商版本 ≥ 54410 且 启用了 input_format_defaults_for_omitted_fields setting 时才会发送。低于 54410 时，该数据包绝不会发送，因此较旧的 client 不得 等待它——schema Data 块会直接到来。v54410+ 的 client 应准备好处理任意一种顺序：先收到可选的 TableColumns，然后是 schema 块。

Server → Client，由 TIMEZONE_UPDATES (v54464) 控制。它只在一个地方发送：input 表函数的初始化器中 (即形如 INSERT INTO <table> SELECT ... FROM input('<structure>') 的查询，会从客户端流式传输行) 。服务器发送输入 schema 的 Data 块后 (见INSERT 阶段) ，会立即发出 TimezoneUpdate，携带查询上下文当前的 session_timezone，以便客户端用相同的时区解析接下来要发送的行。对于查询执行过程中任意的 SET session_timezone 变更，服务器不会发送此数据包；它也不会用这个数据包告诉客户端如何格式化后续返回的结果块。

该数据包只会到达一次：紧接在输入 schema 块之后，且在客户端开始发送行块之前。即使解码器忽略 TimezoneUpdate，也必须继续读取后面的 String，以保持线协议对齐。

受 SSH_AUTHENTICATION (v54466) 控制，且默认不启用，需显式选择启用。当 ClientHello 发送 user = " SSH KEY AUTHENTICATION " + <real_user> (包含前导和尾随空格) 以及 password = "" 时，连接会进入 SSH 流程。服务器会读取此前缀，将其剥离以还原真实用户名，然后切换到质询-响应模式。

此流程会替代密码身份验证，并且质询-响应交换发生在 ServerHello 之前——服务器会推迟发送 Hello 回复，直到身份验证成功：

1. 客户端发送带有 SSH 标记前缀且密码为空的 ClientHello。

2. 客户端发送 SSHChallengeRequest (packet 11) 。此时服务器 尚未发送 ServerHello——它会先处理身份验证，并在此阻塞等待该 packet。

3. 服务器回复 SSHChallenge，携带随机字节 (packet 18) 。

4. 客户端构建待签名字符串，并对该字符串进行签名，而不是对原始 challenge 进行签名，然后发送携带签名的 SSHChallengeResponse (packet 12) 。签名消息是以下四个部分按字节拼接的结果，不带任何分隔符，并且严格按以下顺序排列：

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

   Part	Source
   decimal(protocol_version)	客户端的协议版本，以十进制 ASCII 字符串表示 (例如 "54466") ——版本号是字符串形式，而不是 VarUInt 或定宽整数。服务器会使用其在 ClientHello 中收到的同一协议版本进行校验。
   default_database	ClientHello 中的 database field (如果没有则为空字符串) 。
   user	剥离 " SSH KEY AUTHENTICATION " 标记前缀后的真实用户名——也就是服务器在去掉此前缀后还原出的同一个名称。
   challenge	来自 SSHChallenge packet 的原始 challenge 字节。

5. 服务器使用该用户已注册的 public key 验证签名，并重建相同的 decimal(protocol_version) + default_database + user + challenge 字符串。成功后，它会发送 ServerHello——与密码流程中的回复相同——随后 handshake 将正常继续 (Addendum 等) ；失败时，它会返回 Exception 并终止连接。仅对原始 challenge 字节签名的客户端将无法通过身份验证。

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 认证的外部客户端永远不会看到数据包 11、12 或 18——除非用户通过用户名此前缀显式选择启用，否则这些数据包不会在线路上传输。

客户端 → 服务器，仅用于服务器间通信。仅在 parallel_replicas_protocol_version ≥ 8 时可用 (参见 VERSIONED_PARALLEL_REPLICAS_PROTOCOL) 。外部客户端绝不会发送此数据包。

当协商出的 parallel-replicas 版本为 ≥ 8 时，发起端针对跟随者的 MergeTreeAllRangesAnnouncement (数据包类型 15，server→client 方向) 的请求/响应流程会发生变化：

1. 跟随者打开其读取管道，并向发起端发送 MergeTreeAllRangesAnnouncement。
2. 仅当通知中的 mode 不是 Default (WithOrder = 1 或 ReverseOrder = 2，两者都用于按序并行读取) 时，发起端才会回复 MergeTreeAllRangesAnnouncementResponse。对于 mode = Default = 0，发起端会保持静默，而跟随者也不会等待——Default 模式会在每个 MergeTreeReadTaskRequest 中分发 range，且永远不需要预先提供的分片列表。
3. 跟随者会在发出第一个 MergeTreeReadTaskRequest (服务器数据包 16——由 follower→initiator 发送；发起端则回复 MergeTreeReadTaskResponse，客户端数据包 10) 之前阻塞等待响应 (如果预期会有响应) ，并使用返回的分片列表，将 source 的构建范围过滤到恰好由其 #split_i stream 拥有的分片。

在版本 8 以下，无论 mode 如何，该通知都是发出即忘，而跟随者会基于本地已知的每个分片构建 source (这是 legacy behaviour) 。

本节介绍会影响原生协议连接形态的可调参数：

• 传输层设置 — TCP 套接字选项和超时，它们会影响 TCP 连接本身的行为。
• 应用层设置 — 按查询配置的可调参数，这些参数包含在 Query packet 的 settings 列表 中，会影响服务器在线路上传输的内容或其分帧方式。
• 不在此范围内的设置 — 这些设置常被误认为是协议设置，但实际上控制的是 SQL 执行或存储。

下方的默认值反映的是较新的服务器版本；它们可能因版本和部署而异。

这些超时的嵌套关系如下：

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

操作系统的 keepalive 会最先生效，并且可能在内核层静默检测到失效的对端。应用程序的接收超时是下一道防线。空闲超时则是最后一道手段，用于回收长时间未使用的连接。

只要连接持续定期发出查询，就可以无限期保持存活。只有空闲连接会在一小时后被回收，且默认不设最大生命周期限制。

这些设置会随每个查询一起，通过Query 数据包的 settings 列表传递。它们会改变服务器在线上传输的数据内容，或其分帧方式。

Query 数据包 (字段 6) 中的 compression 标志位用于开启或关闭压缩；这些设置用于选择开启压缩时使用的编解码器。

将 send_logs_level 设为除 "none" 之外的任意值时，服务器会在查询执行期间发送 日志 数据包。

这是目标最小值，而非严格的最大值：如果查询生成工作的速度不够快，服务器发送 Progress 数据包的频率可能会更低。

这些设置有时会被误认为是协议级设置，但它们控制的是 SQL 执行、存储或 CPU 使用，而不是线上传输行为。协议实现不需要对它们做特殊处理。

• max_threads — 查询执行期间的并行度。
• max_memory_usage — 单个查询的内存上限。
• max_block_size, preferred_block_size_bytes — 查询处理期间的内部块大小；线上传输的块不受这些设置影响。
• compile_expressions — JIT 编译；仅影响 CPU。
• async_insert_max_data_size — 服务端队列缓冲区。
• 所有 input_format_* 和 output_format_* 设置，除了 input_format_native_* / output_format_native_* 家族 —— 非 native 设置用于选择或调整其他格式 (例如通过 HTTP) ，不会改变原生协议的 Data 块。

*_native_* 设置是个例外：它们会改变原生 TCP Data 块中的字节，因此协议实现必须将其考虑在内。output_format_native_encode_types_in_binary_format 会将列的 type 字段从文本字符串切换为二进制类型编码，output_format_native_write_json_as_string 会将 JSON 列输出为 String，而 output_format_native_use_flattened_dynamic_and_json_serialization 则会选择 FLATTENED Dynamic/JSON 布局。由于这些设置影响的是块体而非数据包封装，因此它们在 Native Format 规范中定义——请参见列在线路上的布局和带版本的类型。

Cancel — 由客户端发起的数据包 (类型 3) ，用于中止正在运行的查询。本页未对此作详细说明。

客户端数据结束标记 — 客户端发送的空 Data 数据包 (0 列、0 行) ，用于关闭输入流。其所在位置因查询类型而异：

• 普通查询 (SELECT 等) ： 在 Query 数据包以及所有外部表 Data 数据包之后发送，用于表示“没有更多外部数据”。随后服务器开始执行。
• INSERT： 客户端不会发送 schema 之前的标记。服务器会先发送 schema 块，客户端再流式传输其行 Data 块，最后才发送空 Data 数据包来终止行流。如果在 schema 块之前发送空标记，服务器会将其视为行已立即结束，从而导致数据丢失。

特性 — 在特定协议版本中引入的一项线格式变更。当协商后的版本大于或等于该特性对应的版本时生效。参见版本控制与特性门控。

Inter-server — 某个字段的角色标签，仅在服务器到服务器的分布式查询中有意义。外部客户端会写入默认值 (通常为空字符串、0 或 false) 。

协商版本 — min(client_version, server_version)，在握手期间计算得出。它决定了在连接的整个生命周期内哪些特性处于激活状态。

数据包 — 一条线上传输消息：以 VarUInt 数据包类型代码开头，后接一个 body，其格式取决于类型。参见数据包封装。

数据包类型代码 — 数据包开头的 VarUInt，用于标识其格式。目前 0–18 的值已分配。参见数据包类型参考。

响应流 — 服务器在查询期间发出的数据包序列。其长度不定，并且恰好以一个 EndOfStream (成功) 或 Exception (失败) 结束。参见查询阶段。

Schema 块 — INSERT 阶段中服务器发送的头部块 (即一个有列但 0 行的 Block) ，用于在客户端发送数据前声明预期的列形态。

Settings 列表 — Query body 中由 (key, flags, value) 元组组成的序列，以空 key 终止。它承载每个查询的应用层配置。参见 Setting。

Stage — Query 数据包中的一个 VarUInt 字段 (字段 5) ，用于控制服务器将查询执行到什么程度。外部客户端通常发送 2 (Complete) ；分布式查询和序列化查询计划会使用更高的值。完整的线传输取值请参见 Query 的字段 5。

终止符 — 用于结束流的数据包。Query 响应以 EndOfStream (成功) 或 Exception (失败) 结束。客户端的输入流则以空 Data 标记结束。