Charger des données Parquet depuis Cloud Storage

Cette page vous offre un aperçu du chargement de données Parquet depuis Cloud Storage dans BigQuery.

Parquet est un format de données Open Source orienté colonnes dont l'utilisation est très répandue dans l'écosystème Apache Hadoop.

Lorsque vous chargez des données Parquet 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 au même emplacement régional ou multirégional que le bucket Cloud Storage.

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

Schémas Parquet

Lorsque vous chargez des fichiers Parquet dans BigQuery, le schéma de la table est automatiquement extrait des données sources auto-descriptives. 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 disposez des fichiers Parquet suivants dans Cloud Storage :

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

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

bq load \
--source_format=PARQUET \
dataset.table \
"gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"

Lorsque vous chargez plusieurs fichiers Parquet ayant des schémas différents, les colonnes identiques spécifiées dans plusieurs schémas doivent posséder le même mode dans chaque définition de schéma.

Lorsque BigQuery détecte le schéma, certains types de données Parquet sont convertis en types de données BigQuery pour devenir compatibles avec la syntaxe SQL de BigQuery. Pour en savoir plus, consultez la section Conversions Parquet.

Compression de fichiers Parquet

BigQuery accepte les codecs de compression suivants pour les blocs de données dans les fichiers Parquet :

  • Snappy
  • GZip
  • LZO_1C and LZO_1X

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 IAM prédéfinis suivants incluent les autorisations bigquery.tables.create et bigquery.tables.updateData :

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Les rôles IAM prédéfinis suivants incluent les autorisations bigquery.jobs.create :

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

En outre, si un utilisateur possède les autorisations bigquery.datasets.create, il obtient également un accès bigquery.dataOwner à l'ensemble de données qu'il crée. L'accès correspondant au rôle bigquery.dataOwner permet à l'utilisateur de créer et de mettre à jour des tables dans l'ensemble de données à l'aide d'une tâche de chargement.

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

Autorisations Cloud Storage

Pour 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 IAM prédéfini storage.objectViewer peut être autorisé à octroyer les autorisations storage.objects.get et storage.objects.list.

Charger des données Parquet dans une nouvelle table

Vous pouvez charger des données Parquet dans une nouvelle table à l'aide de l'une des méthodes suivantes :

  • Cloud Console ou UI Web classique
  • Commande bq load de l'outil de ligne de commande bq
  • Méthode API jobs.insert et configuration d'une tâche load
  • Bibliothèques clientes

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

Console

  1. Ouvrez la page BigQuery dans Cloud Console.

    Accéder à BigQuery

  2. Dans la section Ressources du panneau de navigation, développez votre projet Google Cloud et sélectionnez un ensemble de données.

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

    Créer une table

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

    • Pour le champ 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 Cloud Console. 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.

      Sélectionnez le fichier.

    • Pour Format de fichier, sélectionnez Parquet.

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

      Affichez l'ensemble de données.

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

    • Dans le champ Nom de la table, saisissez le nom de la table que vous créez dans BigQuery.

  6. Aucune action n'est nécessaire dans la section Schéma. Le schéma est auto-décrit dans les fichiers Parquet.

  7. (Facultatif) Pour partitionner la table, choisissez vos options dans le champ Paramètres de partitionnement et de clustering :

    • Pour créer une table partitionnée, cliquez sur Aucun partitionnement, sélectionnez 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 ou TIMESTAMP.
    • Pour créer une table partitionnée par date d'ingestion, cliquez sur Aucun partitionnement, puis sélectionnez Partitionner par date d'ingestion.
  8. (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 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é.

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

  10. (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 Nombre d'erreurs autorisées, acceptez la valeur par défaut 0 ou saisissez le nombre maximal de lignes contenant des erreurs qui peuvent ê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 Valeurs inconnues, conservez l'option Ignorer les valeurs inconnues désactivé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.
  11. Cliquez sur Créer une table.

UI classique

  1. Accédez à l'UI 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, cliquez sur la flèche vers le bas 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 source de la page Créer une table :

    • Cliquez sur Créer à partir de la source.
    • Dans le champ Emplacement, sélectionnez Cloud Storage. Dans le champ de la source, saisissez l'URI Cloud Storage. Sachez que vous ne pouvez pas inclure plusieurs URI dans l'UI 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 Format de fichier, sélectionnez Parquet.
  4. Dans la section Table de destination :

    • Pour le champ 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 Type de table est défini sur Table native.
  5. Dans la section Schéma, aucune action n'est nécessaire. Le schéma est auto-décrit dans les fichiers Parquet.

  6. (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 qui peuvent être ignorées. Si le nombre de lignes contenant des erreurs dépasse cette valeur, la tâche renverra un message invalid et échouera.
    • Sous 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 partitionner la table :
      • Sous Type de partitionnement, cliquez sur Aucun et sélectionnez Jour.
      • Sous 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 ou TIMESTAMP.
      • Pour créer une table partitionnée par date d'ingestion, conservez la valeur par défaut : _PARTITIONTIME.
      • 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 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 champs dans la case Champs de clustering.
    • Sous Destination encryption (Chiffrement de la destination), sélectionnez Customer-managed encryption (Chiffrement géré par le client) pour utiliser une clé Cloud Key Management Service afin de chiffrer la table. Si vous conservez le paramètre Default, BigQuery chiffre les données au repos à l'aide d'une clé gérée par Google.
  7. Cliquez sur Créer une table.

bq

Exécutez la commande bq load, définissez PARQUET à 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 options facultatives sont les suivantes :

  • --max_bad_records : entier spécifiant le nombre maximal d'enregistrements incorrects autorisés avant l'échec total de la tâche. La valeur par défaut est 0. Au plus, cinq erreurs de n'importe quel type sont renvoyées, quelle que soit la valeur --max_bad_records.
  • --time_partitioning_type : active le partitionnement temporel sur une table et définit le type de partition. Actuellement, la seule valeur possible est DAY, qui génère une partition par jour. Cette option est facultative lorsque vous créez une table partitionnée sur une colonne DATE ou TIMESTAMP.
  • --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 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 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 :

    Pour en savoir plus sur les tables en cluster, consultez :

    Pour en savoir plus sur le chiffrement d'une table, consultez :

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

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

Remplacez l'élément suivant :

  • LOCATION : 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 en utilisant le fichier .bigqueryrc.
  • FORMAT : PARQUET.
  • DATASET : ensemble de données existant.
  • TABLE : nom de la table dans laquelle vous chargez des données.
  • PATH_TO_SOURCE : URI Cloud Storage complet ou liste d'URI séparés par des virgules. Les caractères génériques sont également acceptés.

Exemples :

La commande suivante permet de charger les données de gs://mybucket/mydata.parquet dans la table mytable de mydataset.

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

La commande suivante permet de charger les données de gs://mybucket/mydata.parquet dans une table partitionnée par date d'ingestion nommée mytable dans l'ensemble de données mydataset.

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

La commande suivante permet de charger les données de gs://mybucket/mydata.parquet dans une table partitionnée nommée mytable dans l'ensemble de données mydataset. La table est partitionnée en fonction de la colonne mytimestamp.

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

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=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata*.parquet

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=PARQUET \
    mydataset.mytable \
    "gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"

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 de données Parquet en définissant la propriété sourceFormat sur PARQUET.

  5. Pour vérifier l'état de la tâche, appelez jobs.get(JOB_ID*) en remplaçant JOB_ID par 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 inclut 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

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le 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 en langage Go.

import (
	"context"
	"fmt"

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

// importParquet demonstrates loading Apache Parquet data from Cloud Storage into a table.
func importParquet(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.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	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

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java décrite dans le 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 en langage 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;
import java.math.BigInteger;

public class LoadParquet {

  public static void runLoadParquet() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquet(datasetName);
  }

  public static void loadParquet(String datasetName) {
    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();

      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job job = bigquery.create(JobInfo.of(configuration));

      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet loaded successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("GCS Parquet was not loaded. \n" + e.toString());
    }
  }
}

Node.js

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Node.js décrite dans le 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 en langage Node.js.

// 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 Parquet file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.parquet
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

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

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

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

  // 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), metadata);

  // 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;
  }
}

PHP

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour PHP dans le 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 en langage PHP.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET');
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

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 : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

Utilisez la méthode Client.load_table_from_uri () pour démarrer une tâche de chargement à partir de Cloud Storage. Pour utiliser Parquet, définissez la propriété LoadJobConfig.source_format sur la constante SourceFormat PARQUET et transmettez la configuration de la tâche en tant qu'argument job_config à la méthode load_table_from_uri().

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.PARQUET,)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"

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

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

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 Cloud Console Option de l'UI Web classique Option de l'outil de ligne de commande bq Propriété de l'API BigQuery Description
Écrire si la table est vide Écrire si la table est vide Aucune WRITE_EMPTY N'écrit les données que si la table est vide.
Ajouter à la table Ajouter au tableau --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 ou écraser une table à l'aide de l'une des méthodes suivantes :

  • Cloud Console ou UI Web classique
  • Commande bq load de l'outil de ligne de commande bq
  • Méthode API jobs.insert et configuration d'une tâche load
  • Bibliothèques clientes

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

Console

  1. Ouvrez la page BigQuery dans Cloud Console.

    Accéder à BigQuery

  2. Dans la section Ressources du panneau de navigation, développez votre projet Cloud et sélectionnez un ensemble de données.

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

    Créer une table

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

    • Pour le champ 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 Cloud Console. 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.

      Sélectionnez le fichier.

    • Pour Format de fichier, sélectionnez Parquet.

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

      Sélectionner un ensemble de données

    • Dans le champ Nom de la table, saisissez le nom de la table dans BigQuery à laquelle vous ajoutez des données ou que vous écrasez.

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

  6. Dans la section Schéma, aucune action n'est nécessaire. Le schéma est auto-décrit dans les fichiers Parquet.

  7. 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, Cloud Console 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.

  8. Cliquez sur Advanced options (Options avancées).

    • Sous Write preference (Préférences d'écriture), choisissez Append to table (Ajouter à la table) ou Overwrite table (Écraser la table).
    • Pour le champ Nombre d'erreurs autorisées, acceptez la valeur par défaut 0 ou saisissez le nombre maximal de lignes contenant des erreurs qui peuvent ê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 Valeurs inconnues, conservez l'option Ignorer les valeurs inconnues désactivé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.

      Écrasez la table.

  9. Cliquez sur Créer une table.

UI classique

  1. Accédez à l'UI 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, cliquez sur la flèche vers le bas Flèche vers le bas, puis sur 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.

  3. Dans la section Source Data (Données sources) de la page Create Table (Créer une table) :

    • Dans le champ Emplacement, sélectionnez Cloud Storage. Dans le champ de la source, saisissez l'URI Cloud Storage. Sachez que vous ne pouvez pas inclure plusieurs URI dans l'UI. 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 Format de fichier, sélectionnez Parquet.
  4. Dans la section Table de destination de la page Créer une table :

    • Sous 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 Type de table est défini sur Table native.
  5. Dans la section Schéma, aucune action n'est nécessaire. Les informations sur le schéma sont auto-décrites dans les fichiers Parquet.

  6. 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 qui peuvent être ignorées. Si le nombre de lignes contenant des erreurs dépasse cette valeur, la tâche renverra un message invalid et échouera.
    • Sous Préférences d'écriture, choisissez Ajouter à la table ou Écraser la table.
    • Conservez les valeurs par défaut pour Type de partitionnement, Champ de partitionnement, Demander un filtre de partitionnement et 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.
    • Sous Destination encryption (Chiffrement de la destination), sélectionnez Customer-managed encryption (Chiffrement géré par le client) pour utiliser une clé Cloud Key Management Service afin de chiffrer la table. Si vous conservez le paramètre Default, BigQuery chiffre les données au repos à l'aide d'une clé gérée par Google.
  7. Cliquez sur Créer une table.

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. Spécifiez l'option --source_format et définissez-la sur PARQUET. Comme les schémas Parquet 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'option --location et définissez la valeur correspondant à votre emplacement.

Les autres options facultatives sont les suivantes :

  • --max_bad_records : entier spécifiant le nombre maximal d'enregistrements incorrects autorisés avant l'échec total de la tâche. La valeur par défaut est 0. Au plus, cinq erreurs de n'importe quel type sont renvoyées, quelle que soit la valeur --max_bad_records.
  • --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 : 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 : PARQUET.
  • dataset : ensemble de données existant.
  • table : nom de la table dans laquelle vous chargez des données.
  • path_to_source : URI Cloud Storage complet ou liste d'URI séparés par des virgules. Les caractères génériques sont également acceptés.

Exemples :

La commande suivante permet de charger des données depuis gs://mybucket/mydata.parquet en écrasant une table nommée mytable dans l'ensemble de données mydataset.

    bq load \
    --replace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

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

    bq load \
    --noreplace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

Pour en savoir plus sur l'ajout et l'écrasement de données dans une table partitionnée à 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 PARQUET.

  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

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le 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 en langage Go.

import (
	"context"
	"fmt"

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

// importParquetTruncate demonstrates loading Apache Parquet data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importParquetTruncate(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.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	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

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java décrite dans le 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 en langage 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.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;
import java.math.BigInteger;

public class LoadParquetReplaceTable {

  public static void runLoadParquetReplaceTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquetReplaceTable(datasetName);
  }

  public static void loadParquetReplaceTable(String datasetName) {
    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();

      // Imports a GCS file into a table and overwrites table data if table already exists.
      // This sample loads CSV file at:
      // https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      // For more information on LoadJobConfiguration see:
      // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/bigquery/LoadJobConfiguration.Builder.html
      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              // Set the write disposition to overwrite existing table data.
              .setWriteDisposition(WriteDisposition.WRITE_TRUNCATE)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job job = bigquery.create(JobInfo.of(configuration));

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load into the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet overwrote existing table successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \n" + e.toString());
    }
  }
}

Node.js

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Node.js décrite dans le 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 en langage Node.js.

// 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 CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

async function loadParquetFromGCSTruncate() {
  /**
   * 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 = "my_table";

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'PARQUET',
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
    location: 'US',
  };

  // 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), metadata);
  // 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;
  }
}

PHP

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour PHP dans le 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 en langage PHP.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableID = 'The BigQuery table ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET')->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});

// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

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 : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

Pour remplacer les lignes d'une table existante, définissez la propriété LoadJobConfig.write_disposition sur la constante WriteDisposition WRITE_TRUNCATE.

import six

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 = six.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.PARQUET,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"
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 Parquet partitionnées avec Hive

BigQuery accepte le chargement de données Parquet 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 Parquet

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

Conversions de types

Type Parquet Type(s) Parquet converti(s) Type de données BigQuery
BOOLEAN AUCUN Booléen
INT32 AUCUN, UINT_8, UINT_16, UINT_32, INT_8, INT_16, INT_32 Entier
INT32 DECIMAL (voir la section Annotation DECIMAL) Numérique
INT32 DATE Date
INT64 AUCUN, UINT_64, INT_64 Entier
INT64 DECIMAL (voir la section Annotation DECIMAL) Numérique
INT64 TIMESTAMP_MILLIS Horodatage
INT64 TIMESTAMP_MICROS Horodatage
INT96 AUCUN Horodatage
FLOAT AUCUN Virgule flottante
DOUBLE AUCUN Virgule flottante
BYTE_ARRAY AUCUN Octets
BYTE_ARRAY UTF8 Chaîne
FIXED_LEN_BYTE_ARRAY DECIMAL (voir la section Annotation DECIMAL) Numérique
FIXED_LEN_BYTE_ARRAY AUCUN Octets

Les autres combinaisons de types Parquet et de types convertis ne sont pas compatibles.

Annotation DECIMAL

Les types Parquet avec l'annotation DECIMAL peuvent avoir au plus une précision égale à 38 (nombre total de chiffres) et une échelle égale à 9 (chiffres à droite de la virgule). Le nombre d'entiers, qui correspond à la valeur de la précision moins la valeur de l'échelle, peut être de 29 au plus. Par exemple, l'annotation DECIMAL(38, 9) est acceptée, car la précision est de 38 et l'échelle de 9, ce qui donne un nombre d'entiers égal à 29. À l'inverse, l'annotation DECIMAL(38, 5) n'est pas acceptée, car la précision est de 38 et l'échelle de 5, ce qui donne un nombre d'entiers égal à 33.

Conversions de noms de colonnes

Un nom de colonne ne peut contenir que des lettres (a-z, A-Z), des chiffres (0-9) et des traits de soulignement (_), et doit commencer par une lettre ou un trait de soulignement. Sa longueur maximale est de 128 caractères. Un nom de colonne ne peut utiliser aucun des préfixes suivants :

  • _TABLE_
  • _FILE_
  • _PARTITION

Les noms de colonnes en double ne sont pas autorisés, même si la casse est différente. Par exemple, la colonne Column1 est considérée comme identique à la colonne column1.

À l'heure actuelle, vous ne pouvez pas charger des fichiers Parquet contenant un nom de colonne avec un point (.).

Si un nom de colonne Parquet comprend d'autres caractères (hormis un point), ils sont remplacés par des traits de soulignement. Vous pouvez ajouter des traits de soulignement à la fin des noms de colonne pour éviter les conflits. Par exemple, si un fichier Parquet contient deux colonnes Column1 et column1, celles-ci sont respectivement chargées en tant que Column1 et column1_.