Como ver rótulos

Nesta página, você aprende a visualizar rótulos nos recursos do BigQuery.

Visão geral

Para visualizar rótulos:

  • Como usar o Console do Cloud
  • use o comando bq show da ferramenta de linha de comando bq;
  • chame os métodos de API datasets.get ou tables.get;
  • use as bibliotecas de cliente.

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, você precisa, no mínimo, ter permissões bigquery.datasets.get. Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.datasets.get:

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

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. O acesso bigquery.dataOwner permite que o usuário receba informações sobre um conjunto de dados.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Permissões de visualização e tabela

Para receber informações sobre tabelas ou visualizações, você precisa, no mínimo, ter permissões bigquery.tables.get. Todos os papéis predefinidos do IAM incluem permissões bigquery.tables.get, exceto bigquery.user e bigquery.jobUser.

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. O acesso bigquery.dataOwner permite que o usuário receba informações sobre tabelas e visualizações em um conjunto de dados.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Permissões de job

Para acessar os dados e metadados do job, é necessário ter, no mínimo, as permissões bigquery.jobs.get. O papel predefinido do IAM a seguir inclui permissões bigquery.jobs.get:

  • bigquery.admin

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

Os papéis a seguir recebem permissões bigquery.jobs.get para jobs autocriados. Esses usuários só podem visualizar os dados dos jobs que eles enviam:

  • bigquery.user
  • bigquery.jobUser

Para 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. No Console do Cloud, selecione um conjunto de dados, tabela ou visualização. Não é possível visualizar os rótulos do job no Console do Cloud.

  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

bq

Use o comando bq show com o ID do recurso. A sinalização --format pode ser usada para controlar a saída. Se o recurso estiver em um projeto diferente do padrão, adicione o ID do projeto no seguinte formato: [PROJECT_ID]:[DATASET]. Para facilitar a leitura, a saída é controlada com a configuração da sinalização --format como pretty.

bq show --format=pretty [RESOURCE_ID]

Em que [RESOURCE_ID] é um ID válido de conjunto de dados, tabela, visualização ou job.

Exemplos:

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

bq show --format=pretty mydataset

A saída será assim:

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

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

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

O resultado será semelhante ao exemplo a seguir relacionado a uma tabela em cluster:

+-----------------+------------------------------+------------+-------------+-----------------+------------------------------------------------+------------------+---------+
|  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 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 sobre visualizações e tabelas.

Go

Antes de testar essa amostra, siga as instruções de configuração para 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 (em inglês).

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 testar essa amostra, siga as instruções de configuração para Java 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 Java.

Ver no GitHub (em inglês) Feedback
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 testar essa amostra, siga as instruções de configuração para Node.js 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 Node.js (em inglês).

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

Ver no GitHub (em inglês) Feedback

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

Como ver rótulos de tabela

Go

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

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: %v", 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 testar essa amostra, siga as instruções de configuração para Java 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 do BigQuery para Java.

Ver no GitHub (em inglês) Feedback
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 testar essa amostra, siga as instruções de configuração para Node.js 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 do BigQuery para Node.js.

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

Ver no GitHub (em inglês) Feedback
# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'
# table_id = 'my_table'

project = client.project
dataset_ref = bigquery.DatasetReference(project, dataset_id)
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)  # API Request

# View table labels
print("Table ID: {}".format(table_id))
print("Labels:")
if table.labels:
    for label, value in table.labels.items():
        print("\t{}: {}".format(label, value))
else:
    print("\tTable has no labels defined.")
==== YOURS //steffanyb:py-freeze:130:citc/google3/googledata/devsite/site-cloud/en/bigquery/docs/viewing-labels.md

Antes de testar essa amostra, siga as instruções de configuração para Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Ver no GitHub (em inglês) Feedback

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

Como visualizar rótulos de job

Depois que um job é enviado, os rótulos não aparecem no Console do Cloud. Para ver os rótulos em um job, emita o comando bq show -j [JOB_ID] ou use a API ou as bibliotecas de cliente.

Console

Não é possível ver os rótulos do job usando o Console do Cloud.

bq

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

bq show -j --format=pretty bqjob_r1234d57f78901_000023746d4q12_1

A saída será semelhante a esta:

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

A seguir