Como adicionar e usar rótulos

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

Depois de rotular seus recursos, procure-os com base nos valores do rótulo. Por exemplo, use rótulos para agrupar conjuntos de dados por finalidade, ambiente, departamento e assim por diante.

Nesta página, explicamos como adicionar rótulos recursos do BigQuery.

Para saber informações sobre como gerenciar rótulos, consulte Como gerenciar rótulos.

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

Veja 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. Esse tipo de rótulo pode ser usado para contabilidade de custos ou elaboração de orçamentos.

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

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

  • 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 1 e máximo de 63 caracteres. Além disso, elas 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, use a mesma chave com vários recursos.
  • As chaves precisam começar com uma letra minúscula ou um caractere internacional.

Como adicionar 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 da API datasets.insert. No momento, não é possível adicionar um rótulo a um conjunto de dados durante a criação dele por meio do Console do GCP ou da IU clássica da Web do BigQuery.

Nesta página, discutimos como adicionar um rótulo a um conjunto de dados depois de ele ser criado: Para saber mais informações sobre como adicionar um rótulo quando você cria um conjunto de dados, consulte Como criar um conjunto de dados.

Quando um rótulo é adicionado a um conjunto de dados, ele é incluído nos dados de faturamento do armazenamento. No entanto, não haverá rótulos de conjuntos de dados nos dados de faturamento relacionados a jobs.

Permissões necessárias

Para adicionar um rótulo a um conjunto de dados atual, é preciso ter acesso de OWNER no nível do conjunto ou um papel do IAM para envolvidos no projeto que inclua permissões bigquery.datasets.update. Os seguintes papéis do IAM predefinidos para envolvidos no 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 para conjuntos de dados, consulte Papéis primários para conjuntos de dados.

Como adicionar um rótulo a um conjunto de dados

Para adicionar um rótulo a um conjunto de dados após ele ser criado, faça o seguinte:

Console

  1. Na IU da Web do BigQuery, 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.

    Rótulo de lápis

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

    • Clique em Adicionar rótulo.
    • Digite a chave e o valor para adicionar um rótulo. Para aplicar outros rótulos, clique em Adicionar rótulo. Cada chave pode ser usada somente uma vez por conjunto de dados, mas é possível usar a mesma chave em conjuntos diferentes no mesmo projeto.
    • 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 do BigQuery, 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 mais rótulos, clique em Adicionar rótulo. Cada chave pode ser usada somente uma vez por conjunto de dados, mas é possível usar a mesma chave em conjuntos diferentes no mesmo projeto.
    • Modifique as chaves ou valores para atualizar um rótulo.
    • Clique em OK.

      Novo rótulo

Linha de comando

Para adicionar um rótulo a um conjunto de dados atual, insira o comando bq update com a sinalização set_label. Repita a sinalização para adicionar 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 chave-valor para um rótulo que você quer adicionar. A chave precisa ser exclusiva;
  • [PROJECT_ID] é o código do projeto;
  • [DATASET] é o conjunto de dados a que você está adicionando o rótulo.

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 a mydataset no projeto padrão, digite:

    bq update --set_label department:shipping 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. Por exemplo, para adicionar os rótulos department:shipping e cost_center:logistics a mydataset no projeto padrão, digite:

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

API

Para adicionar um rótulo a um conjunto de dados atual, chame o método datasets.patch e preencha a propriedade labels do recurso desse conjunto.

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

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery 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 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 em 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 adicionar rótulos a tabelas e visualizações

É 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 da API tables.insert.

Nesta página, discutimos como adicionar um rótulo a uma visualização ou tabela atual. Para mais informações sobre como adicionar um rótulo a uma tabela ou visualização durante a criação delas, consulte Como criar uma tabela ou Como criar uma visualização.

Só é possível adicionar um rótulo a uma tabela ou visualização atual usando o Console do GCP, a IU da Web clássica do BigQuery, o comando bq update da ferramenta de linha de comando ou o método da 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.

Permissões necessárias

Para adicionar um rótulo a uma tabela ou visualização atual, é necessário ter acesso de OWNER no nível do conjunto de dados ou ter um papel do IAM para envolvidos no projeto que inclua permissões bigquery.tables.update. Os seguintes papéis do IAM predefinidos para envolvidos no 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 para conjuntos de dados, consulte Papéis primários para conjuntos de dados.

Como adicionar um rótulo a uma tabela ou visualização

Para adicionar um rótulo a uma tabela ou visualização existente, faça o seguinte:

Console

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

  2. Clique na guia Detalhes.

    Detalhes da tabela

  3. Clique no ícone de lápis à direita de Rótulos.

    Rótulo de lápis

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

    • Clique em Adicionar rótulo.
    • Digite a chave e o valor para adicionar um rótulo. Para aplicar outros rótulos, clique em Adicionar rótulo. Cada chave pode ser usada somente uma vez por conjunto de dados, mas é possível usar a mesma chave em conjuntos diferentes no mesmo projeto.
    • Modifique as chaves ou os valores para atualizar um rótulo.
    • Clique em Atualizar para salvar as alterações.

IU clássica

Opção 1: editar os rótulos manualmente 1. Na IU da Web do BigQuery, selecione a tabela ou a visualização.

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

    Editar rótulos

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

    • Digite a chave e o valor para adicionar um rótulo. Para aplicar mais rótulos, 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.
    • Clique em OK.

      Novo rótulo

Opção 2: usar uma instrução DDL

As instruções de Linguagem de definição de dados (DDL, na sigla em inglês) permitem criar e modificar tabelas e visualizações usando a sintaxe de consulta SQL padrão.

Saiba mais sobre Como usar as instruções de Linguagem de definição de dados.

  1. Clique em Escrever consulta.

  2. Digite a instrução DDL na área de texto Nova consulta.

     #standardSQL
     ALTER TABLE mydataset.mytable
     SET OPTIONS (
       labels=[("department", "shipping"), ("cost_center", "logistics")]
     )
     

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 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 chave-valor para um rótulo que você quer adicionar. A chave precisa ser exclusiva;
  • [PROJECT_ID] é o código do projeto;
  • [DATASET] é o conjunto de dados que contém a tabela em que você está adicionando um rótulo;
  • [TABLE_OR_VIEW] é o nome da tabela ou visualização em que você está adicionando um rótulo.

Exemplos:

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

    bq update --set_label department:shipping mydataset.mytable

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

    bq update --set_label department:shipping mydataset.myview

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 um rótulo a uma tabela ou visualização atual, chame o método tables.patch e preencha a propriedade labels para o 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 esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery 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 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 em 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 adicionar rótulos a jobs

Os rótulos podem ser adicionados a jobs de consulta usando a sinalização --label da ferramenta de linha de comando. A ferramenta de linha de comando só é compatível com a adição de rótulos a jobs de consulta.

Também é possível adicionar um rótulo a um job após o envio dele por meio da API. Basta especificar a propriedade labels na configuração do job quando você chama o método jobs.insert. A API pode ser usada para adicionar rótulos a qualquer tipo de job.

Não é possível adicionar ou atualizar rótulos em jobs pendentes, em execução ou concluídos.

Quando adicionar um rótulo a um job, o rótulo é incluído nos seus dados de faturamento.

Permissões necessárias

Não é necessária nenhuma permissão especial para adicionar um rótulo a um job. Se você tiver permissões jobs.create, poderá adicionar um rótulo ao job quando enviá-lo.

Para executar um job, é necessário ter permissões bigquery.jobs.create. Permissões bigquery.jobs.create são necessárias para os jobs criados automaticamente pelo BigQuery e os executados programaticamente.

Para executar jobs do BigQuery, conceda permissões bigquery.jobs.create para sua conta de usuário ou serviço, ou conceda a ela um papel do IAM predefinido no nível do projeto que inclua permissões bigquery.jobs.create. Os papéis predefinidos do IAM a seguir incluem as permissões bigquery.jobs.create:

Para saber mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso.

Como adicionar um rótulo a um job

Observe o seguinte ao adicionar um rótulo a um job:

Console

Não é possível adicionar rótulos a jobs usando a IU da Web do BigQuery no console.

IU clássica

Não é possível adicionar rótulos a jobs usando a IU clássica da Web do BigQuery.

Linha de comando

Para adicionar um rótulo a um job de consulta, insira o comando bq query com a sinalização --label. Repita a sinalização para adicionar vários rótulos. A sinalização --nouse_legacy_sql indica que sua consulta está na sintaxe SQL padrão.

bq query --label [KEY:VALUE] --nouse_legacy_sql '[QUERY]'

Em que:

  • [KEY:VALUE] corresponde a um par chave-valor para um rótulo que você quer adicionar ao job de consulta. A chave precisa ser exclusiva. Para adicionar vários rótulos a um job de consulta, repita a sinalização --label e especifique uma chave exclusiva para cada rótulo;
  • [QUERY] é uma consulta SQL padrão válida.

Exemplos:

Para adicionar um rótulo a um job de consulta, digite:

    bq query --label department:shipping --nouse_legacy_sql 'SELECT column1, column2 FROM `mydataset.mytable`'

Para adicionar vários rótulos a um job de consulta, repita a sinalização --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 a um job de consulta, digite:

    bq query --label department:shipping --label cost_center:logistics --nouse_legacy_sql 'SELECT column1, column2 FROM `mydataset.mytable`'

API

Para adicionar um rótulo a um job, chame o método jobs.insert e preencha a propriedade labels do recurso de job. É possível pode usar a API para adicionar rótulos a qualquer tipo de job.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery 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
}

Como criar uma tag

Um rótulo que tem uma chave com um valor vazio é usado como uma tag. Crie um novo rótulo sem valor ou pode transformar um atual 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, faça o seguinte:

Console

  1. Na IU da Web, selecione o recurso apropriado, por exemplo, um conjunto de dados, uma tabela ou uma 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.

    Rótulo de lápis

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

    • Clique em Adicionar rótulo.
    • Insira uma nova chave e deixe o valor em branco. Para aplicar outros rótulos, clique em Adicionar rótulo e repita o processo.
    • Clique em Atualizar para salvar as alterações.

IU clássica

Opção 1: editar os rótulos manualmente

  1. Na IU da Web, selecione o recurso apropriado, por exemplo, um conjunto de dados, uma tabela ou uma 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:

    • Insira uma nova chave e deixe o valor em branco. Para aplicar mais tags, clique em Adicionar rótulo.
    • Clique em OK.

      Incluir tag

Opção 2: usar uma instrução DDL

Com as instruções de linguagem de definição de dados (DDL, na sigla em inglês), é possível criar e modificar tabelas e visualizações usando a sintaxe de consulta do SQL padrão.

Saiba mais sobre Como usar as instruções de Linguagem de definição de dados.

  1. Clique em Escrever consulta.

  2. Digite a instrução DDL na área de texto Nova consulta.

     #standardSQL
     ALTER TABLE mydataset.mytable
     SET OPTIONS (
       labels=[("tag1", ""), ("tag2", "")]
     )
     

Linha de comando

Para adicionar uma tag a um recurso atual, 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.

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

API

Chame o método datasets.patch ou tables.patch e adicione rótulos com o valor definido para a string vazia ("") no recurso do conjunto de dados ou no recurso da tabela. Para transformar os rótulos atuais 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 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

É possível visualizar os rótulos usando a IU da Web do BigQuery, o comando bq show da ferramenta de linha de comando ou os métodos da API datasets.get ou tables.get. Como as visualizações são tratadas como recursos de tabela, use o método tables.get para acessar as informações de rótulos de 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 de READER no nível do conjunto de dados ou um papel do IAM para envolvidos no projeto que inclua permissões bigquery.datasets.get. Todos os papéis do IAM predefinidos para envolvidos no 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 para conjuntos 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 do IAM predefinidos para envolvidos no 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 para conjuntos de dados, consulte Papéis primários para conjuntos de dados.

Permissões de job

Para ver os dados e metadados do job, você precisa ter as permissões bigquery.jobs.get. O papel do IAM predefinido em nível do projeto inclui permissões bigquery.jobs.get:

Se você concede a uma conta o papel bigquery.admin, o usuário poderá visualizar todos os dados do job no projeto, independentemente de quem o enviou.

As permissões bigquery.jobs.get para jobs autocriados são concedidas aos seguintes papéis: Esses usuários só podem visualizar os dados dos jobs que eles enviam:

Para saber mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso.

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

Para visualizar os rótulos de um recurso, faça o seguinte:

Console

  1. Na IU da Web do BigQuery, selecione o recurso apropriado (um conjunto de dados, uma tabela ou uma 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. As informações do rótulo são exibidas na tabela de informações do recurso.

    Detalhes da tabela

IU clássica

  1. Na IU da Web do BigQuery, selecione o recurso apropriado (um conjunto de dados, uma tabela ou uma 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. 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:

Insira 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 tables.get. A resposta inclui todos os rótulos associados a esse recurso.

Como alternativa, também é possível usar datasets.list para visualizar os rótulos de vários conjuntos de dados ou tables.list para ver os rótulos de várias tabelas e visualizações.

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

Go

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

Depois que o job de consulta é enviado, os rótulos dele não aparecem na IU da Web do BigQuery. Para vê-los, insira o comando bq show -j [JOB_ID].

Console

Não é possível ver os rótulos de job usando a IU da Web do BigQuery no console.

IU clássica

Não é possível ver os rótulos de job usando a IU clássica da Web do BigQuery.

CLI

Para ver os rótulos de um job de consulta usando a ferramenta de linha de comando bq, insira o comando bq show -j com o código do job de consulta. A sinalização --format pode ser usada para controlar a saída. Por exemplo, se o código do job de consulta for bqjob_r1234d57f78901_000023746d4q12_1, insira o seguinte comando:

bq show -j --format=pretty bqjob_r1234d57f78901_000023746d4q12_1

O esquema será semelhante a este:

+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
| Job Type |  State  |   Start Time    | Duration |    User Email     | Bytes Processed | Bytes Billed |        Labels        |
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
| query    | SUCCESS | 03 Dec 15:00:41 | 0:00:00  | email@example.com | 255             | 10485760     | department:shipping  |
|          |         |                 |          |                   |                 |              | costcenter:logistics |
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+

API

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

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

Filtre 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

Observe o seguinte ao gerar uma lista filtrada de conjuntos de dados:

Console

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

IU clássica

Atualmente, não é possível filtrar conjuntos de dados usando a IU da Web clássica 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 da API datasets.list e forneça a especificação de filtros usando a propriedade filter.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery 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 em 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()

# 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.")

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.