Esegui una query

BigQuery ti consente di eseguire query immediatamente (in modo interattivo), in batch o in modo continuo, a seconda del tuo caso d'uso. Per convalidare la sintassi SQL e stimare la quantità di dati elaborati dalla query per controllare meglio i costi, puoi eseguire un dry run.

Tipi di query

Puoi eseguire query sui dati BigQuery utilizzando uno dei seguenti tipi di job di query:

• Job di query interattivi. Per impostazione predefinita, BigQuery esegue le query come job di query interattive, che devono essere eseguiti il più rapidamente possibile.

• Job di query batch. Le query batch hanno una priorità inferiore rispetto alle query interattive. Quando un progetto o una prenotazione utilizza tutte le risorse di calcolo disponibili, è più probabile che le query batch vengano messe in coda e rimangano in coda. Dopo l'avvio, una query batch viene eseguita come una query interattiva. Per saperne di più, consulta Code di query.

• Job di query continue. Con questi job, la query viene eseguita continuamente, consentendoti di analizzare i dati in entrata in BigQuery in tempo reale e poi scrivere i risultati in una tabella BigQuery o esportarli in Bigtable o Pub/Sub. Puoi utilizzare questa funzionalità per eseguire attività urgenti, come la creazione e l'applicazione immediata di insight, l'applicazione dell'inferenza di machine learning (ML) in tempo reale e la creazione di pipeline di dati basate su eventi.

Puoi eseguire job di query utilizzando i seguenti metodi:

• Crea ed esegui una query nella consoleGoogle Cloud .
• Esegui il comando bq query nello strumento a riga di comando bq.
• Chiama in modo programmatico il metodo jobs.query o jobs.insert nell'API REST di BigQuery.
• Utilizza le librerie client di BigQuery.

BigQuery salva i risultati delle query in una tabella temporanea (impostazione predefinita) o in una tabella permanente. Quando specifichi una tabella permanente come tabella di destinazione per i risultati, puoi scegliere se aggiungere o sovrascrivere una tabella esistente o creare una nuova tabella con un nome univoco.

Nota: se esegui query sui dati di un progetto per i dati archiviati in un progetto diverso, il progetto che esegue la query viene fatturato per il job di query, mentre il progetto che archivia i dati viene fatturato per la quantità di dati archiviati in BigQuery.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per eseguire un job di query, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Utente job BigQuery (roles/bigquery.jobUser) sul progetto.
• BigQuery Data Viewer (roles/bigquery.dataViewer) su tutte le tabelle e le viste a cui fa riferimento la query. Per eseguire query sulle viste, devi disporre di questo ruolo anche su tutte le tabelle e le viste sottostanti. Se utilizzi viste autorizzate o set di dati autorizzati, non hai bisogno di accedere ai dati di origine sottostanti.

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per eseguire un job di query. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per eseguire un job di query sono necessarie le seguenti autorizzazioni:

• bigquery.jobs.create sul progetto da cui viene eseguita la query, indipendentemente da dove sono archiviati i dati.
• bigquery.tables.getData su tutte le tabelle e le viste a cui fa riferimento la query. Per eseguire query sulle viste, devi disporre di questa autorizzazione anche su tutte le tabelle e le viste sottostanti. Se utilizzi viste autorizzate o set di dati autorizzati, non hai bisogno di accedere ai dati di origine sottostanti.

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Risoluzione dei problemi

Access Denied: Project [project_id]: User does not have bigquery.jobs.create
permission in project [project_id].

Questo errore si verifica quando un'entità non dispone dell'autorizzazione per creare job di query nel progetto.

Risoluzione: un amministratore deve concederti l'autorizzazione bigquery.jobs.create per il progetto su cui stai eseguendo la query. Questa autorizzazione è necessaria in aggiunta a qualsiasi autorizzazione richiesta per accedere ai dati oggetto della query.

Per saperne di più sulle autorizzazioni di BigQuery, consulta Controllo dell'accesso con IAM.

Esegui una query interattiva

Per eseguire una query interattiva, seleziona una delle seguenti opzioni:

Console

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Fai clic su Query SQL.

3. Nell'editor di query, inserisci una query GoogleSQL valida.

   Ad esempio, esegui una query sul set di dati pubblico BigQuery usa_names per determinare i nomi più comuni negli Stati Uniti tra gli anni 1910 e 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;
   

   In alternativa, puoi utilizzare il riquadro Riferimento per creare nuove query.

4. (Facoltativo) Per visualizzare automaticamente i suggerimenti di codice quando digiti una query, fai clic su Strumenti > Completamento automatico basato sul parser. Se non hai bisogno dei suggerimenti di completamento automatico, deseleziona Completamento automatico basato sul parser. In questo modo vengono disattivati anche i suggerimenti di compilazione automatica del nome del progetto.

5. (Facoltativo) Per selezionare altre impostazioni di query, fai clic su Modifica > Impostazioni query.

6. Fai clic su Esegui.

   Se non specifichi una tabella di destinazione, il job di query scrive l'output in una tabella temporanea (cache).

   Ora puoi esplorare i risultati della query nella scheda Risultati del riquadro Risultati delle query.

7. (Facoltativo) Per ordinare i risultati della query per colonna, fai clic su Apri menu di ordinamento accanto al nome della colonna e seleziona un ordinamento. Se i byte stimati elaborati per l'ordinamento sono maggiori di zero, il numero di byte viene visualizzato nella parte superiore del menu.

8. (Facoltativo) Per visualizzare la visualizzazione dei risultati della query, vai alla scheda Visualizzazione. Puoi aumentare o diminuire lo zoom del grafico, scaricarlo come file PNG o attivare/disattivare la visibilità della legenda.

   Nel riquadro Configurazione della visualizzazione, puoi modificare il tipo di visualizzazione e configurare le misure e le dimensioni della visualizzazione. I campi di questo riquadro sono precompilati con la configurazione iniziale dedotta dallo schema della tabella di destinazione della query. La configurazione viene conservata tra le esecuzioni delle query successive nello stesso editor di query.

   Per le visualizzazioni A linee, A barre o A dispersione, le dimensioni supportate sono i tipi di dati INT64, FLOAT64, NUMERIC, BIGNUMERIC, TIMESTAMP, DATE, DATETIME, TIME e STRING, mentre le misure supportate sono i tipi di dati INT64, FLOAT64, NUMERIC e BIGNUMERIC.

   Se i risultati della query includono il tipo GEOGRAPHY, Mappa è il tipo di visualizzazione predefinito, che ti consente di visualizzare i risultati su una mappa interattiva.

9. (Facoltativo) Nella scheda JSON, puoi esplorare i risultati della query nel formato JSON, dove la chiave è il nome della colonna e il valore è il risultato per quella colonna.

bq

1. Nella console Google Cloud , attiva Cloud Shell.

   Attiva Cloud Shell

   Nella parte inferiore della console Google Cloud , viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

2. Utilizza il comando bq query. Nell'esempio seguente, il flag --use_legacy_sql=false consente di utilizzare la sintassi GoogleSQL.

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

   Sostituisci QUERY con una query GoogleSQL valida. Ad esempio, esegui una query sul set di dati pubblico BigQuery usa_names per determinare i nomi più comuni negli Stati Uniti tra gli anni 1910 e 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;'
   

   Il job di query scrive l'output in una tabella temporanea (cache).

   Se vuoi, puoi specificare la tabella di destinazione e la località per i risultati della query. Per scrivere i risultati in una tabella esistente, includi il flag appropriato per aggiungere (--append_table=true) o sovrascrivere (--replace=true) la tabella.

   bq query \
       --location=LOCATION \
       --destination_table=TABLE \
       --use_legacy_sql=false \
       'QUERY'

   Sostituisci quanto segue:

   • LOCATION: la regione o la multiregione per la tabella di destinazione, ad esempio US

     In questo esempio, il set di dati usa_names è archiviato nella località multiregionale degli Stati Uniti. Se specifichi una tabella di destinazione per questa query, anche il set di dati che contiene la tabella di destinazione deve trovarsi nella località multiregionale degli Stati Uniti. Non puoi eseguire query su un set di dati in una località e scrivere i risultati in una tabella in un'altra località.

     Puoi impostare un valore predefinito per la località utilizzando il file.bigqueryrc.

   • TABLE: un nome per la tabella di destinazione, ad esempio myDataset.myTable

     Se la tabella di destinazione è una nuova tabella, BigQuery la crea quando esegui la query. Tuttavia, devi specificare un set di dati esistente.

     Se la tabella non si trova nel progetto corrente, aggiungi l'ID progettoGoogle Cloud utilizzando il formatoPROJECT_ID:DATASET.TABLE, ad esempiomyProject:myDataset.myTable. Se --destination_table non è specificato, viene generato un job di query che scrive l'output in una tabella temporanea.

Terraform

Utilizza la risorsa google_bigquery_job.

Nota: per creare oggetti BigQuery utilizzando Terraform, devi attivare l'API Cloud Resource Manager.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

L'esempio seguente esegue una query. Puoi recuperare i risultati della query visualizzando i dettagli del job:

# Generate a unique job ID.
resource "random_string" "job_id" {
  lower   = true
  length  = 16
  special = false

  keepers = {
    uuid = uuid()
  }
}

# Create a query using the generated job ID.
resource "google_bigquery_job" "my_query_job" {
  job_id = random_string.job_id.id

  query {
    query = "SELECT name, SUM(number) AS total FROM `bigquery-public-data.usa_names.usa_1910_2013` GROUP BY name ORDER BY total DESC LIMIT 100;"
  }
}

Per applicare la configurazione Terraform in un progetto Google Cloud , completa i passaggi descritti nelle sezioni seguenti.

Prepara Cloud Shell

1. Avvia Cloud Shell.

2. Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.

   Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione Terraform deve avere la propria directory (chiamata anche modulo principale).

1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

   Copia il codice campione nel file main.tf appena creato.

   Facoltativamente, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
4. Salva le modifiche.
5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.

   terraform init

   Facoltativamente, per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade:

   terraform init -upgrade

Applica le modifiche

1. Esamina la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative:

   terraform plan

   Apporta le correzioni necessarie alla configurazione.

2. Applica la configurazione Terraform eseguendo il comando seguente e inserendo yes al prompt:

   terraform apply

   Attendi che Terraform visualizzi il messaggio "Apply complete!".

3. Apri il tuo progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud , vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

Nota: gli esempi di Terraform in genere presuppongono che le API richieste siano abilitate nel tuo progetto Google Cloud .

API

Per eseguire una query utilizzando l'API, inserisci un nuovo job e compila la proprietà di configurazione del job query. Facoltativamente, specifica la tua località nella proprietà location nella sezione jobReference della risorsa job.

Esegui il polling dei risultati chiamando getQueryResults. Esegui il polling finché jobComplete non è uguale a true. Controlla la presenza di errori e avvisi nell'elenco errors.

C#

Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery C#.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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"]}");
        }
    }
}

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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 main(String[] args) {
    // TODO(developer): Replace this query before running the sample.
    String 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 100;";
    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(
              row -> {
                System.out.print("name:" + row.get("name").getStringValue());
                System.out.print(", count:" + row.get("total_people").getLongValue());
                System.out.println();
              });

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

Per eseguire una query con un proxy, consulta Configurazione di un proxy.

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

// 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

Prima di provare questo esempio, segui le istruzioni di configurazione di PHP nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery PHP.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Ruby.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Dry run

Un dry run in BigQuery fornisce le seguenti informazioni:

• stima degli addebiti in modalità on demand
• convalida della query
• Byte approssimativi elaborati dalla query in modalità capacità

I dry run non utilizzano slot di query e non ti vengono addebitati costi per l'esecuzione di un dry run. Puoi utilizzare la stima restituita da un dry run per calcolare i costi delle query nel Calcolatore prezzi.

Nota: un dry run di una query federata che utilizza un'origine dati esterna potrebbe segnalare un limite inferiore di 0 byte di dati, anche se vengono restituite righe. Questo perché la quantità di dati elaborati dalla tabella esterna non può essere determinata fino al completamento della query effettiva. L'esecuzione della query federata comporta comunque un costo per l'elaborazione di questi dati.

Attenzione: i dry run sulle tabelle mascherate dalla sicurezza a livello di riga restituiscono sempre 0 byte per impedire attacchi side channel. Per queste tabelle, non puoi fare affidamento sui dry run per stimare i costi delle query.

Esegui un dry run

Per eseguire un dry run, segui questi passaggi:

Console

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Inserisci la query nell'editor di query.

   Se la query è valida, viene visualizzato automaticamente un segno di spunta insieme alla quantità di dati che verranno elaborati dalla query. Se la query non è valida, viene visualizzato un punto esclamativo con un messaggio di errore.

bq

Inserisci una query come la seguente utilizzando il flag --dry_run.

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

Per una query valida, il comando genera la seguente risposta:

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

Nota: se la query elabora una piccola quantità di dati, potrebbe essere necessario convertire i byte elaborati da KB a MB. MB è la misura più piccola utilizzata dal Calcolatore prezzi.

API

Per eseguire un dry run utilizzando l'API, invia un job di query con dryRun impostato su true nel tipo JobConfiguration.

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

// 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

Prima di provare questo esempio, segui le istruzioni di configurazione di PHP nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery PHP.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Imposta la proprietà QueryJobConfig.dry_run su True. Client.query() restituisce sempre un QueryJob completato quando viene fornita una configurazione di query dry run.

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Risolvi i problemi relativi alle query

Per informazioni sulla risoluzione dei problemi durante l'esecuzione delle query, consulta Risolvi i problemi relativi alle query.

Esegui una query batch

Per eseguire una query batch, seleziona una delle seguenti opzioni:

Console

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Fai clic su Query SQL.

3. Nell'editor di query, inserisci una query GoogleSQL valida.

   Ad esempio, esegui una query sul set di dati pubblico BigQuery usa_names per determinare i nomi più comuni negli Stati Uniti tra gli anni 1910 e 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;
   

4. Fai clic su Modifica > Impostazioni query.

5. Nella sezione Gestione delle risorse, seleziona Batch.

6. (Facoltativo) Modifica le impostazioni della query.

7. Fai clic su Salva.

8. Fai clic su Esegui.

   Se non specifichi una tabella di destinazione, il job di query scrive l'output in una tabella temporanea (cache).

bq

1. Nella console Google Cloud , attiva Cloud Shell.

   Attiva Cloud Shell

   Nella parte inferiore della console Google Cloud , viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

2. Utilizza il comando bq query e specifica il flag --batch. Nell'esempio seguente, il flag --use_legacy_sql=false consente di utilizzare la sintassi GoogleSQL.

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

   Sostituisci QUERY con una query GoogleSQL valida. Ad esempio, esegui una query sul set di dati pubblico BigQuery usa_names per determinare i nomi più comuni negli Stati Uniti tra gli anni 1910 e 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;'
   

   Il job di query scrive l'output in una tabella temporanea (cache).

   Se vuoi, puoi specificare la tabella di destinazione e la località per i risultati della query. Per scrivere i risultati in una tabella esistente, includi il flag appropriato per aggiungere (--append_table=true) o sovrascrivere (--replace=true) la tabella.

   bq query \
       --batch \
       --location=LOCATION \
       --destination_table=TABLE \
       --use_legacy_sql=false \
       'QUERY'

   Sostituisci quanto segue:

   • LOCATION: la regione o la multiregione per la tabella di destinazione, ad esempio US

     In questo esempio, il set di dati usa_names è archiviato nella località multiregionale degli Stati Uniti. Se specifichi una tabella di destinazione per questa query, anche il set di dati che contiene la tabella di destinazione deve trovarsi nella località multiregionale degli Stati Uniti. Non puoi eseguire query su un set di dati in una località e scrivere i risultati in una tabella in un'altra località.

     Puoi impostare un valore predefinito per la località utilizzando il file.bigqueryrc.

   • TABLE: un nome per la tabella di destinazione, ad esempio myDataset.myTable

     Se la tabella di destinazione è una nuova tabella, BigQuery la crea quando esegui la query. Tuttavia, devi specificare un set di dati esistente.

     Se la tabella non si trova nel progetto corrente, aggiungi l'ID progettoGoogle Cloud utilizzando il formatoPROJECT_ID:DATASET.TABLE, ad esempiomyProject:myDataset.myTable. Se --destination_table non è specificato, viene generato un job di query che scrive l'output in una tabella temporanea.

API

Per eseguire una query utilizzando l'API, inserisci un nuovo job e compila la proprietà di configurazione del job query. Se vuoi, specifica la tua località nella proprietà location della sezione jobReference della risorsa job.

Quando compili le proprietà del job di query, includi la proprietà configuration.query.priority e imposta il valore su BATCH.

Esegui il polling dei risultati chiamando getQueryResults. Esegui il polling finché jobComplete non è uguale a true. Controlla la presenza di errori e avvisi nell'elenco errors.

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Per eseguire una query batch, imposta la priorità della query su QueryJobConfiguration.Priority.BATCH durante la creazione di un QueryJobConfiguration.

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

// 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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Esegui una query continua

L'esecuzione di un job di query continua richiede una configurazione aggiuntiva. Per saperne di più, consulta Crea query continue.

Utilizza il riquadro Riferimento

Nell'editor di query, il riquadro Riferimento mostra in modo dinamico informazioni sensibili al contesto su tabelle, snapshot, viste e viste materializzate. Il riquadro ti consente di visualizzare l'anteprima dei dettagli dello schema di queste risorse o di aprirle in una nuova scheda. Puoi anche utilizzare il riquadro Riferimento per creare nuove query o modificare quelle esistenti inserendo snippet di query o nomi di campi.

Per creare una nuova query utilizzando il riquadro Riferimento, segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina BigQuery.

   Vai a BigQuery

2. Fai clic su Query SQL.

3. Fai clic su quick_reference_all Riferimento.

4. Fai clic su una tabella o una vista recente o aggiunta a Speciali. Puoi anche utilizzare la barra di ricerca per trovare tabelle e viste.

5. Fai clic su Visualizza azioni, quindi su Inserisci snippet di query.

   

6. (Facoltativo) Puoi visualizzare l'anteprima dei dettagli dello schema della tabella o della vista oppure aprirli in una nuova scheda.

7. Ora puoi modificare la query manualmente o inserire i nomi dei campi direttamente nella query. Per inserire un nome di campo, posiziona il puntatore del mouse e fai clic su un punto dell'editor di query in cui vuoi inserire il nome di campo, quindi fai clic sul nome di campo nel riquadro Riferimento.

Impostazioni query

Quando esegui una query, puoi specificare le seguenti impostazioni:

• Una tabella di destinazione per i risultati della query.

• La priorità del job.

• Se utilizzare i risultati delle query memorizzati nella cache.

• Il timeout del job in millisecondi.

• Se utilizzare la modalità sessione.

• Il tipo di crittografia da utilizzare.

• Il numero massimo di byte fatturati per la query.

• Il dialetto SQL da utilizzare.

• La località in cui eseguire la query. La query deve essere eseguita nella stessa località delle tabelle a cui fa riferimento.

• La prenotazione in cui eseguire la query.

Modalità di creazione job facoltativa

La modalità di creazione job facoltativa può migliorare la latenza complessiva delle query che vengono eseguite per un breve periodo di tempo, ad esempio quelle dei workload di dashboard o esplorazione dei dati. Questa modalità esegue la query e restituisce i risultati in linea per le istruzioni SELECT senza richiedere l'utilizzo di jobs.getQueryResults per recuperare i risultati. Le query che utilizzano la modalità di creazione job facoltativa non creano un job quando vengono eseguite, a meno che BigQuery non stabilisca che la creazione di un job è necessaria per completare la query.

Per attivare la modalità di creazione job facoltativa, imposta il campo jobCreationMode dell'istanza QueryRequest su JOB_CREATION_OPTIONAL nel corpo della richiesta jobs.query.

Quando il valore di questo campo è impostato su JOB_CREATION_OPTIONAL, BigQuery determina se la query può utilizzare la modalità di creazione job facoltativa. In questo caso, BigQuery esegue la query e restituisce tutti i risultati nel campo rows della risposta. Poiché non viene creato un job per questa query, BigQuery non restituisce un jobReference nel corpo della risposta. Restituisce invece un campo queryId, che puoi utilizzare per ottenere informazioni sulla query utilizzando la vista INFORMATION_SCHEMA.JOBS. Poiché non viene creato alcun job, non esiste alcun jobReference che possa essere passato alle API jobs.get e jobs.getQueryResults per cercare queste query.

Se BigQuery determina che è necessario un job per completare la query, viene restituito un jobReference. Puoi esaminare il campo job_creation_reason nella vista INFORMATION_SCHEMA.JOBS per determinare il motivo per cui è stato creato un job per la query. In questo caso, devi utilizzare jobs.getQueryResults per recuperare i risultati al termine della query.

Quando utilizzi il valore JOB_CREATION_OPTIONAL, il campo jobReference potrebbe non essere presente nella risposta. Verifica se il campo esiste prima di accedervi.

Quando JOB_CREATION_OPTIONAL è specificato per le query con più istruzioni (script), BigQuery potrebbe ottimizzare il processo di esecuzione. Nell'ambito di questa ottimizzazione, BigQuery potrebbe determinare che può completare lo script creando meno risorse job rispetto al numero di singole istruzioni, potenzialmente anche eseguendo l'intero script senza creare alcun job. Questa ottimizzazione dipende dalla valutazione dello script da parte di BigQuery e potrebbe non essere applicata in tutti i casi. L'ottimizzazione è completamente automatizzata dal sistema. Non sono richiesti controlli o azioni da parte dell'utente.

Per eseguire una query utilizzando la modalità di creazione job facoltativa, seleziona una delle seguenti opzioni:

Console

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Fai clic su Query SQL.

3. Nell'editor di query, inserisci una query GoogleSQL valida.

   Ad esempio, esegui una query sul set di dati pubblico BigQuery usa_names per determinare i nomi più comuni negli Stati Uniti tra gli anni 1910 e 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;
   

4. Fai clic su Modifica > Modalità query > Creazione di job facoltativa. Per confermare questa scelta, fai clic su Conferma.

5. Fai clic su Esegui.

bq

1. Nella console Google Cloud , attiva Cloud Shell.

   Attiva Cloud Shell

   Nella parte inferiore della console Google Cloud , viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

2. Utilizza il comando bq query e specifica il flag --job_creation_mode=JOB_CREATION_OPTIONAL. Nell'esempio seguente, il flag --use_legacy_sql=false consente di utilizzare la sintassi GoogleSQL.

   bq query \
       --rpc=true \
       --use_legacy_sql=false \
       --job_creation_mode=JOB_CREATION_OPTIONAL \
       --location=LOCATION \
       'QUERY'

   Sostituisci QUERY con una query GoogleSQL valida e LOCATION con una regione valida in cui si trova il set di dati. Ad esempio, esegui una query sul set di dati pubblico BigQuery usa_names per determinare i nomi più comuni negli Stati Uniti tra gli anni 1910 e 2013:

   bq query \
       --rpc=true \
       --use_legacy_sql=false \
       --job_creation_mode=JOB_CREATION_OPTIONAL \
       --location=us \
       '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;'
   

   Il job di query restituisce l'output in linea nella risposta.

   Nota: se necessario, puoi utilizzare --apilog=stdout per registrare le richieste e le risposte API per estrarre il queryId.

API

Per eseguire una query in modalità di creazione job facoltativa utilizzando l'API, esegui una query in modo sincrono e compila la proprietà QueryRequest. Includi la proprietà jobCreationMode e impostane il valore su JOB_CREATION_OPTIONAL.

Controlla la risposta. Se jobComplete è uguale a true e jobReference è vuoto, leggi i risultati dal campo rows. Puoi anche ottenere il queryId dalla risposta.

Se è presente jobReference, puoi controllare jobCreationReason per scoprire perché un job è stato creato da BigQuery. Esegui il polling dei risultati chiamando getQueryResults. Esegui il polling finché jobComplete non è uguale a true. Controlla la presenza di errori e avvisi nell'elenco errors.

Java

Versione disponibile: 2.51.0 e successive

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

// Sample demonstrating short mode query execution.
//
// This feature is controlled by setting the defaultJobCreationMode
// field in the BigQueryOptions used for the client. JOB_CREATION_OPTIONAL
// allows for the execution of queries without creating a job.
public class QueryJobOptional {

  public static void main(String[] args) {
    String query =
        "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";
    queryJobOptional(query);
  }

  public static void queryJobOptional(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.
      BigQueryOptions options = BigQueryOptions.getDefaultInstance();
      options.setDefaultJobCreationMode(JobCreationMode.JOB_CREATION_OPTIONAL);
      BigQuery bigquery = options.getService();

      // Execute the query. The returned TableResult provides access information
      // about the query execution as well as query results.
      TableResult results = bigquery.query(QueryJobConfiguration.of(query));

      JobId jobId = results.getJobId();
      if (jobId != null) {
        System.out.println("Query was run with job state.  Job ID: " + jobId.toString());
      } else {
        System.out.println("Query was run in short mode.  Query ID: " + results.getQueryId());
      }

      // Print the results.
      results
          .iterateAll()
          .forEach(
              row -> {
                System.out.print("name:" + row.get("name").getStringValue());
                System.out.print(", gender: " + row.get("gender").getStringValue());
                System.out.print(", total: " + row.get("total").getLongValue());
                System.out.println();
              });

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

Per eseguire una query con un proxy, consulta Configurazione di un proxy.

Python

Versione disponibile: 3.34.0 e successive

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

# This example demonstrates executing a query without requiring an associated
# job.
from google.cloud import bigquery
from google.cloud.bigquery.enums import JobCreationMode

# Construct a BigQuery client object, specifying that the library should
# avoid creating jobs when possible.
client = bigquery.Client(
    default_job_creation_mode=JobCreationMode.JOB_CREATION_OPTIONAL
)

query = """
    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
"""
# Run the query.  The returned `rows` iterator can return information about
# how the query was executed as well as the result data.
rows = client.query_and_wait(query)

if rows.job_id is not None:
    print("Query was run with job state.  Job ID: {}".format(rows.job_id))
else:
    print(
        "Query was run without creating a job.  Query ID: {}".format(rows.query_id)
    )

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

Nodo

Versione disponibile: 8.1.0 e successive

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

// Demonstrates issuing a query that may be run in short query mode.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery({
  // default behavior is to create jobs when using the jobs.query API
  defaultJobCreationMode: 'JOB_CREATION_REQUIRED',
});

async function queryJobOptional() {
  // SQL query to run.

  const sqlQuery = `
    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`;

  // Run the query
  const [rows, , res] = await bigquery.query({
    query: sqlQuery,
    // Skip job creation to enable short mode.
    jobCreationMode: 'JOB_CREATION_OPTIONAL',
  });

  if (!res.jobReference) {
    console.log(`Query was run in short mode. Query ID: ${res.queryId}`);
  } else {
    const jobRef = res.jobReference;
    const qualifiedId = `${jobRef.projectId}.${jobRef.location}.${jobRef.jobId}`;
    console.log(
      `Query was run with job state. Job ID: ${qualifiedId}, Query ID: ${res.queryId}`,
    );
  }
  // Print the results
  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

Vai

Versione disponibile: 1.69.0 e successive

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

import (
	"context"
	"fmt"
	"io"

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

// queryJobOptional demonstrates issuing a query that doesn't require a
// corresponding job.
func queryJobOptional(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID,
		bigquery.WithDefaultJobCreationMode(bigquery.JobCreationModeOptional),
	)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	q := client.Query(`
		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
		`)
	// Run the query and process the returned row iterator.
	it, err := q.Read(ctx)
	if err != nil {
		return fmt.Errorf("query.Read(): %w", err)
	}

	// The iterator provides information about the query execution.
	// Queries that were run in short query mode will not have the source job
	// populated.
	if it.SourceJob() == nil {
		fmt.Fprintf(w, "Query was run in optional job mode.  Query ID: %q\n", it.QueryID())
	} else {
		j := it.SourceJob()
		qualifiedJobID := fmt.Sprintf("%s:%s.%s", j.ProjectID(), j.Location(), j.ID())
		fmt.Fprintf(w, "Query was run with job state.  Job ID: %q, Query ID: %q\n",
			qualifiedJobID, it.QueryID())
	}

	// Print row data.
	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
}

Driver JDBC

Versione disponibile: JDBC v1.6.1 e successive

Richiede l'impostazione di JobCreationMode=2 nella stringa di connessione.

    jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;JobCreationMode=2;Location=US;
  

Nota: se necessario, puoi aggiungere LogLevel=6;LogPath=log.txt alla stringa di connessione per attivare il logging a livello di TRACE ed estrarre le informazioni per la risoluzione dei problemi, tra cui queryId.

Driver ODBC

Versione disponibile: ODBC v3.0.7.1016 e successive

Richiede l'impostazione di JobCreationMode=2 nel file .ini.

    [ODBC Data Sources]
    Sample DSN=Simba Google BigQuery ODBC Connector 64-bit
    [Sample DSN]
    JobCreationMode=2
  

Nota: se necessario, puoi aggiungere LogLevel=6 e LogPath=log.txt al file .ini per attivare il logging dettagliato ed estrarre le informazioni per la risoluzione dei problemi, tra cui queryId.

Query globali

Le query vengono eseguite nella località dei dati a cui fanno riferimento. Tuttavia, se una query fa riferimento a dati archiviati in più località, viene eseguita una query globale. Quando esegui una query globale, BigQuery è in grado di raccogliere tutti i dati necessari da diverse località in un unico posto, eseguire una query e restituire i risultati. Poiché le query globali richiedono il trasferimento di dati tra località, richiedono autorizzazioni aggiuntive e possono comportare costi aggiuntivi.

Per saperne di più sulle query globali, consulta Query globali.

Quote

Per informazioni sulle quote relative alle query interattive e batch, consulta Job di query.

Per risolvere gli errori di quota relativi alle query, consulta la pagina Risoluzione dei problemi di BigQuery. I seguenti errori relativi alle quote e le relative informazioni per la risoluzione dei problemi sono direttamente correlati alle query:

• Errori relativi al limite della coda di query
• Errori relativi alla quota di importazioni di tabelle o aggiunte di query

Monitora le query

Puoi ottenere informazioni sulle query durante la loro esecuzione utilizzando Esplora job o eseguendo una query sulla vista INFORMATION_SCHEMA.JOBS_BY_PROJECT.

Runtime avanzato

Il runtime avanzato di BigQuery è un insieme di miglioramenti delle prestazioni progettati per accelerare automaticamente i workload analitici senza richiedere l'intervento dell'utente o modifiche al codice. Le query sfruttano automaticamente le ottimizzazioni del runtime avanzato quando sono disponibili la vettorizzazione avanzata o le ottimizzazioni delle query brevi.

Vettorizzazione migliorata

L'esecuzione vettorizzata è un modello di elaborazione delle query che opera su colonne di dati in blocchi che si allineano alle dimensioni della cache della CPU e utilizza istruzioni SIMD (Single Instruction, Multiple Data). La vettorizzazione avanzata estende l'esecuzione delle query vettorizzate in BigQuery ai seguenti aspetti dell'elaborazione delle query:

• Sfruttando codifiche di dati specializzate all'interno del formato di archiviazione Capacitor, le operazioni di valutazione dei filtri possono essere eseguite sui dati codificati.
• Le codifiche specializzate vengono propagate attraverso il piano di query, il che consente di elaborare più dati mentre sono ancora codificati.
• Implementando il folding delle espressioni per valutare le funzioni deterministiche e le espressioni costanti, BigQuery può semplificare i predicati complessi in valori costanti.

Ottimizzazioni delle query brevi

In genere, BigQuery esegue le query in un ambiente distribuito utilizzando un livello intermedio di shuffle. Le ottimizzazioni delle query brevi identificano dinamicamente le query che possono essere eseguite in un'unica fase, riducendo la latenza e il consumo di slot. Le codifiche specializzate possono essere utilizzate in modo più efficace quando una query viene eseguita in un'unica fase. Queste ottimizzazioni sono più efficaci se utilizzate con la modalità di creazione job facoltativa, che riduce al minimo la latenza di avvio, manutenzione e recupero dei risultati dei job.

L'idoneità alle ottimizzazioni per le query brevi è dinamica e influenzata dai seguenti fattori:

• La dimensione prevista dell'analisi dei dati.
• La quantità di spostamento dei dati richiesta.
• La selettività dei filtri delle query.
• Il tipo e il layout fisico dei dati nello spazio di archiviazione.
• La struttura complessiva della query.
• Le statistiche storiche delle esecuzioni di query passate.

Stima l'impatto del runtime avanzato

Per stimare l'impatto del runtime avanzato, puoi utilizzare la seguente query SQL per identificare le query del progetto con il miglioramento stimato maggiore del tempo di esecuzione:

WITH
  jobs AS (
    SELECT
      *,
      query_info.query_hashes.normalized_literals AS query_hash,
      TIMESTAMP_DIFF(end_time, start_time, MILLISECOND) AS elapsed_ms,
      EXISTS(
        SELECT 1
        FROM UNNEST(JSON_QUERY_ARRAY(query_info.optimization_details.optimizations)) AS o
        WHERE JSON_VALUE(o, '$.enhanced_vectorization') = 'applied'
      ) AS has_advanced_runtime
    FROM region-LOCATION.INFORMATION_SCHEMA.JOBS_BY_PROJECT
    WHERE EXTRACT(DATE FROM creation_time) > DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
  ),
  most_recent_jobs_without_advanced_runtime AS (
    SELECT *
    FROM jobs
    WHERE NOT has_advanced_runtime
    QUALIFY ROW_NUMBER() OVER (PARTITION BY query_hash ORDER BY end_time DESC) = 1
  )
SELECT
  job.job_id,
  100 * SAFE_DIVIDE(
    original_job.elapsed_ms - job.elapsed_ms,
    original_job.elapsed_ms) AS percent_execution_time_saved,
  job.elapsed_ms AS new_elapsed_ms,
  original_job.elapsed_ms AS original_elapsed_ms,
FROM jobs AS job
INNER JOIN most_recent_jobs_without_advanced_runtime AS original_job
  USING (query_hash)
WHERE
  job.has_advanced_runtime
  AND original_job.end_time < job.start_time
ORDER BY percent_execution_time_saved DESC
LIMIT 10;

Nota: È possibile confrontare solo le query create a partire dal 30 gennaio 2026, data in cui gli indicatori di ottimizzazione del runtime avanzato (enhanced_vectorization e short_query_optimization) sono diventati costantemente disponibili nella INFORMATION_SCHEMA.JOBS visualizzazione.

Sostituisci quanto segue:

• LOCATION: la località in cui deve essere misurato il rendimento del job

Se è stato applicato il runtime avanzato, i risultati di questa query potrebbero essere simili ai seguenti:

/*--------------+----------------------------+----------------+---------------------*
 |    job_id    | percent_elapsed_time_saved | new_elapsed_ms | original_elapsed_ms |
 +--------------+----------------------------+----------------+---------------------+
 | sample_job1  |         45.38834951456311  |            225 |                 412 |
 | sample_job2  |         45.19480519480519  |            211 |                 385 |
 | sample_job3  |         33.246753246753244 |            257 |                 385 |
 | sample_job4  |         29.28802588996764  |           1311 |                1854 |
 | sample_job5  |         28.18181818181818  |           1027 |                1430 |
 | sample_job6  |         25.804195804195807 |           1061 |                1430 |
 | sample_job7  |         25.734265734265733 |           1062 |                1430 |
 | sample_job8  |         25.454545454545453 |           1066 |                1430 |
 | sample_job9  |         25.384615384615383 |           1067 |                1430 |
 | sample_job10 |         25.034965034965033 |           1072 |                1430 |
 *--------------+----------------------------+----------------+---------------------*/

I risultati di questa query sono solo una stima dell'impatto del runtime avanzato. Molti fattori possono influire sulle prestazioni delle query, tra cui, a titolo esemplificativo, la disponibilità degli slot, la variazione dei dati nel tempo, le definizioni delle viste o delle funzioni definite dall'utente e le differenze nei valori dei parametri di query.

Se i risultati di questa query sono vuoti, significa che nessun job ha utilizzato il runtime avanzato o che tutti i job sono stati ottimizzati più di 30 giorni fa.

Questa query può essere applicata ad altre metriche sul rendimento delle query, come total_slot_ms e total_bytes_billed. Per saperne di più, consulta lo schema per INFORMATION_SCHEMA.JOBS_BY_PROJECT.

Passaggi successivi

• Scopri come gestire i job di query.
• Scopri come visualizzare la cronologia delle query.
• Scopri come salvare e condividere le query.
• Scopri di più sulle code di query.
• Scopri come scrivere i risultati delle query.