Como emitir uma simulação de consulta

Ao executar uma consulta na CLI, use a sinalização --dry_run para estimar o número de bytes lidos pela consulta. Utilize também o parâmetro dryRun ao enviar um job de consulta por meio da API ou das bibliotecas de cliente.

Use a estimativa retornada para calcular os custos da consulta na calculadora de preços. Você não será cobrado pela execução dessa simulação.

Permissões necessárias

Para executar um job de consulta, é necessário ter, no mínimo, as permissões bigquery.jobs.create. Para que esse job seja concluído com sucesso, também é necessário ter acesso aos conjuntos de dados que contêm as tabelas ou visualizações referenciadas pela consulta. Para informações sobre os controles de acesso aos conjuntos de dados, consulte Como controlar o acesso a conjuntos de dados.

Os papéis predefinidos do Cloud IAM abaixo incluem permissões bigquery.jobs.create:

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. O acesso bigquery.dataOwner permite que o usuário consulte tabelas e visualizações no conjunto de dados.

Para mais informações sobre os papéis do Cloud IAM no BigQuery, consulte Papéis e permissões predefinidos.

Como executar simulações

Para executar uma simulação relacionada a um job de consulta:

  • use a sinalização --dry_run com o comando query na CLI;
  • use o parâmetro dryRun na configuração do job quando utilizar a API ou as bibliotecas de cliente.

Como executar uma simulação

Para executar uma simulação:

Console

No momento, não é possível executar uma simulação usando o Console do Cloud.

IU clássica

No momento, não é possível executar uma simulação usando a IU da Web.

CLI

Insira uma consulta como a seguinte usando a sinalização --dry_run.

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

O comando gera a resposta a seguir:

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

API

Para fazer uma simulação usando a API, envie um job de consulta com dryRun definido como true na configuração do job.

Go

Antes de testar esta amostra, siga as instruções de configuração para Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Go (em inglês). 

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 != nil {
		return err
	}
	fmt.Fprintf(w, "This query will process %d bytes\n", status.Statistics.TotalBytesProcessed)
	return nil
}

Python

Para executar uma simulação usando a biblioteca de cliente em Python, configure a propriedade QueryJobConfig.dry_run como True. Se uma configuração de consulta de simulação for fornecida, Client.query() sempre retornará um QueryJob concluído (links em inglês).

Antes de testar esta amostra, siga as instruções de configuração para Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Python (em inglês). 

from google.cloud import bigquery

# TODO(developer): 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))