Écrire des résultats de requête

Ce document explique comment écrire ou enregistrer des résultats de requête.

Tables temporaires et permanentes

BigQuery enregistre tous les résultats de requête dans une table, qui peut être permanente ou temporaire :

  • Une table temporaire est une table nommée de manière aléatoire et enregistrée dans un ensemble de données spécial. Les tables temporaires sont utilisées pour mettre en cache des résultats de requête. Elles ont une durée de vie d'environ 24 heures. Les tables temporaires ne sont pas disponibles pour le partage et ne sont pas consultables à l'aide des méthodes "list" standards ni des autres méthodes de manipulation des tables. Le stockage de tables temporaires n'est pas facturé.

  • Une table permanente peut être une table nouvelle ou existante dans un ensemble de données auquel vous avez accès. Si vous écrivez des résultats de requête dans une nouvelle table, le stockage des données vous est facturé. Lorsque vous écrivez des résultats de requête dans une table permanente, les tables que vous interrogez doivent se trouver dans le même emplacement que l'ensemble de données qui contient la table de destination.

Écrire des résultats de requête dans une table permanente

Lorsque vous écrivez des résultats de requête dans une table permanente, vous pouvez créer une table, ajouter les résultats à une table existante ou remplacer une table existante. Vous pouvez écrire les résultats de la requête dans une table permanente en :

  • utilisant la console GCP ou l'interface utilisateur Web classique de BigQuery ;
  • utilisant la commande bq query de l'outil de ligne de commande ;
  • appelant la méthode API jobs.insert et en configurant une tâche de type query.

Autorisations requises

Les autorisations requises pour écrire des résultats de requête dans une table permanente dépendent de la disposition en écriture des données.

Autorisations d'écrire des résultats de requête dans une nouvelle table

Si vous écrivez des résultats de requête dans une nouvelle table, vous devez disposer d'un accès WRITER au niveau de l'ensemble de données ou disposer d'un rôle IAM comprenant les autorisations bigquery.tables.create au niveau du projet. Les rôles IAM prédéfinis au niveau du projet ci-dessous incluent les autorisations bigquery.tables.create :

En outre, comme le rôle bigquery.user dispose d'autorisations bigquery.datasets.create, un utilisateur ayant le rôle bigquery.user peut créer des tables dans tous les ensembles de données qu'il crée. Lorsqu'un utilisateur détenant le rôle bigquery.user crée un ensemble de données, il bénéficie d'un accès OWNER à celui-ci. L'accès OWNER à un ensemble de données donne à l'utilisateur un contrôle total sur celui-ci et sur toutes les tables qu'il contient.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page Contrôle des accès. Pour en savoir plus sur les rôles au niveau des ensembles de données, consultez la section Rôles primitifs pour les ensembles de données.

Autorisations d'écraser ou d'ajouter des données

Si vous utilisez des résultats de requête pour écraser une table existante ou ajouter des données à cette dernière, vous devez disposer d'un accès WRITER au niveau de l'ensemble de données ou d'un rôle IAM comprenant les autorisations bigquery.tables.updateData au niveau du projet. Les rôles IAM prédéfinis au niveau du projet ci-dessous incluent les autorisations bigquery.tables.updateData :

En outre, comme le rôle bigquery.user dispose d'autorisations bigquery.datasets.create, un utilisateur ayant le rôle bigquery.user peut écraser ou ajouter toutes les tables qu'il crée dans l'ensemble de données. Lorsqu'un utilisateur détenant le rôle bigquery.user crée un ensemble de données, il bénéficie d'un accès OWNER à celui-ci. Un accès OWNER à un ensemble de données confère à l'utilisateur un contrôle total sur cet ensemble et sur toutes les tables qu'il contient.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page Contrôle des accès. Pour en savoir plus sur les rôles au niveau de l'ensemble de données, consultez la section Rôles primitifs pour les ensembles de données.

Écrire des résultats de requête

Pour écrire des résultats de requête dans une table permanente :

Console

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

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

  3. Si l'éditeur de requête est masqué, cliquez sur Afficher l'éditeur en haut à droite de la fenêtre.

  4. Saisissez une requête SQL valide dans la zone de texte de l'éditeur de requête.

  5. Sous l'éditeur, cliquez sur More (Plus) et sélectionnez Query settings (Paramètres de requête).

    Paramètres de requête

  6. Cochez la case Set a destination table for query results (Définir une table de destination pour les résultats de la requête).

    Définir la destination

  7. Dans la section Destination, sélectionnez le nom du projet et le nom de l'ensemble de données où la table doit être créée, puis choisissez le nom de la table.

  8. Dans la section Préférence d'écriture pour la table de destination, choisissez l'une des options suivantes :

    • Écrire si la table est vide : n'écrit les résultats de requête dans la table que si celle-ci est vide.
    • Ajouter à la table : ajoute les résultats de requête à une table existante.
    • Écraser la table : écrase une table existante portant le même nom à l'aide des résultats de requête.
  9. (Facultatif) Dans le champ Zone de traitement, cliquez sur Sélection automatique et choisissez l'emplacement de vos données.

  10. Cliquez sur Exécuter la requête. Cette action crée une tâche de requête qui écrit les résultats dans la table spécifiée.

Si vous oubliez de spécifier une table de destination avant d'exécuter la requête, vous pouvez copier la table temporaire dans une table permanente. Pour ce faire, cliquez sur le bouton Enregistrer l'affichage situé sous l'éditeur.

UI classique

Option 1 : Utiliser une instruction LDD

Les instructions LDD (langage de définition de données) vous permettent de créer et modifier des tables à l'aide de la syntaxe de requête SQL standard.

Pour plus d'informations, consultez la page relative à l'instruction CREATE TABLE et l'exemple CREATE TABLE : Créer une table à partir d'une table existante.

Option 2 : Utiliser l'UI Web classique

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

  2. Cliquez sur le bouton Saisir une requête.

  3. Saisissez une requête SQL BigQuery valide dans la zone de texte Nouvelle requête.

  4. Cliquez sur Afficher les options.

  5. Dans la section Table de destination, cliquez sur Sélectionner une table.

  6. Dans la boîte de dialogue Sélectionner une table de destination :

    1. Pour Projet, choisissez le projet où la table de destination sera créée.

    2. Pour Ensemble de données, choisissez l'ensemble de données où sera stockée la table.

    3. Dans le champ ID de la table, saisissez un nom de table. Le nom doit être unique dans l'ensemble de données de destination. Le nom de la table peut contenir jusqu'à 1 024 caractères et uniquement les caractères de a à z, A à Z, 0 à 9 ou _ (le trait de soulignement).

    4. Cliquez sur OK.

  7. Dans la section Table de destination, pour Préférence d'écriture, sélectionnez l'une des options suivantes :

    • Écrire si la table est vide : n'écrit les résultats de requête dans la table que si celle-ci est vide.
    • Ajouter à la table : ajoute les résultats de requête à une table existante.
    • Écraser la table : écrase une table existante portant le même nom à l'aide des résultats de requête.
  8. (Facultatif) Dans le champ Zone de traitement, cliquez sur Non spécifiée et sélectionnez l'emplacement de vos données.

  9. Cliquez sur Exécuter la requête. Cette action crée une tâche de requête qui écrit les résultats dans la table spécifiée.

Si vous oubliez de spécifier une table de destination avant d'exécuter la requête, vous pouvez copier la table temporaire dans une table permanente. Pour ce faire, cliquez sur le bouton Enregistrer en tant que table dans la fenêtre des résultats.

CLI

Saisissez la commande bq query et spécifiez l'indicateur --destination_table pour créer une table permanente en fonction des résultats de requête. Spécifiez l'indicateur use_legacy_sql=false pour utiliser la syntaxe SQL standard. Pour écrire les résultats de requête dans une table qui ne se trouve pas dans votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données en respectant le format suivant : [PROJECT_ID]:[DATASET].

Définissez l'indicateur --location sur la valeur correspondant à votre emplacement.

Pour contrôler la disposition en écriture d'une table de destination existante, fournissez l'un des indicateurs facultatifs suivants :

  • --append_table : si la table de destination existe, les résultats de requête y sont ajoutés.
  • --replace : si la table de destination existe, elle est remplacée par les résultats de requête.

    bq --location=[LOCATION] query --destination_table [PROJECT_ID]:[DATASET].[TABLE] --use_legacy_sql=false '[QUERY]'
    

Où :

  • [LOCATION] est le nom de l'emplacement utilisé pour traiter la requête. Cet 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 spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
  • [PROJECT_ID] est l'ID de votre projet.
  • [DATASET] est le nom de l'ensemble de données contenant la table dans laquelle vous écrivez les résultats de requête.
  • [TABLE] est le nom de la table dans laquelle vous écrivez les résultats de requête.
  • [QUERY] est une requête en syntaxe SQL standard.

Si aucun indicateur de disposition en écriture n'est spécifié, le comportement par défaut consiste à écrire les résultats dans la table uniquement si celle-ci est vide. Si la table existe et qu'elle n'est pas vide, l'erreur suivante est renvoyée : BigQuery error in query operation: Error processing job '[PROJECT_ID]:bqjob_123abc456789_00000e1234f_1': Already Exists: Table [PROJECT_ID]:[DATASET].[TABLE].

Exemples :

Saisissez la commande suivante pour écrire les résultats de requête dans une table de destination nommée mytable dans mydataset. L'ensemble de données se trouve dans votre projet par défaut. Aucun indicateur de disposition en écriture n'étant spécifié dans la commande, la table doit être nouvelle ou vide. Sinon, une erreur Already exists est renvoyée. La requête extrait les données de l'ensemble de données public USA Name Data.

bq --location=US query --destination_table mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Saisissez la commande suivante pour utiliser les résultats de requête afin d'écraser une table de destination nommée mytable dans mydataset. L'ensemble de données se trouve dans votre projet par défaut. La commande utilise l'indicateur --replace pour écraser la table de destination.

bq --location=US query --destination_table mydataset.mytable --replace --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Saisissez la commande suivante pour ajouter des résultats de requête à une table de destination nommée mytable dans mydataset. L'ensemble de données se trouve dans myotherproject, et non dans votre projet par défaut. La commande utilise l'indicateur --append pour ajouter les résultats de requête à la table de destination.

bq --location=US query --destination_table myotherproject:mydataset.mytable --append --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

API

Pour enregistrer des résultats de requête dans une table permanente, appelez la méthode jobs.insert, configurez une tâche de type query et incluez une valeur pour la propriété destinationTable. Pour contrôler la disposition en écriture d'une table de destination existante, configurez la propriété writeDisposition.

Spécifiez l'emplacement dans la propriété location de la section jobReference de la ressource de tâche.

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

q := client.Query("SELECT 17 as my_col")
q.Location = "US" // Location must match the dataset(s) referenced in query.
q.QueryConfig.Dst = client.Dataset(destDatasetID).Table(destTableID)
job, err := q.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}
it, err := job.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Java

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

Pour enregistrer des résultats de requête dans une table permanente, définissez la table de destination sur l'identifiant TableId souhaité dans une configuration QueryJobConfiguration.

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // Note that setUseLegacySql is set to false by default
    QueryJobConfiguration.newBuilder(query)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Python

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

Pour enregistrer des résultats de requête dans une table permanente, créez une configuration QueryJobConfig et définissez la destination sur la valeur TableReference souhaitée. Transmettez la configuration de la tâche à la méthode de requête.

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

job_config = bigquery.QueryJobConfig()
# Set the destination table
table_ref = client.dataset(dataset_id).table('your_table_id')
job_config.destination = table_ref
sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""

# Start the query, passing in the extra configuration.
query_job = client.query(
    sql,
    # Location must match that of the dataset(s) referenced in the query
    # and of the destination table.
    location='US',
    job_config=job_config)  # API request - starts the query

query_job.result()  # Waits for the query to finish
print('Query results loaded to table {}'.format(table_ref.path))

Écrire des résultats de requête volumineux

Normalement, les requêtes ont une taille de réponse maximale. Si vous prévoyez d'exécuter une requête pouvant renvoyer des résultats plus importants, vous pouvez :

  • en SQL standard, spécifier une table de destination pour les résultats de requête ;
  • en ancien SQL, spécifier une table de destination et définir l'option allowLargeResults.

Lorsque vous spécifiez une table de destination pour des résultats de requête volumineux, le stockage des données vous est facturé.

Limites

En ancien SQL, l'écriture de résultats volumineux est soumise aux limites suivantes :

  • Vous devez spécifier une table de destination.
  • Vous ne pouvez pas spécifier de clause ORDER BY, TOP ni LIMIT de niveau supérieur. Cela annule l'avantage d'utiliser allowLargeResults, car le résultat de la requête ne peut plus être calculé en parallèle.
  • Les fonctions de fenêtrage ne renvoient des résultats de requête volumineux que si elles sont utilisées avec une clause PARTITION BY.

Écrire des résultats volumineux en ancien SQL

Pour écrire des ensembles de résultats volumineux en ancien SQL :

Console

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

  2. Cliquez sur Saisir une nouvelle requête.

  3. Saisissez une requête SQL BigQuery valide dans la zone de texte de l'éditeur de requête. Utilisez le préfixe #legacySQL ou assurez-vous que la case Utiliser l'ancien SQL est cochée dans les paramètres de requête.

  4. Cliquez sur More (Plus), puis sélectionnez Query settings (Paramètres de requête).

    Paramètres de requête

  5. Pour Destination, cochez la case Set a destination table for query results (Définir une table de destination pour les résultats de la requête).

    Définir la destination

  6. Pour Nom du projet, choisissez le projet dans lequel la table de destination sera créée.

  7. Pour Nom de l'ensemble de données, choisissez l'ensemble de données qui stockera la table.

  8. Dans le champ Nom de la table, saisissez un nom de table.

  9. Si vous écrivez un ensemble de résultats volumineux dans une table existante, vous pouvez utiliser les options Destination table write preference (Préférence d'écriture pour la table de destination) pour contrôler la disposition en écriture de la table de destination :

    • Write if empty (Écrire si la table est vide) : n'écrit les résultats de requête dans la table que si celle-ci est vide.
    • Append to table (Ajouter à la table) : ajoute les résultats de requête à une table existante.
    • Overwrite table (Écraser la table) : écrase une table existante portant le même nom à l'aide des résultats de requête.

    Case d'option "Écraser la table"

  10. Pour Results size (Taille des résultats), cochez la case Allow Large Results (no size limit) (Autoriser un nombre élevé de résultats (aucune limite)).

    Taille des résultats de la requête

  11. (Facultatif) Dans le champ Processing location (Zone de traitement), cliquez sur Auto-select (Sélection automatique) et choisissez l'emplacement de vos données.

    Zone de traitement des requêtes

  12. Cliquez sur Enregistrer pour mettre à jour les paramètres de la requête.

  13. Cliquez sur Exécuter. Cette action crée une tâche de requête qui écrit les résultats de requête volumineux dans la table spécifiée.

UI classique

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

  2. Cliquez sur le bouton Saisir une requête.

  3. Saisissez une requête SQL BigQuery valide dans la zone de texte Nouvelle requête. Utilisez le préfixe #legacySQL ou assurez-vous que la case Utiliser l'ancien SQL est cochée dans les options de requête.

  4. Cliquez sur Afficher les options.

  5. Dans le champ Table de destination, cliquez sur Sélectionner une table.

  6. Dans la boîte de dialogue Sélectionner une table de destination :

    1. Pour Projet, choisissez le projet où la table de destination sera créée.

    2. Pour Ensemble de données, choisissez l'ensemble de données où sera stockée la table.

    3. Dans le champ ID de la table, saisissez un nom de table.

    4. Cliquez sur OK.

  7. Si vous écrivez un ensemble de résultats volumineux dans une table existante, vous pouvez utiliser l'option Write Preference (Préférence d'écriture) pour contrôler la disposition en écriture de la table de destination :

    • Write if empty (Écrire si la table est vide) : n'écrit les résultats de requête dans la table que si celle-ci est vide.
    • Append to table (Ajouter à la table) : ajoute les résultats de requête à une table existante.
    • Overwrite table (Écraser la table) : écrase une table existante portant le même nom à l'aide des résultats de requête.
  8. Pour Results Size (Taille des résultats), cochez la case Allow Large Results (Autoriser un nombre élevé de résultats).

    Option "Autoriser un nombre élevé de résultats"

  9. (Facultatif) Dans le champ Zone de traitement, cliquez sur Non spécifiée et sélectionnez l'emplacement de vos données.

  10. Cliquez sur Exécuter la requête. Cette action crée une tâche de requête qui écrit les résultats de requête volumineux dans la table spécifiée.

Ligne de commande

Utilisez conjointement les indicateurs --allow_large_results et --destination_table pour créer la table de destination qui doit contenir l'ensemble de résultats volumineux. Comme l'option --allow_large_results ne s'applique qu'à l'ancien SQL, vous devez également spécifier l'indicateur --use_legacy_sql=true. Pour écrire les résultats de requête dans une table qui ne se trouve pas dans votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données en respectant le format suivant : [PROJECT_ID]:[DATASET]. Fournissez l'indicateur --location, puis définissez sa valeur sur votre emplacement.

Pour contrôler la disposition en écriture d'une table de destination existante, fournissez l'un des indicateurs facultatifs suivants :

  • --append_table : si la table de destination existe, les résultats de requête y sont ajoutés.
  • --replace : si la table de destination existe, elle est remplacée par les résultats de requête.

    bq --location=[LOCATION] query --destination_table [PROJECT_ID]:[DATASET].[TABLE_NAME] --use_legacy_sql=true --allow_large_results "[QUERY]"
    

Où :

  • [LOCATION] est le nom de l'emplacement utilisé pour traiter la requête. 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 indiquer une valeur d'emplacement par défaut à l'aide du fichier .bigqueryrc.
  • [PROJECT_ID] est l'ID de votre projet.
  • [DATASET] est le nom de l'ensemble de données contenant la table dans laquelle vous écrivez les résultats de requête.
  • [TABLE] est le nom de la table dans laquelle vous écrivez les résultats de requête.
  • [QUERY] est une requête dans une syntaxe en ancien SQL.

Exemples :

Saisissez la commande suivante pour écrire les résultats de requête volumineux dans une table de destination nommée mytable dans mydataset. L'ensemble de données se trouve dans votre projet par défaut. Aucun indicateur de disposition en écriture n'étant spécifié dans la commande, la table doit être nouvelle ou vide. Sinon, une erreur Already exists est renvoyée. La requête extrait les données de l'ensemble de données public USA Name Data. Cette requête est utilisée à titre d'exemple uniquement. L'ensemble de résultats renvoyé ne dépasse pas la taille de réponse maximale.

bq --location=US query --destination_table mydataset.mytable --use_legacy_sql=true --allow_large_results "SELECT name,number FROM [bigquery-public-data:usa_names.usa_1910_current] WHERE gender = 'M' ORDER BY number DESC"

Saisissez la commande suivante pour utiliser les résultats de requête volumineux afin d'écraser une table de destination nommée mytable dans mydataset. L'ensemble de données se trouve dans myotherproject, et non dans votre projet par défaut. La commande utilise l'indicateur --replace pour écraser la table de destination.

bq --location=US query --destination_table mydataset.mytable --replace --use_legacy_sql=true --allow_large_results "SELECT name,number FROM [bigquery-public-data:usa_names.usa_1910_current] WHERE gender = 'M' ORDER BY number DESC"

Saisissez la commande suivante pour ajouter des résultats de requête volumineux à une table de destination nommée mytable dans mydataset. L'ensemble de données se trouve dans myotherproject, et non dans votre projet par défaut. La commande utilise l'indicateur --append pour ajouter les résultats de requête à la table de destination.

bq --location=US query --destination_table myotherproject:mydataset.mytable --append --use_legacy_sql=true --allow_large_results "SELECT name,number FROM [bigquery-public-data:usa_names.usa_1910_current] WHERE gender = 'M' ORDER BY number DESC"

API

Pour écrire des résultats volumineux dans une table de destination, appelez la méthode jobs.insert, configurez une tâche de type query et définissez la propriété configuration.query.allowLargeResults sur true. Spécifiez la table de destination à l'aide de la propriété configuration.query.destinationTable. Pour contrôler la disposition en écriture d'une table de destination existante, configurez la propriété configuration.query.writeDisposition.

Spécifiez l'emplacement dans la propriété location de la section jobReference de la ressource de tâche.

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 sur l'API BigQuery Go.

q := client.Query(
	"SELECT corpus FROM [bigquery-public-data:samples.shakespeare] GROUP BY corpus;")
q.UseLegacySQL = true
q.AllowLargeResults = true
q.QueryConfig.Dst = client.Dataset(dstDatasetID).Table(dstTableID)
job, err := q.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}
it, err := job.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Java

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

Pour que des résultats volumineux puissent être renvoyés, définissez Autoriser un nombre élevé de résultats sur true et la table de destination sur l'identifiant TableId souhaité dans une configuration QueryJobConfiguration.

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM [bigquery-public-data:samples.shakespeare] GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // To use legacy SQL syntax, set useLegacySql to true.
    QueryJobConfiguration.newBuilder(query)
        .setUseLegacySql(true)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        // Allow results larger than the maximum response size.
        // If true, a destination table must be set.
        .setAllowLargeResults(true)
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Python

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

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

job_config = bigquery.QueryJobConfig()
# Set use_legacy_sql to True to use legacy SQL syntax.
job_config.use_legacy_sql = True
# Set the destination table
table_ref = client.dataset(dataset_id).table("your_table_id")
job_config.destination = table_ref
job_config.allow_large_results = True
sql = """
    SELECT corpus
    FROM [bigquery-public-data:samples.shakespeare]
    GROUP BY corpus;
"""
# Start the query, passing in the extra configuration.
query_job = client.query(
    sql,
    # Location must match that of the dataset(s) referenced in the query
    # and of the destination table.
    location="US",
    job_config=job_config,
)  # API request - starts the query

query_job.result()  # Waits for the query to finish
print("Query results loaded to table {}".format(table_ref.path))

Télécharger et enregistrer des résultats de requête

Après avoir exécuté une requête SQL, vous pouvez télécharger les résultats dans un fichier sur votre machine locale, enregistrer les résultats dans Google Drive ou Google Sheets, ou enregistrer les résultats dans une table permanente dans BigQuery.

Limites

Le téléchargement et l'enregistrement des résultats de requête sont soumis aux restrictions suivantes :

  • Vous ne pouvez télécharger des résultats de requête que dans un fichier local ou dans Google Sheets dans l'interface utilisateur Web classique de BigQuery. Pour télécharger les résultats sur Google Drive, utilisez la console GCP.
  • Pour que vous puissiez télécharger des résultats de requête à l'aide de l'interface utilisateur Web de BigQuery, l'ensemble de résultats ne doit pas dépasser 16 000 lignes ni 10 Mo. Si les résultats dépassent 10 Mo ou 16 000 lignes, vous pouvez les enregistrer dans une table.
  • Vous ne pouvez télécharger les résultats de requête qu'au format CSV ou JSON délimité par un retour à la ligne.
  • Vous ne pouvez pas télécharger des résultats de requête contenant des données imbriquées et répétées au format CSV.
  • Vous ne pouvez pas enregistrer des résultats de requête contenant des données imbriquées et répétées dans Google Sheets.
  • Lorsque vous enregistrez des résultats de requête dans Google Sheets à l'aide de l'interface utilisateur Web classique de BigQuery, l'ensemble de résultats ne doit pas dépasser 16 000 lignes ni 10 Mo. Si les résultats dépassent 10 Mo ou 16 000 lignes, vous pouvez les enregistrer dans une table.
  • Il n'est pas possible d'enregistrer les résultats dans un fichier local, dans Google Sheets ou sur Google Drive avec l'outil de ligne de commande ni avec l'API.
  • Pour que vous puissiez enregistrer des résultats de requête sur Google Drive à l'aide de la console GCP, l'ensemble de résultats ne doit pas dépasser 1 Go. Si les résultats dépassent 1 Go, vous pouvez les enregistrer dans une table.
  • Vous ne pouvez enregistrer des résultats de requête sur Google Drive qu'au format CSV ou JSON délimité par un retour à la ligne.

Télécharger des résultats de requête dans un fichier local

Il n'est pas possible de télécharger des résultats de requête dans un fichier local avec l'outil de ligne de commande ni avec l'API.

Pour télécharger des résultats de requête dans un fichier CSV ou JSON délimité par un retour à la ligne à l'aide de l'interface utilisateur Web, procédez comme suit :

Console

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

  2. Cliquez sur Saisir une nouvelle requête.

  3. Saisissez une requête SQL valide dans la zone de texte de l'éditeur de requête.

  4. (Facultatif) Pour modifier l'emplacement de traitement, cliquez sur Plus et sélectionnez Paramètres de requête. Dans le champ Zone de traitement, cliquez sur Sélection automatique et choisissez l'emplacement de vos données.

  5. Cliquez sur Exécuter.

  6. Lorsque les résultats sont renvoyés, cliquez sur Enregistrer les résultats et sélectionnez le format/l'emplacement d'enregistrement des résultats.

    Le fichier est téléchargé à l'emplacement de téléchargement par défaut de votre navigateur.

UI classique

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

  2. Cliquez sur le bouton Saisir une requête.

  3. Saisissez une requête SQL BigQuery valide dans la zone de texte Nouvelle requête.

  4. Cliquez sur Afficher les options.

  5. (Facultatif) Dans le champ Zone de traitement, cliquez sur Non spécifiée et sélectionnez l'emplacement de vos données.

  6. Cliquez sur Exécuter la requête.

  7. Lorsque les résultats sont renvoyés, cliquez sur le bouton Download as CSV (Télécharger au format CSV) ou Download as JSON (Télécharger au format JSON) au-dessus.

    Capture d'écran des boutons "Télécharger" et "Enregistrer"

    Le fichier est téléchargé à l'emplacement de téléchargement par défaut de votre navigateur.

Enregistrer des résultats de requête sur Google Drive

Il n'est pas possible d'enregistrer des résultats de requête sur Google Drive avec l'outil de ligne de commande ni avec l'API, ni avec l'interface utilisateur Web classique de BigQuery.

Pour enregistrer des résultats de requête sur Google Drive à l'aide de la console GCP, procédez comme suit :

Console

  1. Ouvrez l'interface utilisateur Web de BigQuery dans la console GCP.

    Accéder à l'UI Web de BigQuery

  2. Saisissez une requête SQL valide dans la zone de texte de l'éditeur de requête.

  3. Cliquez sur Exécuter.

  4. Lorsque les résultats sont renvoyés, cliquez sur Save results (Enregistrer les résultats).

    Capture d'écran du bouton "Enregistrer les résultats"

  5. Sélectionnez CSV (Google Drive) ou JSON (Google Drive). Lorsque vous enregistrez des résultats sur Google Drive, vous ne pouvez pas choisir l'emplacement. Les résultats sont toujours enregistrés à l'emplacement racine "Mon Drive".

  6. L'enregistrement des résultats sur Google Drive peut prendre quelques minutes. Une fois les résultats enregistrés, vous recevez un message pop-up contenant le nom du fichier (bq-results-[TIMESTAMP]-[RANDOM_CHARACTERS].[CSV or JSON]).

    Capture d'écran du bouton "Enregistrer les résultats"

  7. Dans le message pop-up, cliquez sur Ouvrir pour ouvrir le fichier ou accédez à Google Drive, puis cliquez sur Mon Drive.

Enregistrer des résultats de requête dans une table

Pour enregistrer des résultats de requête dans une table :

Console

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

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

  3. Si l'éditeur de requête est masqué, cliquez sur Afficher l'éditeur en haut à droite de la fenêtre.

  4. Saisissez une requête SQL valide dans la zone de texte de l'éditeur de requête.

  5. Sous l'éditeur, cliquez sur More (Plus) et sélectionnez Query settings (Paramètres de requête).

    Paramètres de requête

  6. Cochez la case Set a destination table for query results (Définir une table de destination pour les résultats de la requête).

    Définir la destination

  7. Dans la section Destination, sélectionnez le nom du projet et le nom de l'ensemble de données où la table doit être créée, puis choisissez le nom de la table.

  8. Dans la section Préférence d'écriture pour la table de destination, choisissez l'une des options suivantes :

    • Écrire si la table est vide : n'écrit les résultats de requête dans la table que si celle-ci est vide.
    • Ajouter à la table : ajoute les résultats de requête à une table existante.
    • Écraser la table : écrase une table existante portant le même nom à l'aide des résultats de requête.
  9. (Facultatif) Dans le champ Zone de traitement, cliquez sur Sélection automatique et choisissez l'emplacement de vos données.

  10. Cliquez sur Exécuter la requête. Cette action crée une tâche de requête qui écrit les résultats dans la table spécifiée.

Si vous oubliez de spécifier une table de destination avant d'exécuter la requête, vous pouvez copier la table temporaire dans une table permanente. Pour ce faire, cliquez sur le bouton Enregistrer l'affichage situé sous l'éditeur.

UI classique

Option 1 : Utiliser une instruction LDD

Les instructions LDD (langage de définition de données) vous permettent de créer et modifier des tables à l'aide de la syntaxe de requête SQL standard.

Pour plus d'informations, consultez la page relative à l'instruction CREATE TABLE et l'exemple CREATE TABLE : Créer une table à partir d'une table existante.

Option 2 : Utiliser l'UI Web classique

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

  2. Cliquez sur le bouton Saisir une requête.

  3. Saisissez une requête SQL BigQuery valide dans la zone de texte Nouvelle requête.

  4. Cliquez sur Afficher les options.

  5. Dans la section Table de destination, cliquez sur Sélectionner une table.

  6. Dans la boîte de dialogue Sélectionner une table de destination :

    1. Pour Projet, choisissez le projet où la table de destination sera créée.

    2. Pour Ensemble de données, choisissez l'ensemble de données où sera stockée la table.

    3. Dans le champ ID de la table, saisissez un nom de table. Le nom doit être unique dans l'ensemble de données de destination. Le nom de la table peut contenir jusqu'à 1 024 caractères et uniquement les caractères de a à z, A à Z, 0 à 9 ou _ (le trait de soulignement).

    4. Cliquez sur OK.

  7. Dans la section Table de destination, pour Préférence d'écriture, sélectionnez l'une des options suivantes :

    • Écrire si la table est vide : n'écrit les résultats de requête dans la table que si celle-ci est vide.
    • Ajouter à la table : ajoute les résultats de requête à une table existante.
    • Écraser la table : écrase une table existante portant le même nom à l'aide des résultats de requête.
  8. (Facultatif) Dans le champ Zone de traitement, cliquez sur Non spécifiée et sélectionnez l'emplacement de vos données.

  9. Cliquez sur Exécuter la requête. Cette action crée une tâche de requête qui écrit les résultats dans la table spécifiée.

Si vous oubliez de spécifier une table de destination avant d'exécuter la requête, vous pouvez copier la table temporaire dans une table permanente. Pour ce faire, cliquez sur le bouton Enregistrer en tant que table dans la fenêtre des résultats.

CLI

Saisissez la commande bq query et spécifiez l'indicateur --destination_table pour créer une table permanente en fonction des résultats de requête. Spécifiez l'indicateur use_legacy_sql=false pour utiliser la syntaxe SQL standard. Pour écrire les résultats de requête dans une table qui ne se trouve pas dans votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données en respectant le format suivant : [PROJECT_ID]:[DATASET].

Définissez l'indicateur --location sur la valeur correspondant à votre emplacement.

Pour contrôler la disposition en écriture d'une table de destination existante, fournissez l'un des indicateurs facultatifs suivants :

  • --append_table : si la table de destination existe, les résultats de requête y sont ajoutés.
  • --replace : si la table de destination existe, elle est remplacée par les résultats de requête.

    bq --location=[LOCATION] query --destination_table [PROJECT_ID]:[DATASET].[TABLE] --use_legacy_sql=false '[QUERY]'
    

Où :

  • [LOCATION] est le nom de l'emplacement utilisé pour traiter la requête. Cet 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 spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
  • [PROJECT_ID] est l'ID de votre projet.
  • [DATASET] est le nom de l'ensemble de données contenant la table dans laquelle vous écrivez les résultats de requête.
  • [TABLE] est le nom de la table dans laquelle vous écrivez les résultats de requête.
  • [QUERY] est une requête en syntaxe SQL standard.

Si aucun indicateur de disposition en écriture n'est spécifié, le comportement par défaut consiste à écrire les résultats dans la table uniquement si celle-ci est vide. Si la table existe et qu'elle n'est pas vide, l'erreur suivante est renvoyée : BigQuery error in query operation: Error processing job '[PROJECT_ID]:bqjob_123abc456789_00000e1234f_1': Already Exists: Table [PROJECT_ID]:[DATASET].[TABLE].

Exemples :

Saisissez la commande suivante pour écrire les résultats de requête dans une table de destination nommée mytable dans mydataset. L'ensemble de données se trouve dans votre projet par défaut. Aucun indicateur de disposition en écriture n'étant spécifié dans la commande, la table doit être nouvelle ou vide. Sinon, une erreur Already exists est renvoyée. La requête extrait les données de l'ensemble de données public USA Name Data.

bq --location=US query --destination_table mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Saisissez la commande suivante pour utiliser les résultats de requête afin d'écraser une table de destination nommée mytable dans mydataset. L'ensemble de données se trouve dans votre projet par défaut. La commande utilise l'indicateur --replace pour écraser la table de destination.

bq --location=US query --destination_table mydataset.mytable --replace --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Saisissez la commande suivante pour ajouter des résultats de requête à une table de destination nommée mytable dans mydataset. L'ensemble de données se trouve dans myotherproject, et non dans votre projet par défaut. La commande utilise l'indicateur --append pour ajouter les résultats de requête à la table de destination.

bq --location=US query --destination_table myotherproject:mydataset.mytable --append --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

API

Pour enregistrer des résultats de requête dans une table permanente, appelez la méthode jobs.insert, configurez une tâche de type query et incluez une valeur pour la propriété destinationTable. Pour contrôler la disposition en écriture d'une table de destination existante, configurez la propriété writeDisposition.

Spécifiez l'emplacement dans la propriété location de la section jobReference de la ressource de tâche.

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

q := client.Query("SELECT 17 as my_col")
q.Location = "US" // Location must match the dataset(s) referenced in query.
q.QueryConfig.Dst = client.Dataset(destDatasetID).Table(destTableID)
job, err := q.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}
it, err := job.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Java

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

Pour enregistrer des résultats de requête dans une table permanente, définissez la table de destination sur l'identifiant TableId souhaité dans une configuration QueryJobConfiguration.

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // Note that setUseLegacySql is set to false by default
    QueryJobConfiguration.newBuilder(query)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Python

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

Pour enregistrer des résultats de requête dans une table permanente, créez une configuration QueryJobConfig et définissez la destination sur la valeur TableReference souhaitée. Transmettez la configuration de la tâche à la méthode de requête.

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

job_config = bigquery.QueryJobConfig()
# Set the destination table
table_ref = client.dataset(dataset_id).table('your_table_id')
job_config.destination = table_ref
sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""

# Start the query, passing in the extra configuration.
query_job = client.query(
    sql,
    # Location must match that of the dataset(s) referenced in the query
    # and of the destination table.
    location='US',
    job_config=job_config)  # API request - starts the query

query_job.result()  # Waits for the query to finish
print('Query results loaded to table {}'.format(table_ref.path))

Enregistrer des résultats de requête dans Google Sheets

Il n'est pas possible d'enregistrer des résultats de requête dans Google Sheets avec l'outil de ligne de commande ni avec l'API.

Pour enregistrer des résultats de requête dans Google Sheets à l'aide de l'interface utilisateur Web, procédez comme suit :

Console

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

  2. Cliquez sur Saisir une nouvelle requête.

  3. Saisissez une requête SQL valide dans la zone de texte de l'éditeur de requête.

  4. (Facultatif) Pour modifier l'emplacement de traitement, cliquez sur Plus et sélectionnez Paramètres de requête. Dans le champ Zone de traitement, cliquez sur Sélection automatique et choisissez l'emplacement de vos données.

  5. Cliquez sur Exécuter.

  6. Lorsque les résultats sont renvoyés, cliquez sur Enregistrer les résultats et sélectionnez Google Sheets.

  7. Si nécessaire, suivez les instructions vous invitant à vous connecter à votre compte Google et cliquez sur Autoriser afin que BigQuery puisse écrire les données dans votre dossier Google Drive MY Drive (Mon Drive).

    Une fois que vous avez suivi les messages d'invite, vous devez recevoir un e-mail avec pour objet "Outils client BigQuery connectés à votre compte Google". Il contient des informations sur les autorisations que vous avez accordées ainsi que les étapes à suivre pour les révoquer.

  8. Lorsque les résultats sont enregistrés, un message semblable au suivant apparaît sous les résultats de la requête dans l'interface utilisateur Web BigQuery de la console : Saved to Sheets as "results-20190225-103531. Open (Enregistrés dans Sheets sous le nom 20190225-103531. Ouvrir). Cliquez sur le lien dans le message pour afficher vos résultats dans Google Sheets, ou accédez à votre dossier My Drive (Mon Drive) et ouvrez le fichier manuellement.

    Lorsque vous enregistrez les résultats de requête dans Google Sheets, le nom du fichier commence par results-[DATE], où [DATE] correspond à la date du jour au format YYYYMMDD.

UI classique

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

  2. Cliquez sur le bouton Saisir une requête.

  3. Saisissez une requête SQL BigQuery valide dans la zone de texte Nouvelle requête.

  4. Cliquez sur Afficher les options.

  5. (Facultatif) Dans le champ Zone de traitement, cliquez sur Non spécifiée et sélectionnez l'emplacement de vos données.

  6. Cliquez sur Exécuter la requête.

  7. Lorsque les résultats sont renvoyés, cliquez sur le bouton Save to Google Sheets (Enregistrer dans Google Sheets) au-dessus.

    Capture d'écran des boutons "Télécharger" et "Enregistrer"

  8. Si nécessaire, suivez les instructions vous invitant à vous connecter à votre compte Google et cliquez sur Autoriser afin que BigQuery puisse écrire les données dans votre dossier Google Drive MY Drive (Mon Drive).

    Une fois que vous avez suivi les messages d'invite, vous devez recevoir un e-mail avec pour objet "Outils client BigQuery connectés à votre compte Google". Il contient des informations sur les autorisations que vous avez accordées ainsi que les étapes à suivre pour les révoquer.

  9. Lorsque les résultats sont enregistrés, un message semblable au suivant s'affiche au-dessus des résultats de requête dans l'interface utilisateur Web classique de BigQuery : Results saved to Google Sheets. Click to view (Résultats enregistrés dans Google Sheets. Cliquer pour afficher). Cliquez sur le lien dans le message pour afficher vos résultats dans Google Sheets, ou accédez à votre dossier MY Drive (Mon Drive) et ouvrez le fichier manuellement.

    Lorsque vous enregistrez les résultats de requête dans Google Sheets, le nom du fichier commence par results-[DATE], où [DATE] correspond à la date du jour au format YYYYMMDD.

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

Envoyer des commentaires concernant…

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