Charger des données Avro depuis Google Cloud Storage

Charger des fichiers Avro depuis Cloud Storage

Avro est un format de données Open Source qui regroupe des données sérialisées avec le schéma de données dans un même fichier.

Lorsque vous chargez des données Avro depuis Cloud Storage, vous pouvez les placer dans une nouvelle table ou partition, les ajouter à une table ou une partition existante, ou bien les utiliser pour écraser une table ou une partition. Lorsque les données sont chargées dans BigQuery, elles sont converties au format en colonnes de Capacitor (format de stockage de BigQuery).

Lorsque vous chargez des données depuis Cloud Storage dans une table BigQuery, l'ensemble de données contenant la table doit se trouver dans la même zone régionale ou multirégionale que le bucket Cloud Storage.

Pour en savoir plus sur le chargement des données Avro à partir d'un fichier local, consultez l'article Charger des données dans BigQuery à partir d'une source de données locale.

Avantages d'Avro

Avro est le format préconisé pour charger des données dans BigQuery. Les fichiers Avro présentent les avantages ci-dessous par rapport aux fichiers CSV et JSON (délimités par un retour à la ligne).

• Le format binaire Avro :
  • permet un chargement plus rapide (possibilité de lire les données en parallèle, même si les blocs de données sont compressés) ;
  • ne requiert pas de saisie ni de sérialisation ;
  • est plus facile à analyser, car il n'engendre pas les problèmes d'encodage rencontrés avec d'autres formats comme ASCII.
• Lorsque vous chargez des fichiers Avro dans BigQuery, le schéma de la table est automatiquement extrait des données sources auto-descriptives.

Autorisations requises

Lorsque vous chargez des données dans BigQuery, vous avez besoin d'autorisations au niveau du projet ou de l'ensemble de données qui vous permettent de procéder au chargement dans des tables et partitions BigQuery nouvelles ou existantes. Si vous chargez des données depuis Cloud Storage, vous devez également avoir accès au bucket contenant vos données.

Autorisations BigQuery

Lorsque vous chargez des données dans BigQuery depuis Cloud Storage, vous devez disposer du rôle bigquery.dataOwner ou bigquery.dataEditor au niveau du projet ou de l'ensemble de données. Les deux rôles permettent aux utilisateurs et aux groupes de charger les données dans une nouvelle table, de les ajouter à une table existante ou de les utiliser pour écraser une table.

L'attribution des rôles au niveau du projet donne à l'utilisateur ou au groupe la possibilité de charger les données dans les tables de chaque ensemble de données du projet. L'attribution des rôles au niveau de l'ensemble de données permet à l'utilisateur ou au groupe de charger les données uniquement dans les tables de cet ensemble de données.

Pour en savoir plus sur la configuration de l'accès aux ensembles de données, consultez la section Appliquer des contrôles d'accès aux ensembles de données. Pour plus d'informations sur les rôles IAM dans BigQuery, consultez l'article Contrôle des accès.

Autorisations Cloud Storage

Pour charger les données d'un bucket Cloud Storage, vous devez disposer des autorisations storage.objects.get au niveau du projet ou du bucket concerné. Si vous utilisez un caractère générique dans l'URI, vous devez également disposer des autorisations storage.objects.list.

Le rôle IAM storage.objectViewer prédéfini peut être accordé pour fournir des autorisations storage.objects.get et storage.objects.list.

Schémas Avro

Lors du chargement de fichiers Avro dans BigQuery, le schéma de la table est automatiquement extrait à l'aide des données sources. Lorsque BigQuery récupère le schéma à partir des données sources, le fichier qui figure en dernier selon l'ordre alphabétique est utilisé.

Supposons par exemple que vous disposiez des fichiers Avro suivants dans Cloud Storage :

gs://mybucket/00/
  a.avro
  z.avro
gs://mybucket/01/
  b.avro

La commande ci-dessous de l'interface de ligne de commande permet de charger en une seule fois tous les fichiers (sous forme de liste d'éléments séparés par une virgule). Le schéma est obtenu à partir de mybucket/01/b.avro.

bq --location=US load --source_format=AVRO [DATASET].[TABLE_NAME] "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

Lorsque vous importez plusieurs fichiers Avro avec différents schémas Avro, tous les schémas doivent être compatibles avec la fonctionnalité de résolution de schéma d'Avro.

Lorsque BigQuery détecte le schéma, certains types de données Avro sont convertis en types de données BigQuery de façon à être compatibles avec la syntaxe SQL BigQuery. Pour en savoir plus, consultez la section Conversions Avro.

Compression de fichiers Avro

Les fichiers Avro compressés ne sont pas acceptés, à la différence des blocs de données compressés. BigQuery est compatible avec les codecs DEFLATE et Snappy.

Charger des données Avro dans une nouvelle table

Pour charger des données Avro depuis Google Cloud Storage dans une nouvelle table BigQuery, procédez comme suit :

Interface utilisateur Web

1. Accédez à l'interface utilisateur Web de BigQuery.
   Accéder à l'UI Web de BigQuery

2. Dans le panneau de navigation, passez la souris sur un ensemble de données. Ensuite, cliquez sur la flèche vers le bas , puis sur Créer une table. Le processus de chargement des données est identique au processus de création d'une table vide.

3. Dans la section Données sources de la page Créer une table :

   • Pour Emplacement, sélectionnez Google Cloud Storage. Dans le champ "Source", indiquez l'URI Cloud Storage. Notez que vous ne pouvez pas inclure plusieurs URI dans l'interface utilisateur Web de BigQuery. En revanche, les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver au même emplacement que l'ensemble de données contenant la table que vous créez.
   • Pour le paramètre Format de fichier, sélectionnez Avro.
4. Dans la section Table de destination de la page Créer une table, procédez comme suit :
   • Pour Nom de la table, sélectionnez l'ensemble de données approprié, puis saisissez dans le champ le nom de la table que vous créez dans BigQuery.
   • Vérifiez que Type de table est défini sur Table native.
5. Aucune action n'est nécessaire dans la section Schéma. Le schéma est obtenu à partir des fichiers Avro.
6. Cliquez sur Créer une table.

Ligne de commande

Utilisez la commande bq load, indiquez AVRO pour source_format et spécifiez un URI Cloud Storage. Vous pouvez inclure un seul URI, une liste d'URI séparés par une virgule ou un URI contenant un caractère générique.

Spécifiez l'indicateur --location, puis définissez sa valeur sur votre emplacement.

bq --location=[LOCATION] load --source_format=[FORMAT] [DATASET].[TABLE] [PATH_TO_SOURCE]

où :

• [LOCATION] correspond à votre zone. L'indicateur --location est facultatif si les données se trouvent dans la zone multirégionale US ou EU. Par exemple, si vous utilisez BigQuery dans la région Tokyo, définissez la valeur de l'indicateur sur asia-northeast1. Vous pouvez spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
• [FORMAT] correspond à AVRO.
• [DATASET] est un ensemble de données existant.
• [TABLE] est le nom de la table dans laquelle vous chargez des données.
• [PATH_TO_SOURCE] est un URI Cloud Storage complet ou une liste d'URI séparés par une virgule. Les caractères génériques sont également acceptés.

Exemples :

• La commande ci-dessous permet de charger les données de gs://mybucket/mydata.avro dans la table mytable de mydataset. mybucket et mydataset ont été créés dans la zone multirégionale US.

  bq --location=US load --source_format=AVRO mydataset.mytable gs://mybucket/mydata.avro
  

• La commande ci-dessous permet de charger les données de plusieurs fichiers de gs://mybucket/ dans la table mytable de mydataset. L'URI Cloud Storage utilise un caractère générique. mybucket et mydataset ont été créés dans la zone multirégionale US.

  bq --location=US load --source_format=AVRO mydataset.mytable gs://mybucket/mydata*.avro
  

• La commande suivante permet de charger des données de plusieurs fichiers de gs://mybucket/ dans la table mytable de mydataset : La commande inclut une liste d'URI Cloud Storage séparés par une virgule avec des caractères génériques. mybucket et mydataset ont été créés dans la région asia-northeast1.

  bq --location=asia-northeast1 load --autodetect --source_format=AVRO mydataset.mytable "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"
  

API

Définissez les propriétés ci-dessous pour charger des données Avro à l'aide de l'API.

1. Créez une tâche de chargement qui pointe vers les données sources dans Google Cloud Storage.

2. Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource de la tâche.

3. Les URI sources doivent être complets et respecter le format gs://[BUCKET]/[OBJECT]. Chaque URI peut contenir un caractère générique (*).

4. Spécifiez le format de données en définissant la propriété configuration.load.sourceFormat sur AVRO.

5. Pour vérifier l'état de la tâche, appelez jobs.get([JOB_ID]*), où [JOB_ID] correspond à l'ID de la tâche renvoyée par la requête initiale.

   • Si status.state = DONE, la tâche a bien été exécutée.
   • Si la propriété status.errorResult est présente, la requête a échoué. Cet objet inclura des informations décrivant le problème rencontré. Lorsqu'une requête échoue, aucune table n'est créée et aucune donnée n'est ajoutée.
   • Si la propriété status.errorResult est absente, la tâche a bien été exécutée. Toutefois, des erreurs non fatales, telles que des problèmes d'importation de lignes, ont pu se produire. Les erreurs non fatales sont répertoriées dans la propriété status.errors de l'objet de tâche renvoyé.

Remarques relatives à l'API :

• Les tâches de chargement sont atomiques et cohérentes. En cas d'échec d'une tâche de chargement, aucune donnée n'est disponible. Si une tâche aboutit, toutes les données sont disponibles.

• Nous vous recommandons de générer un identifiant unique et de le transmettre en tant que jobReference.jobId lorsque vous appelez jobs.insert() pour créer une tâche de chargement. Cette approche offre une protection plus robuste contre les pannes réseau, car le client peut lancer une requête ou effectuer de nouvelles tentatives en utilisant l'ID de tâche connu.

• L'appel de jobs.insert() avec un ID de tâche donné est idempotent. En d'autres termes, vous pouvez effectuer autant de tentatives que vous le souhaitez avec le même ID de tâche. Au maximum une de ces opérations réussira.

Ajouter ou écraser des données dans une table avec des données Avro

Vous pouvez charger des données supplémentaires dans une table à partir de fichiers sources ou en ajoutant des résultats de requête.

Dans l'interface utilisateur Web de BigQuery, utilisez l'option Préférence d'écriture pour spécifier l'action à entreprendre lorsque vous chargez des données à partir d'un fichier source ou d'un résultat de requête. La CLI et l'API incluent les options suivantes :

Option de l'interface utilisateur Web	Indicateur de la CLI	Propriété de l'API BigQuery	Description
Écrire si la table est vide	Aucun	WRITE_EMPTY	N'écrit les données que si la table est vide.
Ajouter à la table	--noreplace ou --replace=false. Si --[no]replace n'est pas spécifié, les données sont ajoutées par défaut.	WRITE_APPEND	(Par défaut) Ajoute les données à la fin de la table.
Écraser la table	--replace ou --replace=true	WRITE_TRUNCATE	Efface toutes les données existantes d'une table avant d'écrire les nouvelles données.

Pour charger des données Avro depuis Google Cloud Storage, puis les ajouter à une table BigQuery ou les utiliser pour écraser une table BigQuery, procédez comme indiqué ci-dessous.

Interface utilisateur Web

1. Accédez à l'interface utilisateur Web de BigQuery.
   Accéder à l'UI Web de BigQuery

2. Dans le panneau de navigation, passez la souris sur un ensemble de données. Ensuite, cliquez sur la flèche vers le bas , puis sur Créer une table. Le processus de chargement des données est identique au processus de création d'une table vide.

3. Dans la section Données sources de la page Créer une table :

   • Pour Emplacement, sélectionnez Google Cloud Storage. Dans le champ "Source", indiquez l'URI Cloud Storage. Notez que vous ne pouvez pas inclure plusieurs URI dans l'interface utilisateur. En revanche, les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver au même emplacement que l'ensemble de données contenant la table à laquelle vous ajoutez des données ou que vous écrasez.
   • Pour le paramètre Format de fichier, sélectionnez Avro.
4. Dans la section Table de destination de la page Créer une table, procédez comme suit :
   • Pour Nom de la table, sélectionnez l'ensemble de données approprié, puis saisissez dans le champ le nom de la table à laquelle vous ajoutez des données ou que vous écrasez.
   • Vérifiez que Type de table est défini sur Table native.
5. Aucune action n'est nécessaire dans la section Schéma. Les informations de schéma sont obtenues à partir des fichiers Avro.

6. Dans la section Options, pour l'option Write preference (Préférence d'écriture), choisissez Write if empty (Écrire si la table est vide), Append to table (Ajouter à la table) ou Overwrite table (Écraser la table).

   

7. Cliquez sur Create Table (Créer une table).

Ligne de commande

Saisissez la commande bq load avec l'indicateur --replace pour écraser la table. Spécifiez l'indicateur --location, puis définissez sa valeur sur votre emplacement. Utilisez l'indicateur --noreplace pour ajouter des données à la table. Si aucun indicateur n'est spécifié, les données sont ajoutées par défaut.

bq --location=[LOCATION] load --[no]replace [DATASET].[TABLE] [PATH_TO_SOURCE]

où :

• [LOCATION] correspond à votre zone. L'indicateur --location est facultatif si les données se trouvent dans la zone multirégionale US ou EU.Vous pouvez définir une valeur par défaut pour la zone à l'aide du fichier .bigqueryrc.
• [DATASET] est un ensemble de données existant.
• [TABLE] est le nom de la table dans laquelle vous chargez des données.
• [PATH_TO_SOURCE] est un URI Cloud Storage complet ou une liste d'URI séparés par une virgule. Les caractères génériques sont également acceptés.

Exemples :

• La commande ci-dessous permet de charger les données de gs://mybucket/mydata.avro et d'écraser la table mytable de mydataset. mybucket et mydataset ont été créés dans la zone multirégionale US.

  bq --location=US load --replace --source_format=AVRO mydataset.mytable gs://mybucket/mydata.avro
  

• La commande ci-dessous permet de charger les données de gs://mybucket/mydata.avro et de les ajouter à la table mytable de mydataset. mybucket et mydataset ont été créés dans la région asia-northeast1.

  bq --location=asia-northeast1 load --noreplace --source_format=AVRO mydataset.mytable gs://mybucket/mydata.avro
  

API

Définissez les propriétés ci-dessous pour charger des données CSV à l'aide de l'API.

1. Créez une tâche de chargement qui pointe vers les données sources dans Google Cloud Storage.

2. Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource de la tâche.

3. Les URI sources doivent être complets et respecter le format gs://[BUCKET]/[OBJECT]. Vous pouvez inclure plusieurs URI sous forme de liste en les séparant par une virgule. Notez que les caractères génériques sont également acceptés lorsque vous chargez des données CSV depuis Google Cloud Storage.

4. Spécifiez le format de données en définissant la propriété configuration.load.sourceFormat sur AVRO.

5. Spécifiez la préférence d'écriture en définissant la propriété configuration.load.writeDisposition sur WRITE_TRUNCATE, WRITE_APPEND ou WRITE_EMPTY.

Conversions Avro

BigQuery convertit les types de données Avro en types de données BigQuery, comme décrit ci-dessous.

Types primitifs

Type de données Avro	Type de données BigQuery	Notes
null	BigQuery ignore ces valeurs.
boolean	BOOLEAN
int	INTEGER
long	INTEGER
float	FLOAT
double	FLOAT
bytes	BYTES
bytes correspondant au type logique decimal	NUMERIC
string	STRING	UTF-8 uniquement

Types complexes

Type de données Avro	Type de données BigQuery	Notes
record	RECORD	Les alias sont ignorés. L'attribut "doc" est converti en description de champ. Les valeurs par défaut sont définies lors de la lecture. L'ordre est ignoré. Les champs récursifs sont supprimés. Seul le premier niveau d'imbrication est conservé pour ces derniers.
enum	STRING	La chaîne est la valeur symbolique du type "enum". Les alias sont ignorés. L'attribut "doc" est converti en description de champ.
array	champs répétés	Les tableaux de tableaux ne sont pas acceptés. Les tableaux ne contenant que des types vides (NULL) sont ignorés.
map<T>	RECORD	BigQuery convertit un champ "map<T>" Avro en champ RECORD répété contenant deux champs : une clé et une valeur. BigQuery stocke la clé sous forme de chaîne (STRING) et convertit la valeur dans le type de données correspondant dans BigQuery.
union	Champ pouvant être vide RECORD avec une liste de champs pouvant être vides	Si le type complexe "union" n'inclut qu'un seul type non vide, il est converti en champ pouvant être vide. Dans le cas contraire, il est converti en champ RECORD incluant une liste de champs pouvant être vides. Un seul de ces champs est défini lors de la lecture.
fixed	BYTES	Les alias sont ignorés. La taille est ignorée.

Types logiques

En général, BigQuery ignore l'attribut logicalType et utilise à la place le type Avro sous-jacent.

Type logique Avro	Type de données BigQuery	Notes
date	INTEGER
time-millis	INTEGER
time-micros	INTEGER (converti à partir du type LONG)
timestamp-millis	INTEGER (converti à partir du type LONG)
timestamp-micros	INTEGER (converti à partir du type LONG)
duration	BYTES (converti à partir du type fixed de taille 12)
decimal	NUMERIC (voir la section Type logique décimal)

Pour en savoir plus sur les types de données Avro, consultez la spécification Apache Avro™ 1.8.2.

Type logique décimal

Un type bytes Avro correspondant au type logique decimal peut avoir au plus une valeur precision de 38 (nombre total de chiffres) et une valeur scale de 9 (chiffres à droite de la décimale). Le nombre d'entiers, qui correspond à la précision moins l'échelle (precision - scale), ne peut pas dépasser 29. Par exemple, un type decimal ayant une valeur precision de 38 et une valeur scale de 9 est accepté, car le nombre d'entiers est dans ce cas égal à 29. Un type decimal ayant une valeur precision de 38 et une valeur scale de 5 n'est pas accepté, car le nombre d'entiers est alors égal à 33.

Lorsque vous chargez un fichier Avro contenant une colonne bytes correspondant au type logique decimal dans une table existante, le type de données de la colonne dans la définition de schéma de la table peut être BYTES ou NUMERIC. Si le type de données de la colonne est BYTES, le type logique decimal de la colonne dans le fichier Avro est ignoré.

Pour en savoir plus sur le type logique decimal Avro, consultez la spécification Apache Avro™ 1.8.2.