> ## 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.

# Avro

> Documentação sobre o formato Avro

| Entrada | Saída | Alias |
| - | - | - |
| ✔ | ✔ | |

## Descrição

[Apache Avro](https://avro.apache.org/) é um formato de serialização orientado a linhas que usa codificação binária para processamento eficiente de dados. O formato `Avro` oferece suporte à leitura e à gravação de [arquivos de dados Avro](https://avro.apache.org/docs/current/specification/#object-container-files). Esse formato requer mensagens autodescritivas com um esquema incorporado. Se você estiver usando Avro com um registro de esquemas, consulte o formato [`AvroConfluent`](https://clickhouse.com/docs/pt-BR/reference/formats/Avro/AvroConfluent).

## Mapeamento de tipos de dados

A tabela abaixo mostra todos os tipos de dados compatíveis com o formato Apache Avro e seus respectivos [tipos de dados](https://clickhouse.com/docs/pt-BR/reference/data-types/index.md) no ClickHouse em consultas `INSERT` e `SELECT`.

| Tipo de dado Avro `INSERT` | Tipo de dado ClickHouse | Tipo de dado Avro `SELECT` |
| - | - | - |
| `boolean`, `int`, `long`, `float`, `double` | [Int(8\16\32)](https://clickhouse.com/docs/pt-BR/reference/data-types/int-uint.md), [UInt(8\16\32)](https://clickhouse.com/docs/pt-BR/reference/data-types/int-uint.md) | `int` |
| `boolean`, `int`, `long`, `float`, `double` | [Int64](https://clickhouse.com/docs/pt-BR/reference/data-types/int-uint.md), [UInt64](https://clickhouse.com/docs/pt-BR/reference/data-types/int-uint.md) | `long` |
| `boolean`, `int`, `long`, `float`, `double` | [Float32](https://clickhouse.com/docs/pt-BR/reference/data-types/float.md) | `float` |
| `boolean`, `int`, `long`, `float`, `double` | [Float64](https://clickhouse.com/docs/pt-BR/reference/data-types/float.md) | `double` |
| `bytes`, `string`, `fixed`, `enum` | [String](https://clickhouse.com/docs/pt-BR/reference/data-types/string.md) | `bytes` ou `string` \* |
| `bytes`, `string`, `fixed` | [FixedString(N)](https://clickhouse.com/docs/pt-BR/reference/data-types/fixedstring.md) | `fixed(N)` |
| `enum` | [Enum(8\16)](https://clickhouse.com/docs/pt-BR/reference/data-types/enum.md) | `enum` |
| `array(T)` | [Array(T)](https://clickhouse.com/docs/pt-BR/reference/data-types/array.md) | `array(T)` |
| `map(V, K)` | [Map(V, K)](https://clickhouse.com/docs/pt-BR/reference/data-types/map.md) | `map(string, K)` |
| `union(null, T)`, `union(T, null)` | [Nullable(T)](https://clickhouse.com/docs/pt-BR/reference/data-types/date.md) | `union(null, T)` |
| `union(T1, T2, …)` \*\* | [Variant(T1, T2, …)](https://clickhouse.com/docs/pt-BR/reference/data-types/variant.md) | `union(T1, T2, …)` \*\* |
| `null` | [Nullable(Nothing)](https://clickhouse.com/docs/pt-BR/reference/data-types/special-data-types/nothing.md) | `null` |
| `int (date)` \*\*\* | [Date](https://clickhouse.com/docs/pt-BR/reference/data-types/date.md), [Date32](https://clickhouse.com/docs/pt-BR/reference/data-types/date32.md) | `int (date)` \*\*\* |
| `long (timestamp-millis)` \*\*\* | [DateTime64(3)](https://clickhouse.com/docs/pt-BR/reference/data-types/datetime.md) | `long (timestamp-millis)` \*\*\* |
| `long (timestamp-micros)` \*\*\* | [DateTime64(6)](https://clickhouse.com/docs/pt-BR/reference/data-types/datetime.md) | `long (timestamp-micros)` \*\*\* |
| `bytes (decimal)`  \*\*\* | [DateTime64(N)](https://clickhouse.com/docs/pt-BR/reference/data-types/datetime.md) | `bytes (decimal)`  \*\*\* |
| `int` | [IPv4](https://clickhouse.com/docs/pt-BR/reference/data-types/ipv4.md) | `int` |
| `fixed(16)` | [IPv6](https://clickhouse.com/docs/pt-BR/reference/data-types/ipv6.md) | `fixed(16)` |
| `bytes (decimal)` \*\*\* | [Decimal(P, S)](https://clickhouse.com/docs/pt-BR/reference/data-types/decimal.md) | `bytes (decimal)` \*\*\* |
| `string (uuid)` \*\*\* | [UUID](https://clickhouse.com/docs/pt-BR/reference/data-types/uuid.md) | `string (uuid)` \*\*\* |
| `fixed(16)` | [Int128/UInt128](https://clickhouse.com/docs/pt-BR/reference/data-types/int-uint.md) | `fixed(16)` |
| `fixed(32)` | [Int256/UInt256](https://clickhouse.com/docs/pt-BR/reference/data-types/int-uint.md) | `fixed(32)` |
| `record` | [Tuple](https://clickhouse.com/docs/pt-BR/reference/data-types/tuple.md) | `record` |

* `bytes` é o padrão, controlado pela configuração [`output_format_avro_string_column_pattern`](https://clickhouse.com/docs/pt-BR/reference/settings/formats/output-format#output_format_avro_string_column_pattern)

\*\*  O [tipo Variant](https://clickhouse.com/docs/pt-BR/reference/data-types/variant.md) aceita implicitamente `null` como valor de campo; assim, por exemplo, o Avro `union(T1, T2, null)` será convertido em `Variant(T1, T2)`.
Como resultado, ao gerar Avro a partir do ClickHouse, precisamos sempre incluir o tipo `null` no conjunto de tipos `union` do Avro, pois não sabemos, durante a inferência de esquema, se algum valor é de fato `null`.

\*\*\* [Tipos lógicos do Avro](https://avro.apache.org/docs/1.12.0/specification/#logical-types)

Tipos de dados lógicos do Avro não compatíveis:

* `time-millis`
* `time-micros`
* `duration`

## Configurações de formato

| Configuração | Descrição | Valor padrão |
| - | - | - |
| `input_format_avro_allow_missing_fields` | Se deve usar um valor padrão em vez de gerar um erro quando um campo não for encontrado no esquema. | `0` |
| `input_format_avro_null_as_default` | Se deve usar um valor padrão em vez de gerar um erro ao inserir um valor `null` em uma coluna que não aceita `null`. | `0` |
| `output_format_avro_codec` | Algoritmo de compressão para arquivos de saída Avro. Valores possíveis: `null`, `deflate`, `snappy`, `zstd`. | |
| `output_format_avro_sync_interval` | Frequência do marcador de sincronização em arquivos Avro (em bytes). | `16384` |
| `output_format_avro_string_column_pattern` | Expressão regular para identificar colunas `String` para o mapeamento para o tipo string do Avro. Por padrão, as colunas `String` do ClickHouse são gravadas como o tipo `bytes` do Avro. | |
| `output_format_avro_rows_in_file` | Número máximo de linhas por arquivo de saída Avro. Quando esse limite é atingido, um novo arquivo é criado (se o sistema de armazenamento oferecer suporte à divisão de arquivos). | `1` |

## Exemplos

### Leitura de dados Avro

Para ler dados de um arquivo Avro para uma tabela do ClickHouse:

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

O esquema raiz do arquivo Avro submetido à ingestão deve ser do tipo `record`.

Para encontrar a correspondência entre as colunas da tabela e os campos do esquema Avro, o ClickHouse compara seus nomes.
Essa comparação diferencia maiúsculas de minúsculas, e os campos não usados são ignorados.

Os tipos de dados das colunas da tabela do ClickHouse podem diferir dos campos correspondentes dos dados Avro inseridos. Ao inserir dados, o ClickHouse interpreta os tipos de dados de acordo com a tabela acima e, em seguida, [faz a conversão](https://clickhouse.com/docs/pt-BR/reference/functions/regular-functions/type-conversion-functions.md#CAST) dos dados para o tipo da coluna correspondente.

Ao importar dados, quando um campo não é encontrado no esquema e a configuração [`input_format_avro_allow_missing_fields`](https://clickhouse.com/docs/pt-BR/reference/settings/formats/input-format#input_format_avro_allow_missing_fields) está habilitada, o valor padrão será usado em vez de gerar um erro.

### Gravando dados em Avro

Para gravar dados de uma tabela do ClickHouse em um arquivo Avro:

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

Os nomes das colunas devem:

* Começar com `[A-Za-z_]`
* Ser seguidos apenas por `[A-Za-z0-9_]`

A compressão de saída e o intervalo de sincronização de arquivos Avro podem ser configurados, respectivamente, com as configurações [`output_format_avro_codec`](https://clickhouse.com/docs/pt-BR/reference/settings/formats/output-format#output_format_avro_codec) e [`output_format_avro_sync_interval`](https://clickhouse.com/docs/pt-BR/reference/settings/formats/output-format#output_format_avro_sync_interval).

### Inferindo o esquema Avro

Usando a função [`DESCRIBE`](https://clickhouse.com/docs/pt-BR/reference/statements/describe-table) do ClickHouse, você pode visualizar rapidamente o formato inferido de um arquivo Avro, como no exemplo a seguir.
Este exemplo inclui a URL de um arquivo Avro acessível publicamente no bucket público S3 do 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           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
```
