Пакеты нативного клиента

значение	имя	описание
0	Hello	Начало рукопожатия клиента
1	Запрос	Запрос
2	Данные	Блок с данными
3	Cancel	Отмена запроса
4	Ping	Запрос Ping
5	TableStatus	Запрос состояния таблицы

Пакет Data может быть сжат.

Hello

Например, мы используем Go Client v1.10, который поддерживает версию протокола 54451, и хотим подключиться к базе данных default под пользователем default с паролем secret.

поле	тип	значение	описание
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`	Query id, может быть UUIDv4
client_info	ClientInfo	См. тип	Данные о клиенте
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	Идентификатор исходного запроса
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	Глубина распределения
version_patch	UVarInt	Патч-версия клиента
otel	Bool	Поля трассировки присутствуют
trace_id	FixedString(16)	Trace ID
span_id	FixedString(8)	Span ID
trace_state	String	Состояние трассировки
trace_flags	Byte	Флаги трассировки

Настройки

поле	тип	значение	описание
key	String	`send_logs_level`	Ключ настройки
value	String	`trace`	Значение настройки
important	Bool	`true`	Можно игнорировать или нет

Кодируется как список; пустые key и value обозначают конец списка.

Этап

значение	имя	описание
0	FetchColumns	Получить только типы столбцов
1	WithMergeableState	До состояния, пригодного для слияния
2	Complete	До полной готовности (должно использоваться по умолчанию)

Данные

поле	тип	описание
info	BlockInfo	Закодированная информация о блоке
columns	UVarInt	Число столбцов
rows	UVarInt	Число строк
columns	[]Столбец	Столбцы с данными

Столбец

поле	тип	значение	описание
name	String	`foo`	Имя столбца
type	String	`DateTime64(9)`	Тип столбца
data	bytes	~	Данные столбца

Cancel

У пакета нет тела. Сервер должен отменить запрос.

Ping

Без тела пакета. Сервер должен ответить пакетом pong.