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:

Permissões necessárias

Para atualizar uma visualização, você precisa pelo menos ter as permissões bigquery.tables.update e bigquery.tables.get. Se você for atualizar a consulta SQL da visualização, precisará também ter permissões para consultar as tabelas referenciadas pela consulta.

Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.tables.update e bigquery.tables.get:

  • 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 atualize tabelas e visualizações no conjunto de dados.

Para mais informações sobre os papéis e as 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 Cloud
  • use o comando bq update da ferramenta de linha de comando bq;
  • fazendo uma chamada do método de API tables.patch;
  • use 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 de SQL legado para SQL padrão no Console do Cloud.

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

Console

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

  2. Clique na guia Detalhes.

    Ver detalhes

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

    Editar consulta

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

    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 do SQL padrão definidas pelo usuário.

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

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

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 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"
)

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

Ver no GitHub (em inglês) 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 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 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();

  // Uodate view query
  metadata.view = newViewQuery;

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

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

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()
# project = 'my-project'
# source_dataset_id = 'my_source_dataset'
# source_table_id = 'us_states'
# shared_dataset_ref = bigquery.DatasetReference(project, 'my_shared_dataset')

# This example shows how to update a shared view of a source table of
# US States. The view's query will be updated to contain only states with
# names starting with 'M'.
view_ref = shared_dataset_ref.table("my_shared_view")
view = bigquery.Table(view_ref)
sql_template = 'SELECT name, post_abbr FROM `{}.{}.{}` WHERE name LIKE "M%"'
view.view_query = sql_template.format(project, source_dataset_id, source_table_id)
view = client.update_table(view, ["view_query"])  # API request

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

É possível configurar o prazo de validade padrão da tabela no nível do conjunto de dados (o que afeta tanto as tabelas quanto as visualizações) ou definir o prazo de validade 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, a visualização 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 comando bq update da ferramenta de linha de comando bq;
  • fazendo uma chamada do método de API tables.patch;
  • usando as bibliotecas de cliente.

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 de Linguagem de definição de dados.

Para usar uma instrução DDL no Console do Cloud:

  1. Clique em Escrever nova consulta.

  2. Digite a instrução DDL na área de texto do Editor de consultas.

    ALTER VIEW mydataset.myview
    SET OPTIONS (
    -- Sets view expiration to timestamp 2025-02-03 12:34:56 in the America/Los Angeles time zone
    expiration_timestamp=TIMESTAMP("2025-02-03 12:34:56", "America/Los Angeles")
    );
    
  3. Clique em Run query.

bq

Use o comando bq update com a sinalização --expiration. 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 \
--expiration integer \
project_id:dataset.view

Em que:

  • integer é a vida útil 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 valor 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ê quer atualizar.

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 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 do BigQuery para Go.

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

Ver no GitHub (em inglês) 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 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
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 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.

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:

  • Como usar o Console do Cloud
  • use o comando bq update da ferramenta de linha de comando bq;
  • fazendo uma chamada do método de API tables.patch;
  • usando as 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 Cloud. No entanto, depois de criá-la, é possível adicionar a descrição na página Detalhes.

  1. Na lista Recursos, selecione sua visualização.

  2. Clique na guia Detalhes.

    Ver detalhes

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

    Editar descrição da visualizaçã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 de Linguagem de definição de dados.

Para usar uma instrução DDL no Console do Cloud:

  1. Clique em Escrever nova consulta.

  2. Digite a instrução DDL na área de texto do Editor de consultas.

     ALTER VIEW mydataset.myview
     SET OPTIONS (
       description="Description of myview"
     );
     

  3. Clique em Run query.

bq

Use o comando bq update com a sinalização --description. 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 \
--description "description" \
project_id:dataset.view

Em que:

  • 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ê quer atualizar.

Exemplos:

Use o seguinte comando para alterar a descrição de myview em mydataset para “Descrição de myview.” 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 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 do BigQuery para Go.

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

Ver no GitHub (em inglês) 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 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
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 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.

Ver no GitHub (em inglês) 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."

A seguir