CapnProto

Documentação do CapnProto

Entrada	Saída	Alias
✔	✔

​

Descrição

O formato CapnProto é um formato de mensagem binária semelhante ao Protocol Buffers e ao Thrift, mas diferente de JSON ou MessagePack. As mensagens CapnProto são estritamente tipadas e não são autodescritivas, o que significa que precisam de uma descrição externa do esquema. O esquema é aplicado dinamicamente e armazenado em cache para cada consulta.

Veja também Esquema de formato.

​

Correspondência entre tipos de dados

A tabela abaixo mostra os tipos de dados suportados e como eles correspondem aos tipos de dados do ClickHouse em consultas INSERT e SELECT.

Tipo de dado CapnProto (INSERT)	Tipo de dado do ClickHouse	Tipo de dado 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)))

• Tipos inteiros podem ser convertidos entre si na entrada/saída.
• Para trabalhar com Enum no formato CapnProto, use o setting format_capn_proto_enum_comparising_mode.
• Arrays podem ser aninhados e podem ter um argumento do tipo Nullable. Os tipos Tuple e Map também podem ser aninhados.

​

Exemplo de uso

​

Inserindo e selecionando dados

Você pode inserir dados CapnProto de um arquivo em uma tabela do ClickHouse usando o comando a seguir:

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

Em que schema.capnp é assim:

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

Você pode selecionar dados de uma tabela do ClickHouse e salvá-los em um arquivo no formato CapnProto usando o comando a seguir:

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

​

Usando esquema gerado automaticamente

Se você não tiver um esquema externo CapnProto para seus dados, ainda poderá exportar/importar dados no formato CapnProto usando um esquema gerado automaticamente.

Por exemplo:

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

Nesse caso, o ClickHouse gerará automaticamente o esquema CapnProto com base na estrutura da tabela usando a função structureToCapnProtoSchema e usará esse esquema para serializar os dados no formato CapnProto.

Você também pode ler um arquivo CapnProto com esquema gerado automaticamente (nesse caso, o arquivo deve ser criado usando o mesmo esquema):

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

​

SETTINGS de formato

A SETTING format_capn_proto_use_autogenerated_schema vem habilitada por padrão e se aplica quando format_schema não está definida.

Você também pode salvar o esquema gerado automaticamente em um arquivo durante a entrada/saída usando a SETTING output_format_schema.

Por exemplo:

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

Nesse caso, o esquema CapnProto gerado automaticamente será salvo no arquivo path/to/schema/schema.capnp.