Exécuter une requête

Ce document vous explique comment exécuter une requête dans BigQuery et comprendre la quantité de données que la requête va traiter avant l'exécution en effectuant une simulation.

Requêtes interactives ou par lot

Dans BigQuery, vous pouvez exécuter deux types de requêtes :

Jobs de requête interactives, qui sont des jobs exécutés par BigQuery à la demande
Les jobs de requête par lot, qui sont des jobs que BigQuery attend d'exécuter jusqu'à ce que des ressources de calcul inactives soient disponibles.

Par défaut, BigQuery exécute vos requêtes en tant que jobs de requête interactives, qui sont exécutés dès que possible. BigQuery calcule de manière dynamique la limite de requêtes simultanées en fonction de la disponibilité des ressources et privilégie l'exécution de requêtes interactives simultanées par rapport aux requêtes par lot. Une fois que vous avez atteint la limite de requêtes simultanées, les requêtes supplémentaires attendent dans une file d'attente. Pour en savoir plus, consultez la section Files d'attente de requêtes.

BigQuery enregistre les résultats de la requête dans une table temporaire (par défaut) ou dans une table permanente. Lorsque vous spécifiez une table permanente comme table de destination pour les résultats, vous pouvez choisir d'ajouter ou d'écraser une table existante, ou de créer une table avec un nom unique.

Rôles requis

Pour obtenir les autorisations nécessaires pour exécuter un job de requête, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Utilisateur de job BigQuery (roles/bigquery.jobUser) sur le projet.
Lecteur de données BigQuery (roles/bigquery.dataViewer) sur toutes les tables et vues auxquelles votre requête fait référence. Pour interroger des vues, vous devez également disposer de ce rôle sur toutes les tables et vues sous-jacentes. Si vous utilisez des vues autorisées ou des ensembles de données autorisés, vous n'avez pas besoin d'accéder aux données sources sous-jacentes.

Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Ces rôles prédéfinis contiennent les autorisations requises pour exécuter un job de requête. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour exécuter un job de requête :

bigquery.jobs.create sur le projet
bigquery.tables.getData sur toutes les tables et vues auxquelles votre requête fait référence. Pour interroger des vues, vous devez également disposer de cette autorisation sur toutes les tables et vues sous-jacentes. Si vous utilisez des vues autorisées ou des ensembles de données autorisés, vous n'avez pas besoin d'accéder aux données sources sous-jacentes.

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

Pour plus d'informations sur les autorisations BigQuery, consultez la page Contrôle des accès avec IAM.

Exécuter une requête interactive

Pour exécuter une requête interactive, sélectionnez l'une des options suivantes :

Console

Accédez à la page BigQuery.

Accéder à BigQuery
Cliquez sur Saisir une nouvelle requête.
Dans l'éditeur de requête, saisissez une requête GoogleSQL valide.

Par exemple, interrogez l'ensemble de données public BigQuery usa_names pour déterminer les noms les plus couramment utilisés aux États-Unis entre 1910 et 2013 :
```
SELECT
  name, gender,
  SUM(number) AS total
FROM
  `bigquery-public-data.usa_names.usa_1910_2013`
GROUP BY
  name, gender
ORDER BY
  total DESC
LIMIT
  10;
```
Vous pouvez également spécifier la table de destination et l'emplacement des résultats de la requête :
1. Dans l'éditeur de requête, cliquez sur Plus, puis sur Paramètres de requête.
2. Dans la section Destination, cochez la case Définir une table de destination pour les résultats de la requête.
3. Dans le champ Ensemble de données, saisissez le nom d'un ensemble de données existant pour la table de destination, par exemple myProject.myDataset.
4. Dans le champ ID de la table, saisissez un nom pour la table de destination, par exemple myTable.
5. Si la table de destination est une table existante, choisissez d'ajouter ou d'écraser la table avec les résultats de la requête dans la préférence d'écriture pour la table de destination.
  
  Si la table de destination est une nouvelle table, BigQuery la crée lorsque vous exécutez votre requête.
6. Dans la section Paramètres supplémentaires, cliquez sur le menu Emplacement des données, puis sélectionnez une option.
  
  Dans cet exemple, l'ensemble de données usa_names est stocké dans l'emplacement multirégional États-Unis. Si vous spécifiez une table de destination pour cette requête, l'ensemble de données contenant la table de destination doit également se trouver dans l'emplacement multirégional des États-Unis. Vous ne pouvez pas interroger un ensemble de données dans un emplacement spécifique et écrire les résultats dans une table de destination dont l'emplacement est différent.
7. Cliquez sur Enregistrer.
Cliquez sur Exécuter.

Si vous ne spécifiez pas de table de destination, le job de requête écrit la sortie dans une table (en cache) temporaire.
Facultatif : Pour trier les résultats de la requête par colonne, cliquez sur Ouvrir le menu de tri à côté du nom de la colonne et sélectionnez un ordre de tri. Si le nombre d'octets estimés pris en compte pour le tri est supérieur à zéro, il s'affiche en haut du menu.
Facultatif : Pour visualiser les résultats de votre requête, accédez à l'onglet Graphique. Vous pouvez faire un zoom avant ou arrière sur le graphique, le télécharger au format PNG ou activer/désactiver la visibilité de la légende.

Dans le volet Configuration du graphique, vous pouvez modifier le type de graphique (à lignes, en courbes ou à barres) et configurer les mesures et les dimensions du graphique. Les champs de ce volet sont préremplis avec la configuration initiale déduite du schéma de la table de destination de la requête. La configuration est conservée entre les exécutions de requêtes suivantes dans le même éditeur de requête. Les dimensions acceptent les types de données INTEGER, INT64, FLOAT, FLOAT64, NUMERIC, BIGNUMERIC, TIMESTAMP, DATE, DATETIME, TIME et STRING, tandis que les mesures acceptent les types de données INTEGER, INT64, FLOAT, FLOAT64, NUMERIC et BIGNUMERIC.

bq

Dans la console Google Cloud, activez Cloud Shell.

Activer Cloud Shell

En bas de la fenêtre de la console Google Cloud, une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.
Utilisez la commande bq query. Dans l'exemple suivant, l'option --use_legacy_sql=false vous permet d'utiliser la syntaxe GoogleSQL.
```
bq query \
    --use_legacy_sql=false \
    'QUERY'
```
Remplacez QUERY par une requête GoogleSQL valide. Par exemple, interrogez l'ensemble de données public BigQuery usa_names pour déterminer les noms les plus couramment utilisés aux États-Unis entre 1910 et 2013 :
```
bq query \
    --use_legacy_sql=false \
    'SELECT
      name, gender,
      SUM(number) AS total
    FROM
      `bigquery-public-data.usa_names.usa_1910_2013`
    GROUP BY
      name, gender
    ORDER BY
      total DESC
    LIMIT
      10;'
```
Le job de requête écrit la sortie dans une table (en cache) temporaire.

Sinon, vous pouvez spécifier la table de destination et l'emplacement pour les résultats de la requête. Pour écrire les résultats dans une table existante, ajoutez l'option appropriée afin d'ajouter (--append_table=true) ou d'écraser (--replace=true) la table.
```
bq query \
    --location=LOCATION \
    --destination_table=TABLE \
    --use_legacy_sql=false \
    'QUERY'
```
Remplacez les éléments suivants :
- LOCATION : région ou emplacement multirégional de la table de destination, par exemple US
  
  Dans cet exemple, l'ensemble de données usa_names est stocké dans l'emplacement multirégional États-Unis. Si vous spécifiez une table de destination pour cette requête, l'ensemble de données contenant la table de destination doit également se trouver dans l'emplacement multirégional des États-Unis. Vous ne pouvez pas interroger un ensemble de données dans un emplacement spécifique et écrire les résultats dans une table dont l'emplacement est différent.
  
  Vous pouvez définir une valeur par défaut correspondant à l'emplacement en utilisant le fichier .bigqueryrc.
- TABLE : nom de la table de destination, par exemple myDataset.myTable.
  
  Si la table de destination est une nouvelle table, BigQuery la crée lorsque vous exécutez votre requête. Cependant, vous devez spécifier un ensemble de données existant.
  
  Si la table ne se trouve pas dans votre projet actuel, ajoutez l'ID du projet Google Cloud en utilisant le format PROJECT_ID:DATASET.TABLE (par exemple, myProject:myDataset.myTable). Si --destination_table n'est pas spécifiée, un job de requête est généré pour écrire la sortie dans une table temporaire.

API

Pour exécuter une requête à l'aide de l'API, insérez une nouvelle tâche, puis définissez la propriété de configuration de tâche query. (Facultatif) Spécifiez votre locationemplacementjobReference dans la propriété de la section de la ressource de job.

Interrogez les résultats en appelant getQueryResults jusqu'à ce que jobComplete ait la valeur true. Recherchez les erreurs et les avertissements dans la liste errors.

C#

Avant d'essayer cet exemple, suivez les instructions de configuration pour C# 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 C#.

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.


using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryQuery
{
    public void Query(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        string query = @"
            SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013`
            WHERE state = 'TX'
            LIMIT 100";
        BigQueryJob job = client.CreateQueryJob(
            sql: query,
            parameters: null,
            options: new QueryOptions { UseQueryCache = false });
        // Wait for the job to complete.
        job = job.PollUntilCompleted().ThrowOnAnyError();
        // Display the results
        foreach (BigQueryRow row in client.GetQueryResults(job.Reference))
        {
            Console.WriteLine($"{row["name"]}");
        }
    }
}

Go

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.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// queryBasic demonstrates issuing a query and reading results.
func queryBasic(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	q := client.Query(
		"SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " +
			"WHERE state = \"TX\" " +
			"LIMIT 100")
	// Location must match that of the dataset(s) referenced in the query.
	q.Location = "US"
	// Run the query and print results when the query job is completed.
	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.Fprintln(w, row)
	}
	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.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;

public class SimpleQuery {

  public static void runSimpleQuery() {
    // TODO(developer): Replace this query before running the sample.
    String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
    simpleQuery(query);
  }

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

      // Create the query job.
      QueryJobConfiguration queryConfig = QueryJobConfiguration.newBuilder(query).build();

      // Execute the query.
      TableResult result = bigquery.query(queryConfig);

      // Print the results.
      result.iterateAll().forEach(rows -> rows.forEach(row -> System.out.println(row.getValue())));

      System.out.println("Query ran successfully");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query did not run \n" + e.toString());
    }
  }
}

Pour exécuter une requête avec un proxy, consultez la section Configurer un proxy.

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.

// Import the Google Cloud client library using default credentials
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();
async function query() {
  // Queries the U.S. given names dataset for the state of Texas.

  const query = `SELECT name
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 100`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);
  console.log(`Job ${job.id} started.`);

  // Wait for the query to finish
  const [rows] = await job.getQueryResults();

  // Print the results
  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

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.

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

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $query = 'SELECT id, view_count FROM `bigquery-public-data.stackoverflow.posts_questions`';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$jobConfig = $bigQuery->query($query);
$job = $bigQuery->startQuery($jobConfig);

$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);
    }
});
$queryResults = $job->queryResults();

$i = 0;
foreach ($queryResults as $row) {
    printf('--- Row %s ---' . PHP_EOL, ++$i);
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, json_encode($value));
    }
}
printf('Found %s row(s)' . PHP_EOL, $i);

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.

from google.cloud import bigquery

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

query = """
    SELECT name, SUM(number) as total_people
    FROM `bigquery-public-data.usa_names.usa_1910_2013`
    WHERE state = 'TX'
    GROUP BY name, state
    ORDER BY total_people DESC
    LIMIT 20
"""
rows = client.query_and_wait(query)  # Make an API request.

print("The query data:")
for row in rows:
    # Row values can be accessed by field name or index.
    print("name={}, count={}".format(row[0], row["total_people"]))

Ruby

Avant d'essayer cet exemple, suivez les instructions de configuration pour Ruby 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 Ruby.

require "google/cloud/bigquery"

def query
  bigquery = Google::Cloud::Bigquery.new
  sql = "SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " \
        "WHERE state = 'TX' " \
        "LIMIT 100"

  # Location must match that of the dataset(s) referenced in the query.
  results = bigquery.query sql do |config|
    config.location = "US"
  end

  results.each do |row|
    puts row.inspect
  end
end

Pour en savoir plus, consultez la section Requêtes interactives ou par lot.

Exécuter une requête par lot

Pour exécuter une requête par lot, sélectionnez l'une des options suivantes :

Console

Accédez à la page BigQuery.

Accéder à BigQuery
Cliquez sur Saisir une nouvelle requête.
Dans l'éditeur de requête, saisissez une requête GoogleSQL valide.

Par exemple, interrogez l'ensemble de données public BigQuery usa_names pour déterminer les noms les plus couramment utilisés aux États-Unis entre 1910 et 2013 :
```
SELECT
  name, gender,
  SUM(number) AS total
FROM
  `bigquery-public-data.usa_names.usa_1910_2013`
GROUP BY
  name, gender
ORDER BY
  total DESC
LIMIT
  10;
```
Cliquez sur Plus, puis sur Paramètres de requête.
Dans la section Gestion des ressources, sélectionnez Par lot.
Vous pouvez également spécifier la table de destination et l'emplacement des résultats de la requête :
1. Dans la section Destination, cochez la case Définir une table de destination pour les résultats de la requête.
2. Dans le champ Ensemble de données, saisissez le nom d'un ensemble de données existant pour la table de destination, par exemple myProject.myDataset.
3. Dans le champ ID de la table, saisissez un nom pour la table de destination, par exemple myTable.
4. Si la table de destination est une table existante, choisissez d'ajouter ou d'écraser la table avec les résultats de la requête dans la préférence d'écriture pour la table de destination.
  
  Si la table de destination est une nouvelle table, BigQuery la crée lorsque vous exécutez votre requête.
5. Dans la section Paramètres supplémentaires, cliquez sur le menu Emplacement des données, puis sélectionnez une option.
  
  Dans cet exemple, l'ensemble de données usa_names est stocké dans l'emplacement multirégional États-Unis. Si vous spécifiez une table de destination pour cette requête, l'ensemble de données contenant la table de destination doit également se trouver dans l'emplacement multirégional des États-Unis. Vous ne pouvez pas interroger un ensemble de données dans un emplacement spécifique et écrire les résultats dans une table de destination dont l'emplacement est différent.
Cliquez sur Enregistrer.
Cliquez sur Exécuter.

Si vous ne spécifiez pas de table de destination, le job de requête écrit la sortie dans une table (en cache) temporaire.
Facultatif : Pour trier les résultats de la requête par colonne, cliquez sur Ouvrir le menu de tri à côté du nom de la colonne et sélectionnez un ordre de tri. Si le nombre d'octets estimés pris en compte pour le tri est supérieur à zéro, il s'affiche en haut du menu.
Facultatif : Pour visualiser les résultats de votre requête, accédez à l'onglet Graphique. Vous pouvez faire un zoom avant ou arrière sur le graphique, le télécharger au format PNG ou activer/désactiver la visibilité de la légende.

Dans le volet Configuration du graphique, vous pouvez modifier le type de graphique (à lignes, en courbes ou à barres) et configurer les mesures et les dimensions du graphique. Les champs de ce volet sont préremplis avec la configuration initiale déduite du schéma de la table de destination de la requête. La configuration est conservée entre les exécutions de requêtes suivantes dans le même éditeur de requête. Les dimensions acceptent les types de données INTEGER, INT64, FLOAT, FLOAT64, NUMERIC, BIGNUMERIC, TIMESTAMP, DATE, DATETIME, TIME et STRING, tandis que les mesures acceptent les types de données INTEGER, INT64, FLOAT, FLOAT64, NUMERIC et BIGNUMERIC.

bq

Dans la console Google Cloud, activez Cloud Shell.

Activer Cloud Shell

En bas de la fenêtre de la console Google Cloud, une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.
Exécutez la commande bq query, puis spécifiez l'option --batch. Dans l'exemple suivant, l'option --use_legacy_sql=false vous permet d'utiliser la syntaxe GoogleSQL.
```
bq query \
    --batch \
    --use_legacy_sql=false \
    'QUERY'
```
Remplacez QUERY par une requête GoogleSQL valide. Par exemple, interrogez l'ensemble de données public BigQuery usa_names pour déterminer les noms les plus couramment utilisés aux États-Unis entre 1910 et 2013 :
```
bq query \
    --batch \
    --use_legacy_sql=false \
    'SELECT
      name, gender,
      SUM(number) AS total
    FROM
      `bigquery-public-data.usa_names.usa_1910_2013`
    GROUP BY
      name, gender
    ORDER BY
      total DESC
    LIMIT
      10;'
```
Le job de requête écrit la sortie dans une table (en cache) temporaire.

Sinon, vous pouvez spécifier la table de destination et l'emplacement pour les résultats de la requête. Pour écrire les résultats dans une table existante, ajoutez l'option appropriée afin d'ajouter (--append_table=true) ou d'écraser (--replace=true) la table.
```
bq query \
    --batch \
    --location=LOCATION \
    --destination_table=TABLE \
    --use_legacy_sql=false \
    'QUERY'
```
Remplacez les éléments suivants :
- LOCATION : région ou emplacement multirégional de la table de destination, par exemple US
  
  Dans cet exemple, l'ensemble de données usa_names est stocké dans l'emplacement multirégional États-Unis. Si vous spécifiez une table de destination pour cette requête, l'ensemble de données contenant la table de destination doit également se trouver dans l'emplacement multirégional des États-Unis. Vous ne pouvez pas interroger un ensemble de données dans un emplacement spécifique et écrire les résultats dans une table dont l'emplacement est différent.
  
  Vous pouvez définir une valeur par défaut correspondant à l'emplacement en utilisant le fichier .bigqueryrc.
- TABLE : nom de la table de destination, par exemple myDataset.myTable.
  
  Si la table de destination est une nouvelle table, BigQuery la crée lorsque vous exécutez votre requête. Cependant, vous devez spécifier un ensemble de données existant.
  
  Si la table ne se trouve pas dans votre projet actuel, ajoutez l'ID du projet Google Cloud en utilisant le format PROJECT_ID:DATASET.TABLE (par exemple, myProject:myDataset.myTable). Si --destination_table n'est pas spécifiée, un job de requête est généré pour écrire la sortie dans une table temporaire.

API

Lorsque vous spécifiez les propriétés du job de requête, incluez la propriété configuration.query.priority et définissez la valeur sur BATCH.

Interrogez les résultats en appelant getQueryResults jusqu'à ce que jobComplete ait la valeur true. Recherchez les erreurs et les avertissements dans la liste errors.

Go

import (
	"context"
	"fmt"
	"io"
	"time"

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

// queryBatch demonstrates issuing a query job using batch priority.
func queryBatch(w io.Writer, projectID, dstDatasetID, dstTableID string) error {
	// projectID := "my-project-id"
	// dstDatasetID := "mydataset"
	// dstTableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	// Build an aggregate table.
	q := client.Query(`
		SELECT
  			corpus,
  			SUM(word_count) as total_words,
  			COUNT(1) as unique_words
		FROM ` + "`bigquery-public-data.samples.shakespeare`" + `
		GROUP BY corpus;`)
	q.Priority = bigquery.BatchPriority
	q.QueryConfig.Dst = client.Dataset(dstDatasetID).Table(dstTableID)

	// Start the job.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	// Job is started and will progress without interaction.
	// To simulate other work being done, sleep a few seconds.
	time.Sleep(5 * time.Second)
	status, err := job.Status(ctx)
	if err != nil {
		return err
	}

	state := "Unknown"
	switch status.State {
	case bigquery.Pending:
		state = "Pending"
	case bigquery.Running:
		state = "Running"
	case bigquery.Done:
		state = "Done"
	}
	// You can continue to monitor job progress until it reaches
	// the Done state by polling periodically.  In this example,
	// we print the latest status.
	fmt.Fprintf(w, "Job %s in Location %s currently in state: %s\n", job.ID(), job.Location(), state)

	return nil

}

Java

Pour exécuter une requête par lot, définissez la priorité de la requête sur QueryJobConfiguration.Priority.BATCH lors de la création d'une configuration QueryJobConfiguration.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;

// Sample to query batch in a table
public class QueryBatch {

  public static void runQueryBatch() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String query =
        "SELECT corpus"
            + " FROM `"
            + projectId
            + "."
            + datasetName
            + "."
            + tableName
            + " GROUP BY corpus;";
    queryBatch(query);
  }

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

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              // Run at batch priority, which won't count toward concurrent rate limit.
              .setPriority(QueryJobConfiguration.Priority.BATCH)
              .build();

      TableResult results = bigquery.query(queryConfig);

      results
          .iterateAll()
          .forEach(row -> row.forEach(val -> System.out.printf("%s,", val.toString())));

      System.out.println("Query batch performed successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query batch not performed \n" + e.toString());
    }
  }
}

Node.js

// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function queryBatch() {
  // Runs a query at batch priority.

  // Create query job configuration. For all options, see
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfigurationquery
  const queryJobConfig = {
    query: `SELECT corpus
            FROM \`bigquery-public-data.samples.shakespeare\`
            LIMIT 10`,
    useLegacySql: false,
    priority: 'BATCH',
  };

  // Create job configuration. For all options, see
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfiguration
  const jobConfig = {
    // Specify a job configuration to set optional job resource properties.
    configuration: {
      query: queryJobConfig,
    },
  };

  // Make API request.
  const [job] = await bigquery.createJob(jobConfig);

  const jobId = job.metadata.id;
  const state = job.metadata.status.state;
  console.log(`Job ${jobId} is currently in state ${state}`);
}

Python

from google.cloud import bigquery

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

job_config = bigquery.QueryJobConfig(
    # Run at batch priority, which won't count toward concurrent rate limit.
    priority=bigquery.QueryPriority.BATCH
)

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

# Check on the progress by getting the job's updated state. Once the state
# is `DONE`, the results are ready.
query_job = client.get_job(
    query_job.job_id, location=query_job.location
)  # Make an API request.

print("Job {} is currently in state {}".format(query_job.job_id, query_job.state))

Pour en savoir plus, consultez la section Requêtes interactives ou par lot.

Quotas

Pour en savoir plus sur les quotas concernant les requêtes interactives et par lot, consultez la page Jobs de requête.

Afficher le nombre de requêtes interactives et par lot

Vous pouvez afficher le nombre de requêtes interactives et par lot à l'aide de la vue INFORMATION_SCHEMA.JOBS_BY_PROJECT. L'exemple suivant utilise la vue INFORMATION_SCHEMA.JOBS_BY_PROJECT pour obtenir le nombre de requêtes interactives et par lot exécutées au cours des sept dernières heures :

SELECT
  priority,
  COUNT(*) active_jobs,
FROM
  `region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE
  creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 hour)
  AND end_time IS NULL
  AND job_type = 'QUERY'
GROUP BY priority

La vue INFORMATION_SCHEMA.JOBS_BY_PROJECT utilise le champ priority pour indiquer si une requête est INTERACTIVE ou BATCH. Pour en savoir plus, consultez la section Schéma.

Effectuer une simulation

Une simulation de BigQuery fournit les informations suivantes :

Estimation des frais en mode à la demande
Validation de votre requête
Taille et complexité approximatives de votre requête en mode de capacité

Les simulations n'utilisent pas d'emplacements de requête, et leur exécution ne vous est pas facturée. L'estimation renvoyée par la simulation vous permettra de calculer les coûts de requête dans le simulateur de coût.

Effectuer des simulations

Pour effectuer une simulation, procédez comme suit :

Console

Accédez à la page BigQuery.

Accéder à BigQuery
Saisissez votre requête dans l'Éditeur de requête.

Si la requête est valide, une coche apparaît automatiquement avec la quantité de données que la requête va traiter. Si la requête n'est pas valide, un point d'exclamation apparaît avec un message d'erreur.

bq

Saisissez une requête semblable à celle-ci à l'aide de l'option --dry_run.

bq query \
--use_legacy_sql=false \
--dry_run \
'SELECT
   COUNTRY,
   AIRPORT,
   IATA
 FROM
   `project_id`.dataset.airports
 LIMIT
   1000'

Pour une requête valide, la commande génère la réponse suivante :

Query successfully validated. Assuming the tables are not modified,
running this query will process 10918 bytes of data.

API

Pour effectuer une simulation avec l'API, envoyez une tâche de requête avec la valeur dryRun définie sur true dans le type JobConfiguration.

Go

import (
	"context"
	"fmt"
	"io"

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

// queryDryRun demonstrates issuing a dry run query to validate query structure and
// provide an estimate of the bytes scanned.
func queryDryRun(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	q := client.Query(`
	SELECT
		name,
		COUNT(*) as name_count
	FROM ` + "`bigquery-public-data.usa_names.usa_1910_2013`" + `
	WHERE state = 'WA'
	GROUP BY name`)
	q.DryRun = true
	// Location must match that of the dataset(s) referenced in the query.
	q.Location = "US"

	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	// Dry run is not asynchronous, so get the latest status and statistics.
	status := job.LastStatus()
	if err := status.Err(); err != nil {
		return err
	}
	fmt.Fprintf(w, "This query will process %d bytes\n", status.Statistics.TotalBytesProcessed)
	return nil
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobStatistics;
import com.google.cloud.bigquery.QueryJobConfiguration;

// Sample to run dry query on the table
public class QueryDryRun {

  public static void runQueryDryRun() {
    String query =
        "SELECT name, COUNT(*) as name_count "
            + "FROM `bigquery-public-data.usa_names.usa_1910_2013` "
            + "WHERE state = 'WA' "
            + "GROUP BY name";
    queryDryRun(query);
  }

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

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query).setDryRun(true).setUseQueryCache(false).build();

      Job job = bigquery.create(JobInfo.of(queryConfig));
      JobStatistics.QueryStatistics statistics = job.getStatistics();

      System.out.println(
          "Query dry run performed successfully." + statistics.getTotalBytesProcessed());
    } catch (BigQueryException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

Node.js

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

async function queryDryRun() {
  // Runs a dry query of the U.S. given names dataset for the state of Texas.

  const query = `SELECT name
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 100`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    dryRun: true,
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);

  // Print the status and statistics
  console.log('Status:');
  console.log(job.metadata.status);
  console.log('\nJob Statistics:');
  console.log(job.metadata.statistics);
}

PHP

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $query = 'SELECT id, view_count FROM `bigquery-public-data.stackoverflow.posts_questions`';

// Construct a BigQuery client object.
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);

// Set job configs
$jobConfig = $bigQuery->query($query);
$jobConfig->useQueryCache(false);
$jobConfig->dryRun(true);

// Extract query results
$queryJob = $bigQuery->startJob($jobConfig);
$info = $queryJob->info();

printf('This query will process %s bytes' . PHP_EOL, $info['statistics']['totalBytesProcessed']);

Python

Définissez la propriété QueryJobConfig.dry_run sur True. La méthode Client.query() renvoie toujours une tâche QueryJob terminée lorsque vous lui transmettez une configuration de requête simulée.

from google.cloud import bigquery

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

job_config = bigquery.QueryJobConfig(dry_run=True, use_query_cache=False)

# Start the query, passing in the extra configuration.
query_job = client.query(
    (
        "SELECT name, COUNT(*) as name_count "
        "FROM `bigquery-public-data.usa_names.usa_1910_2013` "
        "WHERE state = 'WA' "
        "GROUP BY name"
    ),
    job_config=job_config,
)  # Make an API request.

# A dry run query completes immediately.
print("This query will process {} bytes.".format(query_job.total_bytes_processed))

Étapes suivantes

Apprenez à gérer les jobs de requête.
Apprenez à afficher l'historique des requêtes.
Découvrez comment enregistrer et partager des requêtes.
Apprenez-en plus sur les files d'attente de requêtes.