> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentación sobre el formato Avro

# Avro

| Entrada | Salida | Alias |
| - | - | - |
| ✔ | ✔ | |

## Descripción

[Apache Avro](https://avro.apache.org/) 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](https://avro.apache.org/docs/current/specification/#object-container-files). Este formato espera mensajes autodescriptivos con un esquema integrado. Si utiliza Avro con un registro de esquemas, consulte el formato [`AvroConfluent`](https://clickhouse.com/docs/es/reference/formats/Avro/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](https://clickhouse.com/docs/es/reference/data-types/index.md) 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)](https://clickhouse.com/docs/es/reference/data-types/int-uint.md), [UInt(8\16\32)](https://clickhouse.com/docs/es/reference/data-types/int-uint.md) | `int` |
| `boolean`, `int`, `long`, `float`, `double` | [Int64](https://clickhouse.com/docs/es/reference/data-types/int-uint.md), [UInt64](https://clickhouse.com/docs/es/reference/data-types/int-uint.md) | `long` |
| `boolean`, `int`, `long`, `float`, `double` | [Float32](https://clickhouse.com/docs/es/reference/data-types/float.md) | `float` |
| `boolean`, `int`, `long`, `float`, `double` | [Float64](https://clickhouse.com/docs/es/reference/data-types/float.md) | `double` |
| `bytes`, `string`, `fixed`, `enum` | [String](https://clickhouse.com/docs/es/reference/data-types/string.md) | `bytes` o `string` \* |
| `bytes`, `string`, `fixed` | [FixedString(N)](https://clickhouse.com/docs/es/reference/data-types/fixedstring.md) | `fixed(N)` |
| `enum` | [Enum(8\16)](https://clickhouse.com/docs/es/reference/data-types/enum.md) | `enum` |
| `array(T)` | [Array(T)](https://clickhouse.com/docs/es/reference/data-types/array.md) | `array(T)` |
| `map(V, K)` | [Map(V, K)](https://clickhouse.com/docs/es/reference/data-types/map.md) | `map(string, K)` |
| `union(null, T)`, `union(T, null)` | [Nullable(T)](https://clickhouse.com/docs/es/reference/data-types/date.md) | `union(null, T)` |
| `union(T1, T2, …)` \*\* | [Variant(T1, T2, …)](https://clickhouse.com/docs/es/reference/data-types/variant.md) | `union(T1, T2, …)` \*\* |
| `null` | [Nullable(Nothing)](https://clickhouse.com/docs/es/reference/data-types/special-data-types/nothing.md) | `null` |
| `int (date)` \*\*\* | [Date](https://clickhouse.com/docs/es/reference/data-types/date.md), [Date32](https://clickhouse.com/docs/es/reference/data-types/date32.md) | `int (date)` \*\*\* |
| `long (timestamp-millis)` \*\*\* | [DateTime64(3)](https://clickhouse.com/docs/es/reference/data-types/datetime.md) | `long (timestamp-millis)` \*\*\* |
| `long (timestamp-micros)` \*\*\* | [DateTime64(6)](https://clickhouse.com/docs/es/reference/data-types/datetime.md) | `long (timestamp-micros)` \*\*\* |
| `bytes (decimal)`  \*\*\* | [DateTime64(N)](https://clickhouse.com/docs/es/reference/data-types/datetime.md) | `bytes (decimal)`  \*\*\* |
| `int` | [IPv4](https://clickhouse.com/docs/es/reference/data-types/ipv4.md) | `int` |
| `fixed(16)` | [IPv6](https://clickhouse.com/docs/es/reference/data-types/ipv6.md) | `fixed(16)` |
| `bytes (decimal)` \*\*\* | [Decimal(P, S)](https://clickhouse.com/docs/es/reference/data-types/decimal.md) | `bytes (decimal)` \*\*\* |
| `string (uuid)` \*\*\* | [UUID](https://clickhouse.com/docs/es/reference/data-types/uuid.md) | `string (uuid)` \*\*\* |
| `fixed(16)` | [Int128/UInt128](https://clickhouse.com/docs/es/reference/data-types/int-uint.md) | `fixed(16)` |
| `fixed(32)` | [Int256/UInt256](https://clickhouse.com/docs/es/reference/data-types/int-uint.md) | `fixed(32)` |
| `record` | [Tuple](https://clickhouse.com/docs/es/reference/data-types/tuple.md) | `record` |

* `bytes` es el valor predeterminado y se controla mediante la configuración [`output_format_avro_string_column_pattern`](https://clickhouse.com/docs/es/reference/settings/formats/output-format#output_format_avro_string_column_pattern)

\*\*  El [tipo Variant](https://clickhouse.com/docs/es/reference/data-types/variant.md) 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](https://avro.apache.org/docs/1.12.0/specification/#logical-types)

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:

```bash theme={null}
$ 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](https://clickhouse.com/docs/es/reference/functions/regular-functions/type-conversion-functions.md#CAST) 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`](https://clickhouse.com/docs/es/reference/settings/formats/input-format#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:

```bash theme={null}
$ 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`](https://clickhouse.com/docs/es/reference/settings/formats/output-format#output_format_avro_codec) y [`output_format_avro_sync_interval`](https://clickhouse.com/docs/es/reference/settings/formats/output-format#output_format_avro_sync_interval), respectivamente.

### Inferir el esquema de Avro

Con la función [`DESCRIBE`](https://clickhouse.com/docs/es/reference/statements/describe-table) 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:

```sql theme={null}
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           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
```