Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

CapnProto

View as MarkdownEdit this pageReport an issueSet up docs MCP
No es compatible con ClickHouse Cloud
Entrada Salida Alias
✔ ✔

Descripción

El formato CapnProto es un formato de mensajes binarios similar a Protocol Buffers y Thrift, pero no a JSON ni a MessagePack. Los mensajes de CapnProto están estrictamente tipados y no son autodescriptivos, lo que significa que requieren una descripción de esquema externa. El esquema se aplica sobre la marcha y se almacena en caché para cada consulta.

Véase también Esquema de formato.

Correspondencia entre tipos de datos

La siguiente tabla muestra los tipos de datos compatibles y su correspondencia con los tipos de datos de ClickHouse en las consultas INSERT y SELECT.

Tipo de dato de CapnProto (INSERT) Tipo de dato de ClickHouse Tipo de dato de 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)))
  • Los tipos enteros pueden convertirse entre sí durante la entrada y la salida.
  • Para trabajar con Enum en formato CapnProto, use la opción format_capn_proto_enum_comparising_mode.
  • Los Array pueden anidarse y pueden tener un valor del tipo Nullable como argumento. Los tipos Tuple y Map también pueden anidarse.

Ejemplo de uso

Insertar y seleccionar datos

Puede insertar datos de CapnProto desde un archivo en una tabla de ClickHouse con el siguiente comando:

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

Donde schema.capnp se ve así:

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

Puede seleccionar datos de una tabla de ClickHouse y guardarlos en un archivo con el formato CapnProto mediante el siguiente comando:

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

Uso de un esquema autogenerado

Si no dispone de un esquema externo de CapnProto para sus datos, aún puede generar o ingerir datos en formato CapnProto mediante un esquema autogenerado.

Por ejemplo:

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

En este caso, ClickHouse autogenerará el esquema de CapnProto según la estructura de la tabla mediante la función structureToCapnProtoSchema y usará este esquema para serializar datos en formato CapnProto.

También puede leer un archivo CapnProto con un esquema autogenerado (en este caso, el archivo debe haberse creado con el mismo esquema):

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

Configuración del formato

La configuración format_capn_proto_use_autogenerated_schema está habilitada de forma predeterminada y se aplica si no se ha establecido format_schema.

También puede guardar el esquema autogenerado en un archivo durante la entrada/salida mediante la configuración output_format_schema.

Por ejemplo:

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

En este caso, el esquema CapnProto autogenerado se guardará en el archivo path/to/schema/schema.capnp.

Navigation