Como criar e gerenciar rótulos

Para ajudar a organizar seus recursos do BigQuery, você pode adicionar rótulos aos seus conjuntos de dados, tabelas e visualizações. Rótulos são pares de chave-valor que você pode anexar a um recurso. Quando você cria recursos do BigQuery, os rótulos são opcionais.

Depois de rotular seus recursos, você pode procurá-los com base nos valores do rótulo. Por exemplo, você pode usar rótulos para agrupar conjuntos de dados por finalidade, ambiente, departamento e assim por diante.

Nesta página, você verá como usar rótulos com seus recursos do BigQuery. Também verá como adicionar, atualizar e remover os rótulos de um recurso.

O que são rótulos?

Um rótulo é um par de chave-valor que ajuda você a organizar seus recursos do BigQuery no Google Cloud Platform. É possível anexar um rótulo a cada recurso e filtrar os recursos com base nesses rótulos. As informações sobre os rótulos são encaminhadas ao sistema de faturamento para que você possa classificar as cobranças de faturamento por rótulo.

Usos comuns dos rótulos

Aqui estão alguns casos de uso comum para rótulos:

  • Rótulos de equipe ou centro de custo: para distinguir os recursos do BigQuery pertencentes a diferentes equipes, adicione rótulos com base na equipe ou no centro de custo. Por exemplo, team:research e team:analytics. Você pode usar esse tipo de rótulo para contabilidade ou orçamento de custos.

  • Rótulos de componentes: por exemplo, component:redis, component:frontend, component:ingest e component:dashboard.

  • Rótulos de ambientes ou de cenários: por exemplo, environment:production e environment:test.

  • Rótulos de proprietário ou contato: adicione rótulos com base no proprietário ou em um contato principal para recursos do BigQuery.

  • Rótulos de estado: por exemplo, state:active, state:readytodelete e state:archive.

Requisitos para rótulos

Os rótulos aplicados a um recurso precisam atender aos seguintes requisitos:

  • Cada recurso pode ter vários rótulos, até um máximo de 64.
  • Cada rótulo precisa ser um par de chave-valor.
  • As chaves têm comprimento mínimo de um e máximo de 63 caracteres, e não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 caracteres.
  • 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.
  • A parte da chave de um rótulo precisa ser única. No entanto, você pode usar a mesma chave com vários recursos.
  • As chaves precisam começar com uma letra minúscula ou um caractere internacional.

Como criar e atualizar rótulos de conjunto de dados

É possível adicionar um rótulo a um conjunto de dados do BigQuery ao criá-lo. Basta usar o comando bq mk da ferramenta de linha de comando ou chamar o método datasets.insert da API. Para mais informações sobre como adicionar um rótulo quando você cria um conjunto de dados, consulte Como criar um conjunto de dados.

Um rótulo pode ser adicionado ou atualizado após a criação de um conjunto de dados. Basta usar a IU da Web do BigQuery ou o comando bq update da ferramenta de linha de comando ou chamar o método datasets.patch da API.

Permissões necessárias

Para adicionar ou atualizar um rótulo de conjunto de dados, após a criação, você precisa ter acesso OWNER ao conjunto de dados ou ter um papel de IAM predefinido para envolvidos no projeto e que inclua permissões bigquery.datasets.update. Os papéis do IAM predefinidos a seguir no nível do projeto incluem permissões bigquery.datasets.update:

Além disso, como o papel bigquery.user tem permissões bigquery.datasets.create, um usuário com bigquery.user pode atualizar qualquer conjunto de dados criado por ele. Quando um usuário com papel bigquery.user cria um conjunto de dados, recebe acesso de OWNER ao conjunto. Com o acesso de OWNER, o usuário tem controle total sobre o conjunto de dados.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso. Para mais informações sobre os papéis no nível do conjunto de dados, consulte Papéis primários para conjuntos de dados.

Como criar ou atualizar um rótulo de conjunto de dados

Para atualizar um rótulo de conjunto de dados ou para adicionar um rótulo a um conjunto de dados depois que ele é criado:

IU da Web

  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, realize as etapas a seguir:

    • Digite a chave e o valor para adicionar um rótulo. Para aplicar rótulos adicionais, clique em Adicionar rótulo. Cada chave pode ser usada somente uma vez por conjunto de dados, mas você pode usar a mesma chave em conjuntos de dados diferentes no mesmo projeto.
    • Modifique as chaves ou valores existentes para atualizar um rótulo.
    • Clique em OK.

      Novo rótulo

Linha de comando

Para adicionar ou atualizar um rótulo de conjunto de dados, insira 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 código 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 criar ou atualizar. Se você especificar a mesma chave que a de um rótulo existente, o valor do rótulo existente será atualizado. A chave precisa ser única;
  • [PROJECT_ID] é o código do projeto;
  • [DATASET] é o conjunto de dados que você está atualizando.

Exemplos:

Para adicionar um rótulo para rastrear os departamentos, insira o comando bq update e especifique department como a chave do rótulo. Por exemplo, para adicionar um rótulo department:shipping para mydataset no projeto padrão, digite:

    bq update --set_label department:shipping mydataset

Para atualizar o rótulo department, 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, digite o comando abaixo. mydataset está em myotherproject, não no projeto padrão.

    bq update --set_label department:logistics myotherproject:mydataset

Para adicionar vários rótulos a um conjunto de dados, repita a sinalização set_label e especifique uma chave exclusiva para cada rótulo. Para excluir vários rótulos em um conjunto de dados, repita a sinalização clear_label e especifique cada par de chave-valor. Por exemplo, para adicionar um rótulo department:shipping e um rótulo cost_center:logistics para mydataset no projeto padrão, digite:

    bq update --set_label department:shipping --set_label cost_center:logistics mydataset

API

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

Como datasets.update substitui todo o recurso do conjunto de dados, o método datasets.patch é recomendado.

Go

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

Neste exemplo, usamos a Biblioteca de cliente HTTP do Google para Java para enviar uma solicitação à API do BigQuery.
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 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 criar e atualizar rótulos de tabela e visualização

É possível adicionar um rótulo a uma tabela ou visualização ao criá-las. Basta usar o comando bq mk da ferramenta de linha de comando ou chamar o método tables.insert da API. Para mais informações sobre como adicionar um rótulo a uma tabela ou visualização ao criá-la, consulte Como criar uma tabela ou Como criar uma visualização.

Um rótulo pode ser adicionado ou atualizado depois que uma tabela ou visualização é criada. Basta usar a IU da Web do BigQuery, o comando bq update da ferramenta de linha de comando ou chamar o método tables.patch da API. Como as visualizações são tratadas como recursos da tabela, use o método tables.patch para modificar as visualizações e as tabelas.

Permissões necessárias

Para criar ou atualizar um rótulo de uma tabela ou visualização, é necessário ter acesso OWNER ao conjunto de dados ou ter um papel de IAM predefinido para envolvidos no projeto e que inclua permissões bigquery.tables.update. Os papéis do IAM predefinidos a seguir 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 o papel bigquery.user pode atualizar tabelas e visualizações em qualquer conjunto de dados criado por ele. Quando um usuário com papel bigquery.user cria um conjunto de dados, recebe acesso de OWNER ao conjunto. O acesso OWNER concede ao usuário o controle total sobre o conjunto e às tabelas e visualizações nele.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso. Para mais informações sobre os papéis no nível do conjunto de dados, consulte Papéis primários para conjuntos de dados.

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

Para atualizar um rótulo de visualização ou tabela, ou para adicionar um rótulo a uma tabela ou visualização depois que ele é criado:

IU da Web

  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, realize as etapas a seguir:

    • Digite a chave e o valor para adicionar um rótulo. Para aplicar rótulos adicionais, clique em Adicionar rótulo. Cada chave pode ser usada apenas uma vez por tabela ou visualização, mas você pode usar a mesma chave em tabelas ou visualizações em conjuntos de dados diferentes.
    • Modifique as chaves ou valores existentes para atualizar um rótulo.
    • Clique em OK.

      Novo rótulo

Linha de comando

Para adicionar ou atualizar um rótulo de visualização ou tabela, insira 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 código 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 criar ou atualizar. Se você especificar a mesma chave que a de um rótulo existente, o valor do rótulo existente será atualizado. A chave precisa ser única;
  • [PROJECT_ID] é o código 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.

Exemplos:

Para adicionar um rótulo para rastrear os departamentos, insira o comando bq update e especifique department como a chave do rótulo. Por exemplo, para adicionar um rótulo department:shipping para mytable no projeto padrão, digite:

    bq update --set_label department:shipping mydataset.mytable

Para adicionar um rótulo para rastrear os departamentos, insira o comando bq update e especifique department como a chave do rótulo. Por exemplo, para adicionar um rótulo department:shipping para myview no projeto padrão, digite:

    bq update --set_label department:shipping mydataset.myview

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

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

Para adicionar vários rótulos a uma tabela ou visualização, repita a sinalização set_label e especifique uma chave exclusiva para cada rótulo. Por exemplo, para adicionar um rótulo department:shipping e um rótulo cost_center:logistics para mytable no projeto padrão, digite:

    bq update --set_label department:shipping --set_label cost_center:logistics mydataset.mytable

API

Para adicionar ou atualizar um rótulo em uma tabela ou visualização existentes, 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 as tabelas.

Como tables.update substitui todo o recurso do conjunto de dados, o método tables.patch é recomendado.

Go

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

Neste exemplo, usamos a Biblioteca de cliente HTTP do Google para Java para enviar uma solicitação à API do BigQuery.
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 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 excluir rótulos

Para remover um rótulo de um conjunto de dados, uma tabela ou uma visualização, use a IU da Web do BigQuery, o comando bq update da ferramenta de linha de comando ou chame um dos métodos da API do BigQuery, datasets.patch ou tables.patch.

Como excluir um rótulo de conjunto de dados

Para remover um rótulo do conjunto de dados, use a IU da Web do BigQuery, o comando bq update da ferramenta de linha de comando ou chame o método datasets.patch da API.

Permissões necessárias

Para excluir um rótulo de um conjunto de dados, é necessário ter acesso OWNER ao conjunto de dados ou ter um papel de IAM predefinido para envolvidos no projeto e que inclua permissões bigquery.datasets.update. Os papéis do IAM predefinidos a seguir no nível do projeto incluem permissões bigquery.datasets.update:

Além disso, como o papel bigquery.user tem permissões bigquery.datasets.create, um usuário com bigquery.user pode atualizar qualquer conjunto de dados criado por ele. Quando um usuário com papel bigquery.user cria um conjunto de dados, recebe acesso de OWNER ao conjunto. Com o acesso de OWNER, o usuário tem controle total sobre o conjunto de dados.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso. Para mais informações sobre os papéis no nível do conjunto de dados, consulte Papéis primários para conjuntos de dados.

Como excluir um rótulo de conjunto de dados

Para excluir um rótulo de um conjunto de dados:

IU da Web

  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, realize as etapas a seguir:

    • Clique no ícone de exclusão (X) para cada rótulo que você quer remover.
    • Clique em OK.

      Excluir rótulo

Linha de comando

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

Se o conjunto de dados estiver em um projeto diferente do padrão, adicione o código do projeto ao conjunto neste formato: [PROJECT_ID]:[DATASET].

    bq update --clear_label [KEY] [PROJECT_ID]:[DATASET]

Em que:

  • [KEY] é a chave para um rótulo que você quer remover;
  • [PROJECT_ID] é o código do projeto;
  • [DATASET] é o conjunto de dados que você está atualizando.

Exemplos:

Para remover o rótulo department:shipping de mydataset, insira o comando bq update com a sinalização --clear_label. mydataset está no projeto padrão.

    bq update --clear_label department mydataset

Para remover o rótulo department:shipping de mydataset em myotherproject, insira o comando bq update com a sinalização --clear_label.

    bq update --clear_label department myotherproject:mydataset

Para remover vários rótulos de um conjunto de dados, repita a sinalização clear_label e especifique a chave de cada rótulo. Por exemplo, para remover os rótulos department:shipping e cost_center:logistics de mydataset no projeto padrão, digite:

    bq update --clear_label department --clear_label cost_center mydataset

API

Para remover um rótulo específico de um conjunto de dados existente, chame o método datasets.patch e atualize a propriedade labels do recurso do conjunto de dados definindo o valor da chave do rótulo como null.

Para remover todos os rótulos de um conjunto de dados, chame o método datasets.patch e remova a propriedade labels.

Como datasets.update substitui todo o recurso do conjunto de dados, o método datasets.patch é recomendado.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go 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 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.DeleteLabel("color")
if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Python

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()
# dataset_ref = client.dataset('my_dataset')
# dataset = client.get_dataset(dataset_ref)  # API request

# This example dataset starts with one label
assert dataset.labels == {'color': 'green'}
# To delete a label from a dataset, set its value to None
dataset.labels['color'] = None

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

assert dataset.labels == {}

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

Para remover o rótulo de uma tabela ou visualização, use a IU da Web do BigQuery ou o comando bq update da ferramenta de linha de comando ou chame o método tables.patch da API. Como as visualizações são tratadas como recursos da tabela, use o método tables.patch para modificar as visualizações e as tabelas.

Permissões necessárias

Para excluir um rótulo de uma tabela ou visualização, é necessário ter acesso OWNER ao conjunto de dados ou ter um papel de IAM predefinido para envolvidos no projeto e que inclua permissões bigquery.tables.update. Os papéis do IAM predefinidos a seguir 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 atribuído ao papel bigquery.user pode atualizar uma tabela ou visualização em qualquer conjunto de dados que ele crie. Quando um usuário com papel bigquery.user cria um conjunto de dados, recebe acesso de OWNER ao conjunto. O acesso OWNER concede ao usuário o controle total sobre o conjunto e todas as tabelas e visualizações nele.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso. Para mais informações sobre os papéis no nível do conjunto de dados, consulte Papéis primários para conjuntos de dados.

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

Para excluir um rótulo de uma tabela ou visualização:

IU da Web

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

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

  3. Na caixa de diálogo Editar rótulos, realize as etapas a seguir:

    • Clique no ícone de exclusão (X) para cada rótulo que você quer remover.
    • Clique em OK.

      Excluir rótulo

Linha de comando

Para excluir um rótulo de visualização ou tabela, insira o comando bq update com a sinalização clear_label. Repita a sinalização para remover vários rótulos.

Se a tabela ou visualização estiver em um projeto diferente do padrão, adicione o código do projeto ao conjunto neste formato: [PROJECT_ID]:[DATASET].

    bq update --clear_label [KEY] [PROJECT_ID]:[TABLE_OR_VIEW]

Em que:

  • [KEY] é a chave para um rótulo que você quer remover;
  • [PROJECT_ID] é o código do projeto;
  • [DATASET] é o conjunto de dados que você está atualizando;
  • [TABLE_OR_VIEW] é o nome da tabela ou visualização que você está atualizando.

Exemplos:

Para remover o rótulo department:shipping de mydataset.mytable, insira o comando bq update com a sinalização --clear_label. mydataset está no projeto padrão.

    bq update --clear_label department mydataset.mytable

Para remover o rótulo department:shipping de mydataset.myview em myotherproject, insira o comando bq update com a sinalização --clear_label.

    bq update --clear_label department myotherproject:mydataset.myview

Para remover vários rótulos de uma tabela ou visualização, repita a sinalização clear_label e especifique a chave de cada rótulo. Por exemplo, para remover os rótulos department:shipping e cost_center:logistics de mydataset.mytable no projeto padrão, digite:

    bq update --clear_label department --clear_label cost_center mydataset.mytable

API

Para remover um rótulo específico de uma tabela ou visualização existentes, chame o método tables.patch e atualize a propriedade labels do recurso de tabela definindo o valor da chave do rótulo como null.

Para remover todos os rótulos de uma tabela ou visualização, chame o método tables.patch e remova a propriedade labels.

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

Go

Antes de testar esta amostra, siga as instruções de configuração do Go 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 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.DeleteLabel("color")
if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Python

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

# This example table starts with one label
assert table.labels == {'color': 'green'}
# To delete a label from a table, set its value to None
table.labels['color'] = None

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

assert table.labels == {}

Como criar uma tag

Um rótulo que tem uma chave com um valor vazio é usado como uma tag. Você pode criar um novo rótulo sem valor ou pode transformar um existente em uma tag.

As tags podem ser úteis em situações em que você está rotulando um recurso, mas não precisa do formato chave-valor. Por exemplo, se você tem uma tabela que contenha dados de teste usados por vários grupos (suporte, desenvolvimento e assim por diante), pode adicionar uma tag test_data à tabela para identificá-la.

Para criar uma tag:

IU da Web

  1. Na IU da Web, selecione o recurso apropriado (um conjunto de dados, uma tabela ou uma visualização).

  2. Para 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, realize as etapas a seguir:

    • Insira uma nova chave e deixe o valor em branco ou exclua o valor de um rótulo existente. Para aplicar tags adicionais, clique em Adicionar rótulo.
    • Clique em OK.

      Adicionar tag

Linha de comando

Use o comando bq update com a sinalização set_label. Especifique a chave, seguida por dois-pontos, mas deixe o valor sem especificação. Isso pode ser usado para atualizar um rótulo existente para uma tag ou para adicionar uma nova tag.

bq update --set_label [KEY]: [RESOURCE_ID]

Em que:

  • [KEY] é a chave de rótulo que você quer usar como 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 projeto padrão, adicione o código do projeto neste formato: [PROJECT_ID]:[DATASET].

Exemplos:

Digite o comando a seguir para criar uma tag test_data para mydataset.mytable. mydataset está no projeto padrão.

bq update --set_label test_data: mydataset

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

bq update --set_label test_data: myotherproject:mydataset

API

Chame o método datasets.patch ou o método tables.patch e adicione rótulos com o valor definido para a string vazia ("") no recurso do conjunto de dados ou no recurso de tabela. Para transformar os rótulos existentes em tags, substitua os respectivos valores pela string vazia.

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

Como visualizar rótulos

Para visualizar os rótulos, use a IU da Web do BigQuery, o comando bq show da ferramenta de linha de comando ou chame os métodos datasets.get ou tables.get da API. Como as visualizações são tratadas como recursos de tabela, use o método tables.get para conseguir informações de rótulos para visualizações e tabelas.

Permissões necessárias

As permissões necessárias para a visualização de rótulos dependem do tipo de recurso que você acessa.

Permissões do conjunto de dados

Para receber informações sobre um conjunto de dados, é preciso ter um papel READER no nível do conjunto de dados ou um papel IAM predefinido para envolvidos no projeto e que inclua permissões bigquery.datasets.get. Todos os papéis do IAM predefinidos no nível do projeto incluem permissões bigquery.datasets.get, exceto bigquery.jobUser

Além disso, um usuário com papel bigquery.user tem permissões bigquery.datasets.create. Assim, um usuário com papel bigquery.user pode receber informações sobre qualquer conjunto de dados que tenha sido criado por ele. Quando um usuário com papel bigquery.user cria um conjunto de dados, recebe acesso de OWNER ao conjunto. Com o acesso de OWNER, o usuário tem controle total sobre o conjunto de dados.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso. Para mais informações sobre os papéis no nível do conjunto de dados, consulte Papéis primários para conjuntos de dados.

Permissões de visualização e tabela

Para receber informações sobre tabelas, é preciso ter o papel READER no conjunto de dados ou um papel do IAM predefinido no nível do projeto que inclua permissões bigquery.tables.get. Se você tem permissões bigquery.tables.get no nível do projeto, pode acessar informações sobre todas as tabelas do projeto. Todos os papéis predefinidos do IAM no nível do projeto incluem permissões bigquery.tables.get exceto bigquery.user e bigquery.jobUser.

Além disso, um usuário com papel bigquery.user tem permissões bigquery.datasets.create. Assim, um usuário com papel bigquery.user pode receber informações sobre tabelas e visualizações em qualquer conjunto de dados que tenha sido criado por ele. Quando um usuário com papel bigquery.user cria um conjunto de dados, recebe acesso de OWNER ao conjunto. O acesso OWNER concede ao usuário o controle total sobre o conjunto e todas as tabelas e visualizações nele.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso. Para mais informações sobre os papéis no nível do conjunto de dados, consulte Papéis primários para conjuntos de dados.

Como visualizar rótulos de visualizações, tabelas e conjuntos de dados

Para visualizar os rótulos de um recurso:

IU da Web

  1. Na IU da Web, selecione o recurso apropriado (um conjunto de dados, uma tabela ou uma visualização).

  2. Para 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. As informações do rótulo são exibidas na tabela de informações do recurso.

Linha de comando

Use o comando bq show com o código do recurso. A sinalização --format pode ser usada para controlar a saída. Se o recurso estiver em um projeto diferente do projeto padrão, adicione o código do projeto neste formato: [PROJECT_ID]:[DATASET]. Para legibilidade, a saída é controlada por meio da configuração da sinalização --format para pretty.

bq show --format=pretty [RESOURCE_ID]

Em que [RESOURCE_ID] é um conjunto de dados, uma tabela ou um nome de visualização válidos.

Exemplos:

Digite o comando a seguir para exibir rótulos de mydataset no projeto padrão.

bq show --format=pretty mydataset

Insira o comando a seguir para exibir rótulos de mydataset.mytable. mydataset está em myotherproject, não no projeto padrão.

bq show --format=pretty myotherproject:mydataset.mytable

API

Chame o método datasets.get ou o tables.get. A resposta inclui todos os rótulos associados a esse recurso.

Como alternativa, use datasets.list para visualizar os rótulos de vários conjuntos de dados ou tables.list para visualizar os rótulos de várias tabelas e visualizações.

Como visualizações são tratadas como recursos de tabela, use os métodos tables.get e tables.list ver informações do rótulo em visualizações e tabelas.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go 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 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")
meta, err := client.Dataset(datasetID).Metadata(ctx)
if err != nil {
	return err
}
fmt.Fprintf(w, "Dataset %s labels:\n", datasetID)
if len(meta.Labels) == 0 {
	fmt.Fprintln(w, "Dataset has no labels defined.")
	return nil
}
for k, v := range meta.Labels {
	fmt.Fprintf(w, "\t%s:%s\n", k, v)
}

Python

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()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
dataset = client.get_dataset(dataset_ref)  # API request

# View dataset labels
print('Dataset ID: {}'.format(dataset_id))
print('Labels:')
if dataset.labels:
    for label, value in dataset.labels.items():
        print('\t{}: {}'.format(label, value))
else:
    print("\tDataset has no labels defined.")

Como filtrar conjuntos de dados usando rótulos

Para filtrar conjuntos de dados com base em rótulos, crie uma especificação de filtro para uso na ferramenta de linha de comando bq ou na API do BigQuery que use a sintaxe a seguir:

    "field[:value][ field[:value]..."

Em que:

  • field é expresso como labels.[KEY], no qual [KEY] é uma chave de rótulo;
  • value é um valor de rótulo opcional.

Atualmente, não é possível listar tabelas ou visualizações com base em uma especificação de filtro.

Limitações

A especificação do filtro tem estas limitações:

  • Somente o operador lógico AND é compatível. As comparações separadas por espaço são tratadas como tendo operadores AND implícitos.
  • O único campo atualmente elegível para a filtragem é "labels.key", no qual "key" é o nome de um rótulo.
  • O filtro pode incluir até dez expressões.
  • A filtragem diferencia maiúsculas de minúsculas.
  • Não é possível filtrar tabelas e visualizações usando uma especificação de filtro.
  • Atualmente, não é possível filtrar conjuntos de dados usando a IU da Web do BigQuery.

Exemplos de especificação de filtros

Para listar conjuntos de dados que têm um rótulo department:shipping, use esta especificação de filtro:

labels.department:shipping

Para listar conjuntos de dados usando vários rótulos, separe os pares de chave-valor com um espaço. O espaço é tratado como um operador AND lógico. Por exemplo, para listar os conjuntos de dados com os rótulos department:shipping e location:usa, use a especificação de filtro abaixo:

labels.department:shipping labels.location:usa

Você pode filtrar a presença de uma chave sozinha, em vez de corresponder com um par de chave-valor. A especificação de filtro a seguir lista todos os conjuntos de dados rotulados como department independentemente do valor:

labels.department

Uma especificação de filtro equivalente usa um asterisco para representar todos os valores possíveis associados à chave department:

labels.department:*

Você também pode usar tags em uma especificação de filtro. Por exemplo, para listar conjuntos de dados com o rótulo department:shipping e a tag test_data, use a especificação de filtro abaixo:

labels.department:shipping labels.test_data

Como gerar listas filtradas

Para gerar uma lista filtrada de conjuntos de dados:

IU da Web

Atualmente, não é possível filtrar conjuntos de dados usando a IU da Web do BigQuery.

Linha de comando

Insira o comando bq ls com a sinalização --filter. Se você estiver listando conjuntos de dados em um projeto diferente do projeto padrão, especifique a sinalização --project_id.

bq ls --filter "[FILTER_SPECIFICATION]" --project_id [PROJECT_ID]

Em que:

  • [FILTER_SPECIFICATION] é uma especificação de filtro válida. A ferramenta de linha de comando retorna uma lista de conjuntos de dados que atendem aos requisitos de filtro;
  • [PROJECT_ID] é o código do projeto.

Exemplos:

Digite o comando a seguir para listar conjuntos de dados no projeto padrão que tenham um rótulo department:shipping:

bq ls --filter "labels.department:shipping"

Digite o comando a seguir para listar conjuntos de dados no projeto padrão que tenham um rótulo department:shipping e uma tag test_data.

bq ls --filter "labels.department:shipping labels.test_data"

Digite o comando a seguir para listar conjuntos de dados em myotherproject que tenham um rótulo department:shipping:

bq ls --filter "labels.department:shipping" --project_id myotherproject

API

Chame o método datasets.list da API e use a propriedade filter para informar a especificação do filtro.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go 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 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")
it := client.Datasets(ctx)
it.Filter = "labels.color:green"
for {
	dataset, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "dataset: %s\n", dataset.DatasetID)
}

Python

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

# The following label filter example will find datasets with an
# arbitrary 'color' label set to 'green'
label_filter = 'labels.color:green'
datasets = list(client.list_datasets(filter=label_filter))

if datasets:
    print('Datasets filtered by {}:'.format(label_filter))
    for dataset in datasets:  # API request(s)
        print('\t{}'.format(dataset.dataset_id))
else:
    print('No datasets found with this filter.')

Próximas etapas

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

Enviar comentários sobre…

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