Como atualizar rótulos

Nesta página, você aprende 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 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 datasets.patch.
Use bibliotecas de cliente

Permissões necessárias

Para atualizar um rótulo de conjunto de dados, é necessário ter, no mínimo, as permissões bigquery.datasets.update. Os papéis predefinidos do Cloud IAM a seguir incluem permissões bigquery.datasets.update:

bigquery.dataOwner
bigquery.admin

Além disso, quando um usuário com permissões bigquery.datasets.create cria um conjunto de dados, ele recebe o acesso de bigquery.dataOwner ao conjunto. Com o acesso de bigquery.dataOwner, o usuário consegue atualizar rótulos em um 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 um rótulo de conjunto de dados

Para atualizar rótulos em um conjunto de dados:

Console

No Console do GCP, selecione o conjunto de dados.
Na página de detalhes do conjunto de dados, clique no ícone de lápis à direita de Rótulos.
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 para cada conjunto de dados, mas é possível usar 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

Na IU da Web, selecione o conjunto de dados.
Na página Detalhes do conjunto de dados, à direita de Rótulos, clique em Editar.
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 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 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 padrão, adicione o ID do projeto ao conjunto neste 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.

Por exemplo:

Para atualizar o rótulo department em mydataset, insira 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, insira o comando abaixo. mydataset está em myotherproject, e não no 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 atualizar um rótulo em um conjunto de dados atual ou adicionar outros rótulos, chame o método datasets.patch e adicione ou atualize a propriedade labels do recurso de conjunto de dados.

Como o método datasets.update substitui todo o recurso do conjunto de dados, recomenda-se usar o datasets.patch.

Go

Antes de testar este exemplo, 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 Go.

Ver no GitHub Feedback

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

Java

Nesta amostra, a biblioteca de cliente HTTP do Google para Java é usada para enviar uma solicitação à API do 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 saber mais informações, consulte a documentação de referência da API BigQuery 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));
}

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

Ver no GitHub Feedback

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# dataset = client.get_dataset(dataset_ref)  # API request

assert dataset.labels == {}
labels = {"color": "green"}
dataset.labels = labels

dataset = client.update_dataset(dataset, ["labels"])  # API request

assert dataset.labels == labels

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 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.
- Como as visualizações são tratadas como recursos da tabela, use o método tables.patch para modificar as visualizações e tabelas.
use bibliotecas de cliente.

Permissões necessárias

Para atualizar um rótulo de visualização ou de tabela, é necessário ter, no mínimo, as permissões bigquery.tables.update. Os papéis predefinidos do Cloud IAM a seguir incluem permissões bigquery.tables.update:

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

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

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

No Console do GCP, selecione a tabela ou a visualização.
Clique na guia Detalhes e no ícone de lápis à direita de Rótulos.
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

Na IU da Web, selecione a tabela ou a visualização.
Na página de detalhes, à direita de Rótulos, clique em Editar. Este exemplo mostra os detalhes de uma tabela.
Na caixa de diálogo Editar rótulos:
- 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 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 visualização estiver em um projeto diferente do padrão, adicione o ID do projeto ao conjunto neste 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.

Por exemplo:

Para atualizar o rótulo department em mytable, insira 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 em mytable, insira o comando a seguir. mytable está em myotherproject, e não no projeto padrão.

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

O resultado será semelhante ao mostrado a seguir:

Table 'myotherproject:mydataset.mytable' successfully updated.

API

Para atualizar um rótulo em uma tabela ou visualização atual ou adicionar outros rótulos, chame o método tables.patch e adicione ou atualize a propriedade labels do recurso de tabela.

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

Como o método tables.update substitui todo o recurso do conjunto de dados, recomenda-se usar o tables.patch.

Go

Ver no GitHub Feedback

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

Java

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

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

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 são úteis nas situações em que você está rotulando um recurso, mas não precisa do formato key:value. Por exemplo, se você tem 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 a seguir incluem permissões bigquery.datasets.update:

bigquery.dataOwner
bigquery.admin

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

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

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

Como converter um rótulo em uma tag

Para converter um rótulo em uma tag:

Console

No Console do GCP, selecione o conjunto de dados, a tabela ou a visualização.
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.
Na página de detalhes, clique no ícone de lápis à direita de Rótulos.
Na caixa de diálogo Editar rótulos, faça o seguinte:
- Exclua o valor de um rótulo existente.
- Clique em Atualizar.

IU clássica

Na IU da Web, selecione o conjunto de dados, a tabela ou a visualização.
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.
Na página de detalhes, à direita de Rótulos, clique em Editar.
Na caixa de diálogo Editar rótulos:
- Exclua o valor de um rótulo existente.
- Clique em OK.

CLI

Para converter um rótulo em uma 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 padrão, adicione o ID do projeto neste formato: project_id:dataset.

Por exemplo:

Insira o comando a seguir para alterar o rótulo test_data:development atual em mydataset para uma tag. mydataset está em myotherproject, e não no projeto padrão.

bq update --set_label test_data: myotherproject:mydataset

O resultado será semelhante ao mostrado a seguir:

Dataset 'myotherproject:mydataset' successfully updated.

API

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

Como as visualizações são tratadas como recursos da tabela, use o método tables.patch para modificar as visualizações e tabelas. Além disso, como tables.update substitui todo o recurso do conjunto de dados, recomenda-se o método tables.patch.

A seguir

Saiba como adicionar rótulos a recursos do BigQuery.
Saiba como visualizar rótulos nos 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.

Como atualizar rótulos de conjuntos de dados

Permissões necessárias

Como atualizar um rótulo de conjunto de dados

Console

IU clássica

CLI

API

Go

Java

Python

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

Permissões necessárias

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

Console

IU clássica

CLI

API

Go

Java

Python

Como atualizar rótulos de job

Como converter rótulos em tags

Permissões necessárias

Como converter um rótulo em uma tag

Console

IU clássica

CLI

API

A seguir

Enviar comentários sobre…