Como criar visualizações

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

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

  • usando o Console do Cloud ou a IU da Web clássica do BigQuery;
  • usando o comando bq mk da ferramenta de linha de comando;
  • chamando o método da API tables.insert;
  • usando as bibliotecas de cliente;
  • enviando uma instrução CREATE VIEW de linguagem de definição de dados (DDL, na sigla em inglês);

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 letras (maiúsculas e minúsculas), números e sublinhados.

Limitações da visualização

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

  • 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 fazer referência a 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 e assim por diante depois que a visualização for criada, o esquema informado ficará 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 a opção Editar consulta no Console do Cloud ou na versão clássica da IU da Web do BigQuery, use o comando bq update --view da CLI, use as bibliotecas de cliente ou use os métodos de API update ou patch.
  • Não é possível incluir uma função definida pelo usuário na consulta SQL que define uma visualização.
  • Não é possível fazer referência a uma visualização em consultas a uma tabela com caracteres curinga.

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

Permissões exigidas

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. No mínimo, para criar uma visualização, você precisa ter as permissões bigquery.tables.create. Os papéis predefinidos do Cloud IAM a seguir incluem permissões bigquery.tables.create.

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

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. O acesso bigquery.dataOwner permite que o usuário crie visualizações no conjunto de dados.

Para mais informações sobre as funções e permissões do Cloud IAM no BigQuery, consulte Funções e permissões predefinidas.

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

Na consulta SQL padrão usada para criar uma visualização, é preciso incluir o código do projeto na tabela e referências de visualização no formulário `project_id.dataset.table`. O SQL padrão requer IDs de projeto explícitos para evitar ambiguidade quando as visualizações são consultadas em projetos diferentes.

Para criar uma visualização:

Console

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

    Salvar visualização.

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

    • Em Nome do projeto, selecione o projeto em que a visualização será armazenada.
    • Em Nome do conjunto de dados, escolha o conjunto de dados que incluirá 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.

IU clássica

  1. Depois de executar uma consulta, clique no botão Salvar visualização na janela de resultados da consulta para salvá-la como visualização.

    Salvar visualização.

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

    • Em Projeto, selecione o projeto que armazenará a visualização.
    • Em Conjunto de dados, escolha o conjunto de dados que conterá a visualização. O conjunto de dados que contiver a visualização e o conjunto que contiver as tabelas mencionadas pela visualização precisam estar no mesmo local.
    • Para o ID da tabela, digite o nome da visualização.
    • Clique em OK.

bq

Use o comando mkcom a sinalização --view. Para consultas SQL padrão, adicione o sinalizador --use_legacy_sql e defina-o 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 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 Funções definidas pelo usuário do SQL padrão.

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.

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

Onde:

  • path_to_file é o caminho do URI ou do sistema de arquivos local para um arquivo de código a ser carregado e avaliado imediatamente como recurso de função definida pelo usuário, usado pela visualização. Repita a sinalização para especificar vários arquivos;
  • integer é a vida útil padrão (em segundos) da visualização. O valor mínimo é de 3.600 segundos (uma hora). O prazo de validade é avaliado para a hora atual mais o valor inteiro. Se você definir esse valor ao criar a visualização, a configuração de validade da tabela padrão do conjunto de dados será ignorada.
  • 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. Para visualizações SQL padrão, a consulta precisar incluir o código do projeto em referências na tabela e as referências de visualização no formulário `[PROJECT_ID].[DATASET].[TABLE]`.
  • 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ê pretende 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. 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 \
--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 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 BigQuery Go.

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
}

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 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 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 BigQuery em Python (em inglês).

# from google.cloud import bigquery
# client = bigquery.Client()
# project = 'my-project'
# source_dataset_id = 'my_source_dataset'
# source_table_id = 'us_states'
# shared_dataset_ref = client.dataset('my_shared_dataset')

# This example shows how to create a shared view of a source table of
# US States. The source table contains all 50 states, while the view will
# contain only states with names starting with 'W'.
view_ref = shared_dataset_ref.table("my_shared_view")
view = bigquery.Table(view_ref)
sql_template = 'SELECT name, post_abbr FROM `{}.{}.{}` WHERE name LIKE "W%"'
view.view_query = sql_template.format(project, source_dataset_id, source_table_id)
view = client.create_table(view)  # API request

print("Successfully created view at {}".format(view.full_table_id))

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

A seguir