Charger des données ORC à partir de Cloud Storage

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

ORC 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 ORC depuis Cloud Storage, vous pouvez les placer dans une nouvelle table ou partition, les ajouter à une table ou partition existante, ou bien les utiliser pour écraser ces dernières. 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 ORC à partir d'un fichier local, consultez la page Charger des données dans BigQuery à partir d'une source de données locale.

Schémas ORC

Lorsque vous chargez des fichiers ORC 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é.

Par exemple, si vous disposez des fichiers ORC suivants dans Cloud Storage :

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

La commande CLI ci-dessous permet de charger tous les fichiers en une seule fois (sous la forme d'une liste d'éléments séparés par une virgule). Le schéma est dérivé de mybucket/01/b.orc :

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

Lorsque BigQuery détecte le schéma, certains types de données ORC sont convertis en types de données BigQuery de façon qu'ils soient compatibles avec la syntaxe SQL de BigQuery. Tous les champs du schéma détecté sont en mode NULLABLE. Pour en savoir plus, consultez la section Conversions ORC.

Lorsque vous chargez plusieurs fichiers ORC ayant des schémas différents, les champs identiques (même nom et même niveau imbriqué) spécifiés dans plusieurs schémas doivent être mappés au même type de données BigQuery converti dans chaque définition de schéma.

Compression ORC

Les fichiers ORC compressés ne sont pas acceptés, à la différence des pieds de page et des bandes de fichiers compressés. Les types de compression acceptés sont Zlib, Snappy, LZO et LZ4.

Autorisations requises

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

Autorisations BigQuery

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

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

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

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

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

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

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

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

Autorisations Cloud Storage

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

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

Charger des données ORC dans une nouvelle table

Vous pouvez charger des données ORC dans une nouvelle table de plusieurs façons :

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

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

Console

  1. Ouvrez l'UI Web de BigQuery dans la console GCP.
    Accéder à la console GCP

  2. Dans la section Ressources du panneau de navigation, développez votre projet 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.

    Afficher l'ensemble de données

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

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

    • Dans le champ relatif à la source, recherchez ou saisissez l'URI Cloud Storage. Sachez que vous ne pouvez pas inclure plusieurs URI dans la console GCP. 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électionner un fichier

    • Pour Format de fichier, sélectionnez ORC.

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

      Afficher l'ensemble de données

    • Vérifiez que le champ 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.

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

  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 ni 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 contribuer à réduire les coûts et à améliorer les performances. Pour en savoir plus, consultez la page Interroger des tables partitionnées. Cette option n'est pas disponible si 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. Actuellement, le clustering n'est disponible que pour les tables partitionnées.

  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 pouvant être ignorées. Si le nombre de lignes contenant des erreurs dépasse cette valeur, la tâche renverra un message invalid et échouera.
    • Pour le champ 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 pour utiliser une clé de service Cloud Key Management. Si vous conservez l'option 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'interface utilisateur Web de BigQuery.
    Accéder à l'UI Web de BigQuery

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

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

    • Cliquez sur Créer à partir de la source.
    • Sous Emplacement, sélectionnez Cloud Storage. Dans le champ relatif à la source, indiquez l'URI Cloud Storage. Sachez que vous ne pouvez pas inclure plusieurs URI dans l'interface utilisateur Web de BigQuery. En revanche, les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver au même emplacement que l'ensemble de données contenant la table que vous créez.
    • Pour Format de fichier, sélectionnez ORC.
  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. Aucune action n'est nécessaire dans la section Schéma. Le schéma est auto-décrit dans les fichiers ORC.

  6. (Facultatif) Dans la section Options :

    • 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 pouvant être ignorées. Si le nombre de lignes contenant des erreurs dépasse cette valeur, la tâche renverra un message invalid et échouera.
    • Pour le champ 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, procédez comme suit :
      • Pour 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 ni 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 contribuer à réduire les coûts et à améliorer les performances. Pour en savoir plus, consultez la page Interroger des tables partitionnées. Cette option n'est pas disponible si Type de partitionnement est défini sur Aucun.
    • Pour mettre la table en cluster, saisissez entre un et quatre noms de champ dans la case Champs de clustering.
    • Sous Chiffrement de la destination, sélectionnez Chiffrement géré par le client pour utiliser une clé Cloud Key Management Service afin de chiffrer la table. Si vous conservez l'option Default, BigQuery chiffre les données au repos à l'aide d'une clé gérée par Google.
  7. Cliquez sur Créer une table.

CLI

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

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

Les autres indicateurs facultatifs sont les suivants :

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

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

    Pour en savoir plus sur les tables en cluster, consultez la page suivante :

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

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

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

Où :

  • location est votre emplacement. L'indicateur --location est facultatif. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, définissez la valeur de l'indicateur sur asia-northeast1. Vous pouvez définir une valeur par défaut correspondant à l'emplacement à l'aide du fichier bigqueryrc.
  • format correspond à ORC.
  • 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 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.orc dans la table mytable de mydataset.

    bq load \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

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

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

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

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

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

    bq load \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata*.orc

La commande ci-dessous permet de charger les données de plusieurs fichiers de gs://mybucket/ dans la table mytable de mydataset. La commande inclut une liste d'URI Cloud Storage séparés par une virgule.

    bq load --autodetect \
    --source_format=ORC \
    mydataset.mytable \
    "gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"

API

  1. Créez une tâche 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 ORC en définissant la propriété sourceFormat sur ORC.

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

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

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

C#

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour C# 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 C#.


using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsOrc
{
    public void LoadTableGcsOrc(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null,
            options: jobOptions
        );
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.orc")
gcsRef.SourceFormat = bigquery.ORC
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())
}

Node.js

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Node.js 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 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 ORC file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.orc
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.orc';

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

  /**
   * TODO(developer): Uncomment the following line 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: 'ORC',
    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 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.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC');
$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 relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

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

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

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

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

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

Ruby

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

require "google/cloud/bigquery"

def load_table_gcs_orc dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, format: "orc"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done!  # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table(table_id)
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

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

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

Dans la console ou l'UI Web classique de BigQuery, utilisez l'option Préférence d'écriture pour spécifier l'action à entreprendre lorsque vous chargez des données à partir d'un fichier source ou d'un résultat de requête.

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

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

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

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

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

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

Console

  1. Ouvrez l'UI Web de BigQuery dans la console GCP.
    Accéder à la console GCP

  2. Dans la section Ressources du panneau de navigation, développez votre projet 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). 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 Create table (Créer une table) :

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

    • Dans le champ relatif à la source, recherchez ou saisissez l'URI Cloud Storage. Sachez que vous ne pouvez pas inclure plusieurs URI dans l'interface utilisateur Web BigQuery. En revanche, les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver au même emplacement que l'ensemble de données contenant la table à laquelle vous ajoutez des données ou que vous écrasez.

      Sélectionner un fichier

    • Pour Format de fichier, sélectionnez ORC.

  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 BigQuery à laquelle vous ajoutez des données ou que vous écrasez.

    • Vérifiez que Table type (Type de table) est défini sur Native table (Table native).

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

  7. Dans Paramètres de partitionnement et de clustering, conservez les valeurs par défaut. L'ajout ou l'écrasement de données dans une table ne permet pas de la convertir en table partitionnée ni en table en cluster. Par ailleurs, la console GCP n'accepte ni l'ajout, ni l'écrasement de données dans une table partitionnée ou en cluster lors d'une tâche de chargement.

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

    • Pour le champ Write preference (Préférence d'écriture), choisissez Append to table (Ajouter à la table) ou Overwrite table (Écraser la table).
    • Pour le champ Nombre d'erreurs autorisées, acceptez la valeur par défaut 0 ou saisissez le nombre maximal de lignes contenant des erreurs pouvant être ignorées. Si le nombre de lignes contenant des erreurs dépasse cette valeur, la tâche renverra un message invalid et échouera.
    • Pour le champ 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 pour utiliser une clé de service Cloud Key Management. Si vous conservez l'option Clé gérée par Google, BigQuery chiffre les données au repos.

      Écraser la table

  9. Cliquez sur Créer une table.

UI classique

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

  2. Dans le panneau de navigation, passez la souris sur un ensemble de données, cliquez sur l'icône de flèche vers le bas image de la flèche vers le bas et cliquez 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 Données sources de la page Créer une table :

    • Sous Emplacement, sélectionnez Cloud Storage. Dans le champ relatif à la source, saisissez l'URI Cloud Storage. Sachez que vous ne pouvez pas inclure plusieurs URI dans l'interface utilisateur. En revanche, les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver 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 ORC.
  4. Dans la section Table de destination de la page Créer une table :

    • Pour le champ Table name (Nom de la table), sélectionnez l'ensemble de données approprié, puis saisissez le nom de la table à laquelle vous ajoutez des données ou que vous écrasez dans le champ correspondant.
    • Vérifiez que Type de table est défini sur Table native.
  5. Aucune action n'est nécessaire dans la section Schéma. Les informations sur le schéma sont auto-décrites dans les fichiers ORC.

  6. Dans la section Options :

    • 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 pouvant être ignorées. Si le nombre de lignes contenant des erreurs dépasse cette valeur, la tâche renverra un message invalid et échouera.
    • Pour le champ Write preference (Préférence d'écriture), choisissez Append to table (Ajouter à la table) ou Overwrite table (Écraser la table).
    • Conservez les valeurs par défaut pour Type de partitionnement, Champ de partitionnement, Demander un filtre de partitionnement et Champs de clustering. L'ajout ou l'écrasement de données dans une table ne permet pas de la convertir en table partitionnée ni en table en cluster. 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 Chiffrement de la destination, sélectionnez Chiffrement géré par le client pour utiliser une clé Cloud Key Management Service afin de chiffrer la table. Si vous conservez l'option Default, BigQuery chiffre les données au repos à l'aide d'une clé gérée par Google.
  7. Cliquez sur Créer une table.

CLI

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

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

Les autres indicateurs facultatifs sont les suivants :

  • --max_bad_records : nombre entier spécifiant le nombre maximal d'enregistrements incorrects autorisés avant l'échec de la tâche. La valeur par défaut est 0. Cinq erreurs, au plus, de n'importe quel type sont renvoyées, quelle que soit la valeur --max_bad_records.
  • --destination_kms_key : clé 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

Où :

  • location est votre emplacement. Ce paramètre --location est facultatif. Vous pouvez spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
  • format correspond à ORC.
  • 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 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.orc en écrasant une table nommée mytable dans mydataset.

    bq load \
    --replace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

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

    bq load \
    --noreplace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

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.

API

  1. Créez une tâche 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 ORC.

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

C#

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour C# 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 C#.


using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsOrcTruncate
{
    public void LoadTableGcsOrcTruncate(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc,
            WriteDisposition = WriteDisposition.WriteTruncate
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null, options: jobOptions);
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.orc")
gcsRef.SourceFormat = bigquery.ORC
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())
}

Node.js

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

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

// Instantiate the 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.orc';

async function loadORCFromGCSTruncate() {
  /**
   * 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: 'ORC',
    // 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 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.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC')->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 relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

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

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

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

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

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

Ruby

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

require "google/cloud/bigquery"

def load_table_gcs_orc_truncate(
    dataset_id = "your_dataset_id",
    table_id   = "your_table_id"
  )
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

  load_job = dataset.load_job table_id,
                              gcs_uri,
                              format: "orc",
                              write:  "truncate"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done!  # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table(table_id)
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

Conversions ORC

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

Types primitifs

Type de données ORC Type de données BigQuery Notes
booléen BOOLEAN
byte INTEGER
short INTEGER
int INTEGER
long INTEGER
float FLOAT
double FLOAT
string STRING UTF-8 uniquement
varchar STRING UTF-8 uniquement
char STRING UTF-8 uniquement
binary BYTES
date DATE
timestamp TIMESTAMP ORC accepte une précision à la nanoseconde, mais BigQuery convertit les valeurs inférieures à la microseconde en microsecondes lors de la lecture des données.
decimal NUMERIC ou STRING Les types NUMERIC sont des valeurs numériques exactes avec 38 chiffres de précision et 9 chiffres décimaux d'échelle. Pour en savoir plus, consultez la section Type NUMERIC. Dans un schéma ORC, si un type "decimal" a au plus 9 chiffres d'échelle, et que le résultat de la soustraction des chiffres d'échelle aux chiffres de précision ne dépasse pas 29, il est converti au format NUMERIC. Sinon, il est converti au format STRING. Dans ce cas, un message d'avertissement est renvoyé.

Types complexes

Type de données ORC Type de données BigQuery Notes
struct RECORD
  • Tous les champs sont en mode NULLABLE.
  • L'ordre des champs est ignoré.
  • Le nom d'un champ doit être un nom de colonne valide.
map<K,V> RECORD Un champ map<K,V> ORC est converti en un élément RECORD répété contenant deux champs : une clé du même type de données que K et une valeur du même type de données que V. Ces deux champs sont en mode NULLABLE.
list champs répétés Les listes imbriquées et les listes de cartes ne sont pas acceptées.
union RECORD
  • Lorsqu'une union n'a qu'une variante, elle est convertie en champ NULLABLE.
  • Sinon, elle est convertie en élément RECORD avec une liste de champs en mode NULLABLE. Ces derniers ont des suffixes tels que champ_0, champ_1, etc. Lors de la lecture des données, un seul de ces champs se voit attribuer une valeur.

Noms de colonne

Un nom de colonne ne doit contenir que des lettres (a-z, A-Z), des chiffres (0-9) et des traits de soulignement (_), et il 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.

Valeurs NULL

Sachez que BigQuery ignore actuellement les éléments NULL pour le type composé de list.

Pour en savoir plus sur les types de données ORC, consultez le document Apache ORC™ Specification v1.

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.