Gerenciar visualizações materializadas

Neste documento, descrevemos como gerenciar visualizações materializadas no BigQuery.

O gerenciamento do BigQuery de visualizações materializadas inclui as seguintes operações:

• Alterar visualizações materializadas
• Listar visualizações materializadas
• Receber informações sobre visualizações materializadas
• Excluir visualizações materializadas
• Atualizar visualizações materializadas

Para mais informações sobre visualizações materializadas, consulte:

• Introdução às visualizações materializadas
• Criar visualizações materializadas
• Usar visualizações materializadas
• Monitorar visualizações materializadas

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedam aos usuários as permissões necessárias para realizar cada tarefa deste documento. As permissões necessárias para executar uma tarefa (se houver) são listadas na seção "Permissões necessárias".

Alterar visualizações materializadas

É possível alterar uma visualização materializada usando o Console do Google Cloud ou a ferramenta de linha de comando bq usando a linguagem de definição de dados (DDL) com ALTER MATERIALIZED VIEW e SET OPTIONS. Para ver uma lista de opções de visualização materializadas, consulte materialized_view_set_options_list.

Veja a seguir um exemplo que define enable_refresh a true. Ajuste conforme necessário para seu caso de uso.

Permissões necessárias

Para alterar visualizações materializadas, você precisa das permissões de IAM bigquery.tables.get e bigquery.tables.update.

Cada um dos seguintes papéis predefinidos do IAM inclui as permissões necessárias para alterar uma visualização materializada:

• bigquery.dataEditor
• bigquery.dataOwner
• bigquery.admin

Para mais informações sobre o BigQuery Identity and Access Management (IAM), consulte Papéis e permissões predefinidos.

SQL

Para mudar uma visualização materializada, use a instrução DDL ALTER MATERIALIZED VIEW SET OPTIONS:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   ALTER MATERIALIZED VIEW PROJECT.DATASET.MATERIALIZED_VIEW
   SET OPTIONS (enable_refresh = true);
   

   Substitua:

   • PROJECT: o nome do projeto que contém a visualização materializada.
   • DATASET: o nome do conjunto de dados que contém a visualização materializada.
   • MATERIALIZED_VIEW: o nome da visualização materializada que você quer mudar.

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Execute o comando bq update:

bq update \
--enable_refresh=true \
--refresh_interval_ms= \
PROJECT.DATASET.MATERIALIZED_VIEW

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.MaterializedViewDefinition;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;

// Sample to update materialized view
public class UpdateMaterializedView {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String materializedViewName = "MY_MATERIALIZED_VIEW_NAME";
    updateMaterializedView(datasetName, materializedViewName);
  }

  public static void updateMaterializedView(String datasetName, String materializedViewName) {
    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();

      TableId tableId = TableId.of(datasetName, materializedViewName);

      // Get existing materialized view
      Table table = bigquery.getTable(tableId);
      MaterializedViewDefinition materializedViewDefinition = table.getDefinition();
      // Update materialized view
      materializedViewDefinition
          .toBuilder()
          .setEnableRefresh(true)
          .setRefreshIntervalMs(1000L)
          .build();
      table.toBuilder().setDefinition(materializedViewDefinition).build().update();
      System.out.println("Materialized view updated successfully");
    } catch (BigQueryException e) {
      System.out.println("Materialized view was not updated. \n" + e.toString());
    }
  }
}

Listar visualizações materializadas

É possível listar as visualizações materializadas usando o Console do Google Cloud, a ferramenta de linha de comando bq ou a API BigQuery.

Permissões necessárias

Para listar visualizações materializadas em um conjunto de dados, você precisa da permissão bigquery.tables.list do IAM.

Cada um dos papéis predefinidos do IAM a seguir inclui as permissões necessárias para listar as visualizações materializadas em um conjunto de dados:

• roles/bigquery.user
• roles/bigquery.metadataViewer
• roles/bigquery.dataViewer
• roles/bigquery.dataOwner
• roles/bigquery.dataEditor
• roles/bigquery.admin

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

O processo para listar visualizações materializadas é idêntico ao processo de listagem de tabelas. Para listar as visualizações materializadas em um conjunto de dados:

Console

1. No painel Explorer, expanda o projeto e selecione um conjunto de dados.

2. Percorra a lista para ver as tabelas no conjunto de dados. Tabelas, visualizações e visualizações materializadas são identificadas por ícones diferentes.

   

bq

Emita o comando bq ls. A sinalização --format pode ser usada para controlar a saída. Se estiver listando visualizações materializadas em um projeto diferente do seu projeto padrão, adicione o ID do projeto ao conjunto de dados no seguinte formato: project_id:dataset.

bq ls --format=pretty project_id:dataset

Em que:

• project_id é o ID do projeto;
• dataset é o nome do conjunto de dados.

Quando você executa o comando, o campo Type exibe o tipo de tabela. Exemplo:

+-------------------------+--------------------+----------------------+-------------------+
|         tableId         | Type               |        Labels        | Time Partitioning |
+-------------------------+--------------------+----------------------+-------------------+
| mytable                 | TABLE              | department:shipping  |                   |
| mymatview               | MATERIALIZED_VIEW  |                      |                   |
+-------------------------+--------------------+----------------------+-------------------+

Exemplos:

Digite o comando a seguir para listar visualizações materializadas no conjunto de dados mydataset no seu projeto padrão.

bq ls --format=pretty mydataset

Digite o comando a seguir para listar visualizações materializadas no conjunto de dados mydataset em myotherproject.

bq ls --format=pretty myotherproject:mydataset

API

Para listar visualizações materializadas usando a API, utilize o método tables.list.

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

// listTables demonstrates iterating through the collection of tables in a given dataset.
func listTables(w io.Writer, projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ts := client.Dataset(datasetID).Tables(ctx)
	for {
		t, err := ts.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Table: %q\n", t.TableID)
	}
	return nil
}

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

# TODO(developer): Set dataset_id to the ID of the dataset that contains
#                  the tables you are listing.
# dataset_id = 'your-project.your_dataset'

tables = client.list_tables(dataset_id)  # Make an API request.

print("Tables contained in '{}':".format(dataset_id))
for table in tables:
    print("{}.{}.{}".format(table.project, table.dataset_id, table.table_id))

Receber informações sobre visualizações materializadas

É possível conseguir informações sobre uma visualização materializada usando o SQL, a ferramenta de linha de comando bq ou a API BigQuery.

Permissões necessárias

Para consultar informações sobre uma visualização materializada, você precisa das seguintes permissões de gerenciamento de identidade e acesso (IAM):

• bigquery.tables.get
• bigquery.tables.list
• bigquery.routines.get
• bigquery.routines.list

Cada um dos seguintes papéis predefinidos do IAM inclui as permissões anteriores:

• roles/bigquery.metadataViewer
• roles/bigquery.dataViewer
• roles/bigquery.admin

Para mais informações sobre as permissões do BigQuery, consulte Controle de acesso com o IAM.

Para receber informações sobre uma visualização materializada, incluindo qualquer réplica de visualização materializada dependentes:

SQL

Para informações sobre visualizações materializadas, consulte a visualização INFORMATION_SCHEMA.TABLES:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   SELECT * FROM PROJECT_ID.DATASET_ID.INFORMATION_SCHEMA.TABLES
   WHERE table_type = 'MATERIALIZED VIEW';
   

   Substitua:

   • PROJECT_ID: o nome do projeto que contém as visualizações materializadas.
   • DATASET_ID: o nome do conjunto de dados que contém as visualizações materializadas

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use o comando bq show (em inglês).

bq show --project=project_id --format=prettyjson dataset.materialized_view

Substitua:

• project_id: o ID do projeto; Você só precisa incluir essa flag para receber informações sobre uma visualização materializada em um projeto diferente do projeto padrão.
• dataset: o nome do conjunto de dados que contém a visualização materializada.
• materialized_view: o nome da visualização materializada sobre a qual você quer mais informações.

Exemplo:

Digite o seguinte comando para mostrar informações sobre a visualização materializada my_mv no conjunto de dados report_views no projeto myproject.

bq show --project=myproject --format=prettyjson report_views.my_mv

API

Para receber informações da visualização materializada usando a API, chame o método tables.get.

Excluir visualizações materializadas

É possível excluir uma visualização materializada por meio do Console do Cloud, da ferramenta de linha de comando bq ou da API.

Cuidado: a exclusão de uma visualização materializada não pode ser desfeita.

A exclusão de uma visualização materializada também exclui todas as permissões associadas a ela. Ao recriar uma visualização materializada excluída, você também precisa reconfigurar manualmente as permissões de acesso anteriormente associadas a ela.

Permissões necessárias

Para criar visualizações materializadas, você precisa da permissão bigquery.tables.delete do IAM.

Cada um dos papéis predefinidos do IAM a seguir inclui as permissões necessárias para excluir uma visualização materializada:

• bigquery.dataEditor
• bigquery.dataOwner
• bigquery.admin

Para mais informações sobre o BigQuery Identity and Access Management (IAM), consulte Papéis e permissões predefinidos.

SQL

Para excluir uma visualização materializada, use a instrução DDL DROP MATERIALIZED VIEW:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   DROP MATERIALIZED VIEW PROJECT.DATASET.MATERIALIZED_VIEW;
   

   Substitua:

   • PROJECT: o nome do projeto que contém a visualização materializada.
   • DATASET: o nome do conjunto de dados que contém a visualização materializada.
   • MATERIALIZED_VIEW: o nome da visualização materializada que você quer excluir

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use o comando bq rm para excluir a visualização materializada.

API

Chame o método tables.delete e especifique valores para os parâmetros projectId, datasetId e tableId:

• Atribua o parâmetro projectId ao ID do projeto.
• Atribua o parâmetro datasetId ao ID do conjunto de dados.
• Atribua o parâmetro tableId ao ID da tabela da visualização materializada que será excluída.

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

// Sample to delete materialized view
public class DeleteMaterializedView {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String materializedViewName = "MY_MATERIALIZED_VIEW_NAME";
    deleteMaterializedView(datasetName, materializedViewName);
  }

  public static void deleteMaterializedView(String datasetName, String materializedViewName) {
    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();

      TableId tableId = TableId.of(datasetName, materializedViewName);

      boolean success = bigquery.delete(tableId);
      if (success) {
        System.out.println("Materialized view deleted successfully");
      } else {
        System.out.println("Materialized view was not found");
      }
    } catch (BigQueryException e) {
      System.out.println("Materialized view was not found. \n" + e.toString());
    }
  }
}

Cuidado: se você excluir a tabela base de uma visualização materializada sem excluir primeiro a visualização materializada, qualquer atualização ou consulta da visualização materializada falhará. Se decidir recriar a tabela base, também será necessário recriar a visualização materializada.

Atualizar visualizações materializadas

A atualização de uma visualização materializada atualiza os resultados armazenados em cache dela para refletir o estado atual das tabelas base. Sempre que possível, o BigQuery lê apenas as alterações desde a última vez em que a visualização foi atualizada. Os dados transmitidos recentemente podem não ser incluídos durante uma atualização da visualização materializada, mas as consultas sempre leem dados transmitidos, independentemente de uma visualização materializada ser usada. Esta seção explica como fazer o seguinte:

• Configurar a atualização automática
• Atualizar manualmente uma visualização materializada

Observação: se você excluir uma tabela base sem excluir primeiro a visualização materializada, as atualizações da visualização materializada não funcionarão. Para recriar uma tabela base, também é preciso recriar a visualização materializada.

Atualização automática

Por padrão, as visualizações materializadas são atualizadas automaticamente em até 5 minutos após uma alteração na tabela base, mas não mais do que a cada 30 minutos. Exemplos de alterações incluem inserções ou exclusões de linha.

Você pode usar o limite de frequência de atualização para gerenciar os custos e o desempenho de consultas das visualizações materializadas. Independentemente do limite de atualização, as visualizações materializadas sempre retornam dados atualizados.

A atualização automática pode ser ativada ou desativada a qualquer momento. O job de atualização automática é executado pela conta do sistema [e-mail] e aparece no histórico de jobs do projeto de visualização materializada.

Ativar e desativar a atualização automática

Para desativar a atualização automática ao criar uma tabela, defina enable_refresh como false.

CREATE MATERIALIZED VIEW PROJECT.DATASET.MATERIALIZED_VIEW
PARTITION BY RANGE_BUCKET(column_name, buckets)
OPTIONS (enable_refresh = false)
AS SELECT ...

Para uma visualização materializada existente, é possível modificar o valor enable_refresh usando ALTER MATERIALIZED VIEW.

ALTER MATERIALIZED VIEW PROJECT.DATASET.MATERIALIZED_VIEW
SET OPTIONS (enable_refresh = true);

Observação: ativar a atualização automática aciona imediatamente uma atualização automática da visualização materializada.

Definir o limite de frequência

É possível configurar um limite de frequência para a execução de atualizações automáticas. Por padrão, as visualizações materializadas são atualizadas a intervalos de 30 minutos.

O limite de frequência de atualização pode ser alterado a qualquer momento.

Para configurar um limite de frequência de atualização ao criar uma visualização materializada, defina refresh_interval_minutes em DDL (ou refresh_interval_ms na API e na ferramenta de linha de comando bq) para o valor desejado.

CREATE MATERIALIZED VIEW PROJECT.DATASET.MATERIALIZED_VIEW
OPTIONS (enable_refresh = true, refresh_interval_minutes = 60)
AS SELECT ...

Da mesma forma, é possível definir o limite de frequência ao modificar uma tabela. O exemplo a seguir pressupõe que você já tenha ativado a atualização automática e queira apenas alterar o limite de frequência:

ALTER MATERIALIZED VIEW PROJECT.DATASET.MATERIALIZED_VIEW
SET OPTIONS (refresh_interval_minutes = 60);

O limite mínimo de frequência de atualização é de 1 minuto. O limite máximo de frequência de atualização é de sete dias.

É possível atualizar manualmente uma visualização materializada a qualquer momento, e seu tempo não está sujeito ao limite de frequência.

Melhor esforço

A atualização automática é realizada da melhor maneira possível. O BigQuery tenta iniciar uma atualização em até cinco minutos após uma alteração na tabela base, supondo que a atualização anterior tenha sido feita há mais de 30 minutos. No entanto, isso não significa que a atualização começará nesse prazo e nem garante quando ela estará concluída.

Observação:A consulta de visualizações materializadas reflete o estado mais recente da tabela base, mas se a visualização não foi atualizada recentemente, o custo/latência da consulta poderá ser maior que o esperado.

A atualização automática é tratada de maneira semelhante a uma consulta com prioridade batch. Se o projeto da visualização materializada não tiver a capacidade no momento, a atualização será atrasada. Se o projeto tiver muitas visualizações com atualizações caras, cada uma delas pode ter um atraso significativo em relação à tabela base.

Atualização manual

É possível atualizar manualmente uma visualização materializada a qualquer momento.

Permissões necessárias

Para atualizar manualmente as visualizações materializadas, você precisa das permissões bigquery.tables.getData, bigquery.tables.update e bigquery.tables.updateData do IAM.

Cada um dos seguintes papéis predefinidos do IAM inclui as permissões necessárias para atualizar manualmente uma visualização materializada:

• bigquery.dataEditor
• bigquery.dataOwner
• bigquery.admin

Para mais informações sobre o BigQuery Identity and Access Management (IAM), consulte Papéis e permissões predefinidos.

Para atualizar os dados na visualização materializada, chame o procedimento do sistema BQ.REFRESH_MATERIALIZED_VIEW. Quando esse procedimento é chamado, o BigQuery identifica as alterações realizadas na tabela base e as aplica à visualização materializada. A consulta que executará BQ.REFRESH_MATERIALIZED_VIEW termina quando a atualização estiver concluída.

CALL BQ.REFRESH_MATERIALIZED_VIEW('PROJECT.DATASET.MATERIALIZED_VIEW');

Atenção: não realize mais de uma atualização por vez. Se executar várias atualizações simultaneamente para a mesma visualização materializada, somente a primeira será concluída.

Monitorar visualizações materializadas

É possível receber informações sobre visualizações materializadas e sobre os respectivos jobs de atualização usando a API BigQuery. Para mais informações, consulte Monitorar visualizações materializadas.