Como receber informações sobre conjuntos de dados

Neste documento, descrevemos como receber informações ou metadados sobre conjuntos de dados no BigQuery.

É possível conseguir informações do conjunto de dados das seguintes maneiras:

usando o Console do Cloud;
use o comando bq show na ferramenta de linha de comando bq.
Chamada do método de API datasets.get
consulte as visualizações INFORMATION_SCHEMA (Beta);
use bibliotecas de cliente.

Permissões necessárias

Para receber informações ou metadados sobre um conjunto de dados, é preciso ter, pelo menos, 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

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

Como receber informações do conjunto de dados

Para receber informações sobre conjuntos de dados em um projeto, faça o seguinte:

Console

No painel Explorer, expanda o projeto e selecione um conjunto de dados. A descrição e os detalhes são exibidos no painel de detalhes. As tabelas de um conjunto de dados são listadas com o nome do conjunto de dados no painel Explorador.

Por padrão, os conjuntos de dados anônimos ficam ocultos no Console do Cloud. Para mostrar informações sobre conjuntos de dados anônimos, use a ferramenta de linha de comando bq ou a API.

bq

Emita o comando bq show. A sinalização --format pode ser usada para controlar a saída. Se estiver recebendo informações sobre um conjunto de dados em um projeto diferente do seu projeto padrão, adicione o ID do projeto ao nome do conjunto de dados no seguinte formato: project_id:dataset.

Para mostrar informações sobre um conjunto de dados anônimo, use o comando bq ls --all para listar todos os conjuntos de dados. Depois, use o nome do conjunto de dados anônimo no comando bq show.

bq show --format=prettyjson project_id:dataset

Substitua:

project_id é o nome do projeto
dataset é o nome do conjunto de dados.

Exemplos:

Digite o comando abaixo para exibir informações sobre mydataset no projeto padrão.

bq show --format=prettyjson mydataset

Digite o comando abaixo para exibir informações sobre mydataset em myotherproject.

bq show --format=prettyjson myotherproject:mydataset

Digite o comando abaixo para exibir informações sobre um conjunto de dados anônimo, _1234abcd56efgh78ijkl1234, no projeto padrão.

bq show --format=prettyjson _1234abcd56efgh78ijkl1234

API

Chame o método da API datasets.get e forneça os parâmetros relevantes.

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 em Go.

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// printDatasetInfo demonstrates fetching dataset metadata and printing some of it to an io.Writer.
func printDatasetInfo(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 ID: %s\n", datasetID)
	fmt.Fprintf(w, "Description: %s\n", meta.Description)
	fmt.Fprintln(w, "Labels:")
	for k, v := range meta.Labels {
		fmt.Fprintf(w, "\t%s: %s", k, v)
	}
	fmt.Fprintln(w, "Tables:")
	it := client.Dataset(datasetID).Tables(ctx)

	cnt := 0
	for {
		t, err := it.Next()
		if err == iterator.Done {
			break
		}
		cnt++
		fmt.Fprintf(w, "\t%s\n", t.TableID)
	}
	if cnt == 0 {
		fmt.Fprintln(w, "\tThis dataset does not contain any tables.")
	}
	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 em Java.

Ver no GitHub Feedback

import com.google.api.gax.paging.Page;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQuery.TableListOption;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetId;
import com.google.cloud.bigquery.Table;

public class GetDatasetInfo {

  public static void runGetDatasetInfo() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    getDatasetInfo(projectId, datasetName);
  }

  public static void getDatasetInfo(String projectId, 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();
      DatasetId datasetId = DatasetId.of(projectId, datasetName);
      Dataset dataset = bigquery.getDataset(datasetId);

      // View dataset properties
      String description = dataset.getDescription();
      System.out.println(description);

      // View tables in the dataset
      // For more information on listing tables see:
      // https://javadoc.io/static/com.google.cloud/google-cloud-bigquery/0.22.0-beta/com/google/cloud/bigquery/BigQuery.html
      Page<Table> tables = bigquery.listTables(datasetName, TableListOption.pageSize(100));

      tables.iterateAll().forEach(table -> System.out.print(table.getTableId().getTable() + "\n"));

      System.out.println("Dataset info retrieved successfully.");
    } catch (BigQueryException e) {
      System.out.println("Dataset info not retrieved. \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.

Ver no GitHub Feedback

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

async function getDataset() {
  // Retrieves dataset named "my_dataset".

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

  // Retrieve dataset reference
  const [dataset] = await bigquery.dataset(datasetId).get();

  console.log('Dataset:');
  console.log(dataset.metadata.datasetReference);
}
getDataset();

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

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
friendly_name = dataset.friendly_name
print(
    "Got dataset '{}' with friendly_name '{}'.".format(
        full_dataset_id, friendly_name
    )
)

# View dataset properties.
print("Description: {}".format(dataset.description))
print("Labels:")
labels = dataset.labels
if labels:
    for label, value in labels.items():
        print("\t{}: {}".format(label, value))
else:
    print("\tDataset has no labels defined.")

# View tables in dataset.
print("Tables:")
tables = list(client.list_tables(dataset))  # Make an API request(s).
if tables:
    for table in tables:
        print("\t{}".format(table.table_id))
else:
    print("\tThis dataset does not contain any tables.")

`INFORMATION_SCHEMA`

INFORMATION_SCHEMA é uma série de visualizações que fornecem acesso a metadados sobre conjuntos de dados, rotinas, tabelas, visualizações, jobs, reservas e dados de streaming.

Visualização `SCHEMATA`

Quando você consulta a visualização INFORMATION_SCHEMA.SCHEMATA, os resultados dessa consulta contêm uma linha para cada conjunto de dados no projeto ao qual o usuário atual tem acesso.

A visualização INFORMATION_SCHEMA.SCHEMATA tem o seguinte esquema:

Nome da coluna	Tipo de dados	Valor
`CATALOG_NAME`	`STRING`	Nome do projeto que contém o conjunto de dados
`SCHEMA_NAME`	`STRING`	O nome do conjunto de dados, também chamado de `datasetId`
`SCHEMA_OWNER`	`STRING`	O valor sempre é `NULL`.
`CREATION_TIME`	`TIMESTAMP`	O horário de criação do conjunto de dados.
`LAST_MODIFIED_TIME`	`TIMESTAMP`	O horário da última modificação do conjunto de dados.
`LOCATION`	`STRING`	A localização geográfica do conjunto de dados.

Exemplos

O exemplo a seguir recupera todas as colunas da visualização INFORMATION_SCHEMA.SCHEMATA, exceto a schema_owner, reservada para uso futuro. Os metadados retornados são de todos os conjuntos de dados no projeto padrão myproject.

Para executar a consulta em um projeto diferente do seu projeto padrão, adicione o ID do projeto ao conjunto de dados no seguinte formato: `project_id`.INFORMATION_SCHEMA.view. Veja um exemplo: `myproject`.INFORMATION_SCHEMA.SCHEMATA.

Para executar a consulta, faça o seguinte:

Console

Abra a página do BigQuery no Console do Cloud.

Acesse a página do BigQuery
Insira a consulta SQL padrão a seguir na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. O SQL padrão é a sintaxe padrão do Console do Cloud.
```
SELECT
 * EXCEPT(schema_owner)
FROM
 INFORMATION_SCHEMA.SCHEMATA
```
Observação: os nomes da visualização INFORMATION_SCHEMA diferenciam maiúsculas e minúsculas.
Clique em Executar.

bq

Use o comando query e especifique a sintaxe SQL padrão usando a sinalização --nouse_legacy_sql ou --use_legacy_sql=false. A sintaxe SQL padrão é obrigatória para consultas INFORMATION_SCHEMA.

Para executar a consulta, insira:

bq query --nouse_legacy_sql \
'SELECT
   * EXCEPT(schema_owner)
 FROM
   INFORMATION_SCHEMA.SCHEMATA'

Os resultados terão o seguinte formato:

  +----------------+---------------+---------------------+---------------------+-----------------+
  |  catalog_name  |  schema_name  |    creation_time    | last_modified_time  |    location     |
  +----------------+---------------+---------------------+---------------------+-----------------+
  | myproject      | mydataset1    | 2018-11-07 19:50:24 | 2018-11-07 19:50:24 | US              |
  | myproject      | mydataset2    | 2018-07-16 04:24:22 | 2018-07-16 04:24:22 | US              |
  | myproject      | mydataset3    | 2018-02-07 21:08:45 | 2018-05-01 23:32:53 | asia-northeast1 |
  +----------------+---------------+---------------------+---------------------+-----------------+

Visualização `SCHEMATA_OPTIONS`

Quando você consulta a visualização INFORMATION_SCHEMA.SCHEMATA_OPTIONS, os resultados da consulta contêm uma linha para cada opção de cada conjunto de dados em um projeto.

A visualização INFORMATION_SCHEMA.SCHEMATA_OPTIONS tem o seguinte esquema:

Nome da coluna	Tipo de dados	Valor
`CATALOG_NAME`	`STRING`	Nome do projeto que contém o conjunto de dados
`SCHEMA_NAME`	`STRING`	O nome do conjunto de dados, também chamado de `datasetId`
`OPTION_NAME`	`STRING`	Um dos valores de nome na tabela opções.
`OPTION_TYPE`	`STRING`	Um dos valores de tipo de dados na tabela de opções.
`OPTION_VALUE`	`STRING`	Uma das opções de valor na tabela de opções.

Tabela de opções

`OPTION_NAME`	`OPTION_TYPE`	`OPTION_VALUE`
`default_table_expiration_days`	`FLOAT64`	A vida útil padrão em dias de todas as tabelas no conjunto de dados.
`friendly_name`	`STRING`	O nome descritivo do conjunto de dados.
`description`	`STRING`	Uma descrição do conjunto de dados.
`labels`	`ARRAY<STRUCT<STRING, STRING>>`	Uma matriz de `STRUCT`s que representa os rótulos no conjunto de dados.

Exemplos

Exemplo 1:

O exemplo a seguir recupera os tempos de expiração da tabela padrão para todos os conjuntos de dados do seu projeto padrão (myproject) ao consultar a visualização INFORMATION_SCHEMA.SCHEMATA_OPTIONS.

Para executar a consulta, faça o seguinte:

Console

Abra a página do BigQuery no Console do Cloud.

Acesse a página do BigQuery
Insira a consulta SQL padrão a seguir na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. O SQL padrão é a sintaxe padrão do Console do Cloud.
```
SELECT
 *
FROM
 INFORMATION_SCHEMA.SCHEMATA_OPTIONS
WHERE
 option_name="default_table_expiration_days"
```
Observação: os nomes da visualização INFORMATION_SCHEMA diferenciam maiúsculas e minúsculas.
Clique em Executar.

bq

Para executar a consulta, insira:

bq query --nouse_legacy_sql \
'SELECT
   *
 FROM
   INFORMATION_SCHEMA.SCHEMATA_OPTIONS
 WHERE
   option_name="default_table_expiration_days"'

Os resultados terão o seguinte formato:

  +----------------+---------------+-------------------------------+-------------+---------------------+
  |  catalog_name  |  schema_name  |          option_name          | option_type |    option_value     |
  +----------------+---------------+-------------------------------+-------------+---------------------+
  | myproject      | mydataset3    | default_table_expiration_days | FLOAT64     | 0.08333333333333333 |
  | myproject      | mydataset2    | default_table_expiration_days | FLOAT64     | 90.0                |
  | myproject      | mydataset1    | default_table_expiration_days | FLOAT64     | 30.0                |
  +----------------+---------------+-------------------------------+-------------+---------------------+

Exemplo 2:

O exemplo a seguir recupera os rótulos de todos os conjuntos de dados do seu projeto padrão (myproject) ao consultar a visualização INFORMATION_SCHEMA.SCHEMATA_OPTIONS.

Para executar a consulta em um projeto diferente do projeto padrão, adicione o ID do projeto ao conjunto de dados no seguinte formato: `project_id`.INFORMATION_SCHEMA.view. Veja um exemplo: `myproject`.INFORMATION_SCHEMA.SCHEMATA_OPTIONS.

Para executar a consulta, faça o seguinte:

Console

Abra a página do BigQuery no Console do Cloud.

Acesse a página do BigQuery
Insira a consulta SQL padrão a seguir na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. O SQL padrão é a sintaxe padrão do Console do Cloud.
```
SELECT
 *
FROM
 INFORMATION_SCHEMA.SCHEMATA_OPTIONS
WHERE
 option_name="labels"
```
Observação: os nomes da visualização INFORMATION_SCHEMA diferenciam maiúsculas e minúsculas.
Clique em Executar.

bq

Para executar a consulta, insira:

bq query --nouse_legacy_sql \
'SELECT
   *
 FROM
   INFORMATION_SCHEMA.SCHEMATA_OPTIONS
 WHERE
   option_name="labels"'

Os resultados terão a aparência abaixo:

  +----------------+---------------+-------------+---------------------------------+------------------------+
  |  catalog_name  |  schema_name  | option_name |          option_type            |      option_value      |
  +----------------+---------------+-------------+---------------------------------+------------------------+
  | myproject      | mydataset1    | labels      | ARRAY<STRUCT<STRING, STRING>>   | [STRUCT("org", "dev")] |
  | myproject      | mydataset2    | labels      | ARRAY<STRUCT<STRING, STRING>>   | [STRUCT("org", "dev")] |
  +----------------+---------------+-------------+---------------------------------+------------------------+

Próximas etapas

Para mais informações sobre a criação de conjuntos de dados, consulte Como criar conjuntos de dados.
Para mais informações sobre a atribuição de controles de acesso a conjuntos de dados, consulte Como controlar o acesso a conjuntos de dados.
Para mais informações sobre a listagem de conjuntos de dados em um projeto, consulte Como listar conjuntos de dados.
Para mais informações sobre a alteração de propriedades de conjuntos de dados, consulte Como atualizar conjuntos de dados.
Para mais informações sobre como criar e gerenciar rótulos, consulte esta página.
Acesse Introdução ao BigQuery INFORMATION_SCHEMA para uma visão geral de INFORMATION_SCHEMA.

Como receber informações sobre conjuntos de dados

Permissões necessárias

Como receber informações do conjunto de dados

Console

bq

API

Go

Java

Node.js

Python

INFORMATION_SCHEMA

Visualização SCHEMATA

Exemplos

Console

bq

Visualização SCHEMATA_OPTIONS

Tabela de opções

Exemplos

Exemplo 1:

Console

bq

Exemplo 2:

Console

bq

Próximas etapas

`INFORMATION_SCHEMA`

Visualização `SCHEMATA`

Visualização `SCHEMATA_OPTIONS`