Protobuf

Entrada	Salida	Alias
✔	✔

Descripción

El formato Protobuf es el formato de Protocol Buffers. Este formato requiere un esquema de formato externo, que se mantiene en caché entre consultas. ClickHouse admite:

tanto la sintaxis proto2 como la proto3.
campos Repeated/optional/required.

Para encontrar la correspondencia entre las columnas de la tabla y los campos del tipo de mensaje de Protocol Buffers, ClickHouse compara sus nombres. Esta comparación no distingue entre mayúsculas y minúsculas, y los caracteres _ (guion bajo) y . (punto) se consideran equivalentes. Si los tipos de una columna y de un campo del mensaje de Protocol Buffers son diferentes, se aplica la conversión necesaria. Se admiten mensajes anidados. Por ejemplo, para el campo z en el siguiente tipo de mensaje:

message MessageType {
  message XType {
    message YType {
      int32 z;
    };
    repeated YType y;
  };
  XType x;
};

ClickHouse intenta encontrar una columna llamada x.y.z (o x_y_z, X.y_Z, etc.). Los mensajes anidados son adecuados para la entrada o salida de estructuras de datos anidadas. Para los campos asignados que no están presentes en los datos transmitidos:

Las columnas asignadas ordinarias no anulables usan el valor predeterminado del campo del esquema protobuf (proto2 [default = …]; de lo contrario, el valor predeterminado del tipo) durante el análisis, no la expresión DEFAULT de la tabla.
Las columnas asignadas Nullable(...) se resuelven como NULL cuando el campo está ausente (no toman el valor predeterminado del campo o tipo protobuf).
Con input_format_protobuf_flatten_google_wrappers habilitado para los envoltorios google.protobuf.*Value:
- un envoltorio ausente en una columna Nullable(...) se trata como un campo externo ausente y se convierte en NULL;
- un envoltorio presente pero vacío (str {}) conserva el valor predeterminado del escalar anidado ('' / 0);
- una columna no anulable asignada a un envoltorio ausente obtiene el valor predeterminado del escalar anidado en lugar de NULL.

El DEFAULT de la tabla (y las expresiones predeterminadas) se aplican a las columnas de la tabla que no tienen ningún campo coincidente en el tipo de mensaje cuando input_format_defaults_for_omitted_fields está habilitado (de forma predeterminada). Si ese SETTING es 0, las columnas no asignadas conservan el valor predeterminado del tipo de datos insertado durante el análisis en lugar de la expresión DEFAULT de la tabla. Ejemplo de un valor predeterminado de campo de un esquema proto2 (usado para un campo asignado ausente del mensaje):

syntax = "proto2";

message MessageType {
  optional int32 result_per_page = 3 [default = 10];
}

Si un mensaje contiene oneof y se establece input_format_protobuf_oneof_presence, ClickHouse completa la columna que indica qué campo de oneof se encontró.

syntax = "proto3";

message StringOrString {
  oneof string_oneof {
    string string1 = 1;
    string string2 = 42;
  }
}

CREATE TABLE string_or_string ( string1 String, string2 String, string_oneof Enum('no'=0, 'hello' = 1, 'world' = 42))  Engine=MergeTree ORDER BY tuple();
INSERT INTO string_or_string from INFILE '$CURDIR/data_protobuf/String1' SETTINGS format_schema='$SCHEMADIR/string_or_string.proto:StringOrString' FORMAT ProtobufSingle;
SELECT * FROM string_or_string

   ┌─────────┬─────────┬──────────────┐
   │ string1 │ string2 │ string_oneof │
   ├─────────┼─────────┼──────────────┤
1. │         │ string2 │ world        │
   ├─────────┼─────────┼──────────────┤
2. │ string1 │         │ hello        │
   └─────────┴─────────┴──────────────┘

El nombre de la columna que indica la presencia debe ser el mismo que el de oneof. Se admiten mensajes anidados (consulte ejemplos básicos). Los mensajes vacíos también se admiten. Los tipos permitidos son Int8, UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Enum, Enum8 o Enum16. Enum (así como Enum8 o Enum16) debe contener 0 para indicar ausencia y la etiqueta de cada caso de oneof que tenga una columna coincidente en la tabla de destino; las representaciones textuales no importan. Para los miembros de mensajes oneof sin columnas coincidentes en la tabla, también se permiten etiquetas Enum faltantes. Si dicha rama está presente en la entrada, ClickHouse trata la presencia de oneof como omitida y escribe 0 en la columna de presencia. El SETTING input_format_protobuf_oneof_presence está deshabilitado de forma predeterminada ClickHouse recibe y envía mensajes protobuf en formato length-delimited. Esto significa que, antes de cada mensaje, su longitud debe escribirse como un entero de longitud variable (varint).

Ejemplo de uso

Lectura y escritura de datos

Los archivos usados en este ejemplo están disponibles en el repositorio de ejemplos

En este ejemplo, leeremos algunos datos de un archivo protobuf_message.bin a una tabla de ClickHouse. Luego los volveremos a escribir en un archivo llamado protobuf_message_from_clickhouse.bin usando el formato Protobuf. Dado el archivo schemafile.proto:

syntax = "proto3";

message MessageType {
  string name = 1;
  string surname = 2;
  uint32 birthDate = 3;
  repeated string phoneNumbers = 4;
};

Generar el archivo binario

Si ya sabes cómo serializar y deserializar datos en el formato Protobuf, puedes omitir este paso.Usaremos Python para serializar algunos datos en protobuf_message.bin y leerlos en ClickHouse. Si quieres usar otro lenguaje, consulta también: “How to read/write length-delimited Protobuf messages in popular languages”.Ejecuta el siguiente comando para generar un archivo Python llamado schemafile_pb2.py en el mismo directorio que schemafile.proto. Este archivo contiene las clases de Python que representan tu mensaje UserData de Protobuf:

protoc --python_out=. schemafile.proto

Ahora, crea un nuevo archivo Python llamado generate_protobuf_data.py en el mismo directorio que schemafile_pb2.py. Pega el siguiente código en él:

import schemafile_pb2  # Módulo generado por 'protoc'
from google.protobuf import text_format
from google.protobuf.internal.encoder import _VarintBytes # Importa el codificador varint interno

def create_user_data_message(name, surname, birthDate, phoneNumbers):
    """
    Crea y completa un mensaje UserData de Protobuf.
    """
    message = schemafile_pb2.MessageType()
    message.name = name
    message.surname = surname
    message.birthDate = birthDate
    message.phoneNumbers.extend(phoneNumbers)
    return message

# Los datos de nuestros usuarios de ejemplo
data_to_serialize = [
    {"name": "Aisha", "surname": "Khan", "birthDate": 19920815, "phoneNumbers": ["(555) 247-8903", "(555) 612-3457"]},
    {"name": "Javier", "surname": "Rodriguez", "birthDate": 20001015, "phoneNumbers": ["(555) 891-2046", "(555) 738-5129"]},
    {"name": "Mei", "surname": "Ling", "birthDate": 19980616, "phoneNumbers": ["(555) 956-1834", "(555) 403-7682"]},
]

output_filename = "protobuf_messages.bin"

# Abre el archivo binario en modo de escritura binaria ('wb')
with open(output_filename, "wb") as f:
    for item in data_to_serialize:
        # Crea una instancia de mensaje Protobuf para el usuario actual
        message = create_user_data_message(
            item["name"],
            item["surname"],
            item["birthDate"],
            item["phoneNumbers"]
        )

        # Serializa el mensaje
        serialized_data = message.SerializeToString()

        # Obtén la longitud de los datos serializados
        message_length = len(serialized_data)

        # Usa _VarintBytes de la biblioteca Protobuf para codificar la longitud
        length_prefix = _VarintBytes(message_length)

        # Escribe el prefijo de longitud
        f.write(length_prefix)
        # Escribe los datos del mensaje serializado
        f.write(serialized_data)

print(f"Protobuf messages (length-delimited) written to {output_filename}")

# --- Opcional: Verificación (volver a leer e imprimir) ---
# Para volver a leer, también usaremos el decodificador interno de varints de Protobuf.
from google.protobuf.internal.decoder import _DecodeVarint32

print("\n--- Verifying by reading back ---")
with open(output_filename, "rb") as f:
    buf = f.read() # Lee todo el archivo en un búfer para facilitar la decodificación varint
    n = 0
    while n < len(buf):
        # Decodifica el prefijo de longitud varint
        msg_len, new_pos = _DecodeVarint32(buf, n)
        n = new_pos

        # Extrae los datos del mensaje
        message_data = buf[n:n+msg_len]
        n += msg_len

        # Analiza el mensaje
        decoded_message = schemafile_pb2.MessageType()
        decoded_message.ParseFromString(message_data)
        print(text_format.MessageToString(decoded_message, as_utf8=True))

Ahora ejecuta el script desde la línea de comandos. Se recomienda ejecutarlo desde un entorno virtual de Python, por ejemplo con uv:

uv venv proto-venv
source proto-venv/bin/activate

Tendrás que instalar las siguientes bibliotecas de Python:

uv pip install --upgrade protobuf

Ejecuta el script para generar el archivo binario:

python generate_protobuf_data.py

Crea una tabla de ClickHouse que coincida con el esquema:

CREATE DATABASE IF NOT EXISTS test;
CREATE TABLE IF NOT EXISTS test.protobuf_messages (
  name String,
  surname String,
  birthDate UInt32,
  phoneNumbers Array(String)
)
ENGINE = MergeTree()
ORDER BY tuple()

Inserte los datos en la tabla desde la línea de comandos:

cat protobuf_messages.bin | clickhouse-client --query "INSERT INTO test.protobuf_messages SETTINGS format_schema='schemafile:MessageType' FORMAT Protobuf"

También puede volver a escribir los datos en un archivo binario con el formato Protobuf:

SELECT * FROM test.protobuf_messages INTO OUTFILE 'protobuf_message_from_clickhouse.bin' FORMAT Protobuf SETTINGS format_schema = 'schemafile:MessageType'

Con el esquema Protobuf, ahora puede deserializar los datos que se escribieron desde ClickHouse en el archivo protobuf_message_from_clickhouse.bin.

Lectura y escritura de datos con ClickHouse Cloud

Con ClickHouse Cloud no es posible cargar un archivo de esquema Protobuf. Sin embargo, puede usar la configuración format_protobuf_schema para especificar el esquema en la consulta. En este ejemplo, le mostramos cómo leer datos serializados desde su máquina local e insertarlos en una tabla de ClickHouse Cloud. Como en el ejemplo anterior, cree la tabla según el esquema de su archivo Protobuf en ClickHouse Cloud:

CREATE DATABASE IF NOT EXISTS test;
CREATE TABLE IF NOT EXISTS test.protobuf_messages (
  name String,
  surname String,
  birthDate UInt32,
  phoneNumbers Array(String)
)
ENGINE = MergeTree()
ORDER BY tuple()

La configuración format_schema_source define la fuente de la configuración format_schema Valores posibles:

‘file’ (predeterminado): no es compatible con Cloud
‘string’: format_schema es el contenido literal del esquema.
‘query’: format_schema es una consulta para obtener el esquema.

`format_schema_source='string'`

Inserte los datos en ClickHouse Cloud, especificando el esquema como una cadena; ejecute:

cat protobuf_messages.bin | clickhouse client --host <hostname> --secure --password <password> --query "INSERT INTO testing.protobuf_messages SETTINGS format_schema_source='syntax = "proto3";message MessageType {  string name = 1;  string surname = 2;  uint32 birthDate = 3;  repeated string phoneNumbers = 4;};', format_schema='schemafile:MessageType' FORMAT Protobuf"

Seleccione los datos insertados en la tabla:

clickhouse client --host <hostname> --secure --password <password> --query "SELECT * FROM testing.protobuf_messages"

Aisha Khan 19920815 ['(555) 247-8903','(555) 612-3457']
Javier Rodriguez 20001015 ['(555) 891-2046','(555) 738-5129']
Mei Ling 19980616 ['(555) 956-1834','(555) 403-7682']

`format_schema_source='query'`

También puede almacenar su esquema Protobuf en una tabla. Cree una tabla en ClickHouse Cloud para insertar datos:

CREATE TABLE testing.protobuf_schema (
  schema String
)
ENGINE = MergeTree()
ORDER BY tuple();

INSERT INTO testing.protobuf_schema VALUES ('syntax = "proto3";message MessageType {  string name = 1;  string surname = 2;  uint32 birthDate = 3;  repeated string phoneNumbers = 4;};');

Inserta los datos en ClickHouse Cloud especificando el esquema en la consulta que se va a ejecutar:

cat protobuf_messages.bin | clickhouse client --host <hostname> --secure --password <password> --query "INSERT INTO testing.protobuf_messages SETTINGS format_schema_source='SELECT schema FROM testing.protobuf_schema', format_schema='schemafile:MessageType' FORMAT Protobuf"

Seleccione los datos insertados en la tabla:

clickhouse client --host <hostname> --secure --password <password> --query "SELECT * FROM testing.protobuf_messages"

Aisha Khan 19920815 ['(555) 247-8903','(555) 612-3457']
Javier Rodriguez 20001015 ['(555) 891-2046','(555) 738-5129']
Mei Ling 19980616 ['(555) 956-1834','(555) 403-7682']

Uso de un esquema autogenerado

Si no dispone de un esquema Protobuf externo para sus datos, aún puede exportar/importar datos en formato Protobuf mediante un esquema autogenerado. Para ello, utilice la configuración format_protobuf_use_autogenerated_schema. Por ejemplo:

SELECT * FROM test.hits format Protobuf SETTINGS format_protobuf_use_autogenerated_schema=1

En este caso, ClickHouse generará automáticamente el esquema de Protobuf según la estructura de la tabla mediante la función structureToProtobufSchema. A continuación, usará este esquema para serializar los datos en formato Protobuf. También puede leer un archivo Protobuf con el esquema autogenerado. En este caso, es necesario que el archivo se haya creado con el mismo esquema:

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

La configuración format_protobuf_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 el archivo durante la entrada/salida mediante la configuración output_format_schema. Por ejemplo:

SELECT * FROM test.hits format Protobuf SETTINGS format_protobuf_use_autogenerated_schema=1, output_format_schema='path/to/schema/schema.proto'

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

Eliminar la caché de Protobuf

Para recargar el esquema Protobuf cargado desde format_schema_path, use la sentencia SYSTEM DROP ... FORMAT CACHE.

SYSTEM DROP FORMAT SCHEMA CACHE FOR Protobuf

Referencia de SQL

Tipos de datos

Motores

Funciones

Formatos

Configuración

Tablas del sistema

Lagos de datos

Descripción

Ejemplo de uso

Lectura y escritura de datos

Lectura y escritura de datos con ClickHouse Cloud

`format_schema_source='string'`

`format_schema_source='query'`

Uso de un esquema autogenerado

Eliminar la caché de Protobuf

​Descripción

​Ejemplo de uso

​Lectura y escritura de datos

​Lectura y escritura de datos con ClickHouse Cloud

​format_schema_source='string'

​format_schema_source='query'

​Uso de un esquema autogenerado

​Eliminar la caché de Protobuf

Descripción

Ejemplo de uso

Lectura y escritura de datos

Lectura y escritura de datos con ClickHouse Cloud

`format_schema_source='string'`

`format_schema_source='query'`

Uso de un esquema autogenerado

Eliminar la caché de Protobuf