Avro

Entrée	Sortie	Alias
✔	✔

Description

Apache Avro 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. 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.

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 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), 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` or `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 est la valeur par défaut, contrôlée par le paramètre output_format_avro_string_column_pattern

** Le type 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 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 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 :

$ 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 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 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 :

$ 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 et output_format_avro_sync_interval.

Inférer le schéma Avro

À l’aide de la fonction ClickHouse DESCRIBE, 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 :

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           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

Référence SQL

Types de données

Moteurs

Fonctions

Formats

Paramètres

Tables système

Lacs de données

Description

Correspondance des types de données

Paramètres du format

Exemples

Lecture de données Avro

Écrire des données Avro

Inférer le schéma Avro

​Description

​Correspondance des types de données

​Paramètres du format

​Exemples

​Lecture de données Avro

​Écrire des données Avro

​Inférer le schéma Avro

Description

Correspondance des types de données

Paramètres du format

Exemples

Lecture de données Avro

Écrire des données Avro

Inférer le schéma Avro