Como atualizar propriedades de visualização

Neste documento, descrevemos como atualizar as propriedades da visualização no BigQuery. Depois de criar uma visualização, é possível atualizar as seguintes propriedades:

Permissões exigidas

A atualização de uma visualização exige as mesmas permissões para a atualização de uma tabela. É necessário ter acesso de WRITER no nível do conjunto de dados ou um papel de IAM no projeto que inclua permissões bigquery.tables.update. Os seguintes papéis de IAM predefinidos no nível do projeto incluem permissões bigquery.tables.update:

Além disso, como o papel bigquery.user tem permissões bigquery.datasets.create, um usuário com papel bigquery.user pode atualizar qualquer visualização criada por ele no conjunto de dados. Quando um usuário com o papel bigquery.user cria um conjunto de dados, ele recebe acesso OWNER ao conjunto. O acesso OWNER concede ao usuário o controle total sobre o conjunto de dados e de todas as tabelas e visualizações nele.

Para saber mais sobre papéis e permissões de IAM no BigQuery, consulte Controle de acesso.

Como atualizar a consulta SQL de uma visualização

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

  • use o Console do GCP ou a IU clássica da Web do BigQuery;
  • Use o comando bq update da ferramenta de linha de comando.
  • chame o método de API tables.patch.

É possível alterar o dialeto de SQL legado para o SQL padrão por meio da CLI ou da API. No entanto, não é possível atualizar uma visualização de SQL legado para SQL padrão no Console do GCP ou na IU clássica da Web do BigQuery.

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

Console

  1. Selecione a visualização no painel Recursos.

  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 que aparecer.

    Editar consulta

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

    Salvar visualização

  5. Antes de clicar em Salvar, verifique se todos os campos estão corretos na caixa de diálogo Salvar visualização.

IU clássica

  1. Selecione a visualização.

  2. No painel Ver detalhes, clique em Detalhes.

  3. Abaixo da caixa Consulta, clique em Editar consulta.

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

    Atualizar visualização

Linha de comando

Emita 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 padrão, inclua a sinalização --use_legacy_sql e configure-a como false.

Há recursos de função externos que são definidos pelo usuário. Se a consulta fizer referência a esses recursos e eles estiverem armazenados no Google Cloud Storage ou em arquivos locais, use a sinalização --view_udf_resource para especificá-los. A sinalização --view_udf_resource não será demonstrada aqui. Para mais informações sobre como usar UDFs, consulte Funções do SQL padrão definidas pelo usuário.

Se você estiver atualizando uma visualização em um projeto diferente do padrão, adicione o código 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]

Em que:

  • [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 código do projeto;
  • [DATASET] é um conjunto de dados que contém a visualização;
  • [VIEW] é o nome da visualização que você quer atualizar.

Exemplos:

Digite o comando a seguir para atualizar a consulta SQL de uma visualização chamada myview em mydataset. mydataset está no projeto padrão. A consulta de exemplo usada para atualizar a visualização consulta dados do conjunto de dados público USA Name Data.

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

Digite o comando a seguir para atualizar a consulta SQL de uma visualização chamada myview em mydataset. mydataset está em myotherproject, e não no projeto padrão. A consulta de exemplo usada para atualizar a visualização consulta dados do conjunto de dados público USA Name Data.

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

Para atualizar uma visualização, chame o método tables.patch com um recurso de tabela que contenha uma propriedade view atualizada. Como tables.update substitui todo o recurso da tabela, recomendamos usar o método tables.patch.

Go

Antes de testar esta 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 (em inglês).

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python em 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 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 = client.dataset('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 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, 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 a IU clássica da Web do BigQuery;
    • No momento, não é possível modificar os prazos de validade de visualizações no Console do GCP.
  • use o comando bq update da CLI;
  • chame o método de API tables.patch.

Ao atualizar o prazo de validade, calcule-o com base na data de criação da visualização. Por exemplo, vamos supor que você criou uma visualização em 3 de janeiro de 2018 e hoje é dia 5. Quando o tempo de expiração é definido como um dia usando a IU da Web do BigQuery, ele é considerado "no passado" e a visualização é excluída imediatamente.

Observe o seguinte ao atualizar o prazo de validade de uma visualização:

Console

Não é possível adicionar ou atualizar o prazo de validade de uma visualização usando a IU da Web do console.

IU clássica

Opção 1: editar o prazo de validade manualmente

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

  2. Na página Ver detalhes, clique em Detalhes.

  3. Em Tempo de expiração, clique em Editar.

  4. Na caixa de diálogo Atualizar expiração, selecione Em e insira o tempo de expiração em dias.

  5. Clique em OK. O prazo de validade atualizado é exibido na página Detalhes.

    Expiração da visualização

Opção 2: usar uma instrução DDL

As instruções de Linguagem de definição de dados (DDL, na sigla em inglês) permitem criar e modificar tabelas e visualizações usando a sintaxe de consulta SQL padrão.

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

  1. Clique em Escrever consulta.

  2. Digite a instrução DDL na área de texto Nova consulta.

     #standardSQL
     ALTER VIEW mydataset.myview
     SET OPTIONS (
       -- Sets view expiration to timestamp 2025-02-03 12:34:56
       expiration_timestamp=TIMESTAMP "2025-02-03 12:34:56"
     );
     

Linha de comando

Emita o comando bq update com a sinalização --expiration. Se você estiver atualizando uma visualização em um projeto diferente do padrão, adicione o código 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 como a hora atual mais o valor inteiro;
  • [PROJECT_ID] é o código 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:

Digite o comando a seguir para atualizar o tempo de expiração de myview em mydataset como cinco dias (43.200 segundos). mydataset está no projeto padrão.

bq update --expiration 432000 mydataset.myview

Digite o comando a seguir para atualizar o tempo de expiração de myview em mydataset como cinco dias (43.200 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 propriedade expirationTime para atualizar a validade da visualização em milissegundos. Como tables.update substitui todo o recurso da tabela, recomendamos usar o tables.patch.

Go

Antes de testar esta 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 (em inglês).

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Python

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

Antes de testar esta amostra, siga as instruções de configuração do Python no 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 Python.

import datetime
import pytz

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').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 GCP ou a IU clássica da Web do BigQuery;
  • Use o comando bq update da CLI.
  • chame o método de API tables.patch.

Para atualizar a descrição de uma visualização, faça o seguinte:

Console

Não é possível adicionar uma descrição ao criar uma visualização usando a IU da Web do BigQuery. Depois que a visualização for criada, será possível adicionar uma descrição na página Detalhes.

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

  2. Clique na guia Detalhes.

Ver detalhes

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

Editar descrição da visualização

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

IU clássica

Opção 1: alterar a descrição manualmente

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

  2. Na página Ver detalhes, clique em Detalhes.

  3. Na seção Descrição, clique em Descrever esta visualização para abrir a caixa de descrição.

  4. Digite uma descrição na caixa. Ao clicar fora da caixa, o texto é salvo.

    Descrição da tabela

Opção 2: usar uma instrução DDL

Com as instruções de linguagem de definição de dados (DDL, na sigla em inglês), é 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.

  1. Clique em Escrever consulta.

  2. Digite a instrução DDL na área de texto Nova consulta.

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

Linha de comando

Emita o comando bq update com a sinalização --description. Se você estiver atualizando uma visualização em um projeto diferente do padrão, adicione o código 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 código 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:

Digite o comando a seguir para alterar a descrição de myview em mydataset para "Descrição de myview". mydataset está no projeto padrão.

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

Digite o comando a seguir para alterar a descrição de myview em mydataset para "Descrição de myview". mydataset está no myotherproject, e 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 propriedade description para atualizar a descrição da visualização no recurso da tabela. Como tables.update substitui todo o recurso da tabela, recomendamos usar o tables.patch.

Go

Antes de testar esta 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 (em inglês).

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

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

// 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);

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

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').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

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.