Como executar jobs de consulta interativa e em lote

Neste documento, descrevemos como executar jobs de consulta interativa (sob demanda) e em lote.

Permissões exigidas

Jobs são ações executadas pelo BigQuery em seu nome para carregar, exportar, consultar ou copiar dados.

Quando você usa o console, a IU clássica da Web do BigQuery ou a CLI para carregar, exportar, consultar ou copiar dados, um recurso de job é criado, agendado e executado automaticamente. Também é possível criar de maneira programática um job de carregamento, exportação, consulta ou cópia. Ao criar um job programaticamente, o BigQuery o agenda e executa para você.

Como os jobs podem levar um longo tempo para serem concluídos, eles são executados assincronamente e podem ser pesquisados por status. As ações mais curtas, como listar recursos ou conseguir metadados, não são gerenciadas por um recurso de job.

Para executar um job de consulta, é preciso ter as permissões bigquery.jobs.create. Para que o job de consulta seja concluído com sucesso, o usuário ou grupo também precisa ter acesso ao conjunto de dados que contém as tabelas referenciadas pela consulta.

É possível definir permissões bigquery.jobs.create para envolvidos no projeto com a concessão de qualquer um dos seguintes papéis de IAM predefinidos:

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

Por padrão, se você conceder a um usuário ou grupo o papel bigquery.user para envolvidos no projeto, nenhum acesso será concedido a nenhum conjunto de dados, tabela ou visualização no projeto. O bigquery.user dá aos usuários a capacidade de criar os próprios conjuntos de dados e executar jobs de consulta em conjuntos de dados a que eles tenham acesso. Se você atribuir o papel bigquery.user ou bigquery.jobUser, também precisará atribuir controles de acesso a cada conjunto de dados que o usuário ou grupo precisar acessar e que não tenha sido criado pelo usuário.

Ao atribuir acesso a um conjunto de dados, existem três opções:

O acesso mínimo necessário para que um usuário execute uma consulta é "Pode ver".

Para mais informações sobre papéis do IAM no BigQuery, consulte Controle de acesso.

Como executar consultas interativas

Por padrão, o BigQuery executa jobs de consulta interativa (sob demanda), o que significa que a consulta é executada o mais rápido possível. Essas consultas são realizadas de acordo com o limite de taxa simultânea e o limite de taxa diária.

Os resultados da consulta são sempre salvos em tabelas temporárias ou permanentes. Você pode optar por anexar ou substituir dados em uma tabela existente ou criar uma nova tabela, se não houver nenhuma com o mesmo nome.

Para executar uma consulta interativa que grava em uma tabela temporária:

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar a IU da Web do BigQuery

  2. Clique em Escrever nova consulta.

    Escrever nova consulta

  3. Insira uma consulta SQL do BigQuery válida na área de texto do Editor de consultas.

  4. (Opcional) Para alterar o local de processamento de dados, clique em Mais e, em seguida, clique em Configurações de consulta. Em Local de processamento, clique em Seleção automática e escolha o local dos dados. Por fim, clique em Salvar para atualizar as configurações da consulta.

  5. Clique em Executar.

Isso cria um job de consulta que grava a saída em uma tabela temporária.

IU clássica

  1. Acesse a IU da Web do BigQuery.
    Acessar a IU da Web do BigQuery

  2. Clique em Escrever consulta.

  3. Insira uma consulta SQL válida do BigQuery na área de texto Nova consulta.

  4. Clique em Mostrar opções.

  5. (Opcional) Em Local de processamento, clique em Não especificado e escolha o local dos dados.

  6. Clique em Executar consulta.

Isso cria um job de consulta que grava a saída em uma tabela temporária.

Linha de comando

Digite o comando bq query e inclua o texto da consulta. Forneça a sinalização --location e defina o valor do local.

É possível especificar as sinalizações opcionais a seguir. A lista inclui algumas das sinalizações mais comuns. Para uma lista completa das sinalizações do comando query, consulte bq query na referência da ferramenta de linha de comando bq.

Especifique a sinalização:

  • --destination_table para criar uma tabela permanente com base nos resultados da consulta. Para gravar os resultados da consulta em uma tabela que não esteja no projeto padrão, adicione o código do projeto ao nome do conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET]. Se --destination_table não for especificada, será gerado um job de consulta que grava a saída em uma tabela temporária (cache);
  • --append_table para anexar os resultados da consulta a uma tabela de destino;
  • --destination_kms_key para usar uma chave do Cloud KMS para criptografar os dados da tabela de destino;
  • --use_legacy_sql=false para usar a sintaxe do SQL padrão. É possível definir uma sintaxe padrão para a ferramenta de linha de comando usando o arquivo .bigqueryrc;
  • --label para aplicar um rótulo ao job de consulta no formato [KEY]:[VALUE]. Repita esta sinalização para especificar vários rótulos;
  • --max_rows ou -n para especificar o número de linhas a retornar nos resultados da consulta.
  • --maximum_bytes_billed para limitar os bytes faturados pela consulta. Se a consulta ultrapassar o limite, ela falhará (sem incorrer em cobranças). Se não especificado, os bytes faturados são definidos como o padrão do projeto;
  • --udf_resource para carregar e avaliar um arquivo de código a ser usado como um recurso de função definido pelo usuário. É possível especificar um URI do Cloud Storage ou o caminho para um arquivo de código local. Repita a sinalização para especificar vários arquivos.

Digite o seguinte comando para executar uma consulta interativa usando a sintaxe padrão do SQL:

bq --location=[LOCATION] query --use_legacy_sql=false '[QUERY]'

em que:

  • [LOCATION] é o nome do local em que a consulta é processada. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, poderá definir o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
  • [QUERY] é uma consulta na sintaxe do SQL padrão.

Exemplos:

Digite o comando a seguir para gravar os resultados da consulta interativa em uma tabela de destino chamada mytable em mydataset. O conjunto de dados está no projeto padrão. A consulta recupera dados de um conjunto de dados público do USA Name Data.

bq --location=US query --destination_table mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Digite o comando a seguir para gravar os resultados da consulta interativa em uma tabela de destino chamada mytable em mydataset. O conjunto de dados está em myotherproject, e não no projeto padrão. A consulta recupera dados de uma tabela não particionada: o conjunto de dados públicos do USA Name Data.

bq --location=US query --destination_table myotherproject:mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Para mais informações, consulte Como usar a ferramenta de linha de comando bq.

API

Para executar uma consulta usando a API, insira um novo job e preencha a propriedade jobs#configuration.query. Especifique o local na propriedade location na seção jobReference do recurso do job.

Procure por resultados chamando getQueryResults. Procure até que jobComplete seja 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 do BigQuery para C#. 

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

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

Go

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 do BigQuery para Go. 

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")

q := client.Query(
	"SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " +
		"WHERE state = \"TX\" " +
		"LIMIT 100")
// Location must match that of the dataset(s) referenced in the query.
q.Location = "US"
job, err := q.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}
it, err := job.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Java

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

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig = QueryJobConfiguration.newBuilder(query).build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Node.js

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

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

async function query() {
  // Queries the Shakespeare dataset with the cache disabled.

  // Create a client
  const bigqueryClient = new BigQuery();

  const query = `SELECT name
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 100`;
  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 bigqueryClient.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));
}
query();

PHP

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

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 em Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Python (em inglês). 

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

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

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

Ruby

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

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

Como executar consultas em lote

O BigQuery também oferece consultas em lote. O BigQuery enfileira cada consulta em lote em seu nome e inicia a consulta assim que os recursos ociosos estão disponíveis no pool de recursos compartilhados do BigQuery. Isso geralmente ocorre em poucos minutos. Se o BigQuery não tiver iniciado a consulta em 24 horas, ele altera a prioridade do job para interativa.

As consultas em lote não contam para o limite de taxa simultânea, o que facilita a execução de muitas consultas de uma vez. As consultas em lote usam os mesmos recursos que as consultas interativas (sob demanda). Se você usa consultas de lote e interativas com preços fixos, compartilhe seus slots alocados.

Para executar uma consulta em lote:

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar a IU da Web do BigQuery

  2. Clique no botão Escrever nova consulta.

    Escrever nova consulta

  3. Insira uma consulta SQL do BigQuery válida na área de texto do Editor de consultas.

  4. Clique no botão Mais e depois em Configurações da consulta.

    Configurações de consulta

  5. Selecione a opção Lote na seção Prioridade do job.

    Execução em lote

  6. (Opcional) Em Local de processamento, clique em Não especificado e escolha o local dos dados.

  7. Clique em Salvar para atualizar as configurações da consulta.

  8. Clique no botão Executar.

IU clássica

  1. Acesse a IU da Web do BigQuery.
    Acessar a IU da Web do BigQuery

  2. Clique no botão Escrever consulta.

  3. Insira uma consulta SQL válida do BigQuery na área de texto Nova consulta.

  4. Clique no botão Mostrar opções.

  5. Selecione a opção Em lote na seção Prioridade da consulta.

  6. (Opcional) Em Local de processamento, clique em Não especificado e escolha o local dos dados.

  7. Clique no botão Executar consulta.

Linha de comando

Digite o comando bq query e inclua o texto da consulta. Especifique a sinalização --batch para executar uma consulta em lote. Forneça a sinalização --location e defina o valor do local.

É possível especificar as sinalizações opcionais a seguir. A lista inclui algumas das sinalizações mais comuns. Para uma lista completa das sinalizações do comando query, consulte bq query na referência da ferramenta de linha de comando bq.

Especifique a sinalização:

  • --destination_table para criar uma tabela permanente com base nos resultados da consulta. Para gravar os resultados da consulta em uma tabela que não esteja no projeto padrão, adicione o código do projeto ao nome do conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET]. Se --destination_table não for especificada, será gerado um job de consulta que grava a saída em uma tabela temporária (cache);
  • --append_table para anexar os resultados da consulta a uma tabela de destino;
  • --destination_kms_key para usar uma chave do Cloud KMS para criptografar os dados da tabela de destino;
  • --use_legacy_sql=false para usar a sintaxe do SQL padrão. É possível definir uma sintaxe padrão para a ferramenta de linha de comando usando o arquivo .bigqueryrc;
  • --label para aplicar um rótulo ao job de consulta no formato [KEY]:[VALUE]. Repita esta sinalização para especificar vários rótulos;
  • --max_rows ou -n para especificar o número de linhas a retornar nos resultados da consulta.
  • --maximum_bytes_billed para limitar os bytes faturados pela consulta. Se a consulta ultrapassar o limite, ela falhará (sem incorrer em cobranças). Se não especificado, os bytes faturados são definidos como o padrão do projeto;
  • --udf_resource para carregar e avaliar um arquivo de código a ser usado como um recurso de função definido pelo usuário. É possível especificar um URI do Cloud Storage ou o caminho para um arquivo de código local. Repita a sinalização para especificar vários arquivos.

Digite o seguinte comando para executar uma consulta em lote usando a sintaxe SQL padrão:

bq --location=[LOCATION] query --batch --use_legacy_sql=false '[QUERY]'

em que:

  • [LOCATION] é o nome do local em que a consulta é processada. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, poderá definir o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
  • [QUERY] é uma consulta na sintaxe do SQL padrão.

Exemplos:

Digite o comando a seguir para gravar os resultados de consulta em lote em uma tabela de destino chamada mytable em mydataset. O conjunto de dados está no projeto padrão. A consulta recupera dados de um conjunto de dados público do USA Name Data.

bq --location=US query --batch --destination_table mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Digite o comando a seguir para gravar os resultados de consulta em lote em uma tabela de destino chamada mytable em mydataset. O conjunto de dados está em myotherproject, e não no projeto padrão. A consulta recupera dados de uma tabela não particionada: o conjunto de dados públicos do USA Name Data.

bq --location=US query --batch --destination_table myotherproject:mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Para mais informações, consulte Como usar a ferramenta de linha de comando bq.

API

Para executar uma consulta usando a API, insira um novo job e preencha a propriedade jobs#configuration.query. 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 com o valor definido como BATCH.

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 do BigQuery para Go. 

	// To run this sample, you will need to create (or reuse) a context and
	// an instance of the bigquery client.  For example:
	// import "cloud.google.com/go/bigquery"
	// ctx := context.Background()
	// client, err := bigquery.NewClient(ctx, "your-project-id")
	// Build an aggregate table.
	q := client.Query(`
		SELECT
  			corpus,
  			SUM(word_count) as total_words,
  			COUNT(1) as unique_words
		FROM ` + "`bigquery-public-data.samples.shakespeare`" + `
		GROUP BY corpus;`)
	q.Priority = bigquery.BatchPriority
	q.QueryConfig.Dst = client.Dataset(dstDatasetID).Table(dstTableID)

	// Start the job.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	// Job is started and will progress without interaction.
	// To simulate other work being done, sleep a few seconds.
	time.Sleep(5 * time.Second)
	status, err := job.Status(ctx)
	if err != nil {
		return err
	}

	state := "Unknown"
	switch status.State {
	case bigquery.Pending:
		state = "Pending"
	case bigquery.Running:
		state = "Running"
	case bigquery.Done:
		state = "Done"
	}
	// You can continue to monitor job progress until it reaches
	// the Done state by polling periodically.  In this example,
	// we print the latest status.
	fmt.Printf("Job %s in Location %s currently in state: %s\n", job.ID(), job.Location(), state)

Java

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, veja a documentação de referência da API do BigQuery para Java.

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

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

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

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

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

Python

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

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

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

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

# Check on the progress by getting the job's updated state. Once the state
# is `DONE`, the results are ready.
query_job = client.get_job(
    query_job.job_id, location=location
)  # API request - fetches job
print("Job {} is currently in state {}".format(query_job.job_id, query_job.state))

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
BigQuery
Comentários sobre o produto
Precisa de ajuda? Acesse nossa página de suporte.