Como atualizar propriedades de visualização

Neste documento, descrevemos como atualizar os metadados ou as propriedades de visualização. Depois de criar uma visualização, é possível atualizar as propriedades a seguir:

• Consulta SQL
• Prazo de validade
• Descrição
• Marcadores

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

Para atualizar uma visualização, você precisa das seguintes permissões do IAM:

• bigquery.tables.update
• bigquery.tables.get

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

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

Além disso, se você tiver a permissão bigquery.datasets.create, poderá atualizar tabelas e visualizações nos conjuntos de dados que criar.

Se você for atualizar a consulta SQL da visualização, precisará também ter permissões para consultar as tabelas referenciadas pela consulta.

Observação: para atualizar o SQL de uma visualização autorizada ou uma visualização 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.

Como atualizar a consulta SQL de uma visualização

Para atualizar a consulta SQL usada para definir uma visualização:

• Como usar o console do Google Cloud
• Use o comando bq update da ferramenta de linha de comando bq.
• chame o tables.patch método de API;
• Como usar bibliotecas de cliente

É possível alterar o dialeto SQL legado para o padrão na API ou na ferramenta de linha de comando bq. Não é possível atualizar uma visualização do SQL legado para o SQL padrão no console do Google Cloud.

Para atualizar a consulta SQL de uma visualização:

Console

1. No painel Explorador, expanda o projeto e o conjunto de dados e selecione a visualização.

2. Clique na guia Details.

3. Acima da caixa Consulta, clique no botão Editar consulta. Clique em Abrir na caixa de diálogo exibida.

   

4. Edite a consulta SQL na caixa Editor de consultas e clique em Salvar visualização.

   

5. Verifique se todos os campos estão corretos na caixa de diálogo Salvar visualização e clique em Salvar.

bq

Use o comando bq update com a sinalização --view. Para usar o SQL padrão ou atualizar o dialeto de consulta do SQL legado para o SQL padrão, inclua a sinalização --use_legacy_sql e a defina como false.

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.

Caso esteja atualizando uma visualização em um projeto diferente do projeto padrão, adicione a ID do projeto ao nome do conjunto de dados no seguinte formato: project_id:dataset.

bq update \
    --use_legacy_sql=false \
    --view_udf_resource=path_to_file \
    --view='query' \
    project_id:dataset.view

Substitua:

• 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;
• query: uma consulta SQL padrão do Google válida
• project_id: ID do projeto
• dataset: o nome do conjunto de dados que contém a visualização que você está atualizando.
• view: o nome da visualização que você está atualizando.

Exemplos

Use o seguinte comando para atualizar a consulta SQL para uma visualização nomeada myview em mydataset. mydataset está em seu projeto padrão. A consulta de exemplo usada para atualizar os dados de consultas de visualização do conjunto de dados público Dados de nomes dos EUA.

bq update \
    --use_legacy_sql=false \
    --view \
    'SELECT
      name,
      number
    FROM
      `bigquery-public-data.usa_names.usa_1910_current`
    WHERE
      gender = "M"
    ORDER BY
      number DESC;' \
    mydataset.myview

Use o seguinte comando para atualizar a consulta SQL para uma visualização nomeada myview em mydataset. mydataset está em myotherproject, não no seu projeto padrão. A consulta de exemplo usada para atualizar os dados de consultas de visualização do conjunto de dados público Dados de nomes dos EUA.

bq update \
    --use_legacy_sql=false \
    --view \
    'SELECT
      name,
      number
    FROM
      `bigquery-public-data.usa_names.usa_1910_current`
    WHERE
      gender = "M"
    ORDER BY
      number DESC;' \
    myotherproject:mydataset.myview

API

É possível atualizar uma visualização chamando o método tables.patch com um recurso de tabela que contenha uma property view atualizada. Como o método tables.update substitui todo o recurso da tabela, é melhor usar o método tables.patch.

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.

Ver no GitHub Feedback

import (
	"context"
	"fmt"

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

// updateView demonstrates updating the query metadata that defines a logical view.
func updateView(projectID, datasetID, viewID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// viewID := "myview"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	view := client.Dataset(datasetID).Table(viewID)
	meta, err := view.Metadata(ctx)
	if err != nil {
		return err
	}

	newMeta := bigquery.TableMetadataToUpdate{
		// This example updates a view into the shakespeare dataset to exclude works named after kings.
		ViewQuery: "SELECT word, word_count, corpus, corpus_date FROM `bigquery-public-data.samples.shakespeare` WHERE corpus NOT LIKE '%king%'",
	}

	if _, err := view.Update(ctx, newMeta, meta.ETag); 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.

Ver 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 update query on a view
public class UpdateViewQuery {

  public static void runUpdateViewQuery() {
    // 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 updateQuery =
        String.format("SELECT TimestampField, StringField FROM %s.%s", datasetName, tableName);
    updateViewQuery(datasetName, viewName, updateQuery);
  }

  public static void updateViewQuery(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();

      // Retrieve existing view metadata
      TableInfo viewMetadata = bigquery.getTable(TableId.of(datasetName, viewName));

      // Update view query
      ViewDefinition viewDefinition = viewMetadata.getDefinition();
      viewDefinition.toBuilder().setQuery(query).build();

      // Set metadata
      bigquery.update(viewMetadata.toBuilder().setDefinition(viewDefinition).build());

      System.out.println("View query updated successfully");
    } catch (BigQueryException e) {
      System.out.println("View query was not updated. \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.

Ver 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 updateViewQuery() {
  // Updates a view named "my_existing_view" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_existing_dataset"
  // const tableId = "my_existing_table"
  const dataset = await bigquery.dataset(datasetId);

  // This example updates a view into the USA names dataset to include state.
  const newViewQuery = `SELECT name, state
  FROM \`bigquery-public-data.usa_names.usa_1910_current\`
  LIMIT 10`;

  // Retrieve existing view
  const [view] = await dataset.table(tableId).get();

  // Retrieve existing view metadata
  const [metadata] = await view.getMetadata();

  // Update view query
  metadata.view = newViewQuery;

  // Set metadata
  await view.setMetadata(metadata);

  console.log(`View ${tableId} updated.`);
}

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.

Ver 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 'M'.
view.view_query = f"SELECT name, post_abbr FROM `{source_id}` WHERE name LIKE 'M%'"

# Make an API request to update the query property of the view.
view = client.update_table(view, ["view_query"])
print(f"Updated {view.table_type}: {str(view.reference)}")

Como atualizar o prazo de validade de uma visualização

É possível configurar o tempo de expiração padrão da tabela no nível do conjunto de dados (o que afeta tanto as tabelas quanto as visualizações) ou definir o tempo de expiração de uma visualização quando ela é criada. Caso você faça isso durante a criação da visualização, a expiração padrão da tabela do conjunto de dados será ignorada. Se você não definir uma validade padrão de tabela no nível do conjunto de dados nem a validade durante a criação da visualização, esta nunca expirará e será necessário excluí-la manualmente.

É possível atualizar o prazo de validade de uma visualização a qualquer momento após criá-la. Para fazer isso:

• Use o console do Google Cloud
• Use uma instrução de linguagem de definição de dados (DDL) escrita na sintaxe SQL padrão
• Use o comando bq update da ferramenta de linha de comando bq.
• chame o tables.patch método de API;
• use bibliotecas de cliente.

Observação: ao definir um prazo de validade já expirado, a visualização será excluída imediatamente.

Para atualizar o prazo de validade de uma visualização:

Console

1. No painel de navegação, selecione a visualização.

2. Na página de detalhes da visualização, clique na guia Detalhes.

3. À direita de Informações da visualização, clique no ícone de edição (lápis).

4. Na caixa de diálogo Informações da visualização, em Validade da visualização, clique em Especificar data.

5. No seletor de data, insira a data e a hora de validade e clique em Ok.

6. Clique em Atualizar. O prazo de validade atualizado é exibido na seção Informações de visualização.

SQL

Com as instruções de linguagem de definição de dados (DDL), é possível criar e modificar tabelas e visualizações usando a sintaxe de consulta do SQL padrão.

Saiba mais sobre Como usar as instruções da linguagem de definição de dados.

Usar uma instrução DDL para atualizar o prazo de validade de uma visualização:

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 VIEW DATASET_ID.MY_VIEW
    SET OPTIONS (
     expiration_timestamp = TIMESTAMP('NEW_TIMESTAMP'));

   Substitua:

   • DATASET_ID: o ID do conjunto de dados que contém a visualização.
   • MY_VIEW: o nome da visualização que será atualizada.
   • NEW_TIMESTAMP: um valor TIMESTAMP

3. Clique em Executar.

Para informações sobre como executar consultas, consulte Como executar consultas interativas.

bq

Use o comando bq update com a sinalização --expiration. Caso esteja atualizando uma visualização em um projeto diferente daquele padrão, adicione o ID do projeto ao nome do conjunto de dados no seguinte formato: project_id:dataset.

bq update \
    --expiration integer \
    project_id:dataset.view

Substitua:

• integer: o ciclo de vida padrão (em segundos) da tabela. O valor mínimo é de 3.600 segundos (uma hora). O prazo de validade é avaliado para a hora atual mais o número inteiro.
• project_id: o ID do projeto
• dataset: o nome do conjunto de dados que contém a visualização que você está atualizando.
• view: o nome da visualização que você está atualizando.

Exemplos

Insira o seguinte comando para atualizar o prazo de validade de myview em mydataset para 5 dias (432.000 segundos). mydataset está em seu projeto padrão.

bq update \
    --expiration 432000 \
    mydataset.myview

Insira o seguinte comando para atualizar o prazo de validade de myview em mydataset para 5 dias (432.000 segundos). mydataset está em myotherproject, e não no projeto padrão.

bq update \
    --expiration 432000 \
    myotherproject:mydataset.myview

API

Chame o método tables.patch e use a property expirationTime no recurso de tabela. Em razão do método tables.update substituir todo o recurso da tabela, o método tables.patch é preferível. Quando você usa a API REST, a validade da visualização é expressa em milissegundos.

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.

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"time"

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

// updateTableExpiration demonstrates setting the table expiration of a table to a specific point in time
// in the future, at which time it will be deleted.
func updateTableExpiration(projectID, datasetID, tableID 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()

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta, err := tableRef.Metadata(ctx)
	if err != nil {
		return err
	}
	update := bigquery.TableMetadataToUpdate{
		ExpirationTime: time.Now().Add(time.Duration(5*24) * time.Hour), // table expiration in 5 days.
	}
	if _, err = tableRef.Update(ctx, update, meta.ETag); 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.

Ver no GitHub Feedback

Table beforeTable = bigquery.getTable(datasetName, tableName);

// Set table to expire 5 days from now.
long expirationMillis = DateTime.now().plusDays(5).getMillis();
TableInfo tableInfo = beforeTable.toBuilder()
        .setExpirationTime(expirationMillis)
        .build();
Table afterTable = bigquery.update(tableInfo);

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.

Ver no GitHub Feedback

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

async function updateTableExpiration() {
  // Updates a table's expiration.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset', // Existing dataset
  // const tableId = 'my_table', // Existing table
  // const expirationTime = Date.now() + 1000 * 60 * 60 * 24 * 5 // 5 days from current time in ms

  // Retreive current table metadata
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();

  // Set new table expiration to 5 days from current time
  metadata.expirationTime = expirationTime.toString();
  const [apiResponse] = await table.setMetadata(metadata);

  const newExpirationTime = apiResponse.expirationTime;
  console.log(`${tableId} expiration: ${newExpirationTime}`);
}

Python

A atualização da validade de uma visualização é o mesmo processo de atualizar a validade de uma tabela.

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.

Ver no GitHub Feedback

import datetime
import pytz

# from google.cloud import bigquery
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, dataset_id)
# table_ref = dataset_ref.table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.expires is None

# set table to expire 5 days from now
expiration = datetime.datetime.now(pytz.utc) + datetime.timedelta(days=5)
table.expires = expiration
table = client.update_table(table, ["expires"])  # API request

# expiration is stored in milliseconds
margin = datetime.timedelta(microseconds=1000)
assert expiration - margin <= table.expires <= expiration + margin

Como atualizar a descrição de uma visualização

É possível atualizar a descrição de uma visualização. Para fazer isso:

• Use o console do Google Cloud
• Use uma instrução de linguagem de definição de dados (DDL) escrita na sintaxe SQL padrão
• Use o comando bq update da ferramenta de linha de comando bq.
• chame o tables.patch método de API;
• use bibliotecas de cliente.

Para atualizar a descrição de uma visualização:

Console

Não é possível adicionar uma descrição durante a criação de uma visualização usando o console do Google Cloud. No entanto, depois de criá-la, é possível adicionar a descrição na página Detalhes.

1. No painel Explorador, expanda o projeto e o conjunto de dados e selecione a visualização.

2. Clique na guia Details.

3. Clique no ícone de lápis ao lado de Descrição.

   

4. Insira uma descrição na caixa de diálogo. Clique em Atualizar para salvar a nova descrição.

SQL

Com as instruções de linguagem de definição de dados (DDL), é possível criar e modificar tabelas e visualizações usando a sintaxe de consulta do SQL padrão.

Saiba mais sobre Como usar as instruções da linguagem de definição de dados.

Usar uma instrução DDL para atualizar a descrição de uma visualização:

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 VIEW DATASET_ID.MY_VIEW
    SET OPTIONS (
     description = 'NEW_DESCRIPTION');

   Substitua:

   • DATASET_ID: o ID do conjunto de dados que contém a visualização.
   • MY_VIEW: o nome da visualização que será atualizada.
   • NEW_DESCRIPTION: a descrição da nova visualização

3. Clique em Executar.

Para informações sobre como executar consultas, consulte Como executar consultas interativas.

bq

Use o comando bq update com a sinalização --description. Caso esteja atualizando uma visualização em um projeto diferente daquele padrão, adicione o ID do projeto ao nome do conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

bq update \
    --description "description" \
    project_id:dataset.view

Substitua:

• description: o texto que descreve a visualização entre aspas
• project_id: o ID do projeto
• dataset: o nome do conjunto de dados que contém a visualização que você está atualizando.
• view: o nome da visualização que você está atualizando.

Exemplos

Use o seguinte comando para alterar a descrição de myview em mydataset para “Descrição da minha visualização.” mydataset está em seu projeto padrão.

bq update \
    --description "Description of myview" \
    mydataset.myview

Use o seguinte comando para alterar a descrição de myview em mydataset para “Descrição de myview.” mydataset está em myotherproject, não no projeto padrão.

bq update \
    --description "Description of myview" \
    myotherproject:mydataset.myview

API

Chame o método tables.patch e use a property description para atualizar a descrição da visualização no recurso de tabela. Em razão do método tables.update substituir todo o recurso da tabela, o método tables.patch é preferível.

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.

Ver no GitHub Feedback

import (
	"context"
	"fmt"

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

// updateTableDescription demonstrates how to fetch a table's metadata and updates the Description metadata.
func updateTableDescription(projectID, datasetID, tableID 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()

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta, err := tableRef.Metadata(ctx)
	if err != nil {
		return err
	}
	update := bigquery.TableMetadataToUpdate{
		Description: "Updated description.",
	}
	if _, err = tableRef.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

A atualização da descrição de uma visualização é o mesmo processo de atualizar a descrição de uma tabela.

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.

Ver no GitHub Feedback

// String datasetName = "my_dataset_name";
// String tableName = "my_table_name";
// String newDescription = "new_description";

Table beforeTable = bigquery.getTable(datasetName, tableName);
TableInfo tableInfo = beforeTable.toBuilder()
    .setDescription(newDescription)
    .build();
Table afterTable = bigquery.update(tableInfo);

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.

Ver no GitHub Feedback

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

async function updateTableDescription() {
  // Updates a table's description.

  // Retreive current table metadata
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();

  // Set new table description
  const description = 'New table description.';
  metadata.description = description;
  const [apiResponse] = await table.setMetadata(metadata);
  const newDescription = apiResponse.description;

  console.log(`${tableId} description: ${newDescription}`);
}

Python

A atualização da descrição de uma visualização é o mesmo processo de atualizar a descrição de uma tabela.

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.

Ver no GitHub Feedback

# from google.cloud import bigquery
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, dataset_id)
# table_ref = dataset_ref.table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.description == "Original description."
table.description = "Updated description."

table = client.update_table(table, ["description"])  # API request

assert table.description == "Updated description."

Segurança das visualizações

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

Próximas etapas

• Para mais informações sobre como gerenciar, copiar e excluir visualizações, consulte Como gerenciar visualizações.
• Para informações sobre a criação de visualizações, consulte Como criar visualizações.
• Para informações sobre a criação de uma visualização autorizada, consulte Como criar visualizações autorizadas.
• Para informações sobre a listagem de visualizações, consulte Como listar visualizações.
• Para informações sobre como receber metadados de visualizações, consulte Como receber informações sobre visualizações.