Criar e usar tabelas

Neste documento, você aprenderá a criar e usar tabelas no BigQuery. Depois de criar uma tabela, você pode:

  • controlar o acesso aos dados de sua tabela;
  • receber informações sobre suas tabelas;
  • listar as tabelas em um conjunto de dados;
  • receber metadados de tabela.

Para mais informações sobre como gerenciar tabelas, incluindo atualização de propriedades, cópia e exclusão de tabelas, consulte Como gerenciar tabelas.

Limitações da tabela

As tabelas do BigQuery estão sujeitas às seguintes limitações:

  • Os nomes das tabelas precisam ser exclusivos por conjunto de dados.
  • O console e a IU da Web clássica do BigQuery aceitam a cópia de apenas uma tabela por vez.
  • Ao copiar tabelas, o conjunto de dados de destino e a tabela a ser copiada precisam estar no mesmo local. Por exemplo, não é possível copiar uma tabela de um conjunto de dados baseado na UE para um conjunto de dados baseado nos EUA.
  • Para copiar várias tabelas de origem para uma de destino usando a CLI ou a API, todas elas precisam ter esquemas idênticos.
  • É possível excluir apenas uma tabela de cada vez usando o console, a IU da Web clássica do BigQuery, a ferramenta de linha de comando ou a API.
  • Ao exportar dados de tabelas, o único destino aceito é o Cloud Storage.

  • À medida que você se aproxima de 50.000 tabelas ou mais em um conjunto de dados, a enumeração delas fica mais lenta. O desempenho de enumeração é prejudicado se você usa uma chamada de API ou a IU da Web clássica do BigQuery. Atualmente, a IU da Web do BigQuery no Console do GCP permite exibir apenas 50.000 tabelas por conjunto de dados.

    Para melhorar o desempenho da IU da Web clássica do BigQuery, use o parâmetro ?minimal para limitar o número de tabelas exibidas a 30.000 tabelas por projeto. Adicione o parâmetro ao URL da IU da Web clássica do BigQuery no seguinte formato: https://bigquery.cloud.google.com/queries/[PROJECT_NAME]?minimal.

Como criar uma tabela

É possível criar uma tabela no BigQuery:

  • manualmente, ao usar o Console do GCP, a IU da Web clássica do BigQuery ou o comando bq mk da ferramenta da linha de comando;
  • de maneira programática, ao chamar o método de API tables.insert;
  • dos resultados da consulta;
  • definindo uma tabela que faz referência a uma fonte de dados externa;
  • ao carregar dados.

Ao criar uma tabela no BigQuery, o nome dela precisa ser exclusivo para cada conjunto de dados. O nome da tabela pode:

  • conter até 1.024 caracteres;
  • conter letras (maiúsculas e minúsculas), números e sublinhados.

Permissões exigidas

Para criar uma tabela, é preciso ter o acesso de WRITER no nível do conjunto de dados ou um papel do IAM para envolvidos no projeto que inclua permissões bigquery.tables.create. Os seguintes papéis predefinidos do IAM do projeto incluem permissões bigquery.tables.create:

Além disso, como o papel bigquery.user tem permissões bigquery.datasets.create, um usuário atribuído ao papel bigquery.user pode criar tabelas em qualquer conjunto de dados que ele criar. Quando um usuário com o papel bigquery.user cria um conjunto de dados, ele recebe o acesso OWNER ao conjunto. Com o acesso 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 para conjuntos de dados, consulte Papéis primários para conjuntos de dados.

Como criar uma tabela vazia com definição de esquema

Ao criar uma tabela vazia com uma definição de esquema, é possível:

  • inserir o esquema usando o Console do GCP ou a IU da Web clássica do BigQuery;
  • fornecer o esquema in-line usando a ferramenta de linha de comando;
  • enviar um arquivo de esquema JSON usando a ferramenta de linha de comando;
  • fornecer o esquema em um recurso de tabela ao chamar o método tables.insert da API.

Para mais informações sobre como especificar um esquema de tabela, consulte Como especificar um esquema.

Depois que a tabela for criada, será possível carregar dados ou gravar os resultados de consulta para preenchê-la.

Para criar uma tabela vazia com definição de esquema, faça o seguinte:

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar a IU da Web do BigQuery

  2. No painel de navegação, na seção Recursos, expanda seu projeto e selecione um conjunto de dados.

  3. No lado direito da janela, no painel de detalhes, clique em Criar tabela. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.

    Criar tabela

  4. Na página Criar tabela, na seção Origem, selecione Tabela em branco.

  5. Na página Criar tabela, na seção Destino:

    • Em Nome do conjunto de dados, escolha o conjunto apropriado.

      Escolher conjunto de dados

    • No campo Nome da tabela, insira o nome da tabela que você está criando no BigQuery.

    • Verifique se o Tipo de tabela está configurado como Tabela nativa.

  6. Na seção Esquema, insira a definição do esquema.

    • Insira as informações do esquema manualmente:

      • Ative Editar como texto e insira o esquema da tabela como uma matriz JSON.

      • Use Adicionar campo para inserir manualmente o esquema.

  7. Na seção Opções avançadas, não altere os valores.

  8. Selecione itens aplicáveis na seção Opções avançadas e clique em Criar tabela. Para informações sobre as opções disponíveis, consulte Opções do JSON.

  9. Clique em Criar tabela.

IU clássica

  1. Clique no ícone de seta para baixo ícone de seta para baixo ao lado do nome do conjunto de dados e selecione Criar nova tabela.

  2. Na página Criar tabela, localizada na seção Dados de origem, clique em Criar tabela em branco.

  3. Na página Criar tabela, na seção Tabela de destino:

    • Em Nome da tabela, escolha o conjunto de dados apropriado e, no campo adequado, insira o nome da tabela que você está criando.
    • Verifique se o Tipo de tabela está definido como Tabela nativa.

  4. Na seção Esquema, insira manualmente a definição do esquema.

    • É possível inserir informações de esquema manualmente com um destes procedimentos:

      • Clique em Editar como texto e insira o esquema da tabela como matriz JSON:

        Adicionar esquema como uma matriz JSON

      • Usando Adicionar campo para inserir o esquema:

        Adicionar esquema usando "Adicionar campos"

  5. Na seção Opções, deixe os valores padrão.

  6. Clique em Criar tabela.

Linha de comando

Use o comando mk com a sinalização --table ou -t. Você pode fornecer informações de esquema de tabela in-line ou por meio de um arquivo JSON. Os parâmetros opcionais incluem --expiration, --description, --time_partitioning_type, --destination_kms_key e --label. Se você está criando uma tabela em um projeto diferente do projeto padrão, adicione o código do projeto ao conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

--time_partitioning_type e --destination_kms_key não são demonstrados aqui. Para mais informações sobre --time_partitioning_type, consulte as tabelas particionadas por tempo de ingestão ou as tabelas particionadas. Para mais informações sobre --destination_kms_key, consulte as chaves de criptografia gerenciadas pelo cliente.

Para criar uma tabela vazia em um conjunto de dados existente com uma definição de esquema, digite:

bq mk --table --expiration [INTEGER] --description [DESCRIPTION] --label [KEY:VALUE, KEY:VALUE] [PROJECT_ID]:[DATASET].[TABLE] [SCHEMA]

Em que:

  • [INTEGER] é a vida útil padrão em segundos da tabela. O valor mínimo é de 3.600 segundos (uma hora). O tempo de expiração é avaliado para a hora atual mais o valor inteiro. Quando você define um tempo de expiração ao criar a tabela, o padrão do conjunto de dados relativo a esse tempo é ignorado;
  • [DESCRIPTION] é uma descrição da tabela entre aspas;
  • [KEY:VALUE] é o par de chave-valor que representa um rótulo. Você pode inserir vários marcadores usando uma lista separada por vírgulas;
  • [PROJECT_ID] é ID do projeto;
  • [DATASET] é um conjunto de dados no projeto;
  • [TABLE] é o nome da tabela que você está criando;
  • [SCHEMA] é a definição de esquema in-line no formato [FIELD]:[DATA_TYPE],[FIELD]:[DATA_TYPE] ou o caminho para o arquivo de esquema JSON em sua máquina local.

Ao especificar o esquema na linha de comando, não é possível incluir um tipo RECORD (STRUCT) nem uma descrição de coluna. Também não é possível especificar o modo da coluna. Todos os modos assumem NULLABLE como padrão. Para incluir tipos RECORD, descrições e modos, forneça um arquivo de esquema JSON.

Exemplos:

Digite o seguinte comando para criar uma tabela usando uma definição de esquema in-line. Este comando cria uma tabela chamada mytable no mydataset em seu projeto padrão. A expiração da tabela está configurada para 3.600 segundos (1 hora), a descrição está definida para This is my table e o rótulo está definido para organization:development. O comando usa o atalho -t em vez de --table. O esquema é especificado in-line como: qtr:STRING,sales:FLOAT,year:STRING.

bq mk -t --expiration 3600 --description "This is my table" --label organization:development mydataset.mytable qtr:STRING,sales:FLOAT,year:STRING

Digite o comando a seguir para criar uma tabela usando um arquivo de esquema JSON. Este comando cria uma tabela chamada mytable no mydataset em seu projeto padrão. A expiração da tabela está configurada para 3.600 segundos (1 hora), a descrição está definida para This is my table e o rótulo está definido para organization:development. O caminho para o arquivo de esquema é /tmp/myschema.json.

bq mk --table --expiration 3600 --description "This is my table" --label organization:development mydataset.mytable /tmp/myschema.json

Digite o comando a seguir para criar uma tabela usando um arquivo de esquema JSON. Este comando cria uma tabela chamada mytable em mydataset no myotherproject. A expiração da tabela está configurada para 3.600 segundos (1 hora), a descrição está definida para This is my table e o rótulo está definido para organization:development. O caminho para o arquivo de esquema é /tmp/myschema.json.

bq mk --table --expiration 3600 --description "This is my table" --label organization:development myotherproject:mydataset.mytable /tmp/myschema.json

Após a criação da tabela, será possível atualizar a validade, a descrição e os rótulos dela. Você também pode modificar a definição do esquema.

API

Chame o método tables.insert com um recurso de tabela definido.

C#

Antes de testar esta amostra, siga as instruções de configuração do C# no 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 C#. 

using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryCreateTable
{
    public BigQueryTable CreateTable(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var dataset = client.GetDataset(datasetId);
        // Create schema for new table.
        var schema = new TableSchemaBuilder
        {
            { "full_name", BigQueryDbType.String },
            { "age", BigQueryDbType.Int64 }
        }.Build();
        // Create the table
        return dataset.CreateTable(tableId: "your_table_id", schema: schema);
    }
}

Go

Antes de testar esta 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 para Go (em inglês). 

sampleSchema := bigquery.Schema{
	{Name: "full_name", Type: bigquery.StringFieldType},
	{Name: "age", Type: bigquery.IntegerFieldType},
}

metaData := &bigquery.TableMetadata{
	Schema:         sampleSchema,
	ExpirationTime: time.Now().AddDate(1, 0, 0), // Table will be automatically deleted in 1 year.
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, metaData); err != nil {
	return err
}

Java

Antes de testar esta 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. 

TableId tableId = TableId.of(datasetName, tableName);
// Table field definition
Field field = Field.of(fieldName, LegacySQLTypeName.STRING);
// Table schema definition
Schema schema = Schema.of(field);
TableDefinition tableDefinition = StandardTableDefinition.of(schema);
TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();
Table table = bigquery.create(tableInfo);

Node.js

Antes de testar esta amostra, siga as instruções de configuração do Node.js em 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');

async function createTable() {
  // Creates a new table named "my_table" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_new_dataset";
  // const tableId = "my_new_table";
  // const schema = "Name:string, Age:integer, Weight:float, IsMagic:boolean";

  // Create a client
  const bigqueryClient = new BigQuery();

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    schema: schema,
    location: 'US',
  };

  // Create a new table in the dataset
  const [table] = await bigqueryClient
    .dataset(datasetId)
    .createTable(tableId, options);

  console.log(`Table ${table.id} created.`);
}
createTable();

PHP

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

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableId = 'The BigQuery table ID';
// $fields = [
//    [
//        'name' => 'field1',
//        'type' => 'string',
//        'mode' => 'required'
//    ],
//    [
//        'name' => 'field2',
//        'type' => 'integer'
//    ],
//];

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$schema = ['fields' => $fields];
$table = $dataset->createTable($tableId, ['schema' => $schema]);
printf('Created table %s' . PHP_EOL, $tableId);

Python

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

from google.cloud import bigquery

schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]

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

# TODO(developer): Set table_id to the ID of the table to create
# table_id = "your-project.your_dataset.your_table_name"

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # API request
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

Ruby

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

require "google/cloud/bigquery"

def create_table dataset_id = "my_dataset"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "my_table"

  table = dataset.create_table table_id do |updater|
    updater.string  "full_name", mode: :required
    updater.integer "age",       mode: :required
  end

  puts "Created table: #{table_id}"
end

Como criar uma tabela a partir do resultado de uma consulta

Para criar uma tabela a partir do resultado de uma consulta, grave-o em uma tabela de destino.

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar a IU da Web do BigQuery

  2. No painel de navegação, localizado na seção Recursos, expanda seu projeto e selecione um conjunto de dados.

  3. Se o Editor de consultas estiver oculto, clique em Exibir editor no canto superior à direita da janela.

  4. Insira uma consulta SQL válida na área de texto do Editor de consultas.

  5. Clique em Mais abaixo do editor e selecione Configurações de consulta.

    Configurações de consulta

  6. Marque a caixa Definir uma tabela de destino para os resultados da consulta.

    Definir destino

  7. Na seção Destino, selecione o Nome do Projeto e o Nome do conjunto de dados em que a tabela será criada. Depois, escolha o Nome da tabela.

  8. Na seção Preferência de gravação na tabela de destino, escolha uma das seguintes opções:

    • Gravar apenas se a tabela estiver vazia: grava os resultados da consulta na tabela somente se ela estiver vazia.
    • Anexar à tabela: anexa os resultados da consulta a uma tabela atual.
    • Substituir tabela: usa os resultados da consulta para substituir uma tabela atual com o mesmo nome.

  9. (Opcional) Em Local de processamento, clique em Seleção automática e escolha o local dos seus dados.

  10. Clique em Executar consulta. Isso cria um job de consulta que grava os resultados da consulta na tabela que você especificou.

Como alternativa, se você esquecer de especificar uma tabela de destino antes de executar a consulta, será possível copiar a tabela temporária para uma permanente. Basta clicar no botão Salvar visualização abaixo do editor.

IU clássica

Opção 1: usar uma instrução DDL

Com as instruções de linguagem de definição de dados (DDL, na sigla em inglês), é possível criar e modificar tabelas usando a sintaxe de consulta do SQL padrão.

Para mais informações, consulte a página da instrução CREATE TABLE e o exemplo CREATE TABLE: Como criar uma nova tabela a partir de uma atual.

Opção 2: usar a IU clássica da Web

  1. Acesse a IU clássica da Web do BigQuery.
    Acesse a IU da Web clássica do BigQuery

  2. Clique no botão Escrever consulta.

  3. Insira uma consulta SQL válida na área de texto Nova consulta.

  4. Clique em Mostrar opções.

  5. Na seção Tabela de destino, clique em Selecionar tabela.

  6. Na caixa de diálogo Selecionar tabela de destino:

    1. Em Projeto, selecione o projeto em que a tabela de destino será criada.

    2. Em Conjunto de dados, selecione o conjunto de dados que armazenará a tabela.

    3. No campo Código da tabela, insira um nome de tabela. Ele precisa ser exclusivo no conjunto de dados de destino. O nome da tabela pode conter até 1.024 caracteres, sendo eles a-z, A-Z, 0-9 ou _ (caractere de sublinhado).

    4. Clique em OK.

  7. Na seção Tabela de destino, em Preferência de gravação, escolha uma das seguintes opções:

    • Gravar apenas se a tabela estiver vazia: grava os resultados da consulta na tabela somente se ela estiver vazia.
    • Anexar à tabela: anexa os resultados da consulta a uma tabela atual.
    • Substituir tabela: usa os resultados da consulta para substituir uma tabela atual com o mesmo nome.

  8. (Opcional) Em Local de processamento, clique em Não especificado e escolha o local dos dados.

  9. Clique em Executar consulta. Isso cria um job de consulta que grava os resultados da consulta na tabela que você especificou.

Como alternativa, se você esquecer de especificar uma tabela de destino antes de executar a consulta, será possível copiar a tabela temporária para uma permanente. Basta clicar no botão Salvar como tabela na janela de resultados.

CLI

Digite o comando bq query e especifique a sinalização --destination_table para criar uma tabela permanente com base nos resultados da consulta. Especifique a sinalização use_legacy_sql=false para usar a sintaxe SQL padrão. Para gravar os resultados da consulta em uma tabela que não esteja no projeto padrão, adicione o código do projeto ao nome do conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

Forneça a sinalização --location e defina o valor como o local.

Para controlar a disposição de gravação de uma tabela de destino atual, especifique uma das seguintes sinalizações opcionais:

  • --append_table: se a tabela de destino existir, os resultados da consulta serão anexados a ela.

  • --replace: se a tabela de destino existir, ela será substituída pelos resultados da consulta.

    bq --location=[LOCATION] query --destination_table [PROJECT_ID]:[DATASET].[TABLE] --use_legacy_sql=false '[QUERY]'

Em que:

  • [LOCATION] é o nome do local usado para processar a consulta. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região Tokyo, será possível definir o valor da sinalização como asia-northeast1. Defina um valor padrão para o local usando o arquivo .bigqueryrc;
  • [PROJECT_ID] é o ID do projeto;
  • [DATASET] é o nome do conjunto de dados que contém a tabela em que você está gravando os resultados da consulta;
  • [TABLE] é o nome da tabela em que você está gravando os resultados da consulta;
  • [QUERY] é uma consulta na sintaxe SQL padrão.

Se nenhuma sinalização de disposição de gravação for especificada, o comportamento padrão será gravar os resultados na tabela somente se ela estiver vazia. Se a tabela existir e não estiver vazia, o seguinte erro será retornado: BigQuery error in query operation: Error processing job '[PROJECT_ID]:bqjob_123abc456789_00000e1234f_1': Already Exists: Table [PROJECT_ID]:[DATASET].[TABLE].

Exemplos:

Digite o comando a seguir para gravar os resultados da consulta em uma tabela de destino chamada mytable em mydataset. O conjunto de dados está no projeto padrão. Como nenhuma sinalização de disposição de gravação está especificada no comando, a tabela precisa ser nova ou estar vazia. Caso contrário, um erro Already exists é retornado. A consulta recupera dados do conjunto de dados público USA Name Data.

bq --location=US query --destination_table mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Digite o comando a seguir para usar os resultados da consulta a fim de substituir uma tabela de destino chamada mytable em mydataset. O conjunto de dados está no projeto padrão. O comando usa a sinalização --replace para substituir a tabela de destino.

bq --location=US query --destination_table mydataset.mytable --replace --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Digite o comando a seguir para anexar os resultados da consulta a uma tabela de destino chamada mytable em mydataset. O conjunto de dados está em myotherproject, e não no projeto padrão. O comando usa a sinalização --append para anexar os resultados da consulta à tabela de destino.

bq --location=US query --destination_table myotherproject:mydataset.mytable --append --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

API

Para salvar os resultados da consulta em uma tabela permanente, chame o método jobs.insert, configure um job query e inclua um valor na propriedade configuration.query.destinationTable. Para controlar a disposição de gravação de uma tabela de destino atual, configure a propriedade configuration.query.writeDisposition.

Especifique o local na propriedade location na seção jobReference do recurso do job.

Go

Antes de testar esta 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.

bigquery/snippets/snippet.go 
// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")

q := client.Query("SELECT 17 as my_col")
q.Location = "US" // Location must match the dataset(s) referenced in query.
q.QueryConfig.Dst = client.Dataset(destDatasetID).Table(destTableID)
job, err := q.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}
it, err := job.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Java

Antes de testar esta 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.

Para salvar os resultados da consulta em uma tabela permanente, defina a tabela de destino como o TableId de sua escolha em um QueryJobConfiguration.

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // Note that setUseLegacySql is set to false by default
    QueryJobConfiguration.newBuilder(query)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Python

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

Para salvar os resultados da consulta em uma tabela permanente, crie um QueryJobConfig e defina o destino como a TableReference de sua escolha. Passe a configuração do job para o método de consulta. 

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'your_dataset_id'

job_config = bigquery.QueryJobConfig()
# Set the destination table
table_ref = client.dataset(dataset_id).table('your_table_id')
job_config.destination = table_ref
sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""

# Start the query, passing in the extra configuration.
query_job = client.query(
    sql,
    # Location must match that of the dataset(s) referenced in the query
    # and of the destination table.
    location='US',
    job_config=job_config)  # API request - starts the query

query_job.result()  # Waits for the query to finish
print('Query results loaded to table {}'.format(table_ref.path))

Como criar uma tabela que faz referência a uma fonte de dados externa

Uma fonte de dados externa (também conhecida como fonte de dados federada) é uma fonte de dados que você pode consultar diretamente, mesmo que os dados não estejam armazenados no BigQuery. Em vez de carregar os dados ou fazer streaming deles, você cria uma tabela que faz referência à fonte de dados externa.

O BigQuery é compatível com consulta de dados diretamente do:

Você pode consultar dados em uma fonte de dados externa compatível criando uma tabela temporária ou permanente que faz referência a dados armazenados na fonte de dados externa. Para saber mais sobre como trabalhar com fontes de dados externas, consulte estes tópicos:

Como criar uma tabela ao carregar dados

Ao carregar dados no BigQuery, é possível: carregá-los a uma tabela ou partição nova, anexá-los a uma tabela ou partição existente ou substituir a tabela ou partição. Não é necessário criar uma tabela vazia antes de carregar dados nela. Você pode criar a nova tabela e carregar seus dados ao mesmo tempo.

Ao carregar dados no BigQuery, forneça o esquema de tabela ou partição. Para formatos de dados compatíveis, use a detecção automática de esquema.

Para mais informações sobre como carregar dados, consulte Introdução ao carregamento de dados no BigQuery.

Como controlar o acesso às tabelas

Não é possível atribuir controles de acesso diretamente às tabelas. Você pode controlar o acesso à tabela configurando controles de acesso no nível do conjunto de dados ou para envolvidos no projeto.

Os controles de acesso no nível do conjunto de dados especificam as operações que usuários, grupos e contas de serviço podem executar nas tabelas nesse conjunto de dados específico. Se você atribuir apenas permissões no nível do conjunto de dados, também precisará atribuir um papel primitivo ou predefinido para envolvidos no projeto que forneça acesso a ele. Por exemplo, bigquery.user.

Em vez de conceder acesso a conjuntos de dados individuais, você pode atribuir papéis do IAM predefinidos para envolvidos no projeto que concedem permissões aos dados de todas as tabelas em todos os conjuntos de dados de um projeto.

Você também pode criar papéis personalizados do IAM. Se você criar um papel personalizado, as permissões concedidas dependerão das operações da tabela que você quer atribuir ao usuário, grupo ou a conta de serviço.

Para mais informações sobre papéis e permissões, consulte estes tópicos:

Para informações sobre como trabalhar com dados de tabelas, consulte Como gerenciar dados de tabelas.

Como usar tabelas

Como conseguir informações sobre tabelas

Para conseguir informações ou metadados sobre tabelas, faça o seguinte:

  • Use o Console do GCP ou a IU da Web clássica do BigQuery.
  • Use o comando bq show da CLI.
  • Chame o método de API tables.get.
  • Consulte as visualizações INFORMATION_SCHEMA (Beta).

Permissões exigidas

Para informações sobre tabelas, é necessário ter o acesso READER no nível do conjunto de dados ou um papel do IAM para envolvidos no projeto que inclua permissões bigquery.tables.get. Se você tem permissões bigquery.tables.get no nível do projeto, pode acessar informações sobre todas as tabelas do projeto. Todos os papéis predefinidos do IAM para envolvidos no projeto incluem permissões bigquery.tables.get, exceto bigquery.jobUser e bigquery.user.

Além disso, um usuário com papel bigquery.user tem permissões bigquery.datasets.create. Isso permite que um usuário com o papel bigquery.user receba informações sobre tabelas em qualquer conjunto de dados criado por ele. Quando um usuário com o papel bigquery.user cria um conjunto de dados, ele recebe o acesso OWNER ao conjunto. O acesso OWNER a um conjunto de dados concede ao usuário controle total sobre o conjunto e todas as tabelas contidas 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 para conjuntos de dados, consulte Papéis primários para conjuntos de dados.

Como receber informações de tabelas

Para informações sobre tabelas, faça o seguinte:

Console

  1. No painel de navegação, localizado na seção Recursos, expanda seu projeto e selecione um conjunto de dados. Clique no nome do conjunto de dados para expandi-lo. Isso exibe as tabelas e visualizações no conjunto de dados.

  2. Clique no nome da tabela.

  3. Abaixo do editor, clique em Detalhes. Essa página exibe a descrição e as informações da tabela.

  4. Clique na guia Esquema para ver a definição do esquema da tabela.

IU clássica

  1. No painel de navegação, clique no ícone de seta para baixo ícone de seta para baixo à esquerda do conjunto de dados para expandi-lo ou clique duas vezes no nome do conjunto. Isso exibe as tabelas e visualizações no conjunto de dados.

  2. Clique no nome da tabela.

  3. Clique em Detalhes. A página Detalhes da tabela exibe a descrição e as informações da tabela.

    Ver detalhes da tabela

  4. Clique na guia Esquema para visualizar a definição do esquema da tabela.

CLI

Emita o comando bq show para exibir todas as informações da tabela. Use a sinalização --schema para exibir apenas informações de esquema de tabela. A sinalização --format pode ser usada para controlar a saída.

Se você estiver recebendo informações sobre uma tabela em um projeto diferente do padrão, adicione o código do projeto ao conjunto de dados no formato abaixo: [PROJECT_ID]:[DATASET].

bq show --schema --format=prettyjson [PROJECT_ID]:[DATASET].[TABLE]

Em que:

  • [PROJECT_ID] é o ID do projeto;
  • [DATASET] é o nome do conjunto de dados;
  • [TABLE] é o nome da tabela.

Exemplos:

Digite o comando a seguir para exibir todas as informações sobre mytable em mydataset. mydataset está no projeto padrão.

bq show --format=prettyjson mydataset.mytable

Digite o comando a seguir para exibir todas as informações sobre mytable em mydataset. mydataset está em myotherproject, e não no projeto padrão.

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

Digite o comando a seguir para exibir somente as informações de esquema sobre mytable em mydataset. mydataset está em myotherproject, e não no projeto padrão.

bq show --schema --format=prettyjson myotherproject:mydataset.mytable

API

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

Go

Antes de testar esta 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 para Go (em inglês). 

meta, err := client.Dataset(datasetID).Table(tableID).Metadata(ctx)
if err != nil {
	return err
}
// Print basic information about the table.
fmt.Printf("Schema has %d top-level fields\n", len(meta.Schema))
fmt.Printf("Description: %s\n", meta.Description)
fmt.Printf("Row in managed storage: %d\n", meta.NumRows)

Java

Antes de testar esta 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. 

TableId tableId = TableId.of(projectId, datasetName, tableName);
Table table = bigquery.getTable(tableId);

PHP

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

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
//$projectId = 'The Google project ID';
//$datasetId = 'The BigQuery dataset ID';
//$tableId   = 'The BigQuery table ID';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);

Python

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

from google.cloud import bigquery

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

# TODO(developer): Set table_id to the ID of the model to fetch.
# table_id = 'your-project.your_dataset.your_table'

table = client.get_table(table_id)

print(
    "Got table '{}.{}.{}'.".format(table.project, table.dataset_id, table.table_id)
)

# View table properties
print("Table schema: {}".format(table.schema))
print("Table description: {}".format(table.description))
print("Table has {} rows".format(table.num_rows))

Como receber informações da tabela usando INFORMATION_SCHEMA (Beta)

INFORMATION_SCHEMA é uma série de visualizações que fornece acesso a metadados sobre conjuntos de dados, tabelas e visualizações.

É possível consultar as visualizações INFORMATION_SCHEMA.TABLES e INFORMATION_SCHEMA.TABLE_OPTIONS para recuperar metadados sobre tabelas e visualizações em um projeto. Também é possível consultar as visualizações INFORMATION_SCHEMA.COLUMNS e INFORMATION_SCHEMA.COLUMN_FIELD_PATHS para recuperar metadados sobre as colunas (campos) de uma tabela.

As visualizações TABLES e TABLE_OPTIONS também contêm informações de alto nível sobre visualizações. Para informações detalhadas, consulte a visualização INFORMATION_SCHEMA.VIEWS.

Visualização TABLES

Quando consultamos a visualização INFORMATION_SCHEMA.TABLES, os resultados contêm uma linha para cada tabela ou visualização no conjunto de dados.

As consultas na visualização INFORMATION_SCHEMA.TABLES precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas ou visualizações.

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

Nome da coluna Tipo de dado Valor
TABLE_CATALOG STRING O nome do projeto que contém o conjunto de dados.
TABLE_SCHEMA STRING O nome do conjunto de dados que contém a tabela ou visualização, também conhecido como o datasetId.
TABLE_NAME STRING O nome da tabela ou visualização, também conhecido como o tableId.
TABLE_TYPE STRING O tipo de tabela:
IS_INSERTABLE_INTO STRING YES ou NO, dependendo da compatibilidade da tabela com instruções DML INSERT.
IS_TYPED STRING O valor sempre é NO.
CREATION_TIME TIMESTAMP O horário de criação da tabela.

Exemplos

Exemplo 1:

O exemplo a seguir recupera todas as colunas da visualização INFORMATION_SCHEMA.TABLES, exceto is_typed, que é reservada para uso futuro. Os metadados retornados correspondem a todas as tabelas em mydataset no projeto padrão (myproject).

O mydataset contém as seguintes tabelas:

  • mytable1: uma tabela padrão do BigQuery.
  • myview1: uma visualização do BigQuery.

As consultas na visualização INFORMATION_SCHEMA.TABLES precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

Para executar a consulta em um projeto diferente do padrão, adicione o código do projeto ao conjunto de dados no seguinte formato: `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] por exemplo, `myproject`.mydataset.INFORMATION_SCHEMA.TABLES.

Para executar a consulta, faça o seguinte:

Console

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

    Acesse a IU da Web do BigQuery

  2. Digite a seguinte consulta SQL padrão na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. SQL padrão é a sintaxe padrão no Console do GCP.

    SELECT
 * EXCEPT(is_typed)
FROM
 mydataset.INFORMATION_SCHEMA.TABLES

  3. Clique em Executar.

Linha de comando

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 é necessária para consultas de INFORMATION_SCHEMA.

Para executar a consulta, digite:

bq query --nouse_legacy_sql \
'SELECT * EXCEPT(is_typed) FROM mydataset.INFORMATION_SCHEMA.TABLES'

Os resultados terão a aparência abaixo:

  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | myproject      | mydataset     | mytable1       | BASE TABLE | YES                | 2018-10-29 20:34:44 |
  | myproject      | mydataset     | myview1        | VIEW       | NO                 | 2018-12-29 00:19:20 |
  +----------------+---------------+----------------+------------+--------------------+---------------------+

Exemplo 2:

O exemplo a seguir recupera todas as tabelas do tipo BASE TABLE da visualização INFORMATION_SCHEMA.TABLES. A coluna is_typed é excluída. Os metadados retornados são para tabelas em mydataset no projeto padrão (myproject).

As consultas na visualização INFORMATION_SCHEMA.TABLES precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

Para executar a consulta em um projeto diferente do padrão, adicione o código do projeto ao conjunto de dados no seguinte formato: `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] por exemplo, `myproject`.mydataset.INFORMATION_SCHEMA.TABLES.

Para executar a consulta, faça o seguinte:

Console

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

    Acesse a IU da Web do BigQuery

  2. Digite a seguinte consulta SQL padrão na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. SQL padrão é a sintaxe padrão no Console do GCP.

    SELECT
 * EXCEPT(is_typed)
FROM
 mydataset.INFORMATION_SCHEMA.TABLES
WHERE
 table_type="BASE TABLE"

  3. Clique em Executar.

Linha de comando

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 é necessária para consultas de INFORMATION_SCHEMA.

Para executar a consulta, digite:

bq query --nouse_legacy_sql \
'SELECT * EXCEPT(is_typed) FROM mydataset.INFORMATION_SCHEMA.TABLES
WHERE table_type="BASE TABLE"'

Os resultados terão a aparência abaixo:

  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | myproject      | mydataset     | mytable1       | BASE TABLE | NO                 | 2018-10-31 22:40:05 |
  +----------------+---------------+----------------+------------+--------------------+---------------------+

Visualização TABLE_OPTIONS

Quando consultamos a visualização INFORMATION_SCHEMA.TABLE_OPTIONS, os resultados contêm uma linha para cada tabela ou visualização no conjunto de dados.

As consultas na visualização INFORMATION_SCHEMA.TABLE_OPTIONS precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas ou visualizações.

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

Nome da coluna Tipo de dado Valor
TABLE_CATALOG STRING O nome do projeto que contém o conjunto de dados.
TABLE_SCHEMA STRING O nome do conjunto de dados que contém a tabela ou visualização, também conhecido como o datasetId.
TABLE_NAME STRING O nome da tabela ou visualização, também conhecido como o tableId.
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
partition_expiration_days FLOAT64 A vida útil padrão em dias de todas as partições em uma tabela particionada.
expiration_timestamp FLOAT64 A vida útil padrão em dias da tabela.
kms_key_name STRING O nome da chave do Cloud KMS usada para criptografar a tabela.
friendly_name STRING O nome descritivo da tabela.
description STRING Uma descrição da tabela.
labels ARRAY<STRUCT<STRING, STRING>> Uma matriz de STRUCTs que representa os rótulos na tabela.

Exemplos

Exemplo 1:

O exemplo a seguir recupera os prazos de validade padrão de todas as tabelas em mydataset no projeto padrão (myproject) por meio da consulta da visualização INFORMATION_SCHEMATA.TABLE_OPTIONS.

As consultas na visualização INFORMATION_SCHEMA.TABLE_OPTIONS precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

Para executar a consulta em um projeto diferente do padrão, adicione o código do projeto ao conjunto de dados no seguinte formato: `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] por exemplo, `myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS.

Para executar a consulta, faça o seguinte:

Console

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

    Acesse a IU da Web do BigQuery

  2. Digite a seguinte consulta SQL padrão na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. SQL padrão é a sintaxe padrão no Console do GCP.

    SELECT
 *
FROM
 mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE
 option_name="expiration_timestamp"

  3. Clique em Executar.

Linha de comando

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 é necessária para consultas de INFORMATION_SCHEMA.

Para executar a consulta, digite:

bq query --nouse_legacy_sql \
'SELECT * FROM mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE option_name="expiration_timestamp"'

Os resultados terão a aparência abaixo:

  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | table_catalog  | table_schema  | table_name |     option_name      | option_type |             option_value             |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | myproject      | mydataset     | mytable1   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2020-01-16T21:12:28.000Z" |
  | myproject      | mydataset     | mytable2   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2021-01-01T21:12:28.000Z" |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+

Exemplo 2:

O exemplo a seguir recupera os metadados sobre todas as tabelas em mydataset que contêm dados de teste. A consulta usa os valores na opção description para localizar as tabelas que contêm “test” (teste) em qualquer lugar da descrição. mydataset está no projeto padrão (myproject).

Para executar a consulta em um projeto diferente do padrão, adicione o código do projeto ao conjunto de dados no seguinte formato: `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] por exemplo, `myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS.

Para executar a consulta, faça o seguinte:

Console

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

    Acesse a IU da Web do BigQuery

  2. Digite a seguinte consulta SQL padrão na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. SQL padrão é a sintaxe padrão no Console do GCP.

    SELECT
 *
FROM
 mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE
 option_name="description" AND option_value LIKE "%test%"

  3. Clique em Executar.

Linha de comando

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 é necessária para consultas de INFORMATION_SCHEMA.

Para executar a consulta, digite:

bq query --nouse_legacy_sql \
'SELECT * FROM mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE option_name="description" AND option_value LIKE "%test%"'

Os resultados terão a aparência abaixo:

  +----------------+---------------+------------+-------------+-------------+--------------+
  | table_catalog  | table_schema  | table_name | option_name | option_type | option_value |
  +----------------+---------------+------------+-------------+-------------+--------------+
  | myproject      | mydataset     | mytable1   | description | STRING      | "test data"  |
  | myproject      | mydataset     | mytable2   | description | STRING      | "test data"  |
  +----------------+---------------+------------+-------------+-------------+--------------+

Visualização COLUMNS

Quando consultamos a visualização INFORMATION_SCHEMA.COLUMNS, os resultados contêm uma linha para cada coluna (campo) em uma tabela.

As consultas na visualização INFORMATION_SCHEMA.COLUMNS precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

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

Nome da coluna Tipo de dado Valor
TABLE_CATALOG STRING O nome do projeto que contém o conjunto de dados.
TABLE_SCHEMA STRING O nome do conjunto de dados que contém a tabela, também conhecido como o datasetId.
TABLE_NAME STRING O nome da tabela ou visualização, também conhecido como o tableId.
COLUMN_NAME STRING O nome da coluna.
ORDINAL_POSITION INT64 O deslocamento de índice 1 da coluna dentro da tabela. Se for uma pseudocoluna, como _PARTITIONTIME ou _PARTITIONDATE, o valor será NULL.
IS_NULLABLE STRING YES ou NO, dependendo de o modo da coluna permitir valores NULL ou não.
DATA_TYPE STRING O tipo de dados SQL padrão da coluna.
IS_GENERATED STRING O valor sempre é NEVER.
GENERATION_EXPRESSION STRING O valor sempre é NULL.
IS_STORED STRING O valor sempre é NULL.
IS_HIDDEN STRING YES ou NO, dependendo do tipo de coluna (se é ou não é uma pseudocoluna, como _PARTITIONTIME ou _PARTITIONDATE).
IS_UPDATABLE STRING O valor sempre é NULL.
IS_SYSTEM_DEFINED STRING YES ou NO, dependendo do tipo de coluna (se é ou não é uma pseudocoluna, como _PARTITIONTIME ou _PARTITIONDATE).
IS_PARTITIONING_COLUMN STRING YES ou NO, dependendo de a coluna ser de particionamento ou não.
CLUSTERING_ORDINAL_POSITION STRING O deslocamento com índice 1 da coluna dentro das colunas de clustering da tabela. O valor será NULL se a tabela não estiver em um cluster.

Exemplos

O exemplo a seguir recupera os metadados da visualização INFORMATION_SCHEMA.COLUMNS correspondentes à tabela population_by_zip_2010 no conjunto de dados census_bureau_usa. Esse conjunto de dados faz parte do programa de conjunto de dados públicos do BigQuery.

Como a tabela está no projeto bigquery-public-data, adicione o código dele ao conjunto de dados no seguinte formato: `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] por exemplo, `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES.

As colunas a seguir são excluídas dos resultados da consulta porque atualmente estão reservadas para uso futuro:

  • IS_GENERATED
  • GENERATION_EXPRESSION
  • IS_STORED
  • IS_UPDATABLE

As consultas na visualização INFORMATION_SCHEMA.COLUMNS precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

Para executar a consulta, faça o seguinte:

Console

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

    Acesse a IU da Web do BigQuery

  2. Digite a seguinte consulta SQL padrão na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. SQL padrão é a sintaxe padrão no Console do GCP.

    SELECT
 * EXCEPT(is_generated, generation_expression, is_stored, is_updatable)
FROM
 `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.COLUMNS
WHERE
 table_name="population_by_zip_2010"

  3. Clique em Executar.

Linha de comando

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 é necessária para consultas de INFORMATION_SCHEMA.

Para executar a consulta, digite:

bq query --nouse_legacy_sql \
'SELECT * EXCEPT(is_generated, generation_expression, is_stored, is_updatable)
FROM `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.COLUMNS
WHERE table_name="population_by_zip_2010"'

Os resultados terão a aparência abaixo. Para melhor legibilidade, table_catalog e table_schema foram excluídos dos resultados:

+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
|       table_name       | column_name | ordinal_position | is_nullable | data_type | is_hidden | is_system_defined | is_partitioning_column | clustering_ordinal_position |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
| population_by_zip_2010 | zipcode     |                1 | NO          | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | geo_id      |                2 | YES         | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | minimum_age |                3 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | maximum_age |                4 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | gender      |                5 | YES         | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | population  |                6 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+

Visualização COLUMN_FIELD_PATHS

Quando consultamos a visualização INFORMATION_SCHEMA.COLUMN_FIELD_PATHS, os resultados contêm uma linha para cada coluna aninhada em uma coluna RECORD (ou STRUCT).

As consultas na visualização INFORMATION_SCHEMA.COLUMN_FIELD_PATHS precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

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

Nome da coluna Tipo de dado Valor
TABLE_CATALOG STRING O nome do projeto que contém o conjunto de dados.
TABLE_SCHEMA STRING O nome do conjunto de dados que contém a tabela, também conhecido como o datasetId.
TABLE_NAME STRING O nome da tabela ou visualização, também conhecido como o tableId.
COLUMN_NAME STRING O nome da coluna.
FIELD_PATH STRING O caminho para uma coluna aninhada dentro de uma coluna RECORD (ou "STRUCT").
DATA_TYPE STRING O tipo de dados SQL padrão da coluna.
DESCRIPTION STRING A descrição da coluna.

Exemplos

O exemplo a seguir recupera os metadados da visualização INFORMATION_SCHEMA.COLUMN_FIELD_PATHS correspondentes à tabela commits no conjunto de dados github_repos. Esse conjunto de dados faz parte do programa de conjunto de dados públicos do BigQuery.

Como a tabela está no projeto bigquery-public-data, adicione o código dele ao conjunto de dados no seguinte formato: `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW]. Por exemplo, `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS.

A tabela commits contém as seguintes colunas aninhadas e repetidas ou só aninhadas:

  • author: coluna RECORD aninhada
  • committer: coluna RECORD aninhada
  • trailer: coluna RECORD aninhada e repetida
  • difference: coluna RECORD aninhada e repetida

A consulta recuperará os metadados sobre as colunas author e difference.

As consultas na visualização INFORMATION_SCHEMA.COLUMN_FIELD_PATHS precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

Para executar a consulta, faça o seguinte:

Console

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

    Acesse a IU da Web do BigQuery

  2. Digite a seguinte consulta SQL padrão na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. SQL padrão é a sintaxe padrão no Console do GCP.

    SELECT
 *
FROM
 `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
WHERE
 table_name="commits"
 AND column_name="author"
 OR column_name="difference"

  3. Clique em Executar.

Linha de comando

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 é necessária para consultas de INFORMATION_SCHEMA.

Para executar a consulta, digite:

bq query --nouse_legacy_sql \
'SELECT * FROM `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
WHERE table_name="commits" AND column_name="author" OR column_name="difference"'

Os resultados terão a aparência abaixo. Para melhor legibilidade, table_catalog e table_schema foram excluídos dos resultados:

  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | table_name | column_name |     field_path      |                                                                      data_type                                                                      | description |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | commits    | author      | author              | STRUCT<name STRING, email STRING, time_sec INT64, tz_offset INT64, date TIMESTAMP>                                                                  | NULL        |
  | commits    | author      | author.name         | STRING                                                                                                                                              | NULL        |
  | commits    | author      | author.email        | STRING                                                                                                                                              | NULL        |
  | commits    | author      | author.time_sec     | INT64                                                                                                                                               | NULL        |
  | commits    | author      | author.tz_offset    | INT64                                                                                                                                               | NULL        |
  | commits    | author      | author.date         | TIMESTAMP                                                                                                                                           | NULL        |
  | commits    | difference  | difference          | ARRAY<STRUCT<old_mode INT64, new_mode INT64, old_path STRING, new_path STRING, old_sha1 STRING, new_sha1 STRING, old_repo STRING, new_repo STRING>> | NULL        |
  | commits    | difference  | difference.old_mode | INT64                                                                                                                                               | NULL        |
  | commits    | difference  | difference.new_mode | INT64                                                                                                                                               | NULL        |
  | commits    | difference  | difference.old_path | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_path | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.old_sha1 | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_sha1 | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.old_repo | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_repo | STRING                                                                                                                                              | NULL        |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+

Como listar tabelas em um conjunto de dados

Use estes métodos para listar tabelas em conjuntos de dados:

  • Use o Console do GCP ou a IU da Web clássica do BigQuery.
  • Use o comando bq ls da CLI.
  • Chame o método de API tables.list.

Permissões exigidas

Para listar tabelas em um conjunto de dados, é necessário ter o papel READER no conjunto de dados ou um do IAM para envolvidos no projeto que inclua permissões bigquery.tables.list. Se você tiver permissões bigquery.tables.list para envolvidos no projeto, será possível listar tabelas em qualquer conjunto de dados no projeto. Todos os papéis do IAM predefinidos para envolvidos no projeto incluem permissões bigquery.tables.list, exceto bigquery.jobUser.

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 para conjuntos de dados, consulte Papéis primários para conjuntos de dados.

Como listar tabelas

Para listar as tabelas em um conjunto de dados, faça o seguinte:

Console

  1. Na IU da Web, localizada no painel de navegação, clique no ícone de seta para baixo ícone de seta para baixo à esquerda do seu conjunto de dados para expandi-lo ou clique no nome do conjunto. Isso exibe as tabelas e visualizações no conjunto de dados.

  2. Percorra a lista para ver as tabelas no conjunto de dados. Tabelas e visualizações são identificadas por diferentes ícones.

IU clássica

  1. Na IU da Web, localizada no painel de navegação, clique no ícone da seta para baixo ícone de seta para baixo à esquerda do conjunto de dados para expandi-lo ou clique duas vezes no nome do conjunto. Isso exibe as tabelas e visualizações no conjunto de dados.

  2. Percorra a lista para ver as tabelas no conjunto de dados. Tabelas e visualizações são identificadas por diferentes ícones.

    Ver tabelas

Linha de comando

Emita o comando bq ls. A sinalização --format pode ser usada para controlar a saída. Se você estiver listando tabelas em um projeto diferente do padrão, adicione o código do projeto ao conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

bq ls --format=pretty [PROJECT_ID]:[DATASET]

em que:

  • [PROJECT_ID] é o ID do projeto;
  • [DATASET] é o nome do conjunto de dados.

Ao executar o comando, o campo Type exibe TABLE ou VIEW. Por exemplo:

+-------------------------+-------+----------------------+-------------------+
|         tableId         | Type  |        Labels        | Time Partitioning |
+-------------------------+-------+----------------------+-------------------+
| mytable                 | TABLE | department:shipping  |                   |
| myview                  | VIEW  |                      |                   |
+-------------------------+-------+----------------------+-------------------+

Exemplos:

Digite o comando a seguir para listar as tabelas no conjunto de dados mydataset no projeto padrão.

bq ls --format=pretty mydataset

Digite o comando a seguir para listar as tabelas no conjunto de dados mydataset em myotherproject.

bq ls --format=pretty myotherproject:mydataset

API

Para listar tabelas usando a API, chame o método tables.list.

C#

Antes de testar esta amostra, siga as instruções de configuração do C# no 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 C#. 

using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;
using System.Linq;

public class BigQueryListTables
{
    public void ListTables(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Retrieve list of tables in the dataset
        List<BigQueryTable> tables = client.ListTables(datasetId).ToList();
        // Display the results
        if (tables.Count > 0)
        {
            Console.WriteLine($"Tables in dataset {datasetId}:");
            foreach (var table in tables)
            {
                Console.WriteLine($"\t{table.Reference.TableId}");
            }
        }
        else
        {
            Console.WriteLine($"{datasetId} does not contain any tables.");
        }
    }
}

Go

Antes de testar esta 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 para Go (em inglês). 

ts := client.Dataset(datasetID).Tables(ctx)
for {
	t, err := ts.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "Table: %q\n", t.TableID)
}

Java

Antes de testar esta 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. 

DatasetId datasetId = DatasetId.of(projectId, datasetName);
Page<Table> tables = bigquery.listTables(datasetId, TableListOption.pageSize(100));
for (Table table : tables.iterateAll()) {
  // do something with the table
}

Node.js

Antes de testar esta amostra, siga as instruções de configuração do Node.js em 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');

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

// Create a client
const bigqueryClient = new BigQuery();

async function listTables() {
  // Lists tables in "my_dataset".

  // List all tables in the dataset
  const [tables] = await bigqueryClient.dataset(datasetId).getTables();

  console.log('Tables:');
  tables.forEach(table => console.log(table.id));
}
listTables();

PHP

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

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$tables = $dataset->tables();
foreach ($tables as $table) {
    print($table->id() . PHP_EOL);
}

Python

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

from google.cloud import bigquery

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

# TODO(developer): Set dataset_id to the ID of the dataset that contains
#                  the tables you are listing.
# dataset_id = 'your-project.your_dataset'

tables = client.list_tables(dataset_id)

print("Tables contained in '{}':".format(dataset_id))
for table in tables:
    print("{}.{}.{}".format(table.project, table.dataset_id, table.table_id))

Ruby

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

require "google/cloud/bigquery"

def list_tables dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id

  puts "Tables in dataset #{dataset_id}:"
  dataset.tables.each do |table|
    puts "\t#{table.table_id}"
  end
end

A seguir

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
BigQuery
Comentários sobre o produto
Precisa de ajuda? Acesse nossa página de suporte.