Como atualizar rótulos

Nesta página, você aprende a atualizar rótulos em recursos do BigQuery.

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. As permissões necessárias para executar uma tarefa (se houver) são listadas na seção "Permissões necessárias".

Atualizar rótulos do conjunto de dados

Para atualizar o rótulo de um conjunto de dados:

  • Como usar o console do Google Cloud
  • Usar instruções DDL do SQL;
  • use o comando bq update da ferramenta de linha de comando bq;
  • chame o datasets.patch método de API;
  • use as bibliotecas de cliente.

Permissões necessárias

Para atualizar um rótulo de conjunto de dados, você precisa da permissão bigquery.datasets.update do IAM.

Cada um dos papéis predefinidos do IAM a seguir inclui as permissões necessárias para atualizar o rótulo de um conjunto de dados:

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

Além disso, se você tiver a permissão bigquery.datasets.create, poderá atualizar os rótulos dos conjuntos de dados que criar.

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

Atualizar um rótulo de conjunto de dados

Para atualizar rótulos em um conjunto de dados, selecione uma das seguintes opções:

Console

  1. No console do Google Cloud , selecione o conjunto de dados.

  2. Clique na guia Detalhes e em Editar detalhes.

  3. Na seção Rótulos, modifique os campos Chave ou Valor para atualizar um rótulo. Para aplicar mais rótulos, clique em Adicionar rótulos. Cada chave pode ser usada somente uma vez por conjunto de dados, mas é possível usar a mesma chave em conjuntos diferentes no mesmo projeto.

  4. Clique em Salvar.

SQL

Use a instrução DDL ALTER SCHEMA SET OPTIONS para definir os rótulos em um conjunto de dados atual. A definição dos rótulos substitui os rótulos no conjunto de dados. O exemplo a seguir define um único rótulo no conjunto de dados mydataset:

  1. No console do Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. No editor de consultas, digite a seguinte instrução:

    ALTER SCHEMA mydataset
SET OPTIONS (labels = [('sensitivity', 'high')]);

  3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Para adicionar rótulos adicionais ou atualizar um rótulo de conjunto de dados, emita o comando bq update com a sinalização set_label. Repita a sinalização para adicionar ou atualizar vários rótulos.

Se o conjunto de dados estiver em um projeto diferente do projeto padrão, adicione o ID do projeto ao conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

bq update \
--set_label key:value \
project_id:dataset

Em que:

  • key:value corresponde a um par de chave-valor para um rótulo que você quer adicionar ou atualizar. Se você especificar a mesma chave que a de um rótulo atual, seu valor será atualizado. A chave precisa ser única.
  • project_id é o ID do projeto.
  • dataset é o conjunto de dados que você está atualizando.

Exemplo:

Para atualizar o rótulo department em mydataset, digite o comando bq update e especifique department como a chave do rótulo. Por exemplo, para atualizar o rótulo department:shipping para department:logistics, digite o seguinte comando. mydataset está em myotherproject, não seu projeto padrão.

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset

O resultado será semelhante ao mostrado a seguir. 

Dataset 'myotherproject:mydataset' successfully updated.

API

Para adicionar rótulos ou atualizar um rótulo para um conjunto de dados existente, chame o método datasets.patch e adicione ou atualize a propriedade labels para o recurso do conjunto de dados.

Como o método datasets.update substitui todo o recurso do conjunto de dados, é melhor usar o método datasets.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.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import (
	"context"
	"fmt"

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

// addDatasetLabel demonstrates adding label metadata to an existing dataset.
func addDatasetLabel(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

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

	update := bigquery.DatasetMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Nesta amostra, a biblioteca de cliente HTTP do Google para Java é usada para enviar uma solicitação à API BigQuery.

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.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.HashMap;
import java.util.Map;

// Sample to updates a label on dataset
public class LabelDataset {

  public static void runLabelDataset() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    labelDataset(datasetName);
  }

  public static void labelDataset(String datasetName) {
    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();

      // This example dataset starts with existing label { color: 'green' }
      Dataset dataset = bigquery.getDataset(datasetName);
      // Add label to dataset
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      dataset.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \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.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

async function labelDataset() {
  // Updates a label on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";

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

  // Add label to dataset metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await dataset.setMetadata(metadata);

  console.log(`${datasetId} labels:`);
  console.log(apiResponse.labels);
}

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.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = "your-project.your_dataset"

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.labels = {"color": "green"}
dataset = client.update_dataset(dataset, ["labels"])  # Make an API request.

print("Labels added to {}".format(dataset_id))

Atualizar rótulos de tabelas e visualizações

Para atualizar um rótulo depois que uma tabela ou visualização é criada:

  • Como usar o console do Google Cloud
  • use o comando bq update da ferramenta de linha de comando bq;
  • utilize o método da API tables.patch
      ;
    • Como as visualizações são tratadas como recursos de tabela, você usa o método tables.patch para modificar visualizações e tabelas.
  • usando as bibliotecas de cliente.

Permissões necessárias

Para atualizar um rótulo de tabela ou visualização, você precisa da permissão do IAM bigquery.tables.update.

Cada um dos papéis predefinidos do IAM a seguir inclui as permissões necessárias para atualizar um rótulo de tabela ou 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 os rótulos das tabelas e visualizações nos conjuntos de dados que criar.

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

Atualizar um rótulo de tabela ou visualização

Para atualizar um rótulo de visualização ou de tabela, faça o seguinte:

Console

  1. No console do Google Cloud , selecione a tabela ou a visualização.

  2. No painel de detalhes, clique em Editar > Editar detalhes.

  3. Na seção Rótulos, modifique os campos Chave ou Valor para atualizar um rótulo. Para aplicar mais rótulos, clique em Adicionar rótulos. Cada chave pode ser usada somente uma vez por tabela ou visualização, mas é possível usar a mesma chave em tabelas ou visualizações em conjuntos de dados diferentes.

  4. Clique em Salvar.

SQL

Use a ALTER TABLE SET OPTIONS Instrução DDL para definir os rótulos em uma tabela existente ou ALTER VIEW SET OPTIONS Instrução DDL para definir os rótulos em uma visualização existente. A definição dos rótulos substitui os que já estão na tabela ou na visualização. O exemplo a seguir define dois rótulos na tabela mytable:

  1. No console do Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. No editor de consultas, digite a seguinte instrução:

    ALTER TABLE mydataset.mytable
SET OPTIONS (
  labels = [('department', 'shipping'), ('cost_center', 'logistics')]);

  3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Para adicionar rótulos ou atualizar um rótulo de visualização ou tabela, emita o comando bq update com a sinalização set_label. Repita a sinalização para adicionar ou atualizar vários rótulos.

Se a tabela ou a visualização estiver em um projeto diferente do seu projeto padrão, adicione a ID do projeto ao conjunto de dados no seguinte formato: project_id:dataset.

bq update \
--set_label key:value \
project_id:dataset.table_or_view

Em que:

  • key:value corresponde a um par de chave-valor para um rótulo que você quer adicionar ou atualizar. Se você especificar a mesma chave que a de um rótulo atual, seu valor será atualizado. A chave precisa ser única.
  • project_id é o ID do projeto.
  • dataset é o conjunto de dados que contém a tabela ou a visualização que você está atualizando;
  • table_or_view é o nome da tabela ou visualização que você está atualizando.

Exemplo:

Para atualizar o rótulo department para mytable, digite o comando bq update e especifique department como a chave do rótulo. Por exemplo, para atualizar o rótulo department:shipping para department:logistics para mytable, digite o seguinte comando. mytable está em myotherproject, não seu projeto padrão.

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset.mytable

A saída será assim: 

Table 'myotherproject:mydataset.mytable' successfully updated.

API

Para adicionar rótulos ou atualizar o rótulo de uma tabela ou visualização existente, chame o método tables.patch e adicione ou atualize a propriedade labels para o recurso da tabela.

Como as visualizações são tratadas como recursos de tabela, você usa o método tables.patch para modificar visualizações e tabelas.

Além disso, como o método tables.update substitui todo o recurso do conjunto de dados, é 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.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import (
	"context"
	"fmt"

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

// addTableLabel demonstrates adding Label metadata to a BigQuery table.
func addTableLabel(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()

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

	update := bigquery.TableMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Nesta amostra, a biblioteca de cliente HTTP do Google para Java é usada para enviar uma solicitação à API BigQuery.

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.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import java.util.HashMap;
import java.util.Map;

// Sample to adds a label to an existing table
public class LabelTable {

  public static void runLabelTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    labelTable(datasetName, tableName);
  }

  public static void labelTable(String datasetName, String tableName) {
    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();

      // This example table starts with existing label { color: 'green' }
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      // Add label to table
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      table.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \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.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

async function labelTable() {
  // Adds a label to an existing table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  // Retrieve current table metadata
  const [metadata] = await table.getMetadata();

  // Add label to table metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(`${tableId} labels:`);
  console.log(apiResponse.labels);
}

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.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

# 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.labels == {}
labels = {"color": "green"}
table.labels = labels

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

assert table.labels == labels

Atualizar rótulos de jobs

Não é possível atualizar um rótulo de job. Para atualizar o rótulo de um job, reenvie o job com um novo rótulo especificado.

Atualizar rótulos de reserva

É possível atualizar um rótulo em uma reserva. A atualização de um rótulo usando SQL substitui todos os rótulos atuais na reserva.

Papéis necessários do IAM

Para receber a permissão necessária para atualizar um rótulo em uma reserva, peça ao administrador para conceder a você o papel do IAM de Editor de recursos do BigQuery (roles/bigquery.resourceEditor) no projeto de administração. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão bigquery.reservations.update, que é necessária para atualizar um rótulo em uma reserva.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Atualizar um rótulo em uma reserva

Para atualizar um rótulo em uma reserva:

Console

  1. No Google Cloud console, acesse a página BigQuery.

    Acessar o BigQuery

  2. No menu de navegação, clique em Workload Manager.

  3. Clique na guia Reservas de slots.

  4. Encontre a reserva que você quer atualizar.

  5. Expanda a opção Ações.

  6. Clique em Editar.

  7. Para expandir a seção Configurações avançadas, clique na seta .

  8. Atualize os nomes do par de chave-valor.

  9. Clique em Salvar.

bq

Para atualizar um rótulo em uma reserva, emita o comando bq update com as sinalizações set_label e --reservation. Para atualizar vários rótulos, repita a flag.

bq update --set_label KEY:VALUE  --reservation RESERVATION_NAME

Substitua:

  • KEY:VALUE: um par de chave-valor para um rótulo que você quer atualizar na reserva. A chave precisa ser exclusiva. As chaves e os valores contêm apenas letras minúsculas, caracteres numéricos, sublinhados e traços. Todos os caracteres precisam usar a codificação UTF-8, e os caracteres internacionais são permitidos. Para atualizar vários rótulos em uma reserva, repita a flag --set_label e especifique uma chave exclusiva para cada rótulo.
  • RESERVATION_NAME: o nome da reserva.

SQL

Para atualizar um rótulo em uma reserva, use a instrução DDL ALTER RESERVATION SET OPTIONS para definir os rótulos em uma reserva atual. A definição dos rótulos substitui os rótulos na reserva. O exemplo a seguir define um rótulo na reserva myreservation:

  1. No console do Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. No editor de consultas, digite a seguinte instrução:

    ALTER RESERVATION myreservation
SET OPTIONS (
  labels = [('sensitivity', 'high')]);

  3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

Converter rótulos em tags

Um rótulo que tem uma chave com um valor vazio é usado como tag. É possível criar um rótulo sem valor ou transformar um atual em uma tag em um conjunto de dados, tabela ou visualização. Não é possível converter um rótulo de job em uma tag.

As tags podem ser úteis em situações em que você está rotulando um recurso, mas não precisa do formato key:value. Por exemplo, se você tiver uma tabela que contém dados de teste usados por vários grupos (suporte, desenvolvimento, entre outros), é possível adicionar uma tag test_data à tabela para identificá-la.

Permissões necessárias

Para converter um rótulo em uma tag, você precisa das seguintes permissões do IAM:

  • bigquery.datasets.update (permite converter um rótulo de conjunto de dados)
  • bigquery.tables.update (permite converter uma tabela ou rótulo de visualização)

Cada um dos papéis predefinidos do IAM a seguir inclui as permissões necessárias para converter um rótulo de conjunto de dados:

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

Cada um dos papéis predefinidos do IAM a seguir inclui as permissões necessárias para converter um rótulo de tabela ou 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 os rótulos dos conjuntos de dados que criou e as tabelas e visualizações neles.

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

Converter um rótulo em uma tag

Para converter um rótulo em uma tag:

Console

  1. No console do Google Cloud , selecione o conjunto de dados, a tabela ou a visualização.

  2. Abra o painel Editar detalhes:

    • Para um conjunto de dados, clique na guia Detalhes e em Editar detalhes.
    • Para uma tabela ou visualização, no painel de detalhes, clique em Editar > Editar detalhes.

  3. Na seção Rótulos, exclua o valor no campo Valor do rótulo que você quer atualizar.

  4. Clique em Salvar.

bq

Para converter um rótulo em tag, use o comando bq update com a sinalização set_label. Determine a chave, seguida por dois-pontos, mas deixe o valor sem especificação. Isso atualiza um rótulo atual para uma tag.

bq update \
--set_label key: \
resource_id

Em que:

  • key: é a chave do rótulo que você quer atualizar para uma tag;
  • resource_id é um conjunto de dados válido, uma tabela ou um nome de visualização. Se o recurso estiver em um projeto diferente do seu projeto padrão, adicione o ID do projeto no seguinte formato: project_id:dataset.

Exemplos:

Digite o seguinte comando para alterar o rótulo test_data:development existente em mydataset para uma tag. mydataset está em myotherproject, não seu projeto padrão.

bq update --set_label test_data: myotherproject:mydataset

A saída será assim: 

Dataset 'myotherproject:mydataset' successfully updated.

API

Para transformar um rótulo existente em uma tag, chame o método datasets.patch ou o método tables.patch e substitua os valores do rótulo pela string vazia ("") no recurso do conjunto de dados ou no recurso da tabela.

Como as visualizações são tratadas como recursos de tabela, você usa o método tables.patch para modificar visualizações e tabelas. Além disso, como o método tables.update substitui todo o recurso do conjunto de dados, é melhor usar o método tables.patch.

A seguir