Перейти к основному содержимому
Перейти к основному содержимому

Protobuf

Not supported in ClickHouse Cloud
Входные данныеВыходные данныеПсевдоним
✔✔

Описание​

Формат Protobuf является форматом Protocol Buffers.

Этот формат требует внешней схемы формата, которая кэшируется между запросами.

ClickHouse поддерживает:

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

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

Основные примеры​

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

SELECT * FROM test.table FORMAT Protobuf SETTINGS format_schema = 'schemafile:MessageType'

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

Где файл schemafile.proto выглядит следующим образом:

syntax = "proto3";

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

Чтобы найти соответствие между колонками таблицы и полями типа сообщения 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 и так далее).

Вложенные сообщения подходят для ввода или вывода вложенных структур данных.

Значения по умолчанию, определенные в схеме protobuf, как тот, что следует, не применяются; вместо них используются значения по умолчанию таблицы:

syntax = "proto2";

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

Если сообщение содержит oneof и 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) должен содержать все возможные теги oneof плюс 0, чтобы указать на отсутствие, строковые представления не имеют значения.

Настройка input_format_protobuf_oneof_presence по умолчанию отключена.

ClickHouse принимает и отправляет сообщения protobuf в формате length-delimited. Это означает, что перед каждым сообщением его длина должна быть записана как целое число переменной длины (varint).

См. также: как читать/писать сообщения protobuf с длиной-разделителем на популярных языках.

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

Если у вас нет внешней схемы Protobuf для ваших данных, вы все равно можете вводить/выводить данные в формате Protobuf, используя сгенерированную схему.

Например:

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

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

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

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

Настройка format_protobuf_use_autogenerated_schema включена по умолчанию и применяется, если format_schema не установлен.

Вы также можете сохранить сгенерированную схему в файл во время ввода/вывода, используя настройку 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

Настройки формата​