> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 原生客户端数据包

> 原生协议客户端

| 值 | 名称                | 描述      |
| - | ----------------- | ------- |
| 0 | [Hello](#hello)   | 开始客户端握手 |
| 1 | [Query](#query)   | 查询请求    |
| 2 | [Data](#data)     | 含数据的块   |
| 3 | [Cancel](#cancel) | 取消查询    |
| 4 | [Ping](#ping)     | Ping 请求 |
| 5 | TableStatus       | 表状态请求   |

`Data` 包可以压缩。

<div id="hello">
  ## Hello
</div>

例如，我们使用支持 `54451` 协议版本的 `Go Client` v1.10，
并希望使用 `default` 用户和 `secret` 密码连接到 `default` 数据库。

| 字段                | 类型      | 值             | 描述       |
| ----------------- | ------- | ------------- | -------- |
| client\_name      | String  | `"Go Client"` | 客户端实现名称  |
| version\_major    | UVarInt | `1`           | 客户端主版本号  |
| version\_minor    | UVarInt | `10`          | 客户端次版本号  |
| protocol\_version | UVarInt | `54451`       | TCP 协议版本 |
| database          | String  | `"default"`   | 数据库名称    |
| username          | String  | `"default"`   | 用户名      |
| password          | String  | `"secret"`    | 密码       |

<div id="protocol-version">
  ### 协议版本
</div>

协议版本指客户端的 TCP 协议版本。

通常它等于最新的兼容服务器修订版本，但
不要将其与后者混为一谈。

<div id="defaults">
  ### 默认值
</div>

所有值都应**显式设置**，服务端没有默认值。
在客户端，默认使用 `"default"` 数据库、`"default"` 用户名和 `""` (空字符串) 密码。

<div id="query">
  ## 查询
</div>

| 字段              | 类型                    | 值          | 描述              |
| --------------- | --------------------- | ---------- | --------------- |
| query\_id       | String                | `1ff-a123` | 查询 ID，可为 UUIDv4 |
| client\_info    | [客户端信息](#client-info) | 见类型        | 客户端信息           |
| settings        | [设置](#settings)       | 见类型        | 设置列表            |
| secret          | String                | `secret`   | 服务器间共享密钥        |
| [stage](#stage) | UVarInt               | `2`        | 执行至查询阶段         |
| compression     | UVarInt               | `0`        | 禁用=0，启用=1       |
| body            | String                | `SELECT 1` | 查询文本            |

<div id="client-info">
  ### 客户端信息
</div>

| 字段                 | 类型              | 描述                           |
| ------------------ | --------------- | ---------------------------- |
| query\_kind        | byte            | None=0，Initial=1，Secondary=2 |
| initial\_user      | String          | 初始用户                         |
| initial\_query\_id | String          | 初始查询 ID                      |
| initial\_address   | String          | 初始地址                         |
| initial\_time      | Int64           | 初始时间                         |
| interface          | byte            | TCP=1，HTTP=2                 |
| os\_user           | String          | 操作系统用户                       |
| client\_hostname   | String          | 客户端主机名                       |
| client\_name       | String          | 客户端名称                        |
| version\_major     | UVarInt         | 客户端主版本号                      |
| version\_minor     | UVarInt         | 客户端次版本号                      |
| protocol\_version  | UVarInt         | 客户端协议版本                      |
| quota\_key         | String          | 配额键                          |
| distributed\_depth | UVarInt         | Distributed 深度               |
| version\_patch     | UVarInt         | 客户端补丁版本                      |
| otel               | Bool            | 包含 trace 字段                  |
| trace\_id          | FixedString(16) | trace ID                     |
| span\_id           | FixedString(8)  | span ID                      |
| trace\_state       | String          | trace 状态                     |
| trace\_flags       | Byte            | trace 标志                     |

<div id="settings">
  ### 设置
</div>

| 字段        | 类型     | 值                 | 描述     |
| --------- | ------ | ----------------- | ------ |
| key       | String | `send_logs_level` | 设置的键名  |
| value     | String | `trace`           | 设置的值   |
| important | Bool   | `true`            | 是否可以忽略 |

编码为列表，空的 key 和 value 表示列表结束。

<div id="stage">
  ### 阶段
</div>

| 值 | 名称                 | 描述             |
| - | ------------------ | -------------- |
| 0 | FetchColumns       | 仅拉取列类型         |
| 1 | WithMergeableState | 到可合并状态为止       |
| 2 | Complete           | 直到完全完成 (应为默认值) |

<div id="data">
  ## Data
</div>

| 字段      | 类型                    | 描述      |
| ------- | --------------------- | ------- |
| info    | BlockInfo             | 编码后的块信息 |
| columns | UVarInt               | 列数      |
| rows    | UVarInt               | 行数      |
| columns | [\[\]Column](#column) | 带数据的列   |

<div id="column">
  ### 列
</div>

| 字段   | 类型     | 值               | 描述  |
| ---- | ------ | --------------- | --- |
| name | String | `foo`           | 列名  |
| type | String | `DateTime64(9)` | 列类型 |
| data | bytes  | \~              | 列数据 |

<div id="cancel">
  ## Cancel
</div>

无数据包主体。服务器应取消该查询。

<div id="ping">
  ## Ping
</div>

无数据包主体。服务器应[返回 pong](/zh/resources/develop-contribute/native-protocol/server#pong)。