CapnProto

Документация по CapnProto

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

​

Описание

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.