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

  1. No Console do GCP, 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.

    Ícone de lápis em 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 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

  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.

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

      Novo rótulo

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.

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

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.

# 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

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 nos respectivos conjuntos de dados e nas tabelas e visualizações nesses conjuntos.

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

  1. No Console do GCP, 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.

    Editar rótulos

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

      Novo rótulo

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

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.

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

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.

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

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.

# 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

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 nos respectivos conjuntos de dados e nas tabelas e visualizações nesses conjuntos.

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

  1. No Console do GCP, 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.

    Detalhes da tabela

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

    Ícone de lápis em Rótulos

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

  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:

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

      Adicionar tag

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

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

Enviar comentários sobre…

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