基础知识

注意

客户端协议参考文档正在编写中。

目前大部分示例仅提供 Go 语言版本。

本文档描述了 ClickHouse TCP 客户端使用的二进制协议。

Varint

对于长度、数据包代码以及其他场景，采用 无符号 varint 编码。 请使用 binary.PutUvarint 和 binary.ReadUvarint。

注意

有符号 varint 不会被使用。

字符串

可变长度字符串编码为 (length, value)，其中 length 为 varint，value 为 UTF-8 字符串。

参考资料

校验长度以防止 OOM：

0 ≤ len < MAX

编码

s := "Hello, world!"

// 将字符串长度写为 uvarint。
buf := make([]byte, binary.MaxVarintLen64)
n := binary.PutUvarint(buf, uint64(len(s)))
buf = buf[:n]

// 写入字符串内容。
buf = append(buf, s...)

解码

r := bytes.NewReader([]byte{
    0xd, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x2c,
    0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x21,
})

// 读取长度。
n, err := binary.ReadUvarint(r)
if err != nil {
        panic(err)
}

// 检查 n 以防止 OOM 或 make() 运行时异常。
const maxSize = 1024 * 1024 * 10 // 10 MB
if n > maxSize || n < 0 {
    panic("invalid n")
}

buf := make([]byte, n)
if _, err := io.ReadFull(r, buf); err != nil {
        panic(err)
}

fmt.Println(string(buf))
// Hello, world!

十六进制转储

00000000  0d 48 65 6c 6c 6f 2c 20  77 6f 72 6c 64 21        |.Hello, world!|

Base64

DUhlbGxvLCB3b3JsZCE

Go

data := []byte{
    0xd, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x2c,
    0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x21,
}

整数

提示

ClickHouse 对固定大小的整数采用 小端序（Little Endian） 存储。

Int32

v := int32(1000)

// 编码。
buf := make([]byte, 8)
binary.LittleEndian.PutUint32(buf, uint32(v))

// 解码。
d := int32(binary.LittleEndian.Uint32(buf))
fmt.Println(d) // 1000

十六进制转储

00000000  e8 03 00 00 00 00 00 00                           |........|

Base64

6AMAAAAAAAA

布尔值

布尔值使用单个字节表示，1 为 true，0 为 false。