Como usar resultados de consulta armazenados em cache

Neste documento, você verá como usar no BigQuery resultados armazenados em cache.

Visão geral

O BigQuery grava todos os resultados de consulta em uma tabela. Ela é explicitamente identificada pelo usuário (tabela de destino) ou é uma tabela temporária de resultados armazenados em cache. Essas tabelas temporárias são mantidas por projeto e por usuário. Elas não geram custos de armazenamento. No entanto, ao gravar os resultados da consulta em uma tabela permanente, haverá cobrança pelo armazenamento dos dados.

Todos os resultados de consultas, incluindo 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 limitações a seguir:

  • 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 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 instruçõ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, é possível que atributos como a propriedade defaultTableExpirationMs no nível do conjunto de dados eliminem 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 por 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, no Console do Cloud, na IU clássica da Web, na linha de comando ou na API;
  • se qualquer uma das tabelas referenciadas ou visualizações lógicas tiver sido alterada desde o armazenamento dos resultados em cache;
  • quando qualquer uma das tabelas referenciadas pela consulta tiver recebido recentemente inserções de streaming (um buffer de streaming é anexado à tabela), mesmo que não chegue nenhuma linha nova;
  • se a consulta usar funções não determinísticas. 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 uma 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 os melhores possíveis 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 bigquery.dataOwner a esse conjunto. O acesso bigquery.dataOwner concede controle total sobre o conjunto de dados apenas ao usuário que executou o job. Isso inclui 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.

O usuário que executa a consulta tem acesso total ao conjunto de dados e à tabela de resultados em cache. No entanto, 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 Cloud e na IU clássica da Web do BigQuery. Use a CLI ou a API para listar conjuntos de dados anônimos e auditar controles de acesso a eles.

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 de consulta como false.

Para desativar a opção Usar resultados em cache, siga estas etapas:

Console

  1. Abra o Console do Cloud.
    Acessar o Console do Cloud

  2. Clique em Escrever nova consulta.

  3. Insira uma consulta SQL 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.

    Opção de resultados armazenados em cache

IU clássica

  1. Acesse a versão clássica da 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 na área de texto Nova consulta.

  4. Clique em Mostrar opções.

  5. Desmarque Usar resultados em cache.

Opção de resultados armazenados em cache

CLI

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 atuais:

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

API

Para processar uma consulta sem usar os resultados armazenados em cache atuais, defina a propriedade useQueryCache como false na configuração do job de query.

Go

Antes de testar essa 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.

import (
	"context"
	"fmt"
	"io"

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

// queryDisableCache demonstrates issuing a query and requesting that the query cache is bypassed.
func queryDisableCache(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 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"

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

Para processar uma consulta sem usar os resultados armazenados em cache atuais, defina o uso do cache de consulta como false ao criar um QueryJobConfiguration (páginas em inglês).

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

Node.js

Antes de testar essa amostra, siga as instruções de configuração para 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 do BigQuery para 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 bigquery = 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 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));
}

Python

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

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.QueryJobConfig(use_query_cache=False)
sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""
query_job = client.query(sql, job_config=job_config)  # Make an API request.

for row in query_job:
    print(row)

Como garantir o uso do cache

Ao usar a função jobs.insert para executar uma consulta, é possível causar a falha de um job de consulta, a menos que os resultados armazenados em cache possam ser usados pelas configurações da propriedade createDisposition da configuração do job de copy como CREATE_NEVER.

Se não houver resultado de consulta no cache, o erro NOT_FOUND será 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 Cloud ou a IU clássica da Web do BigQuery, a string de resultados não conterá informações sobre o número de bytes processados e exibirá a mensagem “armazenado em cache”.

    Indicador de cache na IU

  • Se você estiver usando a API do BigQuery, a propriedade cacheHit no resultado da consulta será definida como true.

Impacto da segurança no nível da coluna

Por padrão, o BigQuery armazena em cache os resultados da consulta por 24 horas, observando-se as exceções anteriores. O cache de 24 horas também se aplica a consultas de dados protegidos por segurança no nível da coluna, que usa tags de política. Uma alteração como remover um grupo ou um usuário do papel Leitor de controle granular do Data Catalog usado para uma tag de política não invalida o cache de 24 horas. Uma alteração no grupo de controle de acesso Leitor de controle granular do Data Catalog propriamente dito é propagada imediatamente, mas a alteração não invalida o cache.

O impacto disso é que, caso o usuário tenha realizado uma consulta, os resultados dela permanecem visíveis na tela. O usuário também pode recuperar esses resultados do cache, mesmo que tenha perdido o acesso aos dados nas últimas 24 horas.

Nas 24 horas após um usuário ser removido do papel Leitor de controle granular do Data Catalog para uma tag da política, ele só terá acesso aos dados armazenados em cache que já tinha permissão para ver antes. Se forem adicionadas linhas à tabela, o usuário não as verá, mesmo que os resultados sejam armazenados em cache.