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 da ferramenta de linha de comando bq mk;
• Chamada do 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. Não é possível executar consultas DML (inserir, atualizar ou excluir) em uma visualização.
• 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.
• Não é possível executar um job do BigQuery que exporta dados 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 combinar consultas de SQL padrão e de SQL legado ao usar visualizações. Uma consulta SQL padrão não pode referenciar 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 as colunas forem adicionadas, excluídas ou modificadas após a criação da visualização, o esquema informado será impreciso até que a visualização seja atualizada. Mesmo que o esquema informado seja impreciso, todas as consultas enviadas produzirão resultados precisos.
• Não é possível atualizar automaticamente uma visualização do SQL legado para a sintaxe SQL padrão. 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 criar as visualizações, 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, é preciso ter a permissão bigquery.tables.create do IAM.

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

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin

Além disso, se você tiver a permissão bigquery.datasets.create, é possível criar visualizações nos conjuntos de dados que você criou. Para criar uma visualização para dados que não pertencem a você, é necessário ter a permissão bigquery.jobs.create 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 os papéis e as 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 até 1.024 caracteres
• 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:

• 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....datasest_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 Save.

Observação: quando você cria uma visualização usando o console do Google Cloud, não é possível adicionar um identificador, 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 informações sobre como executar consultas, consulte Como executar consultas interativas.

bq

Use o comando bq mk com a sinalização --view. Para consultas SQL padrão do Google, adicione a sinalização --use_legacy_sql e defina-a como false. Os parâmetros opcionais incluem --expiration, --description e --label.

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 sinalização --view_udf_resource para especificar esses recursos. A sinalização --view_udf_resource não é demonstrada aqui. Para mais informações sobre o uso de UDFs, consulte UDFs e a ferramenta de linha de comando bq.

Se você estiver criando uma visualização em um projeto diferente do seu projeto padrão, especifique o código do projeto usando a sinalização --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:VALUE \
--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 sinalização 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 sinalização --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:VALUE é o par de chave-valor que representa um rótulo. Repita a sinalização --label para especificar várias etiquetas.
• QUERY é uma consulta válida.
• PROJECT_ID é o ID do projeto (caso você não tenha 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.

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.

Conferir no GitHub Feedback

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.

Conferir no GitHub Feedback

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.

Conferir no GitHub Feedback

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

Conferir no GitHub Feedback

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.