Protobuf

Ввод	Вывод	Псевдоним
✔	✔

Описание

Формат Protobuf — это формат Protocol Buffers. Для этого формата требуется внешняя схема, которая кэшируется между запросами. ClickHouse поддерживает:

оба синтаксиса: proto2 и proto3.
поля Repeated/optional/required.

Чтобы установить соответствие между столбцами таблицы и полями типа сообщения Protocol Buffers, ClickHouse сравнивает их имена. Это сравнение регистронезависимо, а символы _ (подчёркивание) и . (точка) считаются эквивалентными. Если типы столбца и поля сообщения Protocol Buffers различаются, применяется необходимое преобразование. Поддерживаются вложенные сообщения. Например, для поля z в следующем типе сообщения:

message MessageType {
  message XType {
    message YType {
      int32 z;
    };
    repeated YType y;
  };
  XType x;
};

ClickHouse пытается найти столбец с именем x.y.z (или x_y_z, X.y_Z и так далее). Вложенные сообщения подходят для ввода и вывода вложенных структур данных. Для сопоставленных полей, отсутствующих в передаваемых данных:

Обычные не допускающие NULL сопоставленные столбцы при разборе используют значение по умолчанию поля из схемы protobuf (proto2 [default = …], в противном случае — значение по умолчанию типа), а не выражение DEFAULT таблицы.
Сопоставленные столбцы Nullable(...) получают значение NULL, если поле отсутствует (они не используют значение по умолчанию поля или типа protobuf).
Если для обёрток google.protobuf.*Value включён SETTING input_format_protobuf_flatten_google_wrappers:
- отсутствующая обёртка в столбце Nullable(...) рассматривается как отсутствующее внешнее поле и становится NULL;
- присутствующая, но пустая обёртка (str {}) сохраняет значение по умолчанию вложенного скаляра ('' / 0);
- не допускающий NULL столбец, сопоставленный с отсутствующей обёрткой, получает значение по умолчанию вложенного скаляра, а не NULL.

DEFAULT таблицы (и выражения по умолчанию) применяются к столбцам таблицы, для которых нет соответствующего поля в типе сообщения, если включён SETTING input_format_defaults_for_omitted_fields (по умолчанию). Если значение этого SETTING равно 0, несопоставленные столбцы сохраняют значение по умолчанию типа данных, вставленное во время разбора, вместо выражения DEFAULT таблицы. Пример значения по умолчанию поля схемы proto2 (используется для сопоставленного поля, отсутствующего в сообщении):

syntax = "proto2";

message MessageType {
  optional int32 result_per_page = 3 [default = 10];
}

Если сообщение содержит oneof и задан SETTING input_format_protobuf_oneof_presence, ClickHouse заполняет столбец, указывающий, какое поле oneof присутствует в сообщении.

syntax = "proto3";

message StringOrString {
  oneof string_oneof {
    string string1 = 1;
    string string2 = 42;
  }
}

CREATE TABLE string_or_string ( string1 String, string2 String, string_oneof Enum('no'=0, 'hello' = 1, 'world' = 42))  Engine=MergeTree ORDER BY tuple();
INSERT INTO string_or_string from INFILE '$CURDIR/data_protobuf/String1' SETTINGS format_schema='$SCHEMADIR/string_or_string.proto:StringOrString' FORMAT ProtobufSingle;
SELECT * FROM string_or_string

   ┌─────────┬─────────┬──────────────┐
   │ string1 │ string2 │ string_oneof │
   ├─────────┼─────────┼──────────────┤
1. │         │ string2 │ world        │
   ├─────────┼─────────┼──────────────┤
2. │ string1 │         │ hello        │
   └─────────┴─────────┴──────────────┘

Имя столбца, указывающего на наличие, должно совпадать с именем oneof. Вложенные сообщения поддерживаются (см. basic-examples). Пустые сообщения тоже поддерживаются. Допустимые типы: Int8, UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Enum, Enum8 или Enum16. Enum (а также Enum8 или Enum16) должен содержать 0 для обозначения отсутствия и тег каждого варианта oneof, имеющего соответствующий столбец в целевой таблице; строковые представления значения не имеют. Для членов сообщения oneof без соответствующих столбцов таблицы также допускается отсутствие тегов Enum. Если такой вариант присутствует во входных данных, ClickHouse считает наличие oneof неуказанным и записывает 0 в столбец наличия. По умолчанию SETTING input_format_protobuf_oneof_presence отключена ClickHouse принимает и выводит protobuf-сообщения в формате с префиксом длины. Это означает, что перед каждым сообщением его длина должна быть записана как целое число переменной длины (varint).

Пример использования

Чтение и запись данных

Файлы примераФайлы, используемые в этом примере, доступны в репозитории с примерами

В этом примере мы прочитаем данные из файла protobuf_message.bin в таблицу ClickHouse. Затем запишем их обратно в файл protobuf_message_from_clickhouse.bin в формате Protobuf. Дан файл schemafile.proto:

syntax = "proto3";

message MessageType {
  string name = 1;
  string surname = 2;
  uint32 birthDate = 3;
  repeated string phoneNumbers = 4;
};

Создание двоичного файла

Если вы уже знаете, как сериализовать и десериализовать данные в формате Protobuf, можете пропустить этот шаг.Мы будем использовать Python, чтобы сериализовать данные в protobuf_message.bin и загрузить их в ClickHouse. Если вы хотите использовать другой язык, см. также: “Как читать и записывать Protobuf-сообщения с префиксом длины на популярных языках”.Выполните следующую команду, чтобы создать Python-файл с именем schemafile_pb2.py в том же каталоге, что и schemafile.proto. Этот файл содержит Python-классы, представляющие ваше Protobuf-сообщение UserData:

protoc --python_out=. schemafile.proto

Теперь создайте новый Python-файл с именем generate_protobuf_data.py в том же каталоге, что и schemafile_pb2.py. Вставьте в него следующий код:

import schemafile_pb2  # Модуль, созданный с помощью 'protoc'
from google.protobuf import text_format
from google.protobuf.internal.encoder import _VarintBytes # Импортируем внутренний кодировщик varint

def create_user_data_message(name, surname, birthDate, phoneNumbers):
    """
    Создает и заполняет Protobuf-сообщение UserData.
    """
    message = schemafile_pb2.MessageType()
    message.name = name
    message.surname = surname
    message.birthDate = birthDate
    message.phoneNumbers.extend(phoneNumbers)
    return message

# Данные пользователей для этого примера
data_to_serialize = [
    {"name": "Aisha", "surname": "Khan", "birthDate": 19920815, "phoneNumbers": ["(555) 247-8903", "(555) 612-3457"]},
    {"name": "Javier", "surname": "Rodriguez", "birthDate": 20001015, "phoneNumbers": ["(555) 891-2046", "(555) 738-5129"]},
    {"name": "Mei", "surname": "Ling", "birthDate": 19980616, "phoneNumbers": ["(555) 956-1834", "(555) 403-7682"]},
]

output_filename = "protobuf_messages.bin"

# Открываем двоичный файл в режиме двоичной записи ('wb')
with open(output_filename, "wb") as f:
    for item in data_to_serialize:
        # Создаем экземпляр Protobuf-сообщения для текущего пользователя
        message = create_user_data_message(
            item["name"],
            item["surname"],
            item["birthDate"],
            item["phoneNumbers"]
        )

        # Сериализуем сообщение
        serialized_data = message.SerializeToString()

        # Получаем длину сериализованных данных
        message_length = len(serialized_data)

        # Используем внутреннюю функцию _VarintBytes из библиотеки Protobuf для кодирования длины
        length_prefix = _VarintBytes(message_length)

        # Записываем префикс длины
        f.write(length_prefix)
        # Записываем сериализованные данные сообщения
        f.write(serialized_data)

print(f"Protobuf messages (length-delimited) written to {output_filename}")

# --- Необязательно: проверка (чтение и вывод) ---
# Для чтения мы также используем внутренний декодер varint из Protobuf.
from google.protobuf.internal.decoder import _DecodeVarint32

print("\n--- Verifying by reading back ---")
with open(output_filename, "rb") as f:
    buf = f.read() # Считываем весь файл в buffer для более простого декодирования varint
    n = 0
    while n < len(buf):
        # Декодируем varint-префикс длины
        msg_len, new_pos = _DecodeVarint32(buf, n)
        n = new_pos

        # Извлекаем данные сообщения
        message_data = buf[n:n+msg_len]
        n += msg_len

        # Разбираем сообщение
        decoded_message = schemafile_pb2.MessageType()
        decoded_message.ParseFromString(message_data)
        print(text_format.MessageToString(decoded_message, as_utf8=True))

Теперь запустите скрипт из командной строки. Рекомендуется запускать его в виртуальном окружении Python, например с помощью uv:

uv venv proto-venv
source proto-venv/bin/activate

Вам потребуется установить следующие Python-библиотеки:

uv pip install --upgrade protobuf

Запустите скрипт, чтобы создать двоичный файл:

python generate_protobuf_data.py

Создайте таблицу ClickHouse, соответствующую схеме:

CREATE DATABASE IF NOT EXISTS test;
CREATE TABLE IF NOT EXISTS test.protobuf_messages (
  name String,
  surname String,
  birthDate UInt32,
  phoneNumbers Array(String)
)
ENGINE = MergeTree()
ORDER BY tuple()

Вставьте данные в таблицу с помощью командной строки:

cat protobuf_messages.bin | clickhouse-client --query "INSERT INTO test.protobuf_messages SETTINGS format_schema='schemafile:MessageType' FORMAT Protobuf"

Вы также можете записать данные обратно в двоичный файл в формате Protobuf:

SELECT * FROM test.protobuf_messages INTO OUTFILE 'protobuf_message_from_clickhouse.bin' FORMAT Protobuf SETTINGS format_schema = 'schemafile:MessageType'

Имея схему Protobuf, теперь вы можете десериализовать данные, записанные ClickHouse в файл protobuf_message_from_clickhouse.bin.

Чтение и запись данных с помощью ClickHouse Cloud

В ClickHouse Cloud нельзя загрузить файл схемы Protobuf. Однако можно использовать SETTING format_protobuf_schema, чтобы указать схему в запросе. В этом примере мы покажем, как считать сериализованные данные с локальной машины и вставить их в таблицу в ClickHouse Cloud. Как и в предыдущем примере, создайте таблицу в ClickHouse Cloud в соответствии со схемой Protobuf:

CREATE DATABASE IF NOT EXISTS test;
CREATE TABLE IF NOT EXISTS test.protobuf_messages (
  name String,
  surname String,
  birthDate UInt32,
  phoneNumbers Array(String)
)
ENGINE = MergeTree()
ORDER BY tuple()

SETTING format_schema_source задаёт источник для SETTING format_schema Возможные значения:

‘file’ (по умолчанию): не поддерживается в Cloud
‘string’: format_schema содержит буквальное содержимое схемы.
‘query’: format_schema — это запрос для получения схемы.

`format_schema_source='string'`

Чтобы выполнить вставку данных в ClickHouse Cloud, указав схему строкой, выполните:

cat protobuf_messages.bin | clickhouse client --host <hostname> --secure --password <password> --query "INSERT INTO testing.protobuf_messages SETTINGS format_schema_source='syntax = "proto3";message MessageType {  string name = 1;  string surname = 2;  uint32 birthDate = 3;  repeated string phoneNumbers = 4;};', format_schema='schemafile:MessageType' FORMAT Protobuf"

Выберите вставленные в таблицу данные:

clickhouse client --host <hostname> --secure --password <password> --query "SELECT * FROM testing.protobuf_messages"

Aisha Khan 19920815 ['(555) 247-8903','(555) 612-3457']
Javier Rodriguez 20001015 ['(555) 891-2046','(555) 738-5129']
Mei Ling 19980616 ['(555) 956-1834','(555) 403-7682']

`format_schema_source='query'`

Вы также можете хранить схему Protobuf в таблице. Создайте в ClickHouse Cloud таблицу, в которую будут вставляться данные:

CREATE TABLE testing.protobuf_schema (
  schema String
)
ENGINE = MergeTree()
ORDER BY tuple();

INSERT INTO testing.protobuf_schema VALUES ('syntax = "proto3";message MessageType {  string name = 1;  string surname = 2;  uint32 birthDate = 3;  repeated string phoneNumbers = 4;};');

Вставьте данные в ClickHouse Cloud, указав схему в запросе, который нужно выполнить:

cat protobuf_messages.bin | clickhouse client --host <hostname> --secure --password <password> --query "INSERT INTO testing.protobuf_messages SETTINGS format_schema_source='SELECT schema FROM testing.protobuf_schema', format_schema='schemafile:MessageType' FORMAT Protobuf"

Выберите данные, которые были вставлены в таблицу:

clickhouse client --host <hostname> --secure --password <password> --query "SELECT * FROM testing.protobuf_messages"

Aisha Khan 19920815 ['(555) 247-8903','(555) 612-3457']
Javier Rodriguez 20001015 ['(555) 891-2046','(555) 738-5129']
Mei Ling 19980616 ['(555) 956-1834','(555) 403-7682']

Использование автоматически сгенерированной схемы

Если у вас нет внешней схемы Protobuf для ваших данных, вы всё равно можете выводить и читать данные в формате Protobuf, используя автоматически сгенерированную схему. Для этого используйте SETTING format_protobuf_use_autogenerated_schema. Например:

SELECT * FROM test.hits format Protobuf SETTINGS format_protobuf_use_autogenerated_schema=1

В этом случае ClickHouse автоматически сгенерирует схему Protobuf в соответствии со структурой таблицы с помощью функции structureToProtobufSchema. Затем эта схема будет использоваться для сериализации данных в формате Protobuf. Вы также можете читать файл Protobuf с автоматически сгенерированной схемой. В этом случае файл должен быть создан с использованием той же схемы:

$ cat hits.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_protobuf_use_autogenerated_schema=1 FORMAT Protobuf"

SETTING format_protobuf_use_autogenerated_schema включен по умолчанию и применяется, если format_schema не задан. Вы также можете сохранять автоматически сгенерированную схему в файл при вводе и выводе данных, используя SETTING output_format_schema. Например:

SELECT * FROM test.hits format Protobuf SETTINGS format_protobuf_use_autogenerated_schema=1, output_format_schema='path/to/schema/schema.proto'

В этом случае автоматически сгенерированная схема Protobuf будет сохранена в файле path/to/schema/schema.capnp.

Очистка кэша protobuf

Чтобы перезагрузить схему Protobuf, загруженную из format_schema_path, используйте оператор SYSTEM DROP ... FORMAT CACHE.

SYSTEM DROP FORMAT SCHEMA CACHE FOR Protobuf

Справочник по ClickHouse SQL

Типы данных

Движки

Функции

Форматы

Интерфейсы

Настройки

Системные таблицы

Озёра данных

Описание

Пример использования

Чтение и запись данных

Чтение и запись данных с помощью ClickHouse Cloud

`format_schema_source='string'`

`format_schema_source='query'`

Использование автоматически сгенерированной схемы

Очистка кэша protobuf

​Описание

​Пример использования

​Чтение и запись данных

​Чтение и запись данных с помощью ClickHouse Cloud

​format_schema_source='string'

​format_schema_source='query'

​Использование автоматически сгенерированной схемы

​Очистка кэша protobuf

Описание

Пример использования

Чтение и запись данных

Чтение и запись данных с помощью ClickHouse Cloud

`format_schema_source='string'`

`format_schema_source='query'`

Использование автоматически сгенерированной схемы

Очистка кэша protobuf