CapnProto

Not supported in ClickHouse Cloud

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

Описание

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

См. также Схема формата.

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

Приведённая ниже таблица показывает поддерживаемые типы данных и то, как они сопоставляются с типами данных 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.

Описание​

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

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

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

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

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