Como usar resultados de consulta armazenados em cache

Neste documento, mostramos como usar resultados em cache no BigQuery.

Visão geral

O BigQuery grava todos os resultados de consulta em uma tabela. A tabela é explicitamente identificada pelo usuário (a tabela de destino) ou é uma tabela temporária de resultados armazenados em cache. As tabelas temporárias de resultados armazenados em cache são mantidas por projeto e por usuário. Não há custos de armazenamento para tabelas temporárias, mas se você gravar os resultados da consulta em uma tabela permanente, será cobrado pelo armazenamento dos dados.

Todos os resultados de consultas, incluindo consultas interativas e em lote, são armazenados em cache em tabelas temporárias por aproximadamente 24 horas, com algumas exceções.

Limitações

O uso do cache de consulta está sujeito às seguintes limitações:

  • Quando você executa uma consulta duplicada, o BigQuery tenta reutilizar os resultados armazenados em cache. Para recuperar dados do cache, o texto da consulta duplicada precisa ser exatamente o mesmo da consulta original.
  • Para que os resultados da consulta permaneçam na tabela de resultados armazenados em cache, o conjunto de resultados precisa ser menor que o tamanho máximo da resposta. Para mais informações sobre como gerenciar conjuntos grandes de resultados, consulte Como retornar resultados extensos de consulta.
  • Não é possível apontar para tabelas de resultados armazenados em cache com declarações DML.
  • Embora seja permitido pela semântica atual, o uso de resultados armazenados em cache como entrada para jobs dependentes não é recomendado. Por exemplo, não convém enviar jobs de consulta que recuperam resultados da tabela de cache. Em vez disso, grave os resultados em uma tabela de destino nomeada. Para permitir uma limpeza fácil, recursos como a propriedade defaultTableExpirationMs de conjunto de dados poderão expirar os dados automaticamente após o prazo especificado.

Preços e cotas

Quando os resultados da consulta são recuperados de uma tabela de resultados armazenados em cache, a propriedade statistics.query.cacheHit de estatísticas do job é retornada como true e você não é cobrado pela consulta. Embora não haja cobrança em consultas que usam resultados armazenados em cache, elas estão sujeitas às políticas de cota do BigQuery. Além de reduzir custos, essas consultas são significativamente mais rápidas porque o BigQuery não precisa computar o conjunto de resultados.

Exceções para consultar resultados armazenados em cache

Os resultados de consultas não são armazenados em cache:

  • Quando uma tabela de destino é especificada na configuração do job, o Console do GCP, a interface de usuário da Web clássica, a linha de comando ou a API.
  • Se qualquer uma das tabelas referenciadas ou visualizações lógicas foi alterada desde que os resultados foram armazenados em cache.
  • quando qualquer uma das tabelas referenciadas pela consulta recebeu recentemente inserções de streaming (um buffer de streaming é anexado à tabela), mesmo que não chegue nenhuma linha nova;
  • se a consulta usa funções que não são deterministas, por exemplo, funções de data e hora, como CURRENT_TIMESTAMP() e NOW(), e outras funções, como CURRENT_USER(), retornam valores diferentes dependendo de quando a consulta é executada;
  • se você estiver consultando várias tabelas usando um caractere curinga;
  • se os resultados armazenados em cache expirarem. A duração comum do cache é de 24 horas, mas os resultados são de esforço máximo e podem ser invalidados antes;
  • se a consulta for executada em uma fonte de dados externa.

Como os resultados em cache são armazenados

Quando você executa uma consulta, uma tabela de resultados armazenados em cache temporária é criada em um conjunto de dados especial denominado "conjunto de dados anônimo". Ao contrário dos conjuntos de dados regulares, que herdam as permissões do modelo de hierarquia de recursos do IAM (permissões de projeto e de organização), o acesso a conjuntos de dados anônimos é restrito ao proprietário do conjunto de dados. O proprietário de um conjunto de dados anônimo é o usuário que executou a consulta que produziu o resultado armazenado em cache.

Quando um conjunto de dados anônimo é criado, o usuário que executa o job de consulta recebe explicitamente o acesso OWNER ao conjunto de dados anônimo. O acesso OWNER dá o controle total sobre o conjunto de dados apenas ao usuário que executou o job de consulta. Isso inclui controle total sobre as tabelas de resultados armazenados em cache no conjunto de dados anônimo. Se você pretende compartilhar resultados de consultas, não use os resultados armazenados em cache em um conjunto de dados anônimo. Em vez disso, grave os resultados em uma tabela de destino nomeada.

Embora o usuário que execute a consulta tenha acesso total ao conjunto de dados e à tabela de resultados armazenados em cache, não é recomendável utilizá-los como entradas para jobs dependentes.

Os nomes de conjuntos de dados anônimos começam com um sublinhado. Isso os oculta da lista de conjuntos de dados no Console do GCP e na interface de usuário da Web clássica do BigQuery. É possível listar conjuntos de dados anônimos e auditar os respectivos controles de acesso usando a CLI ou a API.

Como desativar a recuperação de resultados armazenados em cache

A opção Usar resultados em cache reutiliza os resultados de uma execução anterior da mesma consulta, exceto quando as tabelas que estão sendo consultadas são alteradas. O uso de resultados armazenados em cache é útil somente no caso de consultas repetidas. Para novas consultas, a opção Usar resultados em cache não tem nenhum efeito, embora seja ativada por padrão.

Quando você repete uma consulta com a opção Usar resultados em cache desativada, o resultado atual armazenado em cache é substituído. Para isso, o BigQuery precisa computar o resultado da consulta, e você é cobrado por ela. Esse recurso é útil principalmente em cenários comparativos de mercado.

Para desativar a recuperação de resultados armazenados em cache e forçar a avaliação ativa de um job de consulta, defina a propriedade configuration.query.useQueryCache do job como false.

Para desativar a opção Usar resultados em cache:

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.

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

  4. Clique em Mais e selecione Configurações de consulta.

    Configurações de consulta

  5. Em Preferência de cache, desmarque Usar resultados em cache.

    Resultados em cache

IU clássica

  1. Acesse a IU da Web clássica 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 em Mostrar opções.

  5. Desmarque Usar resultados em cache.

Linha de comando

Use a sinalização nouse_cache para substituir o cache de consulta. O exemplo a seguir força o BigQuery a processar a consulta sem usar os resultados armazenados em cache existentes:

 bq --location=US query --nouse_cache --batch "SELECT name,count FROM mydataset.names_2013 WHERE gender = 'M' ORDER BY count DESC LIMIT 6"

API

Para processar uma consulta sem usar os resultados atuais armazenados em cache, defina a propriedade useQueryCache como false.

Go

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

// 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 corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;")
q.DisableQueryCache = 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
}
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)
}

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 BigQuery Node.js.

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

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

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

  const query = `SELECT corpus
    FROM \`bigquery-public-data.samples.shakespeare\`
    GROUP BY corpus`;
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    useQueryCache: false,
  };

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

Java

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

Para processar uma consulta sem usar os resultados armazenados em cache atuais, defina o uso do cache de consulta como false 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)
        // Disable the query cache to force live query evaluation.
        .setUseQueryCache(false)
        .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");
}

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.

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

job_config = bigquery.QueryJobConfig()
job_config.use_query_cache = False
sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""
query_job = client.query(
    sql,
    # Location must match that of the dataset(s) referenced in the query.
    location="US",
    job_config=job_config,
)  # API request

# Print the results.
for row in query_job:  # API request - fetches results
    print(row)

Como garantir o uso do cache

Se você usar a função jobs.insert() para executar uma consulta, será possível forçar um job de consulta a falhar, a menos que os resultados armazenados em cache possam ser usados ao definir a propriedade createDisposition da configuração do job como CREATE_NEVER.

Quando não há resultado de consulta no cache, o erro NOT_FOUND é retornado.

Como verificar o uso do cache

Há duas maneiras de determinar se o BigQuery retornou um resultado usando o cache:

  • Se você estiver usando o Console do GCP ou a IU da Web clássica do BigQuery, a string de resultados não contém informações sobre o número de bytes processados e exibe a palavra "em cache".

    Indicador de cache na IU

  • Se a API BigQuery estiver sendo usada, a propriedade cacheHit no resultado da consulta será definida como true.

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

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.