Visualizar etiquetas

Esta página explica como ver etiquetas nos seus recursos do BigQuery.

Pode ver etiquetas das seguintes formas:

• Usar a Google Cloud consola
• Consultar INFORMATION_SCHEMA visualizações
• Usar o comando bq show da ferramenta de linhas de comando bq
• Chamar os métodos da API datasets.get ou tables.get
• Usar as bibliotecas de cliente

Uma vez que as vistas são tratadas como recursos de tabelas, usa o método tables.get para obter informações de etiquetas para vistas e tabelas.

Antes de começar

Conceda funções de gestão de identidade e acesso (IAM) que dão aos utilizadores as autorizações necessárias para realizar cada tarefa neste documento.

Autorizações necessárias

As autorizações necessárias para ver etiquetas dependem dos tipos de recursos aos quais pode aceder. Para realizar as tarefas neste documento, precisa das seguintes autorizações.

Autorizações para ver detalhes do conjunto de dados

Para ver os detalhes do conjunto de dados, precisa da autorização de gestão de identidade e de acesso (IAM) bigquery.datasets.get.

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para ver os detalhes do conjunto de dados:

• roles/bigquery.user
• roles/bigquery.metadataViewer
• roles/bigquery.dataViewer
• roles/bigquery.dataOwner
• roles/bigquery.dataEditor
• roles/bigquery.admin

Além disso, se tiver a autorização bigquery.datasets.create, pode ver os detalhes dos conjuntos de dados que cria.

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Autorizações para ver a tabela ou ver detalhes

Para ver a tabela ou os detalhes da visualização, precisa da bigquery.tables.getautorização de IAM.

Todas as funções de IAM predefinidas incluem as autorizações de que precisa para ver a tabela ou os detalhes, exceto roles/bigquery.user e roles/bigquery.jobUser.

Além disso, se tiver a autorização bigquery.datasets.create, pode ver detalhes das tabelas e das vistas nos conjuntos de dados que criar.

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Autorizações para ver detalhes do trabalho

Para ver os detalhes da tarefa, precisa da autorização bigquery.jobs.get do IAM.

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para ver os detalhes das tarefas:

• roles/bigquery.admin (permite-lhe ver os detalhes de todas as tarefas no projeto)
• roles/bigquery.user (permite-lhe ver detalhes dos seus trabalhos)
• roles/bigquery.jobUser (permite-lhe ver detalhes dos seus trabalhos)

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Ver etiquetas de conjuntos de dados, tabelas e vistas

Para ver as etiquetas de um recurso, selecione uma das seguintes opções:

Consola

1. Para conjuntos de dados, a página de detalhes do conjunto de dados é aberta automaticamente. Para tabelas e vistas, clique em Detalhes para abrir a página de detalhes. As informações das etiquetas aparecem na tabela de informações do recurso.

   

SQL

Consulte a vista INFORMATION_SCHEMA.SCHEMATA_OPTIONS para ver as etiquetas num conjunto de dados ou a vista INFORMATION_SCHEMA.TABLE_OPTIONS para ver as etiquetas numa tabela. Por exemplo, a seguinte consulta SQL devolve as etiquetas no conjunto de dados denominado mydataset:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte declaração:

   SELECT
     *
   FROM
     INFORMATION_SCHEMA.SCHEMATA_OPTIONS
   WHERE
     schema_name = 'mydataset'
     AND option_name = 'labels';

3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

bq

Use o comando bq show com o ID do recurso. A flag --format pode ser usada para controlar a saída. Se o recurso estiver num projeto diferente do seu projeto predefinido, adicione o ID do projeto no seguinte formato: [PROJECT_ID]:[DATASET]. Para facilitar a leitura, o resultado é controlado através da definição da flag --format como pretty.

bq show --format=pretty [RESOURCE_ID]

Onde [RESOURCE_ID] é um conjunto de dados, uma tabela, uma vista ou um ID da tarefa válido.

Exemplos:

Introduza o seguinte comando para apresentar as etiquetas de mydataset no seu projeto predefinido.

bq show --format=pretty mydataset

O resultado tem o seguinte aspeto:

+-----------------+--------------------------------------------------------+---------------------+
|  Last modified  |                          ACLs                          |       Labels        |
+-----------------+--------------------------------------------------------+---------------------+
| 11 Jul 19:34:34 | Owners:                                                | department:shipping |
|                 |   projectOwners,                                       |                     |
|                 | Writers:                                               |                     |
|                 |   projectWriters                                       |                     |
|                 | Readers:                                               |                     |
|                 |   projectReaders                                       |                     |
+-----------------+--------------------------------------------------------+---------------------+

Introduza o seguinte comando para apresentar etiquetas para mydataset.mytable. O recurso mydataset está em myotherproject e não no seu projeto predefinido.

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

A saída tem o seguinte aspeto para uma tabela agrupada:

+-----------------+------------------------------+------------+-------------+-----------------+------------------------------------------------+------------------+---------+
|  Last modified  |            Schema            | Total Rows | Total Bytes |   Expiration    |               Time Partitioning                | Clustered Fields | Labels  |
+-----------------+------------------------------+------------+-------------+-----------------+------------------------------------------------+------------------+---------+
| 25 Jun 19:28:14 | |- timestamp: timestamp      | 0          | 0           | 25 Jul 19:28:14 | DAY (field: timestamp, expirationMs: 86400000) | customer_id      | org:dev |
|                 | |- customer_id: string       |            |             |                 |                                                |                  |         |
|                 | |- transaction_amount: float |            |             |                 |                                                |                  |         |
+-----------------+------------------------------+------------+-------------+-----------------+------------------------------------------------+------------------+---------+

API

Chame o método datasets.get ou o método tables.get. A resposta inclui todas as etiquetas associadas a esse recurso.

Em alternativa, pode usar datasets.list para ver as etiquetas de vários conjuntos de dados ou tables.list para ver as etiquetas de várias tabelas e vistas.

Uma vez que as vistas são tratadas como recursos de tabelas, usa os métodos tables.get e tables.list para ver informações de etiquetas para vistas e tabelas.

Go

Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// printDatasetLabels retrieves label metadata from a dataset and prints it to an io.Writer.
func printDatasetLabels(w io.Writer, projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	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)
	}
	return nil
}

Java

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

// Sample to get dataset labels
public class GetDatasetLabels {

  public static void runGetDatasetLabels() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    getDatasetLabels(datasetName);
  }

  public static void getDatasetLabels(String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      Dataset dataset = bigquery.getDataset(datasetName);
      dataset
          .getLabels()
          .forEach((key, value) -> System.out.println("Retrieved labels successfully"));
    } catch (BigQueryException e) {
      System.out.println("Label was not found. \n" + e.toString());
    }
  }
}

Node.js

Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function getDatasetLabels() {
  // Gets labels on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";

  // Retrieve current dataset metadata.
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();
  const labels = metadata.labels;

  console.log(`${datasetId} Labels:`);
  for (const [key, value] of Object.entries(labels)) {
    console.log(`${key}: ${value}`);
  }
}
getDatasetLabels();

Python

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = "your-project.your_dataset"

dataset = client.get_dataset(dataset_id)  # Make an 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.")

Ver etiquetas de tabelas

Go

Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// tableLabels demonstrates fetching metadata from a table and printing the Label metadata to an io.Writer.
func tableLabels(w io.Writer, projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	meta, err := client.Dataset(datasetID).Table(tableID).Metadata(ctx)
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "Table %s labels:\n", datasetID)
	if len(meta.Labels) == 0 {
		fmt.Fprintln(w, "Table has no labels defined.")
		return nil
	}
	for k, v := range meta.Labels {
		fmt.Fprintf(w, "\t%s:%s\n", k, v)
	}
	return nil
}

Java

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;

// Sample to get table labels
public class GetTableLabels {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    getTableLabels(datasetName, tableName);
  }

  public static void getTableLabels(String datasetName, String tableName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // This example table starts with existing label { color: 'green' }
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      table
          .getLabels()
          .forEach((key, value) -> System.out.println("Retrieved labels successfully"));
    } catch (BigQueryException e) {
      System.out.println("Label was not deleted. \n" + e.toString());
    }
  }
}

Node.js

Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function getTableLabels() {
  // Gets labels on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  // Retrieve current dataset metadata.
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();
  const labels = metadata.labels;

  console.log(`${tableId} Labels:`);
  for (const [key, value] of Object.entries(labels)) {
    console.log(`${key}: ${value}`);
  }
}
getTableLabels();

Python

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"

table = client.get_table(table_id)  # API Request

# View table labels
print(f"Table ID: {table_id}.")
if table.labels:
    for label, value in table.labels.items():
        print(f"\t{label}: {value}")
else:
    print("\tTable has no labels defined.")

Veja etiquetas de tarefas

Para ver as etiquetas num trabalho, selecione uma das seguintes opções:

SQL

Consulte as INFORMATION_SCHEMA.JOB_BY_* visualizações para ver as etiquetas numa tarefa. Por exemplo, a seguinte consulta SQL devolve o texto da consulta e as etiquetas nas tarefas enviadas pelo utilizador atual no projeto atual:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte declaração:

   SELECT
     query,
     labels
   FROM
     INFORMATION_SCHEMA.JOBS_BY_USER;

3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

bq

Para ver as etiquetas de uma tarefa de consulta através da ferramenta de linhas de comando bq, introduza o comando bq show -j com o ID da tarefa de consulta. A flag --format pode ser usada para controlar a saída. Por exemplo, se a sua tarefa de consulta tiver o ID da tarefa bqjob_r1234d57f78901_000023746d4q12_1, introduza o seguinte comando:

bq show -j --format=pretty bqjob_r1234d57f78901_000023746d4q12_1

O resultado deve ter o seguinte aspeto:

+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
| Job Type |  State  |   Start Time    | Duration |    User Email     | Bytes Processed | Bytes Billed |        Labels        |
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
| query    | SUCCESS | 03 Dec 15:00:41 | 0:00:00  | [e-mail] | 255             | 10485760     | department:shipping  |
|          |         |                 |          |                   |                 |              | costcenter:logistics |
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+

API

Chame o método jobs.get. A resposta inclui todas as etiquetas associadas a esse recurso.

Veja as etiquetas de reservas

Para ver as etiquetas numa reserva, selecione uma das seguintes opções:

SQL

Consulte as INFORMATION_SCHEMA.RESERVATIONS vistas para ver as etiquetas numa reserva. Por exemplo, a seguinte consulta SQL devolve o nome da reserva e as etiquetas:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte declaração:

   SELECT
     reservation_name,
     labels
   FROM
     INFORMATION_SCHEMA.RESERVATIONS
   WHERE reservation_name = RESERVATION_NAME;

   Substitua o seguinte:

   • RESERVATION_NAME: o nome da reserva.

3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

bq

Use o comando bq show para ver as etiquetas de reserva.

bq show --format=prettyjson --reservation=true --location=LOCATION RESERVATION_NAME

Substitua o seguinte:

• LOCATION: a localização da reserva.
• RESERVATION_NAME: o nome da reserva.

O resultado tem um aspeto semelhante ao seguinte:

{
  "autoscale": {
    "maxSlots": "100"
  },
  "creationTime": "2023-10-26T15:16:28.196940Z",
  "edition": "ENTERPRISE",
  "labels": {
    "department": "shipping"
  },
  "name": "projects/myproject/locations/US/reservations/myreservation",
  "updateTime": "2025-06-05T19:37:28.125914Z"
}

O que se segue?

• Saiba como adicionar etiquetas aos recursos do BigQuery.
• Saiba como atualizar etiquetas em recursos do BigQuery.
• Saiba como filtrar recursos através de etiquetas.
• Saiba como eliminar etiquetas em recursos do BigQuery.
• Leia acerca da utilização de etiquetas na documentação do Resource Manager.