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 do GCP, a IU clássica da Web do BigQuery ou a CLI para carregar, exportar, consultar ou copiar dados, um recurso de job é criado, programado e executado automaticamente. Também é possível criar de maneira programática um job de carregamento, exportação, consulta ou cópia. Quando você faz isso, o job é programado e executado pelo BigQuery.

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, é necessário ter, no mínimo, as permissões bigquery.jobs.create. Para que esse job seja concluído com sucesso, você também precisa ter acesso aos conjuntos de dados que contêm as tabelas ou visualizações referenciadas pela consulta. Para mais informações sobre os controles de acesso aos conjuntos de dados, consulte Como controlar o acesso a conjuntos de dados.

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

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

Além disso, quando um usuário com permissões bigquery.datasets.create cria um conjunto de dados, ele recebe o acesso de bigquery.dataOwner ao conjunto. Com o acesso bigquery.dataOwner, o usuário consegue consultar tabelas e visualizações no conjunto de dados.

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

Como executar 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 o Console do GCP

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

  3. Insira uma consulta SQL válida na área de texto New Query.

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

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

CLI

Insira o comando bq query e inclua o texto da consulta.

Opcional: forneça a sinalização --location e defina o valor como seu 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 Key Management Service para criptografar os dados da tabela de destino;
  • --use_legacy_sql=false para usar a sintaxe 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 essa 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 Tokyo, 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 SQL padrão.

Exemplos:

Insira o comando a seguir para gravar os resultados da consulta interativa em uma tabela de destino denominada mytable em mydataset. O conjunto de dados está no projeto padrão. A consulta recupera dados do conjunto de dados público USA Name Data (em inglês).

bq 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'

Insira o comando a seguir para gravar os resultados da consulta interativa em uma tabela de destino denominada 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úblico USA Name Data (em inglês).

bq 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'

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

Chame getQueryResults para apurar os resultados. Apure até que jobComplete seja 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 saber mais informações, consulte a documentação de referência da API BigQuery 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 este exemplo, 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 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 este exemplo, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para saber 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 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 Node.js. 

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

# 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 este exemplo, 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 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 o Console do GCP

  2. Clique no botão Escrever nova consulta.

    Escrever nova consulta

  3. Insira uma consulta SQL 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 em 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 Batch na seção Query Priority.

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

  7. Clique no botão Run query.

CLI

Insira o comando bq query e inclua o texto da consulta. Especifique a sinalização -- batch para executar uma consulta em lote.

Opcional: 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 Key Management Service para criptografar os dados da tabela de destino;
  • --use_legacy_sql=false para usar a sintaxe 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 essa 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 Tokyo, 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 SQL padrão.

Exemplos:

Insira o comando a seguir para gravar os resultados de consulta em lote em uma tabela de destino denominada mytable em mydataset. O conjunto de dados está no projeto padrão. A consulta recupera dados do conjunto de dados público USA Name Data (em inglês).

bq 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'

Insira o comando a seguir para gravar os resultados de consulta em lote em uma tabela de destino denominada 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úblico USA Name Data (em inglês).

bq 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'

API

Para executar uma consulta usando a API, insira um novo job e preencha a propriedade de configuração de job query. (Opcional) Especifique o local na propriedade location na seção jobReference do recurso de 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 este exemplo, 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 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

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

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