Como receber informações sobre conjuntos de dados

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

Para receber informações do conjunto de dados:

• Use o Console do Cloud ou a IU da Web clássica do BigQuery
• Como usar o comando bq show na ferramenta de linha de comando bq
• chame o método da API datasets.get;
• consulte as visualizações INFORMATION_SCHEMA (Beta);
• use as bibliotecas de cliente.

Permissões necessárias

É preciso ter, pelo menos, permissões bigquery.datasets.get para receber informações ou metadados sobre um conjunto de dados. 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 os papéis e as 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

Clique no nome do conjunto de dados no painel Recursos. Abaixo do Editor de consultas, você verá a descrição e os detalhes do conjunto de dados. As tabelas de um conjunto de dados ficam abaixo dele no painel Recursos.

Por padrão, os conjuntos de dados anônimos ficam ocultos na IU da Web do BigQuery. Para mostrar informações sobre conjuntos de dados anônimos, use a ferramenta de linha de comando bq ou a API.

IU clássica

Clique no nome do conjunto de dados. A página Detalhes do conjunto de dados exibe a descrição, os detalhes e as tabelas do conjunto de dados.

Por padrão, os conjuntos de dados anônimos ficam ocultos na IU da Web do BigQuery. Para mostrar informações sobre conjuntos de dados anônimos, use a API ou a ferramenta de linha de comando bq.

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

Em que:

• 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 Go (em inglês).

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 Java (em inglês).

Ver no GitHub (em inglês) 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 (em inglês).

Ver no GitHub (em inglês) 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 Python (em inglês).

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 (Beta)

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

1. Abra a IU da Web do BigQuery no Console do Cloud.

   Acessar o Console do Cloud

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

3. Clique em Run.

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 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_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 de 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 STRUCTs 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_SCHEMATA.SCHEMATA_OPTIONS.

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

Para executar a consulta, faça o seguinte:

Console

1. Abra a IU da Web do BigQuery no Console do Cloud.

   Acessar o Console do Cloud

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

3. Clique em Run.

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

Observação:0.08333333333333333 é a representação do ponto flutuante de duas horas.

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

1. Abra a IU da Web do BigQuery no Console do Cloud.

   Acessar o Console do Cloud

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

3. Clique em Run.

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
   *
 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")] |
  +----------------+---------------+-------------+---------------------------------+------------------------+
  

Observação: os conjuntos de dados sem rótulos não são incluídos nos resultados da consulta.

A seguir

• Para mais informações sobre como criar conjuntos de dados, consulte Como criar conjuntos de dados.
• Para mais informações sobre como atribuir controles de acesso a conjuntos de dados, consulte Como controlar o acesso a conjuntos de dados.
• Para mais informações sobre como listar conjuntos de dados em um projeto, consulte Como listar conjuntos de dados.
• Para mais informações sobre como alterar propriedades do conjunto de dados, consulte Como atualizar conjuntos de dados.
• Para mais informações sobre como criar e gerenciar rótulos, consulte Como criar e gerenciar rótulos.
• Acesse Introdução ao BigQuery INFORMATION_SCHEMA para uma visão geral de INFORMATION_SCHEMA.