Criar visualizações

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

É possível criar uma visualização no BigQuery das seguintes maneiras:

• Usando o Console do Google Cloud.
• usando o comando bq mk da ferramenta de linha de comando bq;
• chamando o método de API tables.insert;
• usando bibliotecas de cliente.
• enviando uma instrução de linguagem de definição de dados (DDL) CREATE VIEW.

Visualizar limitações

As visualizações do BigQuery estão sujeitas às seguintes limitações:

• As visualizações são somente leitura. Por exemplo, não é possível executar consultas que inserem, atualizam ou excluem dados.
• O conjunto de dados que contém a visualização precisa estar no mesmo local que o conjunto de dados que contém as tabelas referenciadas pela visualização.
• Uma referência dentro de uma visualização precisa ser qualificada com um conjunto de dados. O conjunto de dados padrão não afeta o corpo de uma visualização.
• Não é possível usar o método de API JSON TableDataList para recuperar dados de uma visualização. Para mais informações, consulte Tabledata: list.
• Não é possível mesclar consultas do GoogleSQL e do SQL legado ao usar visualizações. Uma consulta do GoogleSQL não pode indicar uma visualização definida usando a sintaxe do SQL legado.
• Não é possível fazer referência a parâmetros de consulta em visualizações.
• Os esquemas das tabelas subjacentes são armazenados com a visualização quando ela é criada. Se colunas forem adicionadas, excluídas ou modificadas depois que a visualização for for criado, a visualização não será atualizada automaticamente, e o esquema informado permanecerão imprecisas até que a definição do SQL da visualização seja alterada ou que a visualização é recriada. Apesar dessa imprecisão, todas as consultas enviadas terão resultados precisos.
• Não é possível atualizar automaticamente uma visualização de SQL legada para a sintaxe GoogleSQL. Para modificar a consulta usada para definir uma visualização, use o seguinte:
  • Opção Editar consulta no Console do Google Cloud
  • O comando bq update --view na ferramenta de linha de comando bq;
  • As bibliotecas de cliente do BigQuery
  • Os métodos da API update ou patch.
• Não é possível incluir uma função definida pelo usuário temporária ou uma tabela temporária na consulta SQL que define uma visualização.
• Não é possível referenciar uma visualização em consultas a uma tabela curinga.

Para informações sobre cotas e limites que se aplicam a visualizações, consulte Limites da visualização.

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.

Permissões necessárias

As visualizações são tratadas como recursos de tabela no BigQuery. Portanto, para criá-las, são necessárias as mesmas permissões usadas para criar uma tabela. Você também precisa ter permissões para consultar as tabelas referenciadas pela consulta SQL da visualização.

Para criar uma visualização, você precisa ter a permissão bigquery.tables.create do IAM. O papel predefinido roles/bigquery.dataEditor do IAM inclui as permissões necessárias para criar uma visualização.

Além disso, se você tiver a permissão bigquery.datasets.create, será possível criar visualizações nos conjuntos de dados que forem criados. Para criar uma visualização para dados que não pertencem a você, é necessário ter a permissão bigquery.tables.getData para essa tabela.

Observação: para criar ou atualizar uma visualização autorizada ou em um conjunto de dados autorizado, você precisa de outras permissões. Para mais informações, consulte permissões necessárias para visualizações autorizadas e permissões necessárias para visualizações em conjuntos de dados autorizados.

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

Nomenclatura da visualização

Ao criar uma visualização no BigQuery, o nome dela precisa ser exclusivo por conjunto de dados. O nome da visualização pode:

• Conter caracteres com um total de até 1.024 bytes UTF-8;
• conter caracteres Unicode na categoria L (letra), M (marca), N (número), Pc (conector, inclusive sublinhado), Pd (travessão), Zs (espaço). Para mais informações, consulte Categoria geral.

Veja a seguir exemplos de nomes de visualização válidos: view 01, ग्राहक, 00_お客様, étudiant-01.

Advertências:

• Por padrão, os nomes de tabelas diferenciam maiúsculas de minúsculas. mytable e MyTable podem coexistir no mesmo conjunto de dados, a menos que façam parte de um conjunto de dados com diferenciação de maiúsculas e minúsculas desativada.
• Alguns nomes e prefixos de nomes de visualização são reservados. Se você receber um erro informando que o nome ou o prefixo da visualização está reservado, selecione um nome diferente e tente novamente.

• Se você incluir vários operadores de ponto (.) em uma sequência, os operadores duplicados serão removidos implicitamente.

  Por exemplo, este: project_name....dataset_name..table_name

  Se tornaria: project_name.dataset_name.table_name

Criar uma visualização

É possível criar uma visualização compondo uma consulta SQL que é usada para definir os dados acessíveis para a exibição. A consulta SQL precisa consistir em uma instrução SELECT. Outros tipos de instrução, como instruções DML, e consultas de várias instruções não são permitidas nas consultas de visualização.

Para criar uma visualização:

Console

1. Depois de executar uma consulta, clique no botão Salvar visualização acima da janela de resultados.

   

2. Na caixa de diálogo Salvar visualização, faça o seguinte:

   • Em Nome do projeto, selecione um projeto para armazenar a visualização.
   • Em Nome do conjunto de dados, escolha um conjunto de dados para armazenar a visualização. O conjunto de dados que contiver a visualização e o conjunto que incluir as tabelas mencionadas por ela precisam estar no mesmo local.
   • Em Nome da tabela, insira o nome da visualização.
   • Clique em Salvar.

Observação: quando você cria uma visualização usando o console do Google Cloud, não é possível adicionar um rótulo, uma descrição ou um prazo de validade. É possível adicionar essas propriedades opcionais ao criar uma visualização usando a API ou a ferramenta de linha de comando bq. Depois de criar uma visualização usando o console do Google Cloud, é possível adicionar uma validade, uma descrição e identificadores. Para mais informações, consulte Como atualizar visualizações.

SQL

Use a instrução CREATE VIEW. O exemplo a seguir cria uma visualização chamada usa_male_names a partir do conjunto de dados público dos nomes dos EUA.

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:

   CREATE VIEW mydataset.usa_male_names(name, number) AS (
     SELECT
       name,
       number
     FROM
       bigquery-public-data.usa_names.usa_1910_current
     WHERE
       gender = 'M'
     ORDER BY
       number DESC
   );

3. Clique em Executar.

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

bq

Use o comando bq mk com a flag --view. Para consultas do GoogleSQL, adicione a flag --use_legacy_sql e defina-a como false. Alguns parâmetros opcionais incluem --add_tags, --expiration, --description e --label. Para obter uma lista completa de parâmetros, consulte a referência Comando bq mk.

Se a consulta se referir a recursos de função externos definidos pelo usuário (UDF, em inglês) armazenados no Cloud Storage ou em arquivos locais, use a flag --view_udf_resource para especificar esses recursos. A flag --view_udf_resource não é demonstrada aqui. Para mais informações sobre o uso de UDFs, consulte UDFs.

Se você estiver criando uma visualização em um projeto diferente do seu projeto padrão, especifique o código do projeto usando a flag --project_id.

Observação: o conjunto de dados que contém a visualização e o que contém as tabelas mencionadas pela visualização precisam estar no mesmo local.

bq mk \
--use_legacy_sql=false \
--view_udf_resource=PATH_TO_FILE \
--expiration=INTEGER \
--description="DESCRIPTION" \
--label=KEY_1:VALUE_1 \
--add_tags=KEY_2:VALUE_2[,...] \
--view='QUERY' \
--project_id=PROJECT_ID \
DATASET.VIEW

Substitua:

• PATH_TO_FILE é o URI ou o caminho do sistema de arquivos local para um arquivo de código a ser carregado e avaliado imediatamente como recurso de UDF, usado pela visualização. Repita a flag para especificar vários arquivos;
• INTEGER define a vida útil (em segundos) da visualização. Se INTEGER for 0, a visualização não expirará. Se você não incluir a flag --expiration, o BigQuery criará a visualização com a vida útil da tabela padrão do conjunto de dados.
• DESCRIPTION é uma descrição da visualização entre aspas;
• KEY_1:VALUE_1 é o par de chave-valor que representa um rótulo. Repita a flag --label para especificar vários rótulos.
• KEY_2:VALUE_2 é o par de chave-valor que representa uma tag. Adicione várias tags na mesma flag usando vírgulas entre os pares de chave-valor.
• QUERY é uma consulta válida.
• PROJECT_ID é o ID do projeto (se você não tiver um projeto padrão configurado).
• DATASET é um conjunto de dados no projeto;
• VIEW é o nome da visualização que você quer criar.

Exemplos:

Digite o seguinte comando para criar uma visualização chamada myview in mydataset em seu projeto padrão. O prazo de validade é definido como 3.600 segundos (uma hora), a descrição como This is my view e a etiqueta como organization:development. A consulta usada para criar a visualização examina os dados do conjunto de dados público USA Name Data.

bq mk \
--use_legacy_sql=false \
--expiration 3600 \
--description "This is my view" \
--label organization:development \
--view \
'SELECT
  name,
  number
FROM
  `bigquery-public-data.usa_names.usa_1910_current`
WHERE
  gender = "M"
ORDER BY
  number DESC' \
mydataset.myview

Digite o seguinte comando para criar uma visualização chamada myview em mydataset em myotherproject. A descrição é definida como This is my view, o rótulo é definido como organization:development e a expiração da visualização é definida como a validade da tabela padrão do conjunto de dados. A consulta usada para criar a visualização examina os dados do conjunto de dados público USA Name Data.

bq mk \
--use_legacy_sql=false \
--description "This is my view" \
--label organization:development \
--project_id myotherproject \
--view \
'SELECT
  name,
  number
FROM
  `bigquery-public-data.usa_names.usa_1910_current`
WHERE
  gender = "M"
ORDER BY
  number DESC' \
mydataset.myview

Após criar a visualização, é possível atualizar a validade, a descrição e os rótulos dela. Para mais informações, consulte Como atualizar visualizações.

Terraform

Use o recurso google_bigquery_table.

Observação: para criar objetos do BigQuery usando o Terraform, é necessário ativar a API Cloud Resource Manager.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

No exemplo a seguir, criamos uma visualização chamada myview:

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "myview"
  deletion_protection = false # set to "true" in production

  view {
    query          = "SELECT global_id, faa_identifier, name, latitude, longitude FROM `bigquery-public-data.faa.us_airports`"
    use_legacy_sql = false
  }

}

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

   Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

   Copie o exemplo de código no main.tf recém-criado.

   Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
4. Salve as alterações.
5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.

   terraform init

   Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:

   terraform init -upgrade

Aplique as alterações

1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:

   terraform plan

   Faça as correções necessárias na configuração.

2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:

   terraform apply

   Aguarde até que o Terraform exiba a mensagem "Apply complete!".

3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

Observação: as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no projeto do Google Cloud.

API

Chame o método tables.insert com um recurso de tabela que contém uma propriedade view.

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"

	"cloud.google.com/go/bigquery"
)

// createView demonstrates creation of a BigQuery logical view.
func createView(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	meta := &bigquery.TableMetadata{
		// This example shows how to create a view of the shakespeare sample dataset, which
		// provides word frequency information.  This view restricts the results to only contain
		// results for works that contain the "king" in the title, e.g. King Lear, King Henry V, etc.
		ViewQuery: "SELECT word, word_count, corpus, corpus_date FROM `bigquery-public-data.samples.shakespeare` WHERE corpus LIKE '%king%'",
	}
	if err := client.Dataset(datasetID).Table(tableID).Create(ctx, meta); err != nil {
		return err
	}
	return nil
}

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;
import com.google.cloud.bigquery.TableInfo;
import com.google.cloud.bigquery.ViewDefinition;

// Sample to create a view
public class CreateView {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String viewName = "MY_VIEW_NAME";
    String query =
        String.format(
            "SELECT TimestampField, StringField, BooleanField FROM %s.%s", datasetName, tableName);
    createView(datasetName, viewName, query);
  }

  public static void createView(String datasetName, String viewName, String query) {
    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, viewName);

      ViewDefinition viewDefinition =
          ViewDefinition.newBuilder(query).setUseLegacySql(false).build();

      bigquery.create(TableInfo.of(tableId, viewDefinition));
      System.out.println("View created successfully");
    } catch (BigQueryException e) {
      System.out.println("View was not created. \n" + e.toString());
    }
  }
}

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

async function createView() {
  // Creates a new view named "my_shared_view" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const myDatasetId = "my_table"
  // const myTableId = "my_table"
  // const projectId = "bigquery-public-data";
  // const sourceDatasetId = "usa_names"
  // const sourceTableId = "usa_1910_current";
  const myDataset = await bigquery.dataset(myDatasetId);

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    view: `SELECT name 
    FROM \`${projectId}.${sourceDatasetId}.${sourceTableId}\`
    LIMIT 10`,
  };

  // Create a new view in the dataset
  const [view] = await myDataset.createTable(myTableId, options);

  console.log(`View ${view.id} created.`);
}

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

client = bigquery.Client()

view_id = "my-project.my_dataset.my_view"
source_id = "my-project.my_dataset.my_table"
view = bigquery.Table(view_id)

# The source table in this example is created from a CSV file in Google
# Cloud Storage located at
# `gs://cloud-samples-data/bigquery/us-states/us-states.csv`. It contains
# 50 US states, while the view returns only those states with names
# starting with the letter 'W'.
view.view_query = f"SELECT name, post_abbr FROM `{source_id}` WHERE name LIKE 'W%'"

# Make an API request to create the view.
view = client.create_table(view)
print(f"Created {view.table_type}: {str(view.reference)}")

Depois de criar a visualização, consulte-a como se consultasse uma tabela.

Segurança das visualizações

Para controlar o acesso a visualizações no BigQuery, consulte Visualizações autorizadas.

A seguir

• Consulte Como criar visualizações autorizadas para mais informações sobre o assunto.
• Para informações sobre como receber metadados de visualizações, consulte Como receber informações sobre visualizações.
• Consulte Como gerenciar visualizações para mais informações.