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

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 o seguinte:

  • até 1.024 caracteres
  • letras (maiúsculas e minúsculas), números e sublinhados;

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 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, use o comando bq update --view na ferramenta de linha de comando bq, use as bibliotecas de cliente ou os métodos de 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.

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

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

Além disso, quando um usuário tem permissões bigquery.datasets.create e cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner ao conjunto. O acesso bigquery.dataOwner permite que o usuário crie visualizações no conjunto de dados.

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

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.

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

bq

Use o comando bq mk com a sinalização --view. Para consultas SQL padrão, 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.

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 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 em 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
}

Java

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

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

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.

Próximas etapas