Exécuter des tâches de requête interactives et par lot

Ce document explique comment exécuter des tâches de requête interactives (à la demande) et par lot.

Autorisations requises

Les tâches sont des actions que BigQuery exécute en votre nom pour charger, exporter, interroger ou copier des données.

Lorsque vous effectuez ces actions à l'aide de Cloud Console, de l'interface utilisateur Web classique de BigQuery ou de la CLI, une ressource de tâche est automatiquement créée, planifiée et exécutée. Vous pouvez également créer une tâche de chargement, d'exportation, de requête ou de copie de manière automatisée. Dans ce cas, BigQuery planifie et exécute la tâche à votre place.

Comme les tâches peuvent durer un certain temps, elles s'exécutent de manière asynchrone, et il est possible d'interroger leur état. Les actions plus courtes (telles que la récupération d'une liste de ressources ou l'obtention de métadonnées) ne sont pas gérées par une ressource de tâche.

Pour exécuter une tâche de requête, vous devez disposer au minimum des autorisations bigquery.jobs.create. Ensuite, pour que cette tâche de requête aboutisse, vous devez également disposer d'un accès aux ensembles de données contenant les tables ou les vues référencées par la requête. Pour plus d'informations sur les contrôles d'accès aux ensembles de données, consultez la page Contrôler l'accès aux ensembles de données.

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

bigquery.user
bigquery.jobUser
bigquery.admin

De plus, lorsqu'un utilisateur possédant les autorisations bigquery.datasets.create crée un ensemble de données, il obtient également le rôle bigquery.dataOwner qui lui permet d'y accéder. L'accès bigquery.dataOwner donne à l'utilisateur la possibilité d'interroger des tables et des vues dans l'ensemble de données.

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

Exécuter des requêtes interactives

Par défaut, BigQuery exécute des tâches de requête interactives (à la demande), ce qui signifie que la requête est exécutée dès que possible. Les requêtes interactives sont comptabilisées dans votre limite de débit simultané et votre limite quotidienne.

Les résultats de requête sont toujours enregistrés dans une table temporaire ou permanente. Vous pouvez choisir d'ajouter les données à une table existante ou de les utiliser pour écraser celle-ci. Vous avez également la possibilité de créer une table s'il n'en existe aucune du même nom.

Pour exécuter une requête interactive qui écrit dans une table temporaire, procédez comme suit :

Console

Ouvrez l'UI Web de BigQuery dans Cloud Console.
Accéder à Cloud Console
Cliquez sur Compose new query (Saisir une nouvelle requête).
Saisissez une requête SQL BigQuery valide dans la zone de texte de l'éditeur de requête.
(Facultatif) Pour modifier la zone de traitement des données, cliquez sur Plus, puis sur Paramètres de requête. Dans le champ Zone de traitement, cliquez sur Sélection automatique et choisissez l'emplacement de vos données. Cliquez ensuite sur Enregistrer pour mettre à jour les paramètres de la requête.
Cliquez sur Exécuter.

Cette action crée une tâche de requête dont les résultats sont écrits dans une table temporaire.

UI classique

Accédez à l'UI Web de BigQuery.
Accéder à l'UI Web de BigQuery
Cliquez sur Saisir une requête.
Saisissez une requête SQL BigQuery valide dans la zone de texte Nouvelle requête.
Cliquez sur Afficher les options.
(Facultatif) Dans le champ Zone de traitement, cliquez sur Non spécifiée et sélectionnez l'emplacement de vos données.
Cliquez sur Exécuter la requête.

Cette action crée une tâche de requête dont les résultats sont écrits dans une table temporaire.

CLI

Saisissez la commande bq query et incluez le texte de votre requête.

(Facultatif) Spécifiez l'option --location en définissant la valeur correspondant à votre emplacement.

Vous pouvez spécifier les options facultatives suivantes. Cette liste comprend certaines des options les plus courantes. Pour obtenir la liste complète des options de la commande query, consultez la section bq query dans la documentation de référence de l'outil de ligne de commande bq.

Spécifiez les options suivantes :

--destination_table pour créer une table permanente à partir des résultats de la requête. Pour écrire les résultats de la 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 selon le format suivant : project_id:dataset. Si --destination_table n'est pas spécifiée, une tâche de requête est générée pour écrire la sortie dans une table (en cache) temporaire.
--append_table pour ajouter les résultats de la requête à une table de destination.
--destination_kms_key pour utiliser une clé Key Management Service afin de chiffrer les données de la table de destination.
--use_legacy_sql=false pour utiliser la syntaxe SQL standard. Vous pouvez définir une syntaxe par défaut pour l'outil de ligne de commande à l'aide du fichier .bigqueryrc.
--label pour appliquer un libellé à la tâche de requête sous la forme clé:valeur. Répétez cette option pour spécifier plusieurs libellés.
--max_rows ou -n pour spécifier le nombre de lignes à afficher dans les résultats de la requête.
--maximum_bytes_billed pour limiter le nombre d'octets facturés pour la requête. Si la requête dépasse la limite, elle échoue (sans frais). Si l'option n'est pas spécifiée, le nombre d'octets facturés est défini sur la valeur par défaut du projet.
--udf_resource pour charger et évaluer un fichier de code à utiliser comme ressource de fonction définie par l'utilisateur. Vous pouvez spécifier un URI Cloud Storage ou le chemin d'accès à un fichier de code local. Répétez cette option pour spécifier plusieurs fichiers.

Saisissez la commande suivante pour exécuter une requête interactive à l'aide de la syntaxe SQL standard :

bq --location=location query \
--use_legacy_sql=false \
'query'

Où :

location est le nom de l'emplacement dans lequel la requête est traitée. L'option --location est facultative. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, vous pouvez définir la valeur de cette option sur asia-northeast1. Vous pouvez définir une valeur par défaut correspondant à l'emplacement en utilisant le fichier .bigqueryrc.
query est une requête en syntaxe SQL standard.

Exemples :

Saisissez la commande suivante pour écrire les résultats de la requête interactive dans une table de destination nommée mytable au sein de l'ensemble de données mydataset. L'ensemble de données se trouve dans votre projet par défaut. La requête extrait les données de l'ensemble de données public USA Name Data.

bq 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 écrire les résultats de la requête interactive dans une table de destination nommée mytable au sein de l'ensemble de données mydataset. Cet ensemble de données se trouve dans le projet myotherproject, et non dans votre projet par défaut. La requête récupère les données d'une table non partitionnée : l'ensemble de données public USA Name Data.

bq query \
--destination_table myotherproject: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'

API

Pour exécuter une requête à l'aide de l'API, insérez une nouvelle tâche, puis définissez la propriété jobs#configuration.query. Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource de tâche.

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 l'exemple ci-dessous, suivez la procédure de configuration pour C# décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery C#.

Afficher sur GitHub Commentaires


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.PollUntilCompleted();
        // Display the results
        foreach (BigQueryRow row in client.GetQueryResults(job.Reference))
        {
            Console.WriteLine($"{row["name"]}");
        }
    }
}

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.

Afficher sur GitHub Commentaires

// 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 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"
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 sur l'API BigQuery Java.

Afficher sur GitHub Commentaires

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig = QueryJobConfiguration.newBuilder(query).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");
}

Node.js

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

Afficher sur GitHub Commentaires

// 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 l'exemple ci-dessous, suivez la procédure de configuration pour PHP décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery PHP.

Afficher sur GitHub Commentaires

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 de Python décrites 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.

Afficher sur GitHub Commentaires

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

query = (
    "SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` "
    'WHERE state = "TX" '
    "LIMIT 100"
)
query_job = client.query(
    query,
    # Location must match that of the dataset(s) referenced in the query.
    location="US",
)  # API request - starts the query

for row in query_job:  # API request - fetches results
    # Row values can be accessed by field name or index
    assert row[0] == row.name == row["name"]
    print(row)

Ruby

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

Afficher sur GitHub Commentaires

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

Exécuter des requêtes par lot

BigQuery propose également des requêtes par lot. Il met en file d'attente chaque requête par lot en votre nom et en lance une dès que des ressources inactives sont disponibles dans le pool de ressources partagées de BigQuery. Cela prend généralement quelques minutes. Si BigQuery n'a pas lancé la requête dans les 24 heures, il redéfinit la priorité de la tâche sur interactive.

Les requêtes par lot ne sont pas comptabilisées dans votre limite de débit simultané, ce qui peut faciliter le lancement de plusieurs requêtes à la fois. Elles utilisent les mêmes ressources que les requêtes interactives (à la demande). Si vous avez opté pour un tarif forfaitaire, les requêtes par lot et les requêtes interactives partagent les emplacements attribués.

Pour exécuter une requête par lot, procédez comme suit :

Console

Ouvrez l'UI Web de BigQuery dans Cloud Console.
Accéder à Cloud Console
Cliquez sur le bouton Compose new query (Saisir une nouvelle requête).
Saisissez une requête SQL valide dans la zone de texte de l'éditeur de requête.
Cliquez sur le bouton More (Plus), puis sur Query settings (Paramètres de la requête).
Sélectionnez l'option Batch (Lot) dans la section Job priority (Priorité de la tâche).
(Facultatif) Dans le champ Zone de traitement, cliquez sur Non spécifiée et sélectionnez l'emplacement de vos données.
Cliquez sur Enregistrer pour mettre à jour les paramètres de la requête.
Cliquez sur Run (Exécuter).

UI classique

Accédez à l'UI Web de BigQuery.
Accéder à l'UI Web de BigQuery
Cliquez sur le bouton Saisir une requête.
Saisissez une requête SQL BigQuery valide dans la zone de texte Nouvelle requête.
Cliquez sur le bouton Afficher les options.
Sélectionnez l'option Par lot dans la section Priorité de la requête.
(Facultatif) Dans le champ Zone de traitement, cliquez sur Non spécifiée et sélectionnez l'emplacement de vos données.
Cliquez sur le bouton Exécuter la requête.

CLI

Saisissez la commande bq query et incluez le texte de votre requête. Spécifiez l'option -- batch pour exécuter une requête par lot.

(Facultatif) Spécifiez l'option --location en définissant la valeur correspondant à votre emplacement.

Spécifiez les options suivantes :

--destination_table pour créer une table permanente à partir des résultats de la requête. Pour écrire les résultats de la 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 selon le format suivant : project_id:dataset. Si --destination_table n'est pas spécifiée, une tâche de requête est générée pour écrire la sortie dans une table (en cache) temporaire.
--append_table pour ajouter les résultats de la requête à une table de destination.
--destination_kms_key pour utiliser une clé Key Management Service afin de chiffrer les données de la table de destination.
--use_legacy_sql=false pour utiliser la syntaxe SQL standard. Vous pouvez définir une syntaxe par défaut pour l'outil de ligne de commande à l'aide du fichier .bigqueryrc.
--label pour appliquer un libellé à la tâche de requête sous la forme clé:valeur. Répétez cette option pour spécifier plusieurs libellés.
--max_rows ou -n pour spécifier le nombre de lignes à afficher dans les résultats de la requête.
--maximum_bytes_billed pour limiter le nombre d'octets facturés pour la requête. Si la requête dépasse la limite, elle échoue (sans frais). Si l'option n'est pas spécifiée, le nombre d'octets facturés est défini sur la valeur par défaut du projet.
--udf_resource pour charger et évaluer un fichier de code à utiliser comme ressource de fonction définie par l'utilisateur. Vous pouvez spécifier un URI Cloud Storage ou le chemin d'accès à un fichier de code local. Répétez cette option pour spécifier plusieurs fichiers.

Saisissez la commande suivante pour exécuter une requête par lot à l'aide de la syntaxe SQL standard :

bq --location=location query \
--batch \
--use_legacy_sql=false \
'query'

Où :

location est le nom de l'emplacement dans lequel la requête est traitée. L'option --location est facultative. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, vous pouvez définir la valeur de cette option sur asia-northeast1. Vous pouvez définir une valeur par défaut correspondant à l'emplacement en utilisant le fichier .bigqueryrc.
query est une requête en syntaxe SQL standard.

Exemples :

Saisissez la commande suivante pour écrire les résultats de la requête par lot dans une table de destination nommée mytable au sein de l'ensemble de données mydataset. L'ensemble de données se trouve dans votre projet par défaut. La requête extrait les données de l'ensemble de données public USA Name Data.

bq query \
--batch \
--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 écrire les résultats de la requête par lot dans une table de destination nommée mytable au sein de l'ensemble de données mydataset. Cet ensemble de données se trouve dans le projet myotherproject, et non dans votre projet par défaut. La requête récupère les données d'une table non partitionnée : l'ensemble de données public USA Name Data.

bq query \
--batch \
--destination_table myotherproject: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'

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 emplacement dans la propriété location de la section jobReference de la ressource de tâche.

Lorsque vous spécifiez les propriétés de la tâche de requête, incluez la propriété configuration.query.priority en définissant sa valeur sur BATCH.

Go

Afficher sur GitHub Commentaires

	// 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")
	// 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.Printf("Job %s in Location %s currently in state: %s\n", job.ID(), job.Location(), state)

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.

Afficher sur GitHub

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    QueryJobConfiguration.newBuilder(query)
        // Run at batch priority, which won't count toward concurrent rate
        // limit.
        .setPriority(QueryJobConfiguration.Priority.BATCH)
        .build();

// Location must match that of the dataset(s) referenced in the query.
JobId jobId = JobId.newBuilder().setRandomJob().setLocation("US").build();
String jobIdString = jobId.getJob();

// API request - starts the query.
bigquery.create(JobInfo.newBuilder(queryConfig).setJobId(jobId).build());

// Check on the progress by getting the job's updated state. Once the state
// is `DONE`, the results are ready.
Job queryJob = bigquery.getJob(
    JobId.newBuilder().setJob(jobIdString).setLocation("US").build());
System.out.printf(
    "Job %s in location %s currently in state: %s%n",
    queryJob.getJobId().getJob(),
    queryJob.getJobId().getLocation(),
    queryJob.getStatus().getState().toString());

Python

Afficher sur GitHub Commentaires

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

job_config = bigquery.QueryJobConfig()
# Run at batch priority, which won't count toward concurrent rate limit.
job_config.priority = bigquery.QueryPriority.BATCH
sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""
# Location must match that of the dataset(s) referenced in the query.
location = "US"

# API request - starts the query
query_job = client.query(sql, location=location, job_config=job_config)

# 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=location
)  # API request - fetches job
print("Job {} is currently in state {}".format(query_job.job_id, query_job.state))

Autorisations requises

Exécuter des requêtes interactives

Console

UI classique

CLI

API

C#

Go

Java

Node.js

PHP

Python

Ruby

Exécuter des requêtes par lot

Console

UI classique

CLI

API

Go

Java

Python

Envoyer des commentaires concernant…