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.

Consultas interativas x em lote

No BigQuery, é possível executar dois tipos de consultas:

Jobs de consulta interativa, que são jobs executados pelo BigQuery sob demanda.
Jobs de consulta em lote, que são jobs que o BigQuery aguarda para executar até que os recursos de computação inativos estejam disponíveis.

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.

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 como conceder papéis, consulte Gerenciar acesso.

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

O erro a seguir ocorre quando um princípio não tem permissão para criar jobs de consulta no projeto: Access Denied: Project [project_id]: User does not have bigquery.jobs.create permission in project [project_id].

Resolução: confirme se você tem a permissão bigquery.jobs.create no projeto em que está fazendo a consulta. Essa permissão é necessária além de quaisquer permissões necessárias para 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

Acessar a página do BigQuery.

Acessar o BigQuery
Clique em Criar uma nova consulta.
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;
```
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.
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.
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.
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.
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

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

Para mais informações, consulte Consultas interativas x em lote.

Executar uma consulta em lote

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

Console

Acessar a página do BigQuery.

Acessar o BigQuery
Clique em Criar uma nova consulta.
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;
```
Clique em Mais e, depois, em Configurações de consulta.
Na seção Gerenciamento de recursos, selecione Batch.
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.
Clique em Save.
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).
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.
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

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

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

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.

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

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

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

Para mais informações, consulte Consultas interativas x em lote.

Cotas

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

Conferir o número de consultas interativas e em lote

É possível conferir o número de consultas interativas e em lote usando a visualização INFORMATION_SCHEMA.JOBS_BY_PROJECT. O exemplo a seguir usa a visualização INFORMATION_SCHEMA.JOBS_BY_PROJECT para conferir o número de consultas interativas e em lote que foram executadas nas últimas sete horas:

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

A visualização INFORMATION_SCHEMA.JOBS_BY_PROJECT usa o campo priority para indicar se uma consulta é INTERACTIVE ou BATCH. Para mais informações, consulte Esquema.

Executar uma 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
tamanho aproximado e complexidade da 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.

Fazer simulações

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

Console

Acesse a página do BigQuery.

Acessar o BigQuery
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.

API

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

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

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

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

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

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.