> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Documentation sur le format AvroConfluent # AvroConfluent | Entrée | Sortie | Alias | | ------ | ------ | ----- | | ✔ | ✔ | |
## Description
[Apache Avro](https://avro.apache.org/) est un format de sérialisation orienté ligne qui utilise un encodage binaire pour traiter efficacement les données. Le format `AvroConfluent` prend en charge la lecture et l'écriture de messages encodés en Avro à l'aide du [Confluent Schema Registry](https://docs.confluent.io/current/schema-registry/index.html) (ou de services compatibles avec l'API). Chaque message utilise le wire format de Confluent : un octet magique (`0x00`), suivi d'un schema ID de 4 octets en big-endian, puis de la donnée binaire Avro. En lecture, ClickHouse résout le schema ID en interrogeant le registry. En écriture, ClickHouse enregistre le schéma dérivé des colonnes de sortie et ajoute l'ID obtenu en préfixe de chaque ligne. Les schémas sont mis en cache pour des performances optimales.
## 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](/fr/reference/data-types/index) ClickHouse correspondants dans les requêtes `INSERT` et `SELECT`. | Type de données Avro `INSERT` | Type de données ClickHouse | Type de données Avro `SELECT` | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------- | | `boolean`, `int`, `long`, `float`, `double` | [Int(8\16\32)](/fr/reference/data-types/int-uint), [UInt(8\16\32)](/fr/reference/data-types/int-uint) | `int` | | `boolean`, `int`, `long`, `float`, `double` | [Int64](/fr/reference/data-types/int-uint), [UInt64](/fr/reference/data-types/int-uint) | `long` | | `boolean`, `int`, `long`, `float`, `double` | [Float32](/fr/reference/data-types/float) | `float` | | `boolean`, `int`, `long`, `float`, `double` | [Float64](/fr/reference/data-types/float) | `double` | | `bytes`, `string`, `fixed`, `enum` | [String](/fr/reference/data-types/string) | `bytes` ou `string` \* | | `bytes`, `string`, `fixed` | [FixedString(N)](/fr/reference/data-types/fixedstring) | `fixed(N)` | | `enum` | [Enum(8\16)](/fr/reference/data-types/enum) | `enum` | | `array(T)` | [Array(T)](/fr/reference/data-types/array) | `array(T)` | | `map(V, K)` | [Map(V, K)](/fr/reference/data-types/map) | `map(string, K)` | | `union(null, T)`, `union(T, null)` | [Nullable(T)](/fr/reference/data-types/date) | `union(null, T)` | | `union(T1, T2, …)` \*\* | [Variant(T1, T2, …)](/fr/reference/data-types/variant) | `union(T1, T2, …)` \*\* | | `null` | [Nullable(Nothing)](/fr/reference/data-types/special-data-types/nothing) | `null` | | `int (date)` \*\*\* | [Date](/fr/reference/data-types/date), [Date32](/fr/reference/data-types/date32) | `int (date)` \*\*\* | | `long (timestamp-millis)` \*\*\* | [DateTime64(3)](/fr/reference/data-types/datetime) | `long (timestamp-millis)` \*\*\* | | `long (timestamp-micros)` \*\*\* | [DateTime64(6)](/fr/reference/data-types/datetime) | `long (timestamp-micros)` \*\*\* | | `bytes (decimal)` \*\*\* | [DateTime64(N)](/fr/reference/data-types/datetime) | `bytes (decimal)` \*\*\* | | `int` | [IPv4](/fr/reference/data-types/ipv4) | `int` | | `fixed(16)` | [IPv6](/fr/reference/data-types/ipv6) | `fixed(16)` | | `bytes (decimal)` \*\*\* | [Decimal(P, S)](/fr/reference/data-types/decimal) | `bytes (decimal)` \*\*\* | | `string (uuid)` \*\*\* | [UUID](/fr/reference/data-types/uuid) | `string (uuid)` \*\*\* | | `fixed(16)` | [Int128/UInt128](/fr/reference/data-types/int-uint) | `fixed(16)` | | `fixed(32)` | [Int256/UInt256](/fr/reference/data-types/int-uint) | `fixed(32)` | | `record` | [Tuple](/fr/reference/data-types/tuple) | `record` | * `bytes` est la valeur par défaut, contrôlée par le paramètre [`output_format_avro_string_column_pattern`](/fr/reference/settings/formats#output_format_avro_string_column_pattern) \*\* Le [type Variant](/fr/reference/data-types/variant) 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 le `union` d’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/current/spec.html#Logical+Types) Types de données logiques Avro non pris en charge : * `time-millis` * `time-micros` * `duration`
## Paramètres de format
[//]: # "NOTE Ces paramètres peuvent être définis au niveau de la session, mais ce n'est pas courant et le fait de trop le mettre en avant dans la documentation peut prêter à confusion pour les utilisateurs." | Paramètre | Description | Valeur par défaut | | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | `input_format_avro_allow_missing_fields` | Indique s'il faut utiliser une valeur par défaut au lieu de renvoyer 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 renvoyer une erreur lors de l'insertion d'une valeur `null` dans une colonne non nullable. | `0` | | `format_avro_schema_registry_url` | L'URL du Confluent Schema Registry. Pour l'authentification de base, des identifiants encodés dans l'URL peuvent être inclus directement dans le chemin de l'URL. | | | `format_avro_schema_registry_connection_timeout` | Délai d'expiration de connexion, en secondes, pour le client HTTP du Schema Registry (utilisé à la fois pour la récupération et l'enregistrement du schéma). Doit être supérieur à 0 et inférieur à 600 (10 minutes). | `1` | | `format_avro_schema_registry_send_timeout` | Délai d'expiration d'envoi, en secondes, pour le client HTTP du Schema Registry. Doit être supérieur à 0 et inférieur à 600 (10 minutes). | `1` | | `format_avro_schema_registry_receive_timeout` | Délai d'expiration de réception, en secondes, pour le client HTTP du Schema Registry. Doit être supérieur à 0 et inférieur à 600 (10 minutes). | `1` | | `output_format_avro_confluent_subject` | En sortie : nom du sujet sous lequel le schéma est enregistré dans le Schema Registry. Obligatoire lors de l'écriture. | | | `output_format_avro_string_column_pattern` | En sortie : expression régulière des colonnes String à sérialiser en `string` Avro (par défaut, `bytes`). | |
## Exemples
### Lecture à partir de Kafka
Pour lire un topic Kafka encodé en Avro à l’aide du [Kafka table engine](/fr/reference/engines/table-engines/integrations/kafka), utilisez le paramètre `format_avro_schema_registry_url` pour fournir l’URL du registre de schémas. ```sql theme={null} CREATE TABLE topic1_stream ( field1 String, field2 String ) ENGINE = Kafka() SETTINGS kafka_broker_list = 'kafka-broker', kafka_topic_list = 'topic1', kafka_group_name = 'group1', kafka_format = 'AvroConfluent', format_avro_schema_registry_url = 'http://schema-registry-url'; SELECT * FROM topic1_stream; ```
### Écriture dans Kafka
Pour écrire des messages AvroConfluent dans un topic Kafka, définissez l’URL du registre de schémas ainsi que le nom du sujet. Le schéma est automatiquement enregistré dans le registre de schémas lors de la première écriture. ```sql theme={null} CREATE TABLE topic1_sink ( field1 String, field2 String ) ENGINE = Kafka() SETTINGS kafka_broker_list = 'kafka-broker', kafka_topic_list = 'topic1', kafka_format = 'AvroConfluent', format_avro_schema_registry_url = 'http://schema-registry-url', output_format_avro_confluent_subject = 'topic1-value'; INSERT INTO topic1_sink VALUES ('hello', 'world'); ```
#### Utiliser l’authentification de base
Si votre registre de schémas nécessite une authentification de base (par exemple, si vous utilisez Confluent Cloud), vous pouvez fournir des identifiants encodés au format URL dans le paramètre `format_avro_schema_registry_url`. ```sql theme={null} CREATE TABLE topic1_stream ( field1 String, field2 String ) ENGINE = Kafka() SETTINGS kafka_broker_list = 'kafka-broker', kafka_topic_list = 'topic1', kafka_group_name = 'group1', kafka_format = 'AvroConfluent', format_avro_schema_registry_url = 'https://:@schema-registry-url'; ```
## Dépannage
Pour surveiller la progression de l’ingestion et déboguer les erreurs du consumer Kafka, vous pouvez interroger la [table système `system.kafka_consumers`](/fr/reference/system-tables/kafka_consumers). Si votre déploiement comporte plusieurs répliques (par exemple, ClickHouse Cloud), vous devez utiliser la [fonction de table `clusterAllReplicas`](/fr/reference/functions/table-functions/cluster). ```sql theme={null} SELECT * FROM clusterAllReplicas('default',system.kafka_consumers) ORDER BY assignments.partition_id ASC; ``` Si vous rencontrez des problèmes de résolution du schéma, vous pouvez utiliser [kafkacat](https://github.com/edenhill/kafkacat) avec [clickhouse-local](/fr/concepts/features/tools-and-utilities/clickhouse-local) pour effectuer le dépannage : ```bash theme={null} $ kafkacat -b kafka-broker -C -t topic1 -o beginning -f '%s' -c 3 | clickhouse-local --input-format AvroConfluent --format_avro_schema_registry_url 'http://schema-registry' -S "field1 Int64, field2 String" -q 'select * from table' 1 a 2 b 3 c ```