Работа с ProtobufWorking with Protobuf

Бинарная сериализация компактнее текстовых форматов (нет накладных расходов на разделители, кавычки, повторяющиеся имена полей в каждой строке JSON) и быстрее парсится — на потоке с высокой частотой событий (тики биржи, метрики, логи с тысяч источников) это напрямую снижает нагрузку на сеть и CPU обеих сторон. Строгая типизация схемой `.proto` даёт то, чего CSV не даёт вообще, а JSON даёт лишь частично: контракт между источником и ClickHouse проверяется при генерации кода, а не только при вставке.Binary serialization is more compact than text formats (no overhead from delimiters, quoting, repeated field names on every JSON row) and parses faster — on a high-frequency event stream (exchange ticks, metrics, logs from thousands of sources) that directly cuts network and CPU load on both ends. Strict typing via the `.proto` schema gives something CSV doesn't offer at all and JSON only partially: the contract between the source and ClickHouse is checked at code-generation time, not only at insert time.

Плата за это — схема существует отдельно от данных и должна быть синхронизирована на обеих сторонах: если `.proto`-файл на источнике и файл, который видит ClickHouse, разошлись (устаревшая копия, не тот путь), сериализация/десериализация либо упадёт с ошибкой, либо, что хуже, тихо даст неверные значения (см. грабли).The cost is that the schema lives separately from the data and must stay in sync on both sides: if the `.proto` file on the source and the one ClickHouse sees have diverged (a stale copy, the wrong path), (de)serialization either fails outright or, worse, silently produces wrong values (see gotchas).

ClickHouse не генерирует схему сам — `.proto`-файл пишется вручную (или переиспользуется существующий из проекта-источника) и должен быть физически доступен серверу ClickHouse по пути, заданному настройкой `format_schema_path` (директория) в `config.d/`, плюс сама настройка вставки указывает конкретный файл и сообщение через `<путь_к_файлу>:<ИмяСообщения>`.ClickHouse doesn't generate the schema itself — the `.proto` file is written by hand (or reused from an existing source-side project) and must be physically reachable by the ClickHouse server at the path set via the `format_schema_path` setting (a directory) in `config.d/`, plus the insert itself specifies the exact file and message via `:`.

// trades.proto
syntax = "proto3";

message Trade {
    int64  ts_millis = 1;
    string symbol    = 2;
    double price     = 3;
    double qty       = 4;
}

<!-- config.d/format_schemas.xml -->
<format_schema_path>/var/lib/clickhouse/format_schemas/</format_schema_path>

# вставка через clickhouse-client, файл + сообщение через двоеточие# insert via clickhouse-client, file + message separated by a colon
cat trades.bin | clickhouse-client \
  --query="INSERT INTO trades FORMAT Protobuf SETTINGS format_schema='trades.proto:Trade'"

Соответствие имён полей `.proto`-сообщения и колонок таблицы — по имени, не по номеру поля; порядок объявления в `.proto` не обязан совпадать с `ORDER BY` или порядком колонок таблицы. Числовые тэги полей (`= 1`, `= 2`) важны только для самого протокола Protobuf (обратная совместимость схемы) — ClickHouse их не использует для маппинга на колонки.Matching between `.proto` message fields and table columns is by name, not by field number; declaration order in `.proto` doesn't need to match `ORDER BY` or the table's column order. The numeric field tags (`= 1`, `= 2`) matter only to the Protobuf wire format itself (schema backward compatibility) — ClickHouse doesn't use them for column mapping.

`FORMAT Protobuf` ожидает поток последовательных length-delimited сообщений (стандартный способ упаковать несколько Protobuf-сообщений подряд в один поток байт) — подходит для батч-вставки через CLI/HTTP. `FORMAT ProtobufSingle` — вариант без префикса длины, для случая ровно одного сообщения за раз, что типично для интеграции с Kafka: движок таблицы `Kafka` в ClickHouse читает сообщения топика по одному, и каждое из них уже является отдельной единицей, не частью потока.`FORMAT Protobuf` expects a stream of sequential length-delimited messages (the standard way to pack multiple Protobuf messages back-to-back into one byte stream) — suited to batch insertion via CLI/HTTP. `FORMAT ProtobufSingle` is a variant without the length prefix, for exactly one message at a time, typical for Kafka integration: ClickHouse's `Kafka` table engine reads topic messages one by one, and each is already a standalone unit, not part of a stream.

CREATE TABLE trades_kafka (
    ts_millis Int64,
    symbol    String,
    price     Float64,
    qty       Float64
) ENGINE = Kafka
SETTINGS
    kafka_broker_list = 'kafka1:9092',
    kafka_topic_list = 'trades',
    kafka_group_name = 'clickhouse_trades',
    kafka_format = 'ProtobufSingle',
    format_schema = 'trades.proto:Trade';

Движок `Kafka` — сам по себе не хранилище (аналогично `Distributed`, см. настройку шардов), а источник потока: связка с целевой `MergeTree`-таблицей и `MATERIALIZED VIEW` между ними — стандартный паттерн (`kafka_engine → materialized view → MergeTree`), где именно материализованное представление перекладывает данные из очереди в постоянное хранилище пачками, соблюдая правило батчинга вставок (см. эксплуатацию).The `Kafka` engine isn't storage itself (similar to `Distributed`, see sharding) but a stream source: pairing it with a target `MergeTree` table and a `MATERIALIZED VIEW` in between is the standard pattern (`kafka_engine → materialized view → MergeTree`), where the materialized view is exactly what moves data from the queue into permanent storage in batches, honoring the insert-batching rule (see operations).

• ClickHouse — Protobuf format
• ClickHouse — Kafka engine