CapnProto - ClickHouse Documentation

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

Описание

CapnProto — это формат бинарных сообщений, похожий на Protocol Buffers и Thrift, но не на JSON или MessagePack. Сообщения CapnProto строго типизированы и не являются самоописываемыми, то есть требуют внешнего описания схемы. Схема применяется на лету и кэшируется для каждого запроса. См. также Format Schema.

Сопоставление типов данных

В таблице ниже показаны поддерживаемые типы данных и их соответствие типам данных ClickHouse в запросах INSERT и SELECT.

Тип данных CapnProto (`INSERT`)	Тип данных ClickHouse	Тип данных CapnProto (`SELECT`)
`UINT8`, `BOOL`	UInt8	`UINT8`
`INT8`	Int8	`INT8`
`UINT16`	UInt16, Date	`UINT16`
`INT16`	Int16	`INT16`
`UINT32`	UInt32, DateTime	`UINT32`
`INT32`	Int32, Decimal32	`INT32`
`UINT64`	UInt64	`UINT64`
`INT64`	Int64, DateTime64, Decimal64	`INT64`
`FLOAT32`	Float32	`FLOAT32`
`FLOAT64`	Float64	`FLOAT64`
`TEXT, DATA`	String, FixedString	`TEXT, DATA`
`union(T, Void), union(Void, T)`	Nullable(T)	`union(T, Void), union(Void, T)`
`ENUM`	Enum(8/16)	`ENUM`
`LIST`	Array	`LIST`
`STRUCT`	Tuple	`STRUCT`
`UINT32`	IPv4	`UINT32`
`DATA`	IPv6	`DATA`
`DATA`	Int128/UInt128/Int256/UInt256	`DATA`
`DATA`	Decimal128/Decimal256	`DATA`
`STRUCT(entries LIST(STRUCT(key Key, value Value)))`	Map	`STRUCT(entries LIST(STRUCT(key Key, value Value)))`

Целочисленные типы можно преобразовывать друг в друга при вводе и выводе.
Для работы с Enum в формате CapnProto используйте настройку format_capn_proto_enum_comparising_mode.
Массивы могут быть вложенными и принимать в качестве аргумента значение типа Nullable. Типы Tuple и Map также могут быть вложенными.

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

Вставка и выборка данных

Вы можете вставить данные CapnProto из файла в таблицу ClickHouse с помощью следующей команды:

$ cat capnproto_messages.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_schema = 'schema:Message' FORMAT CapnProto"

При этом schema.capnp выглядит так:

struct Message {
  SearchPhrase @0 :Text;
  c @1 :Uint64;
}

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

$ clickhouse-client --query = "SELECT * FROM test.hits FORMAT CapnProto SETTINGS format_schema = 'schema:Message'"

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

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

SELECT * FROM test.hits 
FORMAT CapnProto 
SETTINGS format_capn_proto_use_autogenerated_schema=1

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

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

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

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

SELECT * FROM test.hits 
FORMAT CapnProto 
SETTINGS 
    format_capn_proto_use_autogenerated_schema=1,
    output_format_schema='path/to/schema/schema.capnp'

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

​Описание

​Сопоставление типов данных

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

​Вставка и выборка данных

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