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

> Documentation sur le format Avro

# Avro

| Entrée | Sortie | Alias |
| - | - | - |
| ✔ | ✔ | |

## Description

[Apache Avro](https://avro.apache.org/) est un format de sérialisation orienté lignes qui utilise un encodage binaire pour traiter efficacement les données. Le format `Avro` prend en charge la lecture et l’écriture des [fichiers de données Avro](https://avro.apache.org/docs/current/specification/#object-container-files). Ce format requiert des messages auto-descriptifs avec un schéma intégré. Si vous utilisez Avro avec un registre de schémas, consultez le format [`AvroConfluent`](https://clickhouse.com/docs/fr/reference/formats/Avro/AvroConfluent).

## Correspondance des types de données

Le tableau ci-dessous indique tous les types de données pris en charge par le format Apache Avro, ainsi que les [types de données](https://clickhouse.com/docs/fr/reference/data-types/index.md) ClickHouse correspondants dans les requêtes `INSERT` et `SELECT`.

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

* `bytes` est la valeur par défaut, contrôlée par le paramètre [`output_format_avro_string_column_pattern`](https://clickhouse.com/docs/fr/reference/settings/formats/output-format#output_format_avro_string_column_pattern)

\*\*  Le [type Variant](https://clickhouse.com/docs/fr/reference/data-types/variant.md) accepte implicitement `null` comme valeur de champ. Ainsi, par exemple, le `union(T1, T2, null)` d’Avro sera converti en `Variant(T1, T2)`.
Par conséquent, lors de la génération d’Avro à partir de ClickHouse, nous devons toujours inclure le type `null` dans l’ensemble des types du `union` Avro, car nous ne savons pas, lors de l’inférence du schéma, si une valeur est effectivement `null`.

\*\*\* [Types logiques Avro](https://avro.apache.org/docs/1.12.0/specification/#logical-types)

Types de données logiques Avro non pris en charge :

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

## Paramètres du format

| Setting | Description | Default |
| - | - | - |
| `input_format_avro_allow_missing_fields` | Indique s’il faut utiliser une valeur par défaut au lieu de générer une erreur lorsqu’un champ est introuvable dans le schéma. | `0` |
| `input_format_avro_null_as_default` | Indique s’il faut utiliser une valeur par défaut au lieu de générer une erreur lors de l’insertion d’une valeur `null` dans une colonne non nullable. | `0` |
| `output_format_avro_codec` | Algorithme de compression pour les fichiers de sortie Avro. Valeurs possibles : `null`, `deflate`, `snappy`, `zstd`. | |
| `output_format_avro_sync_interval` | Fréquence du marqueur de synchronisation dans les fichiers Avro (en octets). | `16384` |
| `output_format_avro_string_column_pattern` | Expression régulière permettant d’identifier les colonnes `String` pour la correspondance de types des chaînes Avro. Par défaut, les colonnes `String` de ClickHouse sont écrites avec le type Avro `bytes`. | |
| `output_format_avro_rows_in_file` | Nombre maximal de lignes par fichier de sortie Avro. Lorsque cette limite est atteinte, un nouveau fichier est créé (si le système de stockage prend en charge le fractionnement des fichiers). | `1` |

## Exemples

### Lecture de données Avro

Pour lire des données à partir d’un fichier Avro dans une table ClickHouse :

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

Le schéma racine du fichier Avro ingéré doit être de type `record`.

Pour établir la correspondance entre les colonnes de la table et les champs du schéma Avro, ClickHouse compare leurs noms.
Cette comparaison est sensible à la casse, et les champs inutilisés sont ignorés.

Les types de données des colonnes de la table ClickHouse peuvent différer de ceux des champs correspondants dans les données Avro insérées. Lors de l’insertion des données, ClickHouse interprète les types de données conformément au tableau ci-dessus, puis [convertit](https://clickhouse.com/docs/fr/reference/functions/regular-functions/type-conversion-functions.md#CAST) les données dans le type de colonne correspondant.

Lors de l’importation des données, si un champ est introuvable dans le schéma et que le paramètre [`input_format_avro_allow_missing_fields`](https://clickhouse.com/docs/fr/reference/settings/formats/input-format#input_format_avro_allow_missing_fields) est activé, la valeur par défaut est utilisée au lieu de générer une erreur.

### Écrire des données Avro

Pour écrire des données d'une table ClickHouse dans un fichier Avro :

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

Les noms de colonnes doivent :

* Commencer par `[A-Za-z_]`
* Être suivis uniquement de `[A-Za-z0-9_]`

La compression de sortie et l’intervalle de synchronisation des fichiers Avro peuvent être configurés respectivement à l’aide des paramètres [`output_format_avro_codec`](https://clickhouse.com/docs/fr/reference/settings/formats/output-format#output_format_avro_codec) et [`output_format_avro_sync_interval`](https://clickhouse.com/docs/fr/reference/settings/formats/output-format#output_format_avro_sync_interval).

### Inférer le schéma Avro

À l’aide de la fonction ClickHouse [`DESCRIBE`](https://clickhouse.com/docs/fr/reference/statements/describe-table), vous pouvez afficher rapidement le format inféré d’un fichier Avro, comme dans l’exemple suivant.
Cet exemple inclut l’URL d’un fichier Avro accessible au public dans le bucket public 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           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
```