Executar uma consulta

Neste documento, mostramos como executar uma consulta no BigQuery e entender quantos dados a consulta processará antes da execução por meio de uma simulação.

Tipos de consultas

Você pode consultar dados do BigQuery usando um dos seguintes tipos de job de consulta:

• Jobs de consulta interativos. Por padrão, o BigQuery executa jobs de consulta interativos (sob demanda) o mais rápido possível.

• Jobs de consulta contínua (Prévia). Com esses jobs, a consulta é executada continuamente, para que você analise os dados de entrada no BigQuery em tempo real e gravar resultados para uma tabela do BigQuery ou exportar os resultados para Bigtable ou Pub/Sub. Use esse recurso para realizar tarefas urgentes, como criar e agir imediatamente insights, aplicando inferências de machine learning (ML) em tempo real e criar pipelines de dados orientados por eventos.

• Jobs de consulta em lote. Com esses jobs, o BigQuery coloca em fila cada consulta em lote em seu nome e inicia a consulta quando os recursos inativos estão disponíveis, geralmente em alguns minutos.

É possível executar jobs de consulta usando os seguintes métodos:

• Escreva e execute uma consulta no Console do Google Cloud.
• Execute o comando bq query na ferramenta de linha de comando bq.
• Chame o método jobs.query ou jobs.insert de maneira programática na API REST do BigQuery.
• Use as bibliotecas de cliente do BigQuery.

Por padrão, o BigQuery executa suas consultas como jobs de consulta interativos, que são executados o mais rápido possível. O BigQuery calcula dinamicamente o limite de consultas simultâneas com base na disponibilidade de recursos e favorece a execução de mais consultas interativas simultâneas do que consultas em lote. Quando você atinge o limite de consultas simultâneas, outras consultas aguardam em uma fila. Para mais informações, consulte filas de consulta.

O BigQuery salva os resultados da consulta em uma tabela temporária (padrão) ou permanente. Ao especificar uma tabela permanente como de destino para os resultados, você pode escolher adicionar ao final ou substituir uma tabela existente ou criar uma nova tabela com um nome exclusivo.

Observação :se você consultar dados de um projeto para armazenar dados em um projeto diferente, o projeto de consulta será cobrado pelo job de consulta enquanto o projeto que armazena o os dados são cobrados pela quantidade de dados armazenados no BigQuery.

Funções exigidas

Para receber as permissões necessárias para executar um job de consulta, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Usuário de jobs do BigQuery (roles/bigquery.jobUser) no projeto.
• Leitor de dados do BigQuery (roles/bigquery.dataViewer) em todas as tabelas e visualizações referenciadas pela sua consulta. Para consultar visualizações, você também precisa desse papel em todas as tabelas e visualizações subjacentes. Se você estiver usando visualizações autorizadas ou conjuntos de dados autorizados, não será necessário ter acesso aos dados de origem subjacentes.

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para executar um job de consulta. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para executar um job de consulta:

• bigquery.jobs.create no projeto em que a consulta está sendo executada, independentemente de onde os dados são armazenados.
• bigquery.tables.getData em todas as tabelas e visualizações referenciadas pela sua consulta. Para consultar visualizações, você também precisa dessa permissão em todas as tabelas e visualizações subjacentes. Se você estiver usando visualizações autorizadas ou conjuntos de dados autorizados, não será necessário ter acesso aos dados de origem subjacentes.

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Solução de problemas

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

Esse erro ocorre quando um titular não tem permissão para criar jobs de consulta no projeto.

Solução: um administrador precisa conceder a permissão bigquery.jobs.create no projeto que você está consultando. Essa permissão é necessária além de quaisquer permissões necessárias para acessar os dados consultados.

Para mais informações sobre as permissões do BigQuery, consulte Controle de acesso com o IAM.

Executar uma consulta interativa

Para executar uma consulta interativa, selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Ir para o BigQuery

2. Clique em Consulta SQL.

3. No editor de consultas, insira uma consulta válida do GoogleSQL.

   Por exemplo, consulte o conjunto de dados públicos do BigQuery usa_names para determinar os nomes mais comuns nos Estados Unidos entre os anos de 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. Opcional: especifique a tabela de destino e a localização para os resultados da consulta:

   1. No editor de consultas, clique em Mais e, em seguida, em Configurações de consulta.
   2. Na seção Destino, marque Definir uma tabela de destino para os resultados da consulta.
   3. Em Conjunto de dados, insira o nome de um conjunto de dados para a tabela de destino, por exemplo, myProject.myDataset.
   4. Em ID da tabela, insira um nome para a tabela de destino, por exemplo, myTable.

   5. Se a tabela de destino for uma tabela, em Preferência de gravação na tabela de destino, selecione se quer adicionar ao final ou substituir a tabela com os resultados da consulta.

      Se a tabela de destino for uma nova tabela, o BigQuery a criará quando você executar a consulta.

   6. Na seção Configurações adicionais, clique no menu Local dos dados e selecione uma opção.

      Neste exemplo, o conjunto de dados usa_names é armazenado no local multirregional EUA. Se você especificar uma tabela de destino para essa consulta, o conjunto de dados que contém a tabela de destino também precisará estar na multirregião dos EUA. Não é possível consultar um conjunto de dados em um local e gravar os resultados em uma tabela de destino em outro local.

   7. Clique em Save.

5. Clique em Executar.

   Se você não especificar uma tabela de destino, o job de consulta gravará a saída em uma tabela temporária (cache).

   Agora é possível conferir os resultados da consulta na guia Resultados do painel Resultados da consulta.

6. Opcional: para classificar os resultados por coluna, clique em Abrir menu de classificação ao lado do nome da coluna e selecione uma ordem de classificação. Se o número estimado de bytes processados para a classificação for maior do que zero, o número de bytes será exibido na parte de cima do menu.

7. Opcional: para acessar a visualização dos resultados da consulta, acesse a guia Gráfico (visualização). É possível aumentar ou diminuir o zoom do gráfico, fazer o download dele como um arquivo PNG ou alternar a visibilidade da legenda.

   No painel Configuração do gráfico, você pode mudar o tipo de gráfico (linha ou barra) e configurar as medidas e dimensões dele. Os campos nesse painel são preenchidos automaticamente com a configuração inicial inferida do esquema da tabela de destino da consulta. A configuração é preservada entre as seguintes execuções de consulta no mesmo editor de consultas. Suporte a dimensões INTEGER, INT64, FLOAT FLOAT64, NUMERIC, BIGNUMERIC, TIMESTAMP, DATE, DATETIME e TIME e tipos de dados STRING, enquanto as medidas dão suporte a tipos de dados INTEGER, INT64, FLOAT, FLOAT64, NUMERIC e BIGNUMERIC.

8. Opcional: na guia JSON, é possível analisar os resultados da consulta no formato JSON, em que a chave é o nome da coluna e o valor é o resultado dessa coluna.

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use o comando bq query. No exemplo a seguir, a sinalização --use_legacy_sql=false permite usar a sintaxe do GoogleSQL.

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

   Substitua QUERY por uma consulta válida do GoogleSQL. Por exemplo, consulte o conjunto de dados públicos do BigQuery usa_names para determinar os nomes mais comuns nos Estados Unidos entre os anos de 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;'
   

   O job de consulta grava a saída em uma tabela temporária (cache).

   Também é possível especificar a tabela de destino e o local para os resultados da consulta. Para gravar os resultados em uma tabela existente, inclua a sinalização apropriada para adicionar ao final (--append_table=true) ou substituir (--replace=true) a tabela.

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

   Substitua:

   • LOCATION: a região ou a multirregião da tabela de destino, por exemplo, US

     Neste exemplo, o conjunto de dados usa_names é armazenado no local multirregional EUA. Se você especificar uma tabela de destino para essa consulta, o conjunto de dados que contém a tabela de destino também precisará estar na multirregião dos EUA. Não é possível consultar um conjunto de dados em um local e gravar os resultados em uma tabela de destino em outro local.

     É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;

   • TABLE: um nome para a tabela de destino, por exemplo, myDataset.myTable

     Se a tabela de destino for uma nova tabela, o BigQuery a criará ao executar a consulta. No entanto, é necessário especificar um conjunto de dados atual.

     Se a tabela não estiver no projeto atual, adicione o ID do projeto do Google Cloud usando o formato PROJECT_ID:DATASET.TABLE. Por exemplo, myProject:myDataset.myTable. Se --destination_table não for especificado, será gerado um job de consulta que grava a saída em uma tabela temporária (cache).

API

Para executar uma consulta usando a API, insira um novo job e preencha a propriedade de configuração do job query. (Opcional) Especifique o local na propriedade location na seção jobReference do recurso do job.

Pesquise os resultados chamando getQueryResults. Pesquisar até jobComplete igual a true. Verifique se há erros e avisos na lista errors.

C#

Antes de testar esta amostra, siga as instruções de configuração do C# 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 em C#.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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

Go

Antes de testar esta amostra, siga as instruções de configuração do 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 em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Antes de testar esta amostra, siga as instruções de configuração do Java 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 em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

public class SimpleQuery {

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

  public static void simpleQuery(String query) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

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

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

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

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

Para executar uma consulta com um proxy, consulte Como configurar um proxy.

Node.js

Antes de testar esta amostra, siga as instruções de configuração do Node.js 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 em Node.js.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Antes de testar esta amostra, siga as instruções de configuração do PHP 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 em PHP.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Antes de testar esta amostra, siga as instruções de configuração do 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 em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Antes de testar esta amostra, siga as instruções de configuração do Ruby 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 em Ruby.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Executar uma consulta contínua

A execução de um job de consulta contínua requer uma configuração extra. Para mais informações, consulte Criar consultas contínuas.

Executar uma consulta em lote

Para executar uma consulta em lote, selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Ir para o BigQuery

2. Clique em Consulta SQL.

3. No editor de consultas, insira uma consulta válida do GoogleSQL.

   Por exemplo, consulte o conjunto de dados públicos do BigQuery usa_names para determinar os nomes mais comuns nos Estados Unidos entre os anos de 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. Clique em Mais e, depois, em Configurações de consulta.

5. Na seção Gerenciamento de recursos, selecione Batch.

6. Opcional: especifique a tabela de destino e a localização para os resultados da consulta:

   1. Na seção Destino, marque Definir uma tabela de destino para os resultados da consulta.
   2. Em Conjunto de dados, insira o nome de um conjunto de dados para a tabela de destino, por exemplo, myProject.myDataset.
   3. Em ID da tabela, insira um nome para a tabela de destino, por exemplo, myTable.

   4. Se a tabela de destino for uma tabela, em Preferência de gravação na tabela de destino, selecione se quer adicionar ao final ou substituir a tabela com os resultados da consulta.

      Se a tabela de destino for uma nova tabela, o BigQuery a criará quando você executar a consulta.

   5. Na seção Configurações adicionais, clique no menu Local dos dados e selecione uma opção.

      Neste exemplo, o conjunto de dados usa_names é armazenado no local multirregional EUA. Se você especificar uma tabela de destino para essa consulta, o conjunto de dados que contém a tabela de destino também precisará estar na multirregião dos EUA. Não é possível consultar um conjunto de dados em um local e gravar os resultados em uma tabela de destino em outro local.

7. Clique em Save.

8. Clique em Executar.

   Se você não especificar uma tabela de destino, o job de consulta gravará a saída em uma tabela temporária (cache).

9. Opcional: para classificar os resultados por coluna, clique em Abrir menu de classificação ao lado do nome da coluna e selecione uma ordem de classificação. Se o número estimado de bytes processados para a classificação for maior do que zero, o número de bytes será exibido na parte de cima do menu.

10. Opcional: para acessar a visualização dos resultados da consulta, acesse a guia Gráfico (visualização). É possível aumentar ou diminuir o zoom do gráfico, fazer o download dele como um arquivo PNG ou alternar a visibilidade da legenda.

    No painel Configuração do gráfico, você pode mudar o tipo de gráfico (linha ou barra) e configurar as medidas e dimensões dele. Os campos nesse painel são preenchidos automaticamente com a configuração inicial inferida do esquema da tabela de destino da consulta. A configuração é preservada entre as seguintes execuções de consulta no mesmo editor de consultas. Suporte a dimensões INTEGER, INT64, FLOAT FLOAT64, NUMERIC, BIGNUMERIC, TIMESTAMP, DATE, DATETIME e TIME e tipos de dados STRING, enquanto as medidas dão suporte a tipos de dados INTEGER, INT64, FLOAT, FLOAT64, NUMERIC e BIGNUMERIC.

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use o comando bq query e especifique a sinalização --batch. No exemplo a seguir, a sinalização --use_legacy_sql=false permite usar a sintaxe GoogleSQL.

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

   Substitua QUERY por uma consulta válida do GoogleSQL. Por exemplo, consulte o conjunto de dados públicos do BigQuery usa_names para determinar os nomes mais comuns nos Estados Unidos entre os anos de 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;'
   

   O job de consulta grava a saída em uma tabela temporária (cache).

   Também é possível especificar a tabela de destino e o local para os resultados da consulta. Para gravar os resultados em uma tabela existente, inclua a sinalização apropriada para adicionar ao final (--append_table=true) ou substituir (--replace=true) a tabela.

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

   Substitua:

   • LOCATION: a região ou a multirregião da tabela de destino, por exemplo, US

     Neste exemplo, o conjunto de dados usa_names é armazenado no local multirregional EUA. Se você especificar uma tabela de destino para essa consulta, o conjunto de dados que contém a tabela de destino também precisará estar na multirregião dos EUA. Não é possível consultar um conjunto de dados em um local e gravar os resultados em uma tabela de destino em outro local.

     É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;

   • TABLE: um nome para a tabela de destino, por exemplo, myDataset.myTable

     Se a tabela de destino for uma nova tabela, o BigQuery a criará ao executar a consulta. No entanto, é necessário especificar um conjunto de dados atual.

     Se a tabela não estiver no projeto atual, adicione o ID do projeto do Google Cloud usando o formato PROJECT_ID:DATASET.TABLE. Por exemplo, myProject:myDataset.myTable. Se --destination_table não for especificado, será gerado um job de consulta que grava a saída em uma tabela temporária (cache).

API

Para executar uma consulta usando a API, insira um novo job e preencha a propriedade de configuração do job query. (Opcional) Especifique o local na propriedade location na seção jobReference do recurso do job.

Ao preencher as propriedades do job de consulta, inclua a propriedade configuration.query.priority e defina o valor como BATCH.

Pesquise os resultados chamando getQueryResults. Pesquisar até jobComplete igual a true. Verifique se há erros e avisos na lista errors.

Go

Antes de testar esta amostra, siga as instruções de configuração do 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 em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para executar uma consulta em lote, defina a prioridade de consulta como QueryJobConfiguration.Priority.BATCH ao criar uma QueryJobConfiguration.

Antes de testar esta amostra, siga as instruções de configuração do Java 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 em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Antes de testar esta amostra, siga as instruções de configuração do Node.js 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 em Node.js.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Antes de testar esta amostra, siga as instruções de configuração do 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 em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Modo otimizado de consulta curta

Visualização

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Observação: para enviar feedback ou solicitar suporte sobre esse recurso, envie um e-mail para [e-mail].

O modo otimizado para consultas curtas tem como objetivo melhorar a latência geral de consultas curtas, que são comuns em cargas de trabalho, como painéis ou análise de dados. Ele executa a consulta e retorna os resultados inline para instruções SELECT. As consultas que usam o modo otimizado de consulta curta não criam um job quando são executadas, a menos que o BigQuery determine que a criação de um job é necessária para concluir a consulta.

Para ativar o modo otimizado de consulta curta, defina o campo jobCreationMode da instância QueryRequest como JOB_CREATION_OPTIONAL no corpo da solicitação jobs.query.

Quando o valor desse campo é definido como JOB_CREATION_OPTIONAL, o BigQuery determina se a consulta pode usar o novo modo otimizado de consulta curta. Nesse caso, o BigQuery executa a consulta e retorna todos os resultados no campo rows da resposta. Como nenhum job foi criado para essa consulta, o BigQuery não retorna um jobReference no corpo da resposta. Em vez disso, ele retorna um campo queryId que pode ser usado para receber insights sobre a consulta usando a visualização INFORMATION_SCHEMA.JOBS. Como nenhum job é criado, não há jobReference que possa ser transmitido para as APIs jobs.get e jobs.getQueryResults para pesquisar consultas curtas.

Se o BigQuery determinar que um job é necessário para concluir a consulta, um jobReference será retornado. É possível inspecionar o campo job_creation_reason na visualização INFORMATION_SCHEMA.JOBS para determinar o motivo da criação de um job para a consulta. Nesse caso, use jobs.getQueryResults para buscar os resultados quando a consulta for concluída.

Ao usar o valor JOB_CREATION_OPTIONAL, não presuma que o campo jobReference está sempre presente na resposta. Verifique se o campo existe antes de acessá-lo.

O modo otimizado de consulta curta também inclui um cache de resultados de consulta que melhora o desempenho de consultas repetidas quando os dados subjacentes não mudam. Quando você especifica useQueryCache: true (o valor padrão é true, se não for especificado) e jobCreationMode: JOB_CREATION_OPTIONAL em QueryRequest, o BigQuery tenta exibir os resultados do cache. O armazenamento em cache é feito da melhor forma possível.

Para executar uma consulta usando o modo otimizado de consulta curta, selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Ir para o BigQuery

2. Clique em Consulta SQL.

3. No editor de consultas, insira uma consulta válida do GoogleSQL.

   Por exemplo, consulte o conjunto de dados públicos do BigQuery usa_names para determinar os nomes mais comuns nos Estados Unidos entre os anos de 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. Clique em Mais e, depois, em Consulta curta otimizada em Escolher modo de consulta. Clique em CONFIRMAR para confirmar a escolha.

5. Clique em Executar.

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use o comando bq query e especifique a sinalização --job_creation_mode=JOB_CREATION_OPTIONAL. No exemplo a seguir, a sinalização --use_legacy_sql=false permite usar a sintaxe GoogleSQL.

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

   Substitua QUERY por uma consulta válida do GoogleSQL e LOCATION por uma região válida onde o conjunto de dados está localizado. Por exemplo, consulte o conjunto de dados públicos do BigQuery usa_names para determinar os nomes mais comuns nos Estados Unidos entre os anos de 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;'
   

   O job de consulta retorna a saída inline na resposta.

   Observação: use --apilog=stdout para registrar solicitações e respostas de API e extrair o queryId, se necessário.

API

Para executar uma consulta no modo de consulta curta usando a API, execute uma consulta de forma síncrona e preencha a propriedade QueryRequest. Especifique a propriedade jobCreationMode e defina o valor como JOB_CREATION_OPTIONAL.

Verifique a resposta. Se jobComplete for igual a true e jobReference estiver vazio, leia os resultados do campo rows. Também é possível receber o queryId da resposta.

Se jobRefernence estiver presente, você poderá verificar em jobCreationReason por que um job foi criado pelo BigQuery. Pesquise os resultados chamando getQueryResults. Pesquisar até jobComplete igual a true. Verifique se há erros e avisos na lista errors.

Java

Versão disponível: 2.37.1 e mais recentes

Requer a definição da variável de ambiente QUERY_PREVIEW_ENABLED=true.

Exemplo: Linux ou macOS

    export QUERY_PREVIEW_ENABLED=TRUE
  

Exemplo: Windows

    $env:QUERY_PREVIEW_ENABLED=TRUE
  

Antes de testar esta amostra, siga as instruções de configuração do Java 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 em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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.TableResult;

// Sample demonstrating short mode query execution.
//
// While this feature is still in preview, it is controlled by
// setting the environment variable QUERY_PREVIEW_ENABLED=TRUE
// to request short mode execution.
public class QueryShortMode {

  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";
    queryShortMode(query);
  }

  public static void queryShortMode(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();

      // 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());
    }
  }
}

Para executar uma consulta com um proxy, consulte Como configurar um proxy.

Python

Versão disponível: 3.21.0 e mais recentes

Requer a definição da variável de ambiente QUERY_PREVIEW_ENABLED=true.

Exemplo: Linux ou macOS

    export QUERY_PREVIEW_ENABLED=TRUE
  

Exemplo: Windows

    $env:QUERY_PREVIEW_ENABLED=TRUE
  

Antes de testar esta amostra, siga as instruções de configuração do 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 em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

# This example demonstrates issuing a query that may be run in short query mode.
#
# To enable the short query mode preview feature, the QUERY_PREVIEW_ENABLED
# environmental variable should be set to `TRUE`.
from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.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.  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 in short mode.  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"]))

Nó

Versão disponível: 7.6.1 e mais recentes

Requer a definição da variável de ambiente QUERY_PREVIEW_ENABLED=true.

Exemplo: Linux ou macOS

    export QUERY_PREVIEW_ENABLED=TRUE
  

Exemplo: Windows

    $env:QUERY_PREVIEW_ENABLED=TRUE
  

Antes de testar esta amostra, siga as instruções de configuração do Node.js 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 em Node.js.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

// Demonstrates issuing a query that may be run in short query mode.
// To enable the short query mode preview feature, the QUERY_PREVIEW_ENABLED
// environmental variable should be set to `TRUE`.

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

async function queryShortMode() {
  // 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(sqlQuery);

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

Go

Versão disponível: 1.58.0 e mais recentes

Requer a definição da variável de ambiente QUERY_PREVIEW_ENABLED=true.

Exemplo: Linux ou macOS

    export QUERY_PREVIEW_ENABLED=TRUE
  

Exemplo: Windows

    $env:QUERY_PREVIEW_ENABLED=TRUE
  

Antes de testar esta amostra, siga as instruções de configuração do 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 em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"
	"io"

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

// queryShortMode demonstrates issuing a query that may be run in short query mode.
//
// To enable the short query mode preview feature, the QUERY_PREVIEW_ENABLED
// environmental variable should be set to `TRUE`.
func queryShortMode(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: %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 short 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

Versão disponível: JDBC v1.6.1

Exige a configuração de JobCreationMode=2 na string de conexão.

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

Observação: é possível anexar LogLevel=6;LogPath=log.txt à string de conexão para ativar o registro de nível TRACE e extrair informações de solução de problemas, incluindo queryId, se necessário.

Driver ODBC

Versão disponível: ODBC v3.0.7.1016

Requer a configuração JobCreationMode=2 no arquivo .ini.

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

Observação: é possível anexar LogLevel=6 e LogPath=log.txt ao arquivo .ini para ativar o registro de nível detalhado e extrair informações de solução de problemas, incluindo queryId, se necessário.

Cotas

Para informações sobre cotas relacionadas a consultas interativas e em lote, consulte Jobs de consulta.

Monitorar consultas

É possível receber informações sobre as consultas enquanto elas são executadas usando o Explorer de jobs ou consultando a visualização INFORMATION_SCHEMA.JOBS_BY_PROJECT.

Simulação

Uma simulação no BigQuery fornece as seguintes informações:

• estimativa de cobranças no modo sob demanda
• validação da sua consulta
• bytes aproximados processados pela consulta no modo de capacidade

Simulações não usam slots de consulta, e você não é cobrado por realizar uma simulação. Use a estimativa retornada para calcular os custos da consulta na calculadora de preços.

Observação: uma simulação de uma consulta federada que usa uma fonte de dados externa pode relatar um limite inferior de 0 bytes de dados, mesmo que as linhas sejam retornadas. Isso ocorre porque a quantidade de dados processados da tabela externa não pode ser determinada até que a consulta real seja concluída. Executar a consulta federada ainda gera custos para o processamento desses dados.

Executar uma simulação

Para executar uma simulação, faça o seguinte:

Console

1. Acesse a página do BigQuery.

   Acessar o BigQuery

2. Digite a consulta no Editor de consultas.

   Se a consulta for válida, uma marca de seleção será exibida junto com a quantidade de dados que serão processados pela consulta. Se a consulta for inválida, um ponto de exclamação será exibido com uma mensagem de erro.

bq

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'
 

Para uma consulta válida, o comando produz a seguinte resposta:

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

Observação: se a consulta processar uma pequena quantidade de dados, talvez seja necessário converter os bytes processados de KB para MB. Esta é a menor medida usada pela calculadora de preços.

API

Para executar uma simulação usando a API, envie um job de consulta com dryRun definido como true no tipo JobConfiguration.

Go

Antes de testar esta amostra, siga as instruções de configuração do 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 em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Antes de testar esta amostra, siga as instruções de configuração do Java 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 em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Antes de testar esta amostra, siga as instruções de configuração do Node.js 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 em Node.js.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Antes de testar esta amostra, siga as instruções de configuração do PHP 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 em PHP.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Defina 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 do 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 em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

A seguir

• Saiba como gerenciar jobs de consulta.
• Saiba como acessar o histórico de consultas.
• Saiba como salvar e compartilhar consultas.
• Saiba mais sobre filas de consulta.