Avro

Entrada	Salida	Alias
✔	✔

Descripción

Apache Avro es un formato de serialización orientado a filas que utiliza codificación binaria para procesar datos de forma eficiente. El formato Avro permite leer y escribir archivos de datos de Avro. Este formato espera mensajes autodescriptivos con un esquema integrado. Si utiliza Avro con un registro de esquemas, consulte el formato AvroConfluent.

Correspondencia de tipos de datos

La siguiente tabla muestra todos los tipos de datos admitidos por el formato Apache Avro y sus correspondientes tipos de datos de ClickHouse en las consultas INSERT y SELECT.

Tipo de dato de Avro `INSERT`	Tipo de dato de ClickHouse	Tipo de dato de Avro `SELECT`
`boolean`, `int`, `long`, `float`, `double`	Int(8\16\32), UInt(8\16\32)	`int`
`boolean`, `int`, `long`, `float`, `double`	Int64, UInt64	`long`
`boolean`, `int`, `long`, `float`, `double`	Float32	`float`
`boolean`, `int`, `long`, `float`, `double`	Float64	`double`
`bytes`, `string`, `fixed`, `enum`	String	`bytes` o `string` *
`bytes`, `string`, `fixed`	FixedString(N)	`fixed(N)`
`enum`	Enum(8\16)	`enum`
`array(T)`	Array(T)	`array(T)`
`map(V, K)`	Map(V, K)	`map(string, K)`
`union(null, T)`, `union(T, null)`	Nullable(T)	`union(null, T)`
`union(T1, T2, …)` **	Variant(T1, T2, …)	`union(T1, T2, …)` **
`null`	Nullable(Nothing)	`null`
`int (date)` ***	Date, Date32	`int (date)` ***
`long (timestamp-millis)` ***	DateTime64(3)	`long (timestamp-millis)` ***
`long (timestamp-micros)` ***	DateTime64(6)	`long (timestamp-micros)` ***
`bytes (decimal)` ***	DateTime64(N)	`bytes (decimal)` ***
`int`	IPv4	`int`
`fixed(16)`	IPv6	`fixed(16)`
`bytes (decimal)` ***	Decimal(P, S)	`bytes (decimal)` ***
`string (uuid)` ***	UUID	`string (uuid)` ***
`fixed(16)`	Int128/UInt128	`fixed(16)`
`fixed(32)`	Int256/UInt256	`fixed(32)`
`record`	Tuple	`record`

bytes es el valor predeterminado y se controla mediante la configuración output_format_avro_string_column_pattern

** El tipo Variant acepta implícitamente null como valor de un campo, por lo que, por ejemplo, union(T1, T2, null) de Avro se convertirá en Variant(T1, T2). Como resultado, al generar Avro desde ClickHouse, siempre tenemos que incluir el tipo null en el conjunto de tipos de union de Avro, ya que durante la inferencia del esquema no sabemos si algún valor es realmente null. *** Tipos lógicos de Avro Tipos de datos lógicos de Avro no compatibles:

time-millis
time-micros
duration

Configuración de formato

Configuración	Descripción	Predeterminado
`input_format_avro_allow_missing_fields`	Si se debe usar un valor predeterminado en lugar de generar un error cuando no se encuentra un campo en el esquema.	`0`
`input_format_avro_null_as_default`	Si se debe usar un valor predeterminado en lugar de generar un error al insertar un valor `null` en una columna no `Nullable`.	`0`
`output_format_avro_codec`	Algoritmo de compresión para archivos de salida Avro. Posibles valores: `null`, `deflate`, `snappy`, `zstd`.
`output_format_avro_sync_interval`	Frecuencia del marcador de sincronización en archivos Avro (en bytes).	`16384`
`output_format_avro_string_column_pattern`	Expresión regular para identificar columnas `String` para el mapeo al tipo `string` de Avro. De forma predeterminada, las columnas `String` de ClickHouse se escriben como tipo `bytes` de Avro.
`output_format_avro_rows_in_file`	Número máximo de filas por archivo de salida Avro. Cuando se alcanza este límite, se crea un archivo nuevo (si el sistema de almacenamiento admite la división de archivos).	`1`

Ejemplos

Lectura de datos en Avro

Para leer datos desde un archivo Avro en una tabla de ClickHouse:

$ cat file.avro | clickhouse-client --query="INSERT INTO {some_table} FORMAT Avro"

El esquema raíz del archivo Avro ingerido debe ser de tipo record. Para determinar la correspondencia entre las columnas de la tabla y los campos del esquema Avro, ClickHouse compara sus nombres. Esta comparación distingue entre mayúsculas y minúsculas, y los campos no utilizados se omiten. Los tipos de datos de las columnas de la tabla de ClickHouse pueden diferir de los de los campos correspondientes en los datos Avro insertados. Al insertar datos, ClickHouse interpreta los tipos de datos según la tabla anterior y luego convierte los datos al tipo de columna correspondiente. Al importar datos, si no se encuentra un campo en el esquema y la configuración input_format_avro_allow_missing_fields está habilitada, se utilizará el valor predeterminado en lugar de generar un error.

Escritura de datos en Avro

Para escribir datos de una tabla de ClickHouse en un archivo Avro:

$ clickhouse-client --query="SELECT * FROM {some_table} FORMAT Avro" > file.avro

Los nombres de las columnas deben:

Comenzar con [A-Za-z_]
Estar seguidos únicamente de [A-Za-z0-9_]

La compresión de salida y el intervalo de sincronización de los archivos Avro pueden configurarse mediante las opciones output_format_avro_codec y output_format_avro_sync_interval, respectivamente.

Inferir el esquema de Avro

Con la función DESCRIBE de ClickHouse, puede ver rápidamente el formato inferido de un archivo Avro, como en el siguiente ejemplo. Este ejemplo incluye la URL de un archivo Avro disponible públicamente en el bucket público de S3 de ClickHouse:

DESCRIBE url('https://clickhouse-public-datasets.s3.eu-central-1.amazonaws.com/hits.avro', 'Avro');

┌─name───────────────────────┬─type────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ WatchID                    │ Int64           │              │                    │         │                  │                │
│ JavaEnable                 │ Int32           │              │                    │         │                  │                │
│ Title                      │ String          │              │                    │         │                  │                │
│ GoodEvent                  │ Int32           │              │                    │         │                  │                │
│ EventTime                  │ Int32           │              │                    │         │                  │                │
│ EventDate                  │ Date32          │              │                    │         │                  │                │
│ CounterID                  │ Int32           │              │                    │         │                  │                │
│ ClientIP                   │ Int32           │              │                    │         │                  │                │
│ ClientIP6                  │ FixedString(16) │              │                    │         │                  │                │
│ RegionID                   │ Int32           │              │                    │         │                  │                │
...
│ IslandID                   │ FixedString(16) │              │                    │         │                  │                │
│ RequestNum                 │ Int32           │              │                    │         │                  │                │
│ RequestTry                 │ Int32           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

Referencia de SQL

Tipos de datos

Motores

Funciones

Formatos

Configuración

Tablas del sistema

Lagos de datos

Descripción

Correspondencia de tipos de datos

Configuración de formato

Ejemplos

Lectura de datos en Avro

Escritura de datos en Avro

Inferir el esquema de Avro

​Descripción

​Correspondencia de tipos de datos

​Configuración de formato

​Ejemplos

​Lectura de datos en Avro

​Escritura de datos en Avro

​Inferir el esquema de Avro

Descripción

Correspondencia de tipos de datos

Configuración de formato

Ejemplos

Lectura de datos en Avro

Escritura de datos en Avro

Inferir el esquema de Avro