Charger des données Avro depuis 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 le même emplacement régional ou multirégional 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.

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 load \
--source_format=AVRO \
dataset.table \
"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.

Autorisations requises

Lorsque vous chargez des données dans BigQuery, vous avez besoin d'autorisations pour exécuter une tâche de chargement et charger des données dans des tables et partitions BigQuery nouvelles ou existantes. Si vous chargez des données à partir de Cloud Storage, vous devez également disposer d'autorisations pour accéder au bucket contenant vos données.

Autorisations BigQuery

Vous devez au moins disposer des autorisations suivantes pour charger des données dans BigQuery. Elles sont requises si vous chargez des données dans une nouvelle table ou partition, mais également si vous ajoutez ou écrasez une table ou une partition.

bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create

Les rôles Cloud IAM prédéfinis suivants incluent les autorisations bigquery.tables.create et bigquery.tables.updateData :

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

Vous trouverez ci-dessous les rôles Cloud IAM prédéfinis qui incluent les autorisations bigquery.jobs.create :

bigquery.user
bigquery.jobUser
bigquery.admin

En outre, si un utilisateur possède des autorisations bigquery.datasets.create, lorsqu'il crée un ensemble de données, il obtient également le rôle bigquery.dataOwner qui lui permet d'y accéder. L'accès bigquery.dataOwner donne à l'utilisateur la possibilité de créer et de mettre à jour des tables dans l'ensemble de données via une tâche de chargement.

Pour en savoir plus sur les rôles et les autorisations Cloud IAM dans BigQuery, consultez la page Contrôle des accès.

Autorisations Cloud Storage

Pour pouvoir charger des données à partir d'un bucket Cloud Storage, vous devez disposer des autorisations storage.objects.get. Si vous utilisez un caractère générique dans l'URI, vous devez également disposer des autorisations storage.objects.list.

Le rôle Cloud IAM prédéfini storage.objectViewer peut être attribué afin d'accorder les autorisations storage.objects.get et storage.objects.list.

Charger des données Avro dans une nouvelle table

Vous pouvez charger des données Avro dans une nouvelle table par les moyens suivants :

En utilisant la console GCP ou l'interface utilisateur Web classique de BigQuery
En exécutant la commande bq load de la CLI
En appelant la méthode API jobs.insert et en configurant une tâche load
En utilisant les bibliothèques clientes

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

Console

Ouvrez l'UI Web de BigQuery dans la console GCP.
Accéder à la console GCP
Dans la section Resources (Ressources) du panneau de navigation, développez votre projet et sélectionnez un ensemble de données.
À droite de la fenêtre, dans le panneau de détails, cliquez sur Create table (Créer une table). Le processus de chargement des données est identique au processus de création d'une table vide.
Dans la section Source de la page Create table (Créer une table) :
- Pour le champ Create table from (Créer une table à partir de), sélectionnez Cloud Storage.
- Dans le champ "Source", recherchez ou entrez l'URI de stockage Cloud. Notez que vous ne pouvez pas inclure plusieurs URI dans la console GCP, mais les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver dans le même emplacement que l'ensemble de données contenant la table que vous créez.
- Pour le paramètre File format (Format de fichier), sélectionnez Avro.
Dans la section Destination de la page Create Table (Créer une table) :
- Sous Dataset name (Nom de l'ensemble de données), sélectionnez l'ensemble de données approprié.
- Vérifiez que Table type (Type de table) est défini sur Native table (Table native).
- Dans le champ Table name (Nom de la table), saisissez le nom de la table que vous créez dans BigQuery.
Aucune action n'est nécessaire dans la section Schema (Schéma). Le schéma est auto-décrit dans les fichiers Avro.
(Facultatif) Pour partitionner la table, choisissez vos options dans le champ Partition and cluster settings (Paramètres de partitionnement et de clustering) :
- Pour créer une table partitionnée, cliquez sur No partitioning (Aucun partitionnement), sélectionnez Partition by field (Partitionner par champ), puis choisissez une colonne DATE ou TIMESTAMP. Cette option n'est pas disponible si votre schéma n'inclut pas de colonne DATE ni TIMESTAMP.
- Pour créer une table partitionnée par date d'ingestion, cliquez sur No partitioning (Aucun partitionnement), puis sélectionnez Partition by ingestion time (Partitionner par date d'ingestion).
(Facultatif) Pour le champ Partitioning filter (Filtre de partitionnement), cochez la case Require partition filter (Demander un filtre de partitionnement) pour obliger les utilisateurs à inclure une clause WHERE spécifiant les partitions à interroger. Ce type de filtre peut contribuer à réduire les coûts et à améliorer les performances. Pour en savoir plus, consultez la page Interroger des tables partitionnées. Cette option n'est pas disponible si No partitioning (Aucun partitionnement) est sélectionné.
(Facultatif) Pour mettre une table en cluster, saisissez entre un et quatre noms de champ dans la zone Clustering order (Ordre de clustering). Actuellement, le clustering n'est disponible que pour les tables partitionnées.
(Facultatif) Cliquez sur Advanced options (Options avancées).
- Pour le champ Write preference (Préférence d'écriture), laissez l'option Write if empty (Écrire si la table est vide) sélectionnée. Cette option crée une table et y charge vos données.
- Pour le champ Number of errors allowed (Nombre d'erreurs autorisées), acceptez la valeur par défaut 0 ou saisissez le nombre maximal de lignes contenant des erreurs pouvant être ignorées. Si le nombre de lignes contenant des erreurs dépasse cette valeur, la tâche renverra un message invalid et échouera.
- Pour le champ Unknown values (Valeurs inconnues), conservez l'option Ignore unknown values (Ignorer les valeurs inconnues) désactivée. Cette option ne s'applique qu'aux fichiers CSV et JSON.
- Pour le champ Encryption (Chiffrement), cliquez sur Customer-managed key (Clé gérée par le client) pour utiliser une clé de service Cloud Key Management. Si vous conservez l'option Google-managed key (Clé gérée par Google), BigQuery chiffre les données au repos.
Cliquez sur Create table (Créer une table).

UI classique

Accédez à l'interface utilisateur Web de BigQuery.
Accéder à l'UI Web de BigQuery
Dans le panneau de navigation, passez la souris sur un ensemble de données, cliquez sur l'icône de flèche vers le bas , puis cliquez sur Create new table (Créer une table). Le processus de chargement des données est identique au processus de création d'une table vide.
Dans la section Source Date (Données source) de la page Create Table (Créer une table) :
- Cliquez sur Create from source (Créer à partir de la source).
- Pour le champ Location (Emplacement), sélectionnez Cloud Storage. Dans le champ "Source", indiquez l'URI Cloud Storage. Sachez 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 dans le même emplacement que l'ensemble de données contenant la table que vous créez.
- Pour le paramètre File format (Format de fichier), sélectionnez Avro.
Dans la section Destination Table (Table de destination) :
- Pour le champ Table name (Nom de la table), sélectionnez l'ensemble de données approprié, puis saisissez le nom de la table que vous créez dans BigQuery dans le champ correspondant.
- Vérifiez que Table type (Type de table) est défini sur Native table (Table native).
Aucune action n'est nécessaire dans la section Schema (Schéma). Le schéma est auto-décrit dans les fichiers Avro.
(Facultatif) Dans la section Options :
- Pour le champ Number of errors allowed (Nombre d'erreurs autorisées), acceptez la valeur par défaut 0 ou saisissez le nombre maximal de lignes contenant des erreurs pouvant être ignorées. Si le nombre de lignes contenant des erreurs dépasse cette valeur, la tâche renverra un message invalid et échouera.
- Pour le champ Write preference (Préférence d'écriture), laissez l'option Write if empty (Écrire si la table est vide) sélectionnée. Cette option crée une table et y charge vos données.
- Pour partitionner la table :
  - Pour Partitioning Type (Type de partitionnement), cliquez sur None (Aucun) et sélectionnez Day (Jour).
  - Pour Partitioning field (Champ de partitionnement) :
  - Pour créer une table partitionnée, choisissez une colonne DATE ou TIMESTAMP. Cette option n'est pas disponible si votre schéma n'inclut pas de colonne DATE ni TIMESTAMP.
  - Pour créer une table partitionnée par date d'ingestion, conservez la valeur par défaut : _PARTITIONTIME.
  - Cliquez sur la case Require partition filter (Demander un filtre de partitionnement) pour obliger les utilisateurs à inclure une clause WHERE spécifiant les partitions à interroger. Ce type de filtre peut contribuer à réduire les coûts et à améliorer les performances. Pour en savoir plus, consultez la page Interroger des tables partitionnées. Cette option n'est pas disponible si Partitioning type (Type de partitionnement) est défini sur None (Aucun).
- Pour mettre la table en cluster, saisissez entre un et quatre noms de champ dans la case Clustering fields (Champs de clustering).
- Pour le champ Destination encryption (Chiffrement de la destination), sélectionnez Customer-managed encryption (Chiffrement géré par le client) pour utiliser une clé de service Cloud Key Management afin de chiffrer la table. Si vous conservez l'option Default, BigQuery chiffre les données au repos à l'aide d'une clé gérée par Google.
Cliquez sur Create Table (Créer une table).

CLI

Exécutez la commande bq load, indiquez AVRO à l'aide de l'indicateur --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.

(Facultatif) Spécifiez l'indicateur --location et définissez la valeur correspondant à votre emplacement.

Les autres indicateurs facultatifs sont les suivants :

--max_bad_records : nombre entier spécifiant le nombre maximal d'enregistrements incorrects autorisés avant l'échec de la tâche. La valeur par défaut est 0. Cinq erreurs, au plus, de n'importe quel type sont renvoyées, quelle que soit la valeur --max_bad_records.
--time_partitioning_type : active le partitionnement par date d'une table et définit le type de partition. Actuellement, la seule valeur possible est DAY qui génère une partition par jour. Cet indicateur est facultatif lorsque vous créez une table partitionnée sur une colonne DATE ou TIMESTAMP.
--time_partitioning_expiration : entier qui spécifie (en secondes) le moment où une partition par date doit être supprimée. Le délai d'expiration correspond à la date UTC de la partition plus la valeur entière.
--time_partitioning_field : colonne DATE ou TIMESTAMP utilisée pour créer une table partitionnée. Si le partitionnement par date est activé sans cette valeur, une table partitionnée par date d'ingestion est créée.
--require_partition_filter : Lorsque cette option est activée, les utilisateurs doivent inclure une clause WHERE spécifiant les partitions à interroger. Ce type de filtre peut contribuer à réduire les coûts et à améliorer les performances. Pour en savoir plus, consultez la page Interroger des tables partitionnées.
--clustering_fields : liste de quatre noms de colonne séparés par des virgules, utilisée pour créer une table en cluster. Cet indicateur ne peut être utilisé qu'avec des tables partitionnées.
--destination_kms_key : clé du service de gestion des clés Cloud pour le chiffrement des données de la table.

Pour en savoir plus sur les tables partitionnées, consultez :
- Créer et utiliser des tables partitionnées
- Créer et utiliser des tables partitionnées par date d'ingestion
Pour en savoir plus sur les tables en cluster, consultez :
- Créer et utiliser des tables en cluster
Pour en savoir plus sur le chiffrement d'une table, consultez :
- Protéger des données avec des clés Cloud KMS

Pour charger des données Avro dans BigQuery, saisissez la commande suivante :

bq --location=location load \
--source_format=format \
dataset.table \
path_to_source

Où :

location est votre emplacement. Le paramètre --location est facultatif. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, définissez la valeur de l'indicateur sur asia-northeast1. Vous pouvez définir une valeur par défaut correspondant à l'emplacement à l'aide du fichier bigqueryrc.
format est 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 suivante permet de charger les données de gs://mybucket/mydata.avro dans une table nommée mytable dans mydataset.

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

La commande suivante charge les données de gs://mybucket/mydata.avro dans une table partitionnée par date d'ingestion, nommée mytable dans mydataset.

    bq load \
    --source_format=AVRO \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.avro

La commande suivante charge les données de gs://mybucket/mydata.avro dans une table partitionnée nommée mytable dans mydataset. La table est partitionnée en fonction de la colonne mytimestamp.

    bq load \
    --source_format=AVRO \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.avro

La commande ci-dessous permet de charger les données de plusieurs fichiers de gs://mybucket/ dans une table nommée mytable dans mydataset. L'URI Cloud Storage utilise un caractère générique.

    bq 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 une table nommée mytable dans mydataset. La commande inclut une liste d'URI Cloud Storage séparés par une virgule.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

API

Créez une tâche load qui pointe vers les données sources dans Cloud Storage.
(Facultatif) Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource de tâche.
La propriété source URIs doit être complète et respecter le format gs://bucket/object. Chaque URI peut contenir un caractère générique (*).
Spécifiez le format des données Avro en définissant la propriété sourceFormat sur AVRO.
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é par la requête initiale.
- Si la propriété status.state = DONE s'affiche, 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. Ces erreurs 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 ID 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 sur 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. L'une de ces opérations tout au plus aboutira.

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

Afficher sur GitHub Commentaires

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.source_format = bigquery.SourceFormat.AVRO
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"

load_job = client.load_table_from_uri(
    uri, dataset_ref.table("us_states"), job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(dataset_ref.table("us_states"))
print("Loaded {} rows.".format(destination_table.num_rows))

Ajouter ou écraser 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 la console ou l'UI Web classique 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.

Vous disposez des options suivantes lorsque vous chargez des données supplémentaires dans une table :

Option de la console	Option de l'interface Web classique	Indicateur de la CLI	Propriété de l'API BigQuery	Description
Écrire si la table est vide	Écrire si la table est vide	Aucun	`WRITE_EMPTY`	N'écrit les données que si la table est vide.
Ajouter à la table	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	É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.

Si vous chargez des données dans une table existante, la tâche de chargement peut les ajouter ou écraser la table.

Vous pouvez ajouter des données ou écraser une table de plusieurs façons :

En utilisant la console GCP ou l'interface utilisateur Web classique de BigQuery
En exécutant la commande bq load de la CLI
En appelant la méthode API jobs.insert et en configurant une tâche load
En utilisant les bibliothèques clientes

Pour ajouter ou écraser des données Avro dans une table, procédez comme suit :

Console

Ouvrez l'UI Web de BigQuery dans la console GCP.
Accéder à la console GCP
Dans la section Resources (Ressources) du panneau de navigation, développez votre projet et sélectionnez un ensemble de données.
À droite de la fenêtre, dans le panneau de détails, cliquez sur Create table (Créer une table). La procédure d'ajout et d'écrasement de données lors d'une tâche de chargement est identique à la procédure de création d'une table lors d'une tâche de chargement.
Dans la section Source de la page Create table (Créer une table) :
- Pour le champ Create table from (Créer une table à partir de), sélectionnez Cloud Storage.
- Dans le champ source, recherchez ou saisissez l'URI Cloud Storage. Sachez que vous ne pouvez pas inclure plusieurs URI dans l'interface utilisateur Web BigQuery. En revanche, les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver dans le 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 File format (Format de fichier), sélectionnez Avro.
Dans la section Destination de la page Create Table (Créer une table) :
- Sous Dataset name (Nom de l'ensemble de données), sélectionnez l'ensemble de données approprié.
- Dans le champ Table name (Nom de la table), entrez le nom de la table dans BigQuery à laquelle vous ajoutez des données ou que vous écraser.
- Vérifiez que Table type (Type de table) est défini sur Native table (Table native).
Aucune action n'est nécessaire dans la section Schema (Schéma). Le schéma est auto-décrit dans les fichiers Avro.

Remarque : Il est possible de modifier le schéma de la table lorsque vous y ajoutez ou écrasez des données. Pour en savoir plus sur les modifications de schéma acceptées lors d'un chargement, consultez la page Modifier des schémas de table.
Dans Partition and cluster settings (Paramètres de partitionnement et de clustering), conservez les valeurs par défaut. Vous ne pouvez pas convertir une table en table partitionnée ou en cluster, en y ajoutant ou en y écrasant des données. Par ailleurs, la console GCP n'accepte ni l'ajout, ni l'écrasement de données dans une table partitionnée ou en cluster lors d'une tâche de chargement.
Cliquez sur Advanced options (Options avancées).
- Pour le champ Write preference (Préférence d'écriture), choisissez Append to table (Ajouter à la table) ou Overwrite table (Écraser la table).
- Pour le champ Number of errors allowed (Nombre d'erreurs autorisées), acceptez la valeur par défaut 0 ou saisissez le nombre maximal de lignes contenant des erreurs pouvant être ignorées. Si le nombre de lignes contenant des erreurs dépasse cette valeur, la tâche renverra un message invalid et échouera.
- Pour le champ Unknown values (Valeurs inconnues), conservez l'option Ignore unknown values (Ignorer les valeurs inconnues) désactivée. Cette option ne s'applique qu'aux fichiers CSV et JSON.
- Pour le champ Encryption (Chiffrement), cliquez sur Customer-managed key (Clé gérée par le client) pour utiliser une clé de service Cloud Key Management. Si vous conservez l'option Google-managed key (Clé gérée par Google), BigQuery chiffre les données au repos.
Cliquez sur Create table (Créer une table).

UI classique

Accédez à l'interface utilisateur Web de BigQuery.
Accéder à l'UI Web de BigQuery
Dans le panneau de navigation, passez la souris sur un ensemble de données, cliquez sur l'icône de flèche vers le bas , puis cliquez sur Create new table (Créer une table). La procédure d'ajout et d'écrasement de données lors d'une tâche de chargement est identique à la procédure de création d'une table lors d'une tâche de chargement.
Dans la section Source Date (Données source) de la page Create Table (Créer une table) :
- Pour le champ Location (Emplacement), sélectionnez Cloud Storage. Dans le champ relatif à la source, saisissez l'URI Cloud Storage. Sachez 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 dans le 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 File format (Format de fichier), sélectionnez Avro.
Dans la section Destination table (Table de destination) de la page Create Table (Créer une table) :
- Pour le champ Table name (Nom de la table), sélectionnez l'ensemble de données approprié, puis saisissez le nom de la table que vous créez dans BigQuery dans le champ correspondant.
- Vérifiez que Table type (Type de table) est défini sur Native table (Table native).
Aucune action n'est nécessaire dans la section Schema (Schéma). Les informations sur le schéma sont auto-décrites dans les fichiers Avro.

Remarque : Il est possible de modifier le schéma de la table lorsque vous y ajoutez ou écrasez des données. Pour en savoir plus sur les modifications de schéma acceptées lors d'un chargement, consultez la page Modifier des schémas de table.
Dans la section Options :
- Pour le champ Number of errors allowed (Nombre d'erreurs autorisées), acceptez la valeur par défaut 0 ou saisissez le nombre maximal de lignes contenant des erreurs pouvant être ignorées. Si le nombre de lignes contenant des erreurs dépasse cette valeur, la tâche renverra un message invalid et échouera.
- Pour le champ Write preference (Préférence d'écriture), choisissez Append to table (Ajouter à la table) ou Overwrite table (Écraser la table).
- Conservez les valeurs par défaut pour Partitioning Type (Type de partitionnement), Partitioning Field (Champ de partitionnement), Require partition filter (Demander un filtre de partitionnement) et Clustering Fields (Champs de clustering). Vous ne pouvez pas convertir une table en table partitionnée ou en cluster, en y ajoutant des données ou en l'écrasant. Par ailleurs, l'interface utilisateur Web n'accepte ni l'ajout, ni l'écrasement de données dans une table partitionnée ou en cluster lors d'une tâche de chargement.
- Pour le champ Destination encryption (Chiffrement de la destination), sélectionnez Customer-managed encryption (Chiffrement géré par le client) pour utiliser une clé de service Cloud Key Management afin de chiffrer la table. Si vous conservez l'option Default, BigQuery chiffre les données au repos à l'aide d'une clé gérée par Google.
Cliquez sur Create Table (Créer une table).

CLI

Saisissez la commande bq load avec l'indicateur --replace pour écraser la table. Incluez le paramètre --noreplace pour ajouter des données à la table. Si aucun paramètre n'est spécifié, les données sont ajoutées par défaut. Fournissez l'indicateur --source_format et définissez-le sur AVRO. Étant donné que les schémas Avro sont automatiquement récupérés à partir des données sources auto-descriptives, il n'est pas nécessaire de fournir une définition de schéma.

(Facultatif) Spécifiez l'indicateur --location et définissez la valeur correspondant à votre emplacement.

Les autres indicateurs facultatifs sont les suivants :

--max_bad_records : nombre entier spécifiant le nombre maximal d'enregistrements incorrects autorisés avant l'échec de la tâche. La valeur par défaut est 0. Cinq erreurs, au plus, de n'importe quel type sont renvoyées, quelle que soit la valeur --max_bad_records.
--destination_kms_key : clé du service de gestion des clés Cloud pour le chiffrement des données de la table.

bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source

Où :

location est votre emplacement. Le paramètre --location est facultatif. Vous pouvez spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
format est 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 suivante charge les données de gs://mybucket/mydata.avro et écrase une table nommée mytable dans mydataset.

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

La commande suivante permet de charger les données de gs://mybucket/mydata.avro en ajoutant des données à une table nommée mytable dans mydataset.

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

Pour en savoir plus sur l'ajout et l'écrasement de données dans une table partitionnée à l'aide de la CLI, consultez la page Gérer les données de tables partitionnées.

API

Créez une tâche load qui pointe vers les données sources dans Cloud Storage.
(Facultatif) Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource de tâche.
La propriété source URIs doit être complète et respecter le format gs://bucket/object. Vous pouvez inclure plusieurs URI sous la forme d'une liste d'éléments séparés par une virgule. Sachez que les caractères génériques sont également acceptés.
Spécifiez le format de données en définissant la propriété configuration.load.sourceFormat sur AVRO.
Spécifiez la préférence d'écriture en définissant la propriété configuration.load.writeDisposition sur WRITE_TRUNCATE ou WRITE_APPEND.

Python

Afficher sur GitHub Commentaires

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
job_config.source_format = bigquery.SourceFormat.AVRO
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"
load_job = client.load_table_from_uri(
    uri, table_ref, job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(table_ref)
print("Loaded {} rows.".format(destination_table.num_rows))

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

Par défaut, BigQuery ignore l'attribut logicalType et utilise à la place le type Avro sous-jacent.

Type logique Avro	Type de données BigQuery
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 activer la conversion des types logiques Avro en types de données correspondants dans BigQuery, définissez l'indicateur --use_avro_logical_types sur True à l'aide de l'outil de ligne de commande. Vous pouvez également définir la propriété useAvroLogicalTypes dans la ressource de tâche lorsque vous appelez la méthode jobs.insert pour créer une tâche de chargement.

Le tableau ci-dessous indique la conversion des types logiques Avro en types de données BigQuery.

Type logique Avro	Type de données BigQuery converti
date	DATE
time-millis	TIME
time-micros	TIME
timestamp-millis	TIMESTAMP
timestamp-micros	TIMESTAMP
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.

Charger des fichiers Avro depuis Cloud Storage

Avantages d'Avro

Schémas Avro

Compression de fichiers Avro

Autorisations requises

Autorisations BigQuery

Autorisations Cloud Storage

Charger des données Avro dans une nouvelle table

Console

UI classique

CLI

API

Python

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

Console

UI classique

CLI

API

Python

Conversions Avro

Types primitifs

Types complexes

Types logiques

Type logique décimal

Envoyer des commentaires concernant…