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.

Limitações

Os rótulos BigQuery têm estas limitações:

  • Cada recurso pode ter até 64 rótulos.
  • As chaves e os valores de rótulo não podem ter mais de 63 caracteres.
  • As chaves e os valores podem conter somente letras minúsculas, números, sublinhados, hifens e caracteres internacionais.
  • As chaves e os valores de rótulos não podem ultrapassar 128 bytes de tamanho.
  • As chaves de rótulo precisam começar com uma letra.
  • Os rótulos precisam ter uma chave, mas podem ter um valor vazio. Rótulos sem valor podem ser usados como tags.
  • Uma chave de rótulo pode ser usada apenas uma vez por recurso. Por exemplo, você pode ter apenas um rótulo de conjunto de dados ou rótulo de tabela com a chave-valor organization.
  • Quando você adiciona rótulos a tabelas ou visualizações, as chaves de rótulo precisam ser exclusivas dentro do conjunto de dados. Não é possível usar a mesma chave para duas tabelas ou visualizações diferentes no mesmo conjunto de dados.
  • Quando você adiciona rótulos a um conjunto de dados, as chaves de rótulo não precisam ser exclusivas no projeto, mas é necessário que sejam exclusivas por conjunto de dados. Por exemplo, você pode ter dois conjuntos de dados no mesmo projeto com a chave de rótulo department, mas a chave department pode ser usada apenas uma vez para cada conjunto de dados.

Como criar e atualizar rótulos de conjunto de dados

Um rótulo pode ser adicionado a um conjunto de dados quando ele é criado usando o comando bq mk da ferramenta de linha de comando ou chamando o método da API datasets.insert. 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 usando a IU da Web do BigQuery, o comando bq update da ferramenta de linha de comando ou chamando o método da API datasets.patch.

Permissões necessárias

Para adicionar ou atualizar um rótulo de conjunto de dados após a criação desse conjunto, você precisa ter o acesso OWNER no nível do conjunto de dados ou um papel do IAM no nível de projeto que inclua permissões bigquery.datasets.update. Os seguintes papéis do IAM predefinidos 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 primitivos 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, 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 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 para um conjunto de dados existente, chame o método datasets.patch e adicione ou atualize a propriedade labels para o recurso do conjunto de dados.

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

Java

Este exemplo usa a Biblioteca de cliente HTTP do Google para Java para enviar uma solicitação para a BigQuery API.
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

Este exemplo usa a Biblioteca do Google Auth para Python para enviar uma solicitação para a BigQuery API com uma AuthorizedSession, que é compatível com uma sessão Solicitações.
def label_dataset(dataset_id, label_key, label_value, project_id=None):
    """Add or modify a label on a dataset."""
    # Authenticate requests using Google Application Default credentials.
    credentials, default_project_id = google.auth.default(
            scopes=['https://www.googleapis.com/auth/bigquery'])
    session = google.auth.transport.requests.AuthorizedSession(credentials)

    if project_id is None:
        project_id = default_project_id

    # Send a PATCH request to add or modify a label.
    url_format = (
        'https://www.googleapis.com/bigquery/v2/'
        'projects/{project_id}/datasets/{dataset_id}')
    response = session.patch(
        url_format.format(project_id=project_id, dataset_id=dataset_id),
        params={'fields': 'labels'},
        json={
            'labels': {
                label_key: label_value,
            }
        })

    # Check the response for errors.
    response.raise_for_status()

    # Print the new label value from the response.
    labels = response.json()['labels']
    print(
        'Updated label "{}" with value "{}"'.format(
            label_key,
            labels[label_key]))

Como criar e atualizar os rótulos de visualização e tabela

Um rótulo pode ser adicionado a uma tabela ou visualização quando ele é criado usando o comando bq mk da ferramenta de linha de comando ou chamando o método da API tables.insert. Para mais informações sobre como adicionar um rótulo quando você cria uma tabela ou visualização, 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 usando a IU da Web do BigQuery, o comando bq update da ferramenta de linha de comando ou chamando 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 as tabelas.

Permissões necessárias

Para criar ou atualizar um rótulo de visualização ou tabela, é preciso ter acesso OWNER no nível do conjunto de dados ou ter um papel do IAM no nível do projeto que inclui permissões bigquery.tables.update. Os seguintes papéis do IAM predefinidos 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 primitivos 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, 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 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 para uma tabela ou visualização existente, chame o método tables.patch e adicione ou atualize 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 as tabelas.

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

Java

Este exemplo usa a Biblioteca de cliente HTTP do Google para Java para enviar uma solicitação para a BigQuery API.
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

Este exemplo usa a Biblioteca do Google Auth para Python para enviar uma solicitação para a BigQuery API com uma AuthorizedSession, que é compatível com uma sessão Solicitações.
def label_dataset(dataset_id, label_key, label_value, project_id=None):
    """Add or modify a label on a dataset."""
    # Authenticate requests using Google Application Default credentials.
    credentials, default_project_id = google.auth.default(
            scopes=['https://www.googleapis.com/auth/bigquery'])
    session = google.auth.transport.requests.AuthorizedSession(credentials)

    if project_id is None:
        project_id = default_project_id

    # Send a PATCH request to add or modify a label.
    url_format = (
        'https://www.googleapis.com/bigquery/v2/'
        'projects/{project_id}/datasets/{dataset_id}')
    response = session.patch(
        url_format.format(project_id=project_id, dataset_id=dataset_id),
        params={'fields': 'labels'},
        json={
            'labels': {
                label_key: label_value,
            }
        })

    # Check the response for errors.
    response.raise_for_status()

    # Print the new label value from the response.
    labels = response.json()['labels']
    print(
        'Updated label "{}" with value "{}"'.format(
            label_key,
            labels[label_key]))

Como excluir rótulos

Um rótulo pode ser removido de um conjunto de dados, uma tabela ou uma visualização usando a IU da Web do BigQuery, o comando bq update da ferramenta de linha de comando ou chamando o método da API datasets.patch ou tables.patch.

Como excluir um rótulo de conjunto de dados

Para remover um rótulo de 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 da API datasets.patch.

Permissões necessárias

Para excluir um rótulo de conjunto de dados, você precisa ter o acesso OWNER no nível do conjunto de dados ou ter um papel do IAM no nível de projeto que inclua permissões bigquery.datasets.update. Os seguintes papéis do IAM predefinidos 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 primitivos 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, emita 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 para o 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.

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

Para remover um rótulo de visualização ou tabela, use a IU da Web do BigQuery, o comando bq update da ferramenta de linha de comando ou chame 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 as tabelas.

Permissões necessárias

Para excluir um rótulo de visualização ou tabela, você precisa ter acesso OWNER no nível do conjunto de dados ou ter um papel do IAM no nível do projeto que inclua permissões bigquery.tables.update. Os seguintes papéis do IAM predefinidos 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 o 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 primitivos para conjuntos de dados.

Como excluir um rótulo de visualização ou 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, emita 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 existente, chame o método tables.patch e atualize a propriedade labels para o 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, o método tables.patch é recomendado.

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, tabela ou visualização).ve

  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 tables.patch e adicione rótulos com o valor definido à string vazia ("") no recurso do conjunto de dados ou no recurso da tabela. Você pode transformar os rótulos existentes em tags substituindo os valores deles 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, o método tables.patch é recomendado.

Como ver marcadores

É possível ver os rótulos usando a IU da Web do BigQuery, o comando bq show da ferramenta de linha de comando ou chamando 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 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 informações sobre um conjunto de dados, você precisa ter o papel READER no nível do conjunto de dados ou um papel do IAM no nível de projeto que inclua permissões bigquery.datasets.get. Todos os papéis do IAM predefinidos e no nível do projeto incluem permissões bigquery.datasets.get, exceto o 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 primitivos 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 receber informações sobre todas as tabelas contidas nele. Os seguintes papéis do IAM predefinidos no nível do projeto incluem permissões bigquery.tables.get:

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 primitivos 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, tabela ou 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

Digite 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, você também pode usar datasets.list para ver os rótulos de vários conjuntos de dados ou tables.list, para 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 para ver informações do rótulo em visualizações e tabelas.

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 BigQuery API que use a sintaxe a seguir:

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

Em que:

  • field é expresso como labels.[KEY], em que [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

Emita 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 filtro usando a propriedade 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.