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 plus d'informations sur le chargement de données Parquet à partir d'un fichier local, consultez la section Charger des données à partir de fichiers locaux.

Limites

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

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

  • BigQuery n'est pas compatible avec la gestion des versions d'objets Cloud Storage. Si vous incluez un numéro de génération dans l'URI Cloud Storage, la tâche de chargement échoue.

  • Le chargement de données Parquet suit la convention de nommage des colonnes et n'est pas compatible avec les noms de colonnes flexibles par défaut. Pour vous inscrire à cette version bêta, remplissez le formulaire d'inscription.

  • Vous ne pouvez pas utiliser de caractère générique dans l'URI Cloud Storage si l'un des fichiers à charger présente des schémas différents. Toute différence dans la position des colonnes est considérée comme un schéma différent.

Exigences relatives aux fichiers d'entrée

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

  • La taille des lignes ne doit pas dépasser 50 Mo.
  • Si vos données d'entrée contiennent plus de 100 colonnes, envisagez d'utiliser une taille de page inférieure à la taille de page par défaut (1 * 1024 * 1024 octets). Ceci est particulièrement utile si vous utilisez une compression importante.

Avant de commencer

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

Autorisations requises

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

Autorisations pour charger des données dans BigQuery

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

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

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

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

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

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

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

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

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

Autorisations requises

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

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

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

Créer un ensemble de données

Créez un ensemble de données BigQuery pour stocker vos données.

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 Google. Pour en savoir plus, consultez la section Conversions Parquet.

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

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

Compression de fichiers Parquet

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

  • GZip
  • LZO_1C
  • LZO_1X
  • LZ4_RAW
  • Snappy
  • ZSTD

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 :

  • Google Cloud Console
  • 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. Dans la console Google Cloud, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans le volet Explorer, développez votre projet, puis sélectionnez un ensemble de données.
  3. Dans la section Informations sur l'ensemble de données, cliquez sur Créer une table.
  4. Dans le panneau Créer une table, spécifiez les détails suivants :
    1. Dans la section Source, sélectionnez Google Cloud Storage dans la liste Créer une table à partir de. Ensuite, procédez comme suit :
      1. Sélectionnez un fichier dans le bucket Cloud Storage ou saisissez l'URI Cloud Storage. Vous ne pouvez pas inclure plusieurs URI dans la console Google Cloud. En revanche, les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver au même emplacement que l'ensemble de données contenant la table que vous souhaitez créer, ajouter ou écraser. Sélection d'un fichier source pour créer une table BigQuery
      2. Pour Format de fichier, sélectionnez Parquet.
    2. Dans la section Destination, spécifiez les détails suivants :
      1. Pour Ensemble de données, sélectionnez l'ensemble de données dans lequel vous souhaitez créer la table.
      2. Dans le champ Table, saisissez le nom de la table que vous souhaitez créer.
      3. Vérifiez que le champ Type de table est défini sur Table native.
    3. Aucune action n'est nécessaire dans la section Schéma. Le schéma est auto-décrit dans les fichiers Parquet.
    4. Facultatif : spécifiez les paramètres de partitionnement et de clustering. Pour en savoir plus, consultez les pages Créer des tables partitionnées et Créer et utiliser des tables en cluster.
    5. Cliquez sur Options avancées et procédez comme suit :
      • 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.
      • Si vous souhaitez ignorer les valeurs d'une ligne qui ne sont pas présentes dans le schéma de la table, sélectionnez Valeurs inconnues.
      • 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.
    6. Cliquez sur Créer une table.

SQL

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

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

    Accéder à BigQuery

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

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

  3. Cliquez sur Exécuter.

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

bq

Exécutez la commande bq load, définissez 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 indicateurs facultatifs sont les suivants :

  • --time_partitioning_type : Active le partitionnement temporel sur une table et définit le type de partition. Les valeurs possibles sont HOUR, DAY, MONTH et YEAR. Cette option est facultative lorsque vous créez une table partitionnée sur une colonne DATE, DATETIME ou TIMESTAMP. Le type de partition par défaut pour le partitionnement temporel est DAY. Vous ne pouvez pas modifier la spécification de partitionnement sur une table existante.
  • --time_partitioning_expiration : entier qui spécifie (en secondes) le délai au terme duquel une partition temporelle doit être supprimée. Le délai d'expiration correspond à la date UTC de la partition plus la valeur entière.
  • --time_partitioning_field : colonne DATE ou TIMESTAMP utilisée pour créer une table partitionnée. Si le partitionnement par date est activé sans cette valeur, une table partitionnée par date d'ingestion est créée.
  • --require_partition_filter : si cette option est activée, elle oblige les utilisateurs à inclure une clause WHERE spécifiant les partitions à interroger. Ce type de filtre peut réduire les coûts et améliorer les performances. Pour en savoir plus, consultez la section Interroger des tables partitionnées.
  • --clustering_fields : liste pouvant contenir jusqu'à quatre noms de colonne séparés par une virgule, et utilisée pour créer une table en cluster.
  • --destination_kms_key : clé Cloud KMS pour le chiffrement des données de la table.

  • --column_name_character_map : définit le champ d'application et le traitement des caractères dans les noms de colonne, avec la possibilité d'activer les noms de colonnes flexibles. Pour en savoir plus, consultez la section load_option_list.

    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 les éléments suivants :

  • LOCATION : votre position. 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 nouvelle table partitionnée par date d'ingestion nommée mytable dans 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 la table partitionnée mytable de 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 un job 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 job 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.

Accéder

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

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

import (
	"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 cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

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

import 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 cet exemple, suivez les instructions de configuration pour Node.js du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Node.js.

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

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

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

/**
 * This sample loads the 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 cet exemple, suivez les instructions de configuration pour PHP du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour PHP.

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

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 cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Python.

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

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 chaîne 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 Google Cloud, utilisez l'option Préférence d'écriture pour spécifier l'action à entreprendre lorsque vous chargez des données à partir d'un fichier source ou d'un résultat de requête.

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

Option de la console Option de l'outil bq Propriété de l'API BigQuery Description
Écrire si la table est vide Non compatible WRITE_EMPTY N'écrit les données que si la table est vide.
Ajouter à la table --noreplace ou --replace=false. Si --[no]replace n'est pas spécifié, les données sont ajoutées par défaut. WRITE_APPEND (Par défaut) Ajoute les données à la fin de la table.
Écraser la table --replace ou --replace=true WRITE_TRUNCATE Efface toutes les données existantes d'une table avant d'écrire les nouvelles données. Cette action supprime également le schéma de la table, la sécurité au niveau des lignes et la clé Cloud KMS.

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

Vous pouvez ajouter ou écraser une table à l'aide de l'une des méthodes suivantes :

  • Google Cloud Console
  • 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. Dans la console Google Cloud, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans le volet Explorer, développez votre projet, puis sélectionnez un ensemble de données.
  3. Dans la section Informations sur l'ensemble de données, cliquez sur Créer une table.
  4. Dans le panneau Créer une table, spécifiez les détails suivants :
    1. Dans la section Source, sélectionnez Google Cloud Storage dans la liste Créer une table à partir de. Ensuite, procédez comme suit :
      1. Sélectionnez un fichier dans le bucket Cloud Storage ou saisissez l'URI Cloud Storage. Vous ne pouvez pas inclure plusieurs URI dans la console Google Cloud. En revanche, les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver au même emplacement que l'ensemble de données contenant la table que vous souhaitez créer, ajouter ou écraser. Sélection d'un fichier source pour créer une table BigQuery
      2. Pour Format de fichier, sélectionnez Parquet.
    2. Dans la section Destination, spécifiez les détails suivants :
      1. Pour Ensemble de données, sélectionnez l'ensemble de données dans lequel vous souhaitez créer la table.
      2. Dans le champ Table, saisissez le nom de la table que vous souhaitez créer.
      3. Vérifiez que le champ Type de table est défini sur Table native.
    3. Aucune action n'est nécessaire dans la section Schéma. Le schéma est auto-décrit dans les fichiers Parquet.
    4. Facultatif : spécifiez les paramètres de partitionnement et de clustering. Pour en savoir plus, consultez les pages Créer des tables partitionnées et Créer et utiliser des tables en cluster. Vous ne pouvez pas convertir une table en table partitionnée ou en cluster en y ajoutant des données ou les écrasant. La console Google Cloud ne permet pas d'ajouter ni d'écraser des données dans des tables partitionnées ou en cluster lors d'une tâche de chargement.
    5. Cliquez sur Options avancées et procédez comme suit :
      • Sous Préférences d'écriture, choisissez Ajouter à la table ou Écraser la table.
      • Si vous souhaitez ignorer les valeurs d'une ligne qui ne sont pas présentes dans le schéma de la table, sélectionnez Valeurs inconnues.
      • 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.
    6. Cliquez sur Créer une table.

SQL

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

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

    Accéder à BigQuery

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

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

  3. Cliquez sur Exécuter.

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

bq

Saisissez la commande bq load avec l'option --replace pour écraser la table. Utilisez l'option --noreplace pour ajouter des données à la table. Si aucun paramètre n'est spécifié, les données sont ajoutées par défaut. Fournissez l'option --source_format et définissez-la sur 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 indicateurs facultatifs sont les suivants :

  • --destination_kms_key : clé Cloud KMS pour le chiffrement des données de la table.
bq --location=LOCATION load \
--[no]replace \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Remplacez les éléments suivants :

  • 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 les données de gs://mybucket/mydata.parquet et d'ajouter des données à la table mytable de 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 des tables partitionnées à l'aide de l'outil de ligne de commande bq, consultez la section Ajouter ou écraser des données dans une table partitionnée.

API

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

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

  3. La propriété source URIs doit être complète et respecter le format gs://BUCKET/OBJECT. Vous pouvez inclure plusieurs URI sous la forme d'une liste d'éléments séparés par une virgule. Sachez que les caractères génériques sont également acceptés.

  4. Spécifiez le format de données en définissant la propriété configuration.load.sourceFormat sur 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.

Accéder

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

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

import (
	"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 cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

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


import 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 cet exemple, suivez les instructions de configuration pour Node.js du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Node.js.

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

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

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

/**
 * This sample loads the 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 cet exemple, suivez les instructions de configuration pour PHP du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour PHP.

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

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 cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Python.

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

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

from google.cloud import bigquery

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

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

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

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

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.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

Cette section décrit comment BigQuery analyse divers types de données lorsque vous chargez des données Parquet.

Certains types de données Parquet (tels que INT32, INT64, BYTE_ARRAY et FIXED_LEN_BYTE_ARRAY) peuvent être convertis en plusieurs types de données BigQuery. Pour vous assurer que BigQuery convertit correctement les types de données Parquet, spécifiez le type de données approprié dans le fichier Parquet.

Par exemple, pour convertir le type de données Parquet INT32 en type de données BigQuery DATE, spécifiez les éléments suivants :

optional int32 date_col (DATE);

BigQuery convertit les types de données Parquet en types de données BigQuery décrits dans les sections suivantes.

Conversions de types

Type Parquet Types logiques Parquet Type de données BigQuery
BOOLEAN Aucun VALEUR BOOLÉENNE
INT32 Aucun, INTEGER (UINT_8, UINT_16, UINT_32, INT_8, INT_16, INT_32) INT64
INT32 DÉCIMAL NUMERIC, BIGNUMERIC ou STRING
INT32 DATE DATE
INT64 Aucun, INTEGER (UINT_64, INT_64) INT64
INT64 DÉCIMAL NUMERIC, BIGNUMERIC ou STRING
INT64 TIMESTAMP, precision=MILLIS (TIMESTAMP_MILLIS) TIMESTAMP
INT64 TIMESTAMP, precision=MICROS (TIMESTAMP_MICROS) TIMESTAMP
INT96 Aucun TIMESTAMP
FLOAT Aucun FLOAT64
DOUBLE Aucun FLOAT64
BYTE_ARRAY Aucun BYTES
BYTE_ARRAY STRING (UTF8) CHAÎNE
FIXED_LEN_BYTE_ARRAY DÉCIMAL NUMERIC, BIGNUMERIC ou STRING
FIXED_LEN_BYTE_ARRAY Aucun BYTES

Les groupes imbriqués sont convertis en types STRUCT. Les autres combinaisons de types Parquet et de types convertis ne sont pas compatibles.

Types logiques non signés

Les types Parquet UINT_8, UINT_16, UINT_32 et UINT_64 ne sont pas signés. BigQuery considère que les valeurs de ces types sont non signées lors du chargement dans une colonne INTEGER signée BigQuery. Dans le cas de UINT_64, une erreur est renvoyée si la valeur non signée dépasse la valeur maximale INTEGER de 9 223 372 036 854 775 807.

Type logique décimal

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

Type logique Enum

Les types logiques Enum peuvent être convertis en types STRING ou BYTES. Spécifiez le type de cible converti comme suit :

Type logique List

Vous pouvez activer l'inférence de schéma pour les types logiques LIST Parquet. BigQuery vérifie si le nœud LIST est au format standard ou dans l'un des formats décrits par les règles de rétrocompatibilité :

// standard form
<optional | required> group <name> (LIST) {
  repeated group list {
    <optional | required> <element-type> element;
  }
}

Si tel est le cas, le champ correspondant au nœud LIST dans le schéma converti est traité comme si le nœud était associé au schéma suivant :

repeated <element-type> <name>

Les nœuds "list" et "element" sont omis.

Données géospatiales

Vous pouvez charger des fichiers Parquet contenant WKT, WKB encodé en hexadécimal ou GeoJSON dans une colonne STRING ou WKB dans une colonne BYTE_ARRAY en spécifiant un schéma BigQuery avec le type GEOGRAPHY. Consultez la section Charger des données géospatiales.

Conversions de noms de colonnes

Un nom de colonne peut contenir des lettres (a-z, A-Z), des chiffres (0-9) ou des traits de soulignement (_), et doit commencer par une lettre ou un trait de soulignement. Si vous utilisez des noms de colonnes flexibles, BigQuery vous autorise à commencer un nom de colonne par un chiffre. Soyez prudent lorsque vous commencez des noms de colonnes par un chiffre, car l'utilisation de noms de colonnes flexibles avec l'API BigQuery Storage Read ou l'API BigQuery Storage Write nécessite un traitement particulier. Pour en savoir plus sur la compatibilité des noms de colonnes flexibles, consultez Noms de colonnes flexibles.

Les noms de colonne ne doivent pas comporter plus de 300 caractères. Les noms de colonnes ne peuvent utiliser aucun des préfixes suivants :

  • _TABLE_
  • _FILE_
  • _PARTITION
  • _ROW_TIMESTAMP
  • __ROOT__
  • _COLIDENTIFIER

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. Pour en savoir plus sur les règles de dénomination des colonnes, consultez Noms de colonnes dans la documentation de référence GoogleSQL.

Si un nom de table (par exemple, test) est identique à l'un de ses noms de colonne (par exemple, test), l'expression SELECT interprète la colonne test comme un élément STRUCT contenant toutes les autres colonnes de la table. Pour éviter ce conflit, utilisez l'une des méthodes suivantes :

  • Évitez d'utiliser le même nom pour une table et ses colonnes.

  • Attribuez un autre alias à la table. Par exemple, la requête suivante attribue un alias de table t à la table project1.dataset.test :

    SELECT test FROM project1.dataset.test AS t;

  • Incluez le nom de la table lorsque vous référencez une colonne. Exemple :

    SELECT test.test FROM project1.dataset.test;

Noms de colonne flexibles

Vous disposez d'une plus grande flexibilité dans vos noms de colonnes, y compris d'un accès étendu aux caractères dans d'autres langues que l'anglais, ainsi qu'à d'autres symboles.

Les noms de colonnes flexibles acceptent les caractères suivants :

  • N'importe quelle lettre dans n'importe quelle langue comme représenté par l'expression régulière Unicode \p{L}
  • Tout caractère numérique dans n'importe quelle langue comme représenté par l'expression régulière Unicode \p{N}.
  • Tout caractère de ponctuation du connecteur, y compris les traits de soulignement, comme représenté par l'expression régulière Unicode \p{Pc}.
  • Trait d'union ou tiret comme représenté par l'expression régulière Unicode \p{Pd}.
  • Toute marque destinée à accompagner un autre caractère comme représenté par l'expression régulière Unicode \p{M}. Par exemple, les accents, les tréma ou les cadres de délimitation.
  • Les caractères spéciaux suivants :
    • Esperluette (&) comme représenté par l'expression régulière Unicode \u0026.
    • Signe du pourcentage (%) comme représenté par l'expression régulière Unicode \u0025.
    • Signe "égal à" (=) comme représenté par l'expression régulière Unicode \u003D.
    • Signe plus (+) comme représenté par l'expression régulière Unicode \u002B.
    • Signe deux-points (:) comme représenté par l'expression régulière Unicode \u003A.
    • Apostrophe (') comme représenté par l'expression régulière Unicode \u0027.
    • Signe "inférieur à" (<) comme représenté par l'expression régulière Unicode \u003C.
    • Signe "supérieur à" (>) comme représenté par l'expression régulière Unicode \u003E.
    • Signe numérique (#) comme représenté par l'expression régulière Unicode \u0023.
    • Ligne verticale (|) comme représenté par l'expression régulière Unicode \u007c
    • Whitespace.

Les noms de colonnes flexibles n'acceptent pas les caractères spéciaux suivants :

  • Point d'exclamation (!) comme représenté par l'expression régulière Unicode \u0021.
  • Guillemets (") comme représenté par l'expression régulière Unicode \u0022.
  • Signe dollar ($) comme représenté par l'expression régulière Unicode \u0024.
  • Parenthèse gauche (() comme représenté par l'expression régulière Unicode \u0028
  • Parenthèse droite ()) comme représenté par l'expression régulière Unicode \u0029.
  • Astérisque (*) comme représenté par l'expression régulière Unicode \u002A.
  • Virgule (,) comme représenté par l'expression régulière Unicode \u002C.
  • Point (.) comme représenté par l'expression régulière Unicode \u002E.
  • Barre oblique (/) comme représenté par l'expression régulière Unicode \u002F.
  • Point-virgule (;) comme représenté par l'expression régulière Unicode \u003B.
  • Point d'interrogation (?) comme représenté par l'expression régulière Unicode \u003F.
  • Signe arobase (@) comme représenté par l'expression régulière Unicode \u0040.
  • Crochet gauche ([) comme représenté par l'expression régulière Unicode \u005B.
  • Barre oblique inverse (\) comme représenté par l'expression régulière Unicode \u005C.
  • Crochet droit (]) comme représenté par l'expression régulière Unicode \u005D.
  • Accent circonflexe (^) comme représenté par l'expression régulière Unicode \u005E.
  • Accent grave (`) comme représenté par l'expression régulière Unicode \u0060.
  • Accolade gauche {{) comme représenté par l'expression régulière Unicode \u007B
  • Accolade droite (}) comme représenté par l'expression régulière Unicode \u007D
  • Tilde (~) comme représenté par l'expression régulière Unicode \u007E.

Pour obtenir des consignes supplémentaires, consultez la section Noms de colonne.

Les caractères de colonne étendus sont compatibles avec l'API BigQuery Storage Read et l'API BigQuery Storage Write. Pour utiliser la liste étendue des caractères Unicode avec l'API BigQuery Storage Read, vous devez définir une option. Vous pouvez utiliser l'attribut displayName pour récupérer le nom de la colonne. L'exemple suivant montre comment définir une option avec le client Python :

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

Pour utiliser la liste étendue de caractères Unicode avec l'API BigQuery Storage Write, vous devez fournir le schéma avec la notation column_name, sauf si vous utilisez l'objet rédacteur JsonStreamWriter. L'exemple suivant montre comment fournir le schéma :

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

Dans cet exemple, item_name_column et item_description_column sont des noms d'espaces réservés qui doivent être conformes à la convention de dénomination du tampon de protocole. Notez que les annotations column_name ont toujours priorité sur les noms d'espaces réservés.

  • Le chargement de données Parquet n'est pas compatible avec les noms de colonnes flexibles par défaut. Pour vous inscrire à cette version preview, remplissez le formulaire d'inscription. Notez qu'après l'inscription à la version preview, tous les noms de colonne non valides (par exemple, le classement de noms de colonne) renvoient une erreur. Pour les projets non inscrits, la requête de chargement remplace les caractères non valides par des traits de soulignement au lieu de renvoyer une erreur.
  • Le chargement de données CSV à l'aide de la détection automatique de schéma n'est pas compatible par défaut avec les noms de colonne flexibles. Pour vous inscrire à cette version preview, remplissez le formulaire d'inscription. Notez qu'après l'inscription à la version preview, tous les noms de colonne non valides (par exemple, le classement de noms de colonne) renvoient une erreur. Pour les projets non inscrits, la requête de chargement remplace les caractères non valides par des traits de soulignement au lieu de renvoyer une erreur.

Limites

Les noms de colonnes flexibles ne sont pas compatibles avec les tables externes.

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

Déboguer votre fichier Parquet

Si vos tâches de chargement échouent en raison d'erreurs de données, vous pouvez utiliser PyArrow pour vérifier si vos fichiers de données Parquet sont corrompus. Si PyArrow ne parvient pas à lire les fichiers, ceux-ci sont susceptibles d'être rejetés par la tâche de chargement BigQuery. L'exemple suivant montre comment lire le contenu d'un fichier Parquet à l'aide de PyArrow :

from pyarrow import parquet as pq

# Read the entire file
pq.read_table('your_sample_file.parquet')
# Read specific columns
pq.read_table('your_sample_file.parquet',columns=['some_column', 'another_column'])
# Read the metadata of specific columns
file_metadata=pq.read_metadata('your_sample_file.parquet')
for col in file_metadata.row_group(0).to_dict()['columns']:
    print col['column_path_in_schema']
    print col['num_values']

Pour en savoir plus, consultez la documentation PyArrow.