Skip to main content

Basics

🚧 Under construction 🚧

Client protocol reference is in progress.

Most examples are only in Go.

This document describes binary protocol for ClickHouse TCP clients.

Varint

For lengths, packet codes and other cases the unsigned varint encoding is used. Use binary.PutUvarint and binary.ReadUvarint.

note

Signed varint is not used.

String

Variable length strings are encoded as (length, value), where length is varint and value is utf8 string.

caution

Validate length to prevent OOM:

0 ≤ len < MAX

s := "Hello, world!"

// Writing string length as uvarint.
buf := make([]byte, binary.MaxVarintLen64)
n := binary.PutUvarint(buf, uint64(len(s)))
buf = buf[:n]

// Writing string value.
buf = append(buf, s...)
00000000  0d 48 65 6c 6c 6f 2c 20  77 6f 72 6c 64 21        |.Hello, world!|

Integers

tip

ClickHouse uses Little Endian for fixed size integers.

Int32

v := int32(1000)

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

// Decode.
d := int32(binary.LittleEndian.Uint32(buf))
fmt.Println(d) // 1000
00000000  e8 03 00 00 00 00 00 00                           |........|

Boolean

Booleans are represented by single byte, 1 is true and 0 is false.