Charger des données 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.

Remarque : BigQuery n'est pas compatible avec le chargement des fichiers de schéma Avro autonomes (.avsc). Pour importer un schéma dans BigQuery, spécifiez un fichier de schéma JSON.

Limites

Vous êtes soumis aux limitations suivantes lorsque vous chargez des données dans BigQuery à partir d'un bucket Cloud Storage :

• Si l'emplacement de votre ensemble de données est défini sur une valeur autre que l'emplacement multirégional US, le bucket Cloud Storage doit se trouver dans la même région que l'ensemble de données, ou figurer dans le même emplacement multirégional que celui-ci.
• BigQuery ne garantit pas la cohérence des données pour les sources de données externes. Les modifications apportées aux données sous-jacentes lors de l'exécution d'une requête peuvent entraîner un comportement inattendu.
• BigQuery n'est pas compatible avec la gestion des versions d'objets Cloud Storage. Si vous incluez un numéro de génération dans l'URI Cloud Storage, la tâche de chargement échoue.

Exigences relatives aux fichiers d'entrée

Pour éviter les erreurs resourcesExceeded lors du chargement de fichiers Avro dans BigQuery, suivez ces instructions :

• La taille des lignes ne doit pas dépasser 50 Mo.
• Si la ligne contient de nombreux champs de tableau ou des champs de tableau très longs, divisez les valeurs du tableau en champs distincts.

Avant de commencer

Attribuez aux utilisateurs des rôles IAM (Identity and Access Management) incluant les autorisations nécessaires pour effectuer l'ensemble des tâches de ce document et créer un ensemble de données et une table pour stocker les données.

Autorisations requises

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

Autorisations pour charger des données dans BigQuery

Pour charger des données dans une nouvelle table ou partition BigQuery, ou pour ajouter ou écraser une table ou une partition existante, vous avez besoin des autorisations IAM suivantes :

• bigquery.tables.create
• bigquery.tables.updateData
• bigquery.tables.update
• bigquery.jobs.create

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour charger des données dans une table ou une partition BigQuery :

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin (inclut l'autorisation bigquery.jobs.create)
• bigquery.user (inclut l'autorisation bigquery.jobs.create)
• bigquery.jobUser (inclut l'autorisation bigquery.jobs.create)

En outre, si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez créer et mettre à jour des tables à l'aide d'une tâche de chargement dans les ensembles de données que vous créez.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Autorisations pour charger des données à partir de Cloud Storage

Pour obtenir les autorisations nécessaires pour charger des données à partir d'un bucket Cloud Storage, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Storage (roles/storage.admin) sur le bucket. Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Ce rôle prédéfini contient les autorisations requises pour charger des données à partir d'un bucket Cloud Storage. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour charger des données à partir d'un bucket Cloud Storage :

• storage.buckets.get
• storage.objects.get
• storage.objects.list (required if you are using a URI wildcard)

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Créer un ensemble de données et une table

Pour stocker vos données, vous devez créer un ensemble de données BigQuery, puis une table BigQuery au sein de cet ensemble de données.

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

Lorsque vous chargez des fichiers Avro dans une nouvelle table 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

L'exécution de cette commande dans l'outil de ligne de commande bq charge 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 GoogleSQL. Pour en savoir plus, consultez la section Conversions Avro.

Pour fournir un schéma de table permettant de créer des tables externes, définissez la propriété referenceFileSchemaUri dans l'API BigQuery, ou
le paramètre --reference_file_schema_uri dans l'outil de ligne de commande bq sur l'URL du fichier de référence.

Par exemple, --reference_file_schema_uri="gs://mybucket/schema.avro".

Compression de fichiers Avro

BigQuery accepte les codecs de compression suivants pour le contenu des fichiers Avro :

• Snappy
• DEFLATE

Charger des données Avro dans une nouvelle table

Pour charger des données Avro à partir de Cloud Storage dans une nouvelle table BigQuery, sélectionnez l'une des options suivantes :

Console

1. Dans la console Google Cloud, ouvrez la page "BigQuery".

   Accéder à BigQuery

2. Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.

3. Développez l'option Actions puis cliquez sur Ouvrir.

4. Dans le panneau de détails, cliquez sur Créer une table.

5. Dans la section Source de la page Créer une table :

   • Pour le champ Créer une table à partir de, sélectionnez Google Cloud Storage.

   • Dans le champ de la source, recherchez ou saisissez l'URI Cloud Storage. Sachez que vous ne pouvez pas inclure plusieurs URI dans la console Google Cloud. 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.

6. 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 Nom de la table, saisissez le nom de la table que vous créez dans BigQuery.

7. Aucune action n'est nécessaire dans la section Schema (Schéma). Le schéma est auto-décrit dans les fichiers Avro.

8. (Facultatif) Pour partitionner la table, choisissez vos options dans le champ Paramètres de partitionnement et de clustering. Pour en savoir plus, consultez la page Créer des tables partitionnées.

9. (Facultatif) Pour le champ Filtre de partitionnement, cochez la case 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 section Interroger des tables partitionnées. Cette option n'est pas disponible si Aucun partitionnement est sélectionné.

10. (Facultatif) Pour mettre une table en cluster, saisissez entre un et quatre noms de champs dans la zone Ordre de clustering.

11. (Facultatif) Cliquez sur Options avancées.

    • Pour le champ Préférence d'écriture, laissez l'option Écrire si la table est vide sélectionnée. Cette option crée une table et y charge vos données.
    • Pour le champ Valeurs inconnues, conservez l'option Ignorer les valeurs inconnues non cochée. Cette option ne s'applique qu'aux fichiers CSV et JSON.
    • Pour le champ Chiffrement, cliquez sur Clé gérée par le client afin d'utiliser une clé Cloud Key Management Service. Si vous conservez le paramètre Clé gérée par Google, BigQuery chiffre les données au repos.

12. Cliquez sur Créer une table.

Remarque : Lorsque vous chargez des données dans une table vide à l'aide de la console Google Cloud, vous ne pouvez pas ajouter de libellé, de description, de délai d'expiration de la table ni de délai d'expiration de la partition.

Une fois la table créée, vous pouvez mettre à jour son délai d'expiration, sa description et ses libellés, mais vous ne pouvez pas ajouter de délai d'expiration de partition après la création d'une table à l'aide de la console Google Cloud. Pour en savoir plus, consultez la page Gérer des tables.

SQL

Utilisez l'instruction LDD LOAD DATA : L'exemple suivant charge un fichier Avro dans une nouvelle table mytable :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans l'éditeur de requête, saisissez l'instruction suivante :

   LOAD DATA OVERWRITE mydataset.mytable
   FROM FILES (
     format = 'avro',
     uris = ['gs://bucket/path/file.avro']);
   

3. Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Exécutez la commande bq load, définissez AVRO à l'aide de l'option --source_format et spécifiez un URI Cloud Storage. Vous pouvez inclure un seul URI, une liste d'URI séparés par des virgules ou un URI contenant un caractère générique.

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

Les autres indicateurs facultatifs sont les suivants :

• --time_partitioning_type : active le partitionnement temporel sur une table et définit le type de partition. Les valeurs possibles sont HOUR, DAY, MONTH et YEAR. Cette option est facultative lorsque vous créez une table partitionnée sur une colonne DATE, DATETIME ou TIMESTAMP. Le type de partition par défaut pour le partitionnement temporel est DAY. Vous ne pouvez pas modifier la spécification de partitionnement sur une table existante.
• --time_partitioning_expiration : entier qui spécifie (en secondes) le délai au terme duquel une partition temporelle 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 : si cette option est activée, elle oblige 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 section Interroger des tables partitionnées.
• --clustering_fields : liste pouvant contenir jusqu'à quatre noms de colonne séparés par une virgule, et utilisée pour créer une table en cluster.

• --destination_kms_key : clé Cloud KMS pour le chiffrement des données de la table.

  Pour en savoir plus sur les tables partitionnées, consultez :

  • Créer des tables partitionnées

  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

Remplacez l'élément suivant :

• location correspond à votre emplacement. L'option --location est facultative. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, vous pouvez définir la valeur de l'option 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 la table mytable de mydataset.

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

La commande suivante permet de charger les données de gs://mybucket/mydata.avro dans la table partitionnée par date d'ingestion mytable de mydataset.

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

La commande suivante permet de charger les données de gs://mybucket/mydata.avro dans une nouvelle table partitionnée de mydataset nommée mytable. 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 l'ensemble de données 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 l'ensemble de données 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

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

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

3. 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 (*).

4. Spécifiez le format des données Avro en définissant la propriété 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 tâche renvoyé par la requête initiale.

   • Si la réponse est 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. 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.

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importAvro demonstrates loading Apache Avro data from Cloud Storage into a table.
func importAvro(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.avro")
	gcsRef.SourceFormat = bigquery.Avro
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to load Avro data from Cloud Storage into a new BigQuery table
public class LoadAvroFromGCS {

  public static void runLoadAvroFromGCS() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro";
    loadAvroFromGCS(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCS(String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.of(tableId, sourceUri, FormatOptions.avro());

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Avro from GCS successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Node.js.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

async function loadTableGCSAvro() {
  // Imports a GCS file into a table with Avro source format.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'us_states';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const jobConfigurationLoad = {
    load: {sourceFormat: 'AVRO'},
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), jobConfigurationLoad);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Python.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(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_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

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

Extraire les données JSON des données Avro

Il existe deux façons de vous assurer que les données Avro sont chargées dans BigQuery en tant que données JSON :

1. Annotez votre schéma Avro avec sqlType défini sur JSON. Par exemple, si vous chargez des données avec le schéma Avro suivant, la colonne json_field est lue en tant que type JSON :

   {
       "type": {"type": "string", "sqlType": "JSON"},
       "name": "json_field"
   }
   

2. Spécifiez explicitement le schéma de la table de destination BigQuery et définissez le type de colonne sur JSON. Pour en savoir plus, consultez la section Spécifier un schéma.

Si vous ne spécifiez pas JSON comme type dans le schéma Avro ou le schéma de la table BigQuery, les données seront lues sous forme de STRING.

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 Google Cloud, 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'outil bq	Propriété de l'API BigQuery	Description
Écrire si la table est vide	Incompatible	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. Cette action supprime également le schéma de la table, la sécurité au niveau des lignes et la clé Cloud KMS.

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

Remarque : Cette page ne couvre ni l'ajout, ni l'écrasement de données dans une table partitionnée. Pour en savoir plus sur l'ajout et l'écrasement de données dans une table partitionnée, consultez la section Ajouter ou écraser des données dans une table partitionnée.

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

Console

1. Dans la console Google Cloud, ouvrez la page "BigQuery".

   Accéder à BigQuery

2. Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.

3. Développez l'option Actions puis cliquez sur Ouvrir.

4. Dans le panneau de détails, cliquez sur Créer une table.

5. Dans la section Source de la page Créer une table :

   • Pour le champ Create table from (Créer une table à partir de), sélectionnez Cloud Storage.

   • Dans le champ de la source, recherchez ou saisissez l'URI Cloud Storage. Sachez que vous ne pouvez pas inclure plusieurs URI dans la console Google Cloud. 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.

6. 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 Nom de la table, saisissez le nom de la table à laquelle vous ajoutez des données ou que vous écrasez dans BigQuery.

   • Vérifiez que Type de table est défini sur Table native.

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

8. Sous 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 Google Cloud 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.

9. Cliquez sur Options avancées.

   • Sous Préférences d'écriture, choisissez Ajouter à la table ou Écraser la table.
   • Pour le champ Valeurs inconnues, conservez l'option Ignorer les valeurs inconnues non cochée. Cette option ne s'applique qu'aux fichiers CSV et JSON.
   • Pour le champ Chiffrement, cliquez sur Clé gérée par le client afin d'utiliser une clé Cloud Key Management Service. Si vous conservez le paramètre Clé gérée par Google, BigQuery chiffre les données au repos.

10. Cliquez sur Créer une table.

SQL

Utilisez l'instruction LDD LOAD DATA : L'exemple suivant ajoute un fichier Avro à la table mytable :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans l'éditeur de requête, saisissez l'instruction suivante :

   LOAD DATA INTO mydataset.mytable
   FROM FILES (
     format = 'avro',
     uris = ['gs://bucket/path/file.avro']);
   

3. Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Saisissez la commande bq load avec l'option --replace pour écraser la table. Utilisez l'option --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'option --source_format et définissez-la 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.

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.

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

Les autres indicateurs facultatifs sont les suivants :

• --destination_kms_key : clé Cloud KMS pour le chiffrement des données de la table.

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

Remplacez l'élément suivant :

• location correspond à votre emplacement. L'option --location est facultative. 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 permet de charger des données depuis gs://mybucket/mydata.avro en écrasant une table nommée mytable dans l'ensemble de données 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 et d'ajouter des données à la table mytable de 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 des tables partitionnées à l'aide de l'outil de ligne de commande bq, consultez la section Ajouter ou écraser des données dans une table partitionnée.

API

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

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

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

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 ou WRITE_APPEND.

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importAvroTruncate demonstrates loading Apache Avro data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importAvroTruncate(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.avro")
	gcsRef.SourceFormat = bigquery.Avro
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	// Default for import jobs is to append data to a table.  WriteTruncate
	// specifies that existing data should instead be replaced/overwritten.
	loader.WriteDisposition = bigquery.WriteTruncate

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to overwrite the BigQuery table data by loading a AVRO file from GCS
public class LoadAvroFromGCSTruncate {

  public static void runLoadAvroFromGCSTruncate() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro";
    loadAvroFromGCSTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCSTruncate(
      String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.avro())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .build();

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Table is successfully overwritten by AVRO file loaded from GCS");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Node.js.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

async function loadTableGCSAvroTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'us_states';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const jobConfigurationLoad = {
    load: {
      sourceFormat: 'AVRO',
      writeDisposition: 'WRITE_TRUNCATE',
    },
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), jobConfigurationLoad);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Python.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

import io

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = io.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    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_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

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

Charger des données Avro partitionnées avec Hive

BigQuery accepte le chargement de données Avro partitionnées avec Hive et stockées dans Cloud Storage. Il insère alors les colonnes de partitionnement Hive en tant que colonnes dans la table de destination gérée par BigQuery. Pour en savoir plus, consultez la page Charger des données partitionnées externes.

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 sans attribut logicalType	Type de données BigQuery	Notes
null	BigQuery ignore ces valeurs.
boolean	BOOLEAN
int	INTEGER
long	INTEGER
float	FLOAT
double	FLOAT
bytes	BYTES
string	STRING	UTF-8 uniquement

Types logiques

Par défaut, BigQuery ignore l'attribut logicalType pour la plupart des types et utilise à la place le type Avro sous-jacent. Pour convertir des types logiques Avro en types de données correspondants dans BigQuery, définissez l'option --use_avro_logical_types sur true à l'aide de l'outil de ligne de commande bq, ou définissez la propriété useAvroLogicalTypes dans la ressource de job lorsque vous appelez la méthode jobs.insert pour créer un job 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 : type logique désactivé	Type de données BigQuery : type logique activé
date	INTEGER	DATE
time-millis	INTEGER	TIME
time-micros	INTEGER (converti à partir du type LONG)	TIME
timestamp-millis	INTEGER (converti à partir du type LONG)	TIMESTAMP
timestamp-micros	INTEGER (converti à partir du type LONG)	TIMESTAMP
local-timestamp-millis	INTEGER (converti à partir du type LONG)	DATETIME
local-timestamp-micros	INTEGER (converti à partir du type LONG)	DATETIME
duration	BYTES (converti à partir du type fixed de taille 12)	BYTES (converti à partir du type fixed de taille 12)
decimal	NUMERIC, BIGNUMERIC ou STRING (voir Type logique décimal)	NUMERIC, BIGNUMERIC ou STRING (voir Type logique décimal)

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

Remarque : Lors de l'exportation vers Avro depuis BigQuery, DATETIME est exporté en tant que STRING avec une heure logique personnalisée non reconnue en tant que DATETIME lors de l'importation dans BigQuery.

Type logique de date

Dans tous les fichiers Avro que vous souhaitez charger, vous devez spécifier des types logiques de date au format suivant :

{
       "type": {"logicalType": "date", "type": "int"},
       "name": "date_field"
}

Type logique décimal

Les types logiques Decimal peuvent être convertis en types NUMERIC, BIGNUMERIC ou STRING. Le type converti dépend des paramètres de précision et d'évolutivité du type logique decimal et des types cibles décimaux spécifiés. Spécifiez le type de cible décimal comme suit :

• Pour une tâche de chargement à l'aide de l'API jobs.insert, utilisez le champ JobConfigurationLoad.decimalTargetTypes.
• Pour un job de chargement effectué à l'aide de la commande bq load dans l'outil de ligne de commande bq, utilisez l'option --decimal_target_types.
• Pour une requête sur une table avec des sources externes, utilisez le champ ExternalDataConfiguration.decimalTargetTypes.
• Pour une table externe persistante créée avec le LDD, utilisez l'option decimal_target_types.

Pour assurer la rétrocompatibilité, si les types cibles décimaux ne sont pas spécifiés, vous pouvez charger un fichier Avro contenant une colonne bytes avec le type logique decimal dans une colonne BYTES d'une table existante. Dans ce cas, le type logique decimal de la colonne du fichier Avro est ignoré. Ce mode de conversion est obsolète et pourrait être supprimé prochainement.

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

Type logique d'heure

Dans tous les fichiers Avro que vous souhaitez charger, vous devez spécifier des types logiques d'heure dans l'un des formats suivants.

Pour la précision à la milliseconde :

{
       "type": {"logicalType": "time-millis", "type": "int"},
       "name": "time_millis_field"
}

Pour la précision à la microseconde :

{
       "type": {"logicalType": "time-micros", "type": "int"},
       "name": "time_micros_field"
}

Type logique d'horodatage

Dans tous les fichiers Avro que vous souhaitez charger, vous devez spécifier des types logiques d'horodatage dans l'un des formats suivants.

Pour la précision à la milliseconde :

{
       "type": {"logicalType": "timestamp-millis", "type": "long"},
       "name": "timestamp_millis_field"
}

Pour la précision à la microseconde :

{
       "type": {"logicalType": "timestamp-micros", "type": "long"},
       "name": "timestamp_micros_field"
}

Type logique d'horodatage local

Dans tous les fichiers Avro que vous souhaitez charger, vous devez spécifier un type logique d'horodatage local dans l'un des formats suivants.

Pour la précision à la milliseconde :

{
       "type": {"logicalType": "local-timestamp-millis", "type": "long"},
       "name": "local_timestamp_millis_field"
}

Pour la précision à la microseconde :

{
       "type": {"logicalType": "local-timestamp-micros", "type": "long"},
       "name": "local_timestamp_micros_field"
}

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.

Limites

• La mise en forme d'un tableau imbriqué n'est pas acceptée dans BigQuery. Les fichiers Avro utilisant ce format doivent être convertis avant l'importation.
• Dans un fichier Avro, les noms et espaces de noms d'un nom complet ne peuvent contenir que des caractères alphanumériques et le trait de soulignement _. L'expression régulière suivante indique les caractères autorisés : [A-Za-z_][A-Za-z0-9_]*

Pour en savoir plus, consultez la page Limites des tâches de chargement BigQuery.