Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

CapnProto

View as MarkdownEdit this pageReport an issueSet up docs MCP
Не поддерживается в ClickHouse Cloud
Ввод Вывод Псевдоним
✔ ✔

Описание

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.

Navigation