原生客户端数据包

View as MarkdownEdit this pageReport an issueSet up docs MCP

值	名称	描述
0	Hello	开始客户端握手
1	Query	查询请求
2	Data	含数据的块
3	Cancel	取消查询
4	Ping	Ping 请求
5	TableStatus	表状态请求

Data 包可以压缩。

Hello

例如，我们使用支持 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"`	密码

协议版本

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

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

默认值

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

查询

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

客户端信息

字段	类型	描述
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 标志

设置

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

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

阶段

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

Data

字段	类型	描述
info	BlockInfo	编码后的块信息
columns	UVarInt	列数
rows	UVarInt	行数
columns	[]Column	带数据的列

列

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

Cancel

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

Ping

无数据包主体。服务器应返回 pong。