Como atualizar rótulos

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

Como atualizar rótulos de conjuntos de dados

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

• use o Console do Cloud ou a IU da Web clássica do BigQuery;
• use o comando bq update da ferramenta de linha de comando;
• Chame o método de API datasets.patch.
• usando as bibliotecas de cliente.

Permissões necessárias

No mínimo, para atualizar um rótulo de conjunto de dados, você precisa ter as permissões bigquery.datasets.update. Os papéis predefinidos do Cloud IAM abaixo incluem permissões bigquery.datasets.update:

• 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 os rótulos em um conjunto de dados.

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

Como atualizar um rótulo de conjunto de dados

Para atualizar rótulos em um conjunto de dados:

Console

1. No Console do Cloud, selecione o conjunto de dados.

2. Na página de detalhes do conjunto de dados, clique no ícone de lápis à direita de Rótulos.

   

3. Na caixa de diálogo Editar rótulos, faça isto:

   • Para aplicar outros rótulos, clique em Adicionar rótulo. Cada chave pode ser usada apenas uma vez para cada conjunto de dados, mas é possível utilizar a mesma chave em conjuntos de dados diferentes dentro do mesmo projeto.
   • Modifique as chaves ou valores para atualizar um rótulo.
   • Clique em Atualizar para salvar as alterações.

IU clássica

1. Na IU da Web, selecione o conjunto de dados.

2. Na página Detalhes do conjunto de dados, à direita de Rótulos, clique em Editar.

   

3. Na caixa de diálogo Editar rótulos, faça isto:

   • Para aplicar outros rótulos, clique em Adicionar rótulo. Cada chave pode ser usada apenas uma vez para cada conjunto de dados, mas é possível utilizar a mesma chave em conjuntos de dados diferentes dentro do mesmo projeto.
   • Modifique as chaves ou valores para atualizar um rótulo.

   • Clique em OK.

     

CLI

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 exclusiva;
• 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 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.

Ver no GitHub Feedback

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

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

Ver no GitHub Feedback

static final HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
static final JsonFactory JSON_FACTORY = new JacksonFactory();

public static class Dataset {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Dataset addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a dataset.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelDataset(
    String projectId, String datasetId, String labelKey, String labelValue) throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Dataset dataset = new Dataset();
  dataset.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, dataset);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url = new GenericUrl(String.format(urlFormat, projectId, datasetId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Dataset responseDataset = response.parseAs(Dataset.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseDataset.getLabels().get(labelKey));
}

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.

Ver no GitHub Feedback

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

Ver no GitHub Feedback

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

Como atualizar rótulos de tabelas e visualizações

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

• use o Console do Cloud ou a IU da Web clássica do BigQuery;
• use o comando bq update da ferramenta de linha de comando;
• Como utilizar o método de 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

No mínimo, para atualizar uma tabela ou ver um rótulo, você precisa receber as permissões bigquery.tables.update. Os papéis predefinidos do Cloud IAM abaixo incluem permissões bigquery.tables.update:

• 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 a bigquery.dataOwner permite que o usuário atualize rótulos nos seus conjuntos de dados e em tabelas e visualizações desses conjuntos de dados.

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

Como atualizar um rótulo de visualização ou de tabela

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

Console

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

2. Clique na guia Detalhes e no ícone de lápis à direita de Rótulos.

3. Na caixa de diálogo Editar rótulos:

   • Para aplicar outros rótulos, clique em Adicionar rótulo. Cada chave pode ser usada apenas uma vez por tabela ou visualização, mas é possível utilizar a mesma chave em tabelas ou visualizações em conjuntos de dados diferentes.
   • Modifique as chaves ou valores para atualizar um rótulo.
   • Clique em Atualizar para salvar as alterações.

IU clássica

1. Na IU da Web, selecione a tabela ou a visualização.

2. Na página de detalhes, à direita de Rótulos, clique em Editar. Este exemplo mostra os detalhes de uma tabela.

   

3. Na caixa de diálogo Editar rótulos, faça isto:

   • Para incluir mais rótulos, clique em Adicionar rótulo. Cada chave pode ser usada apenas uma vez por tabela ou visualização, mas é possível utilizar a mesma chave em tabelas ou visualizações em conjuntos de dados diferentes.
   • Modifique as chaves ou valores para atualizar um rótulo.

   • Clique em OK.

     

CLI

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 exclusiva;
• 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 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.

Ver no GitHub Feedback

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

Ver no GitHub Feedback

public static class Table {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Table addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a table.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelTable(
    String projectId,
    String datasetId,
    String tableId,
    String labelKey,
    String labelValue)
    throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Table table = new Table();
  table.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, table);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s/tables/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url =
      new GenericUrl(String.format(urlFormat, projectId, datasetId, tableId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Table responseTable = response.parseAs(Table.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseTable.getLabels().get(labelKey));
}

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.

Ver no GitHub Feedback

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

Ver no GitHub Feedback

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

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

assert table.labels == labels

Como atualizar rótulos de job

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

Como 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 você 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 e assim por diante), é 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 ter, no mínimo, as mesmas permissões exigidas para atualizar rótulos.

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

Os papéis predefinidos do Cloud IAM abaixo incluem permissões bigquery.datasets.update:

• bigquery.dataOwner
• bigquery.admin

Os papéis predefinidos do Cloud IAM abaixo incluem permissões bigquery.tables.update:

• 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 a bigquery.dataOwner permite que o usuário atualize rótulos nos seus conjuntos de dados e em tabelas e visualizações desses conjuntos de dados.

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

Como converter um rótulo em uma tag

Para converter um rótulo em uma tag:

Console

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

2. No caso dos conjuntos de dados, a página Detalhes do conjunto de dados é aberta automaticamente. Para tabelas e visualizações, clique em Detalhes para abrir essa página.

   

3. Na página de detalhes, clique no ícone de lápis à direita de Rótulos.

   

4. Na caixa de diálogo Editar rótulos, faça isto:

   • Exclua o valor de um rótulo existente.
   • Clique em Atualizar.

IU clássica

1. Na IU da Web, selecione o conjunto de dados, a tabela ou a visualização.

2. No caso dos conjuntos de dados, a página Detalhes do conjunto de dados é aberta automaticamente. Para tabelas e visualizações, clique em Detalhes para abrir essa página.

3. Na página de detalhes, à direita de Rótulos, clique em Editar.

4. Na caixa de diálogo Editar rótulos, faça isto:

   • Exclua o valor de um rótulo existente.

   • Clique em OK.

     

CLI

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 de rótulo que você quer atualizar para uma tag;
• resource_id é um nome válido do conjunto de dados, tabela ou 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

• Saiba como adicionar rótulos a recursos do BigQuery.
• Saiba como visualizar rótulos em recursos do BigQuery.
• Saiba como filtrar recursos usando rótulos.
• Saiba como excluir rótulos em recursos do BigQuery.
• Leia Como usar rótulos na documentação do Resource Manager.