Como criar e usar tabelas

Este documento descreve como criar e usar tabelas padrão ou "nativas" no BigQuery. Para informações sobre como criar outros tipos de tabelas, consulte:

• Como criar e usar tabelas particionadas por tempo de ingestão
• Como criar e usar tabelas particionadas por uma coluna DATE ou TIMESTAMP
• Como criar e usar tabelas em cluster

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

Antes de começar

Antes de criar uma tabela no BigQuery:

• defina um projeto seguindo um Guia de primeiros passos do BigQuery;
• crie um conjunto de dados do BigQuery.

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 do Cloud e a versão clássica da IU da Web do BigQuery só aceitam copiar 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.
• Ao copiar várias tabelas de origem para uma tabela de destino usando a CLI, a API ou as bibliotecas de cliente, todas as tabelas de origem precisam ter esquemas idênticos.
• Só é possível excluir uma tabela por vez usando o Console do Cloud, a versão clássica da IU da Web do BigQuery, a ferramenta de linha de comando, a API ou as bibliotecas de cliente.
• 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 da enumeração é prejudicado se você usa uma chamada de API ou a versão clássica da IU da Web do BigQuery. Atualmente, a IU da Web do BigQuery no Console do Cloud permite exibir apenas 50.000 tabelas por conjunto de dados.

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

Nomenclatura de tabelas

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

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

Como criar uma tabela

É possível criar uma tabela no BigQuery:

• usando manualmente o Console do Cloud, a IU da Web clássica do BigQuery ou o comando bq mk da ferramenta de linha de comando;
• programaticamente, chamando o método da API tables.insert;
• usando as bibliotecas de cliente;
• a partir dos resultados da consulta;
• definindo uma tabela que faz referência a uma fonte de dados externa;
• ao carregar dados;
• usando uma instrução DDL CREATE TABLE.

Permissões necessárias

Para criar uma tabela, você precisa ter pelo menos as seguintes permissões:

• bigquery.tables.create para criar a tabela
• bigquery.tables.updateData para gravar dados na tabela usando um job de carregamento, de consulta ou de cópia
• bigquery.jobs.create para executar um job de consulta, de carregamento ou de cópia que grave os dados na tabela

Outras permissões, como bigquery.tables.getData, podem ser necessárias para acessar os dados que você está gravando na tabela.

Os seguintes papéis predefinidos do Cloud IAM incluem as permissões bigquery.tables.create e bigquery.tables.updateData:

• bigquery.dataEditor
• bigquery.dataOwner
• bigquery.admin

Os papéis predefinidos do Cloud IAM abaixo incluem permissões bigquery.jobs.create:

• bigquery.user
• bigquery.jobUser
• bigquery.admin

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. O acesso bigquery.dataOwner permite que o usuário crie e atualize tabelas no conjunto de dados.

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

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

Após a criação da tabela, é possível carregar dados nela ou preenchê-la gravando resultados da consulta.

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 Cloud.
   Acessar a IU da Web do BigQuery

2. Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.

3. No lado direito da janela, no painel de detalhes, clique em Criar tabela.

   

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

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

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

     

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

   • Verifique se o Tipo de tabela está definido 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.

       Observação: é possível ver o esquema de uma tabela atual no formato JSON. Basta digitar o seguinte comando: bq show --format=prettyjson dataset.table.

     • Use Adicionar campo para inserir manualmente o esquema.

7. Em Configurações de partição e cluster, use o valor padrão No partitioning.

8. Na seção Opções avançadas, para Criptografia, use o valor padrão Google-managed key. Por padrão, o BigQuery criptografa o conteúdo do cliente armazenado em repouso.

9. Clique em Criar tabela.

Observação: ao criar uma tabela vazia usando o Console do Cloud, não é possível adicionar um rótulo, uma descrição ou um prazo de validade. É possível adicionar essas propriedades opcionais ao criar uma tabela usando a CLI ou a API. Depois de criar uma tabela no Console do Cloud, é possível adicionar uma expiração, uma descrição e rótulos.

DDL

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

Saiba mais sobre Como usar as instruções da linguagem de definição de dados.

Para criar uma tabela no Console do Cloud usando uma instrução DDL:

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

2. Clique em Escrever nova consulta.

3. Digite a instrução do DDL CREATE TABLE na área de texto do Editor de consultas.

   A consulta a seguir cria uma tabela chamada newtable que expira em 1º de janeiro de 2023. A descrição da tabela é "uma tabela que expira em 2023", e o rótulo é org_unit:development.

    CREATE TABLE mydataset.newtable
    (
      x INT64 OPTIONS(description="An optional INTEGER field"),
      y STRUCT<
        a ARRAY<STRING> OPTIONS(description="A repeated STRING field"),
        b BOOL
      >
    )
    OPTIONS(
      expiration_timestamp=TIMESTAMP "2020-01-01 00:00:00 UTC",
      description="a table that expires in 2020",
      labels=[("org_unit", "development")]
    )

4. Opcional: clique em Mais e selecione Configurações de consulta.

5. Opcional: em Local de processamento, clique em Seleção automática e escolha o local dos seus dados. Se você deixar o local de processamento definido como não especificado, ele será detectado automaticamente.

6. Clique em Executar. Quando a consulta for concluída, a tabela será exibida no painel Recursos.

IU clássica

1. Clique no ícone de seta para baixo ao lado do nome do conjunto de dados na navegação e clique em Criar nova tabela.

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

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 uma matriz JSON:

       

       Observação: é possível ver o esquema de uma tabela atual no formato JSON ao digitar o seguinte comando: bq show --schema --format=prettyjson project_id:dataset.table.

     • Use Adicionar campo para inserir o esquema:

       

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

   • Tipo de particionamento: None
   • Campo de particionamento: precisa estar indisponível
   • Exigir filtro de partição: precisa estar indisponível
   • Campos em cluster: precisa estar indisponível
   • Criptografia de destino: Default Por padrão, o BigQuery criptografa o conteúdo do cliente armazenado em repouso usando uma chave gerenciada pela Google.

6. Clique em Criar tabela.

Observação: ao criar uma tabela vazia usando a IU da Web, não é possível adicionar um rótulo, uma descrição ou um prazo de validade. É possível adicionar essas propriedades opcionais ao criar uma tabela usando a CLI ou a API. Depois de criar uma tabela usando a IU da Web do BigQuery, é possível adicionar expiração, descrição e rótulos.

CLI

Use o comando mk com a sinalização --table ou -t. É possível fornecer informações de esquema de tabela in-line ou por meio de um arquivo JSON. Parâmetros opcionais incluem:

• --expiration
• --description
• --time_partitioning_type
• --destination_kms_key
• --label.

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

Se você estiver criando uma tabela em um projeto diferente do projeto padrão, adicione o ID do projeto ao conjunto de dados no seguinte formato: project_id:dataset.

Para criar uma tabela vazia em um conjunto de dados 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 prazo de validade é a soma do horário UTC atual com o valor inteiro. Quando você define um prazo de validade 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. Insira vários marcadores usando uma lista separada por vírgulas.
• project_id é o ID do projeto.
• dataset é um conjunto de dados no projeto;
• table é o nome da tabela que você está criando.
• schema é uma definição de esquema in-line no formato field:data_type,field:data_type ou o caminho para o arquivo de esquema JSON na máquina local.

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

Exemplos:

Digite o comando a seguir para criar uma tabela usando uma definição de esquema in-line. Esse comando cria uma tabela denominada mytable em mydataset no projeto padrão. A expiração da tabela é configurada para 3.600 segundos (uma hora), a descrição é definida como This is my table e o rótulo, como 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. Esse comando cria uma tabela denominada mytable em mydataset no projeto padrão. A expiração da tabela é configurada para 3.600 segundos (uma hora), a descrição é definida como This is my table e o rótulo, como 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. Esse comando cria uma tabela denominada mytable em mydataset em myotherproject. A expiração da tabela é configurada para 3.600 segundos (uma hora), a descrição é definida como This is my table e o rótulo, como 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, é possível atualizar a expiração, a descrição e os rótulos da tabela. É possível também 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 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 C#.

Ver no GitHub Feedback

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

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"time"

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

// createTableExplicitSchema demonstrates creating a new BigQuery table and specifying a schema.
func createTableExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

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

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

Java

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

Ver no GitHub Feedback

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 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 and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new 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_dataset";
  // const tableId = "my_table";
  // const schema = 'Name:string, Age:integer, Weight:float, IsMagic:boolean';

  // 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 bigquery
    .dataset(datasetId)
    .createTable(tableId, options);

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

PHP

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

Ver no GitHub Feedback

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

Ver no GitHub Feedback

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 table to create.
# table_id = "your-project.your_dataset.your_table_name"

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

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

Ruby

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

Ver no GitHub Feedback

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

   Acessar o Console do Cloud

2. Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.

3. Se o editor de consultas estiver oculto, clique em Mostrar editor no canto superior direito 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.

   

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

   

7. Na seção Destino, selecione o Nome do projeto e o Nome do conjunto de dados em que a tabela será criada e escolha um Nome de 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 apenas 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.

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, clique no botão Salvar resultados abaixo do editor para copiar a tabela de resultados em cache para uma tabela permanente.

DDL

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

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

IU clássica

1. Acesse a versão clássica da IU da Web do BigQuery.
   Acessar a versão clássica da IU da Web 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, escolha um projeto para armazenar o conjunto de dados e a tabela.

   2. Em Conjunto de dados, escolha o conjunto de dados para armazenar a tabela.

   3. No campo ID 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 apenas 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 apenas 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 seus 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 clicando no botão Salvar como tabela na janela de resultados.

CLI

Insira 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 ID do projeto ao nome do conjunto de dados no seguinte formato: project_id:dataset.

(Opcional) Forneça a sinalização --location e defina o valor do 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 de Tóquio, defina o valor da sinalização como asia-northeast1. É possível definir 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:

Observação: nestes exemplos, consultamos um conjunto de dados públicos localizado nos EUA. Como o conjunto de dados público é armazenado no local multirregional dos EUA, o conjunto de dados que contém a tabela de destino também precisa estar nesse país. Não é possível consultar um conjunto de dados em um local e gravar os resultados em uma tabela de destino em outro local.

Digite o comando a seguir para gravar resultados de 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, é retornado um erro Already exists. A consulta recupera dados do conjunto de dados público USA Name Data (link em inglês).

bq 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 resultados da consulta e 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 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 resultados de consulta a uma tabela de destino chamada mytable em mydataset. O conjunto de dados está em my-other-project, e não no projeto padrão. O comando usa a sinalização --append para anexar os resultados da consulta à tabela de destino.

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

O resultado de cada um desses exemplos será semelhante ao abaixo. Para facilitar a leitura, ocultamos parte do resultado.

Waiting on bqjob_r123abc456_000001234567_1 ... (2s) Current status: DONE
+---------+--------+
|  name   | number |
+---------+--------+
| Robert  |  10021 |
| John    |   9636 |
| Robert  |   9297 |
| ...              |
+---------+--------+

API

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

Para controlar o local de processamento do job de consulta, especifique a property location na seção jobReference do recurso do job.

Go

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

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

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

// queryWithDestination demonstrates saving the results of a query to a specific table by setting the destination
// via the API properties.
func queryWithDestination(w io.Writer, projectID, destDatasetID, destTableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}

	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)
	// Run the query and print results when the query job is completed.
	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.Fprintln(w, row)
	}
	return nil
}

Java

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

Para salvar resultados de consulta em uma tabela permanente, defina a tabela de destino como o TableId desejado em uma QueryJobConfiguration (links em inglês).

Ver no GitHub

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

Para salvar resultados de consulta em uma tabela permanente, crie um QueryJobConfig e defina o destino como a TableReference desejada. Transmita a configuração do job para o método de consulta (links em inglês).

Ver no GitHub Feedback

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 destination table.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.QueryJobConfig(destination=table_id)

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, job_config=job_config)  # Make an API request.
query_job.result()  # Wait for the job to complete.

print("Query results loaded to the table {}".format(table_id))

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

Uma fonte de dados externa (também chamada de "federada") pode ser consultada diretamente, mesmo que os dados não estejam armazenados no BigQuery. Em vez de carregar os dados ou fazer streaming deles, crie uma tabela que faça referência à fonte de dados externa.

O BigQuery é compatível com a consulta de dados diretamente de um destes:

• Bigtable
• Cloud Storage
• Google Drive

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 consultar dados do Cloud Bigtable
• Como consultar dados do Cloud Storage
• Como consultar dados do Google Drive

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 ou substituir a tabela ou partição. Não é necessário criar uma tabela vazia antes de carregar dados nela. É possível 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 a tabelas ou visualizações. O nível mais baixo de recursos do BigQuery aos quais é possível conceder acesso é o nível do conjunto de dados. Para configurar o acesso a tabelas e visualizações, conceda um papel do Cloud IAM a uma entidade no nível do conjunto de dados ou acima.

A atribuição de um papel no nível do conjunto de dados especifica as operações que uma entidade tem permissão para executar em tabelas e visualizações nesse conjunto de dados específico. Para informações sobre a configuração de controles de acesso no nível do conjunto de dados, consulte Como controlar o acesso a conjuntos de dados.

Também é possível conceder papéis do Cloud IAM em um nível mais alto da hierarquia de recursos do Google Cloud, como projeto, pasta ou organização. A concessão de papéis em um nível mais alto dá à entidade acesso a um conjunto mais amplo de recursos. Por exemplo, a concessão de um papel a uma entidade no nível do projeto concede a ela permissões referentes a todos os conjuntos de dados em todo o projeto. Para mais informações sobre a concessão de acesso a recursos, consulte Como conceder, alterar e revogar o acesso a recursos na documentação do Cloud IAM.

Também é possível criar papéis personalizados do Cloud IAM. Se você criar um papel personalizado, as permissões concedidas dependerão das operações específicas que a entidade poderá executar.

Para saber mais sobre papéis e permissões, consulte:

• Como entender os papéis na documentação do Cloud IAM
• Permissões e papéis predefinidos do BigQuery
• Como controlar o acesso a conjuntos de dados

Como usar tabelas

Como conseguir informações sobre tabelas

É possível conseguir informações ou metadados sobre tabelas:

• usando o Console do Cloud ou a IU da Web clássica do BigQuery;
• usando o comando bq show da CLI;
• chamando o método da API tables.get;
• usando as bibliotecas de cliente;
• consultando as visualizações INFORMATION_SCHEMA (Beta);

Permissões necessárias

No mínimo, para ver informações sobre tabelas, você precisa receber as permissões bigquery.tables.get. Os papéis predefinidos do Cloud IAM a seguir incluem permissões bigquery.tables.get:

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

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. O acesso bigquery.dataOwner permite que o usuário recupere metadados da tabela.

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

Como receber informações de tabelas

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

Console

1. Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados. Clique no nome do conjunto de dados para expandi-lo. Isso exibe as tabelas e visualizações do 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 à esquerda do conjunto de dados para expandi-lo ou clique duas vezes no nome do conjunto de dados. Isso exibe as tabelas e visualizações do 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.

   

4. Clique na guia Esquema para ver 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 somente informações de esquema da 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 projeto padrão, adicione o ID do projeto ao conjunto de dados no seguinte formato: 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á em seu 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 seu projeto padrão.

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

Digite o comando a seguir para exibir apenas informações de esquema sobre mytable em mydataset. mydataset está em myotherproject, 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 do 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 .

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

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

Ver no GitHub Feedback

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

Node.js

Antes de testar esta amostra, siga as instruções de configuração do 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 getTable() {
  // Retrieves table named "my_table" in "my_dataset".

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

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

  console.log('Table:');
  console.log(table.metadata.tableReference);
}
getTable();

PHP

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

Ver no GitHub Feedback

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

Ver no GitHub Feedback

# TODO(developer): Import the client library.
# 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)  # Make an API request.

# View table properties
print(
    "Got table '{}.{}.{}'.".format(table.project, table.dataset_id, table.table_id)
)
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 fornecem acesso a metadados sobre conjuntos de dados, rotinas, tabelas e visualizações.

Consulte 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 ver informações detalhadas, consulte a visualização INFORMATION_SCHEMA.VIEWS.

Visualização TABLES

Os resultados das consultas na visualização INFORMATION_SCHEMA.TABLES contêm uma linha para cada tabela ou visualização do conjunto de dados.

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

Nome da coluna	Tipo de dados	Valor
TABLE_CATALOG	STRING	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 datasetId
TABLE_NAME	STRING	O nome da tabela ou visualização, também conhecido como tableId
TABLE_TYPE	STRING	O tipo de tabela: BASE TABLE: uma tabela do BigQuery VIEW: uma visualização do BigQuery EXTERNAL: uma tabela que faz referência a uma fonte de dados externa
IS_INSERTABLE_INTO	STRING	YES ou NO dependendo da compatibilidade da tabela com as 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).

mydataset contém as seguintes tabelas:

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

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`.dataset.INFORMATION_SCHEMA.view. Veja um 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 Cloud.

   Acesse 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(is_typed)
   FROM
    mydataset.INFORMATION_SCHEMA.TABLES
   

   Observação: os nomes da visualização INFORMATION_SCHEMA diferenciam maiúsculas e minúsculas.

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 é obrigatória para consultas INFORMATION_SCHEMA.

Para executar a consulta, insira:

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 em seu projeto padrão — myproject.

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`.dataset.INFORMATION_SCHEMA.view. Veja um 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 Cloud.

   Acesse 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(is_typed)
   FROM
    mydataset.INFORMATION_SCHEMA.TABLES
   WHERE
    table_type="BASE TABLE"
   

   Observação: os nomes da visualização INFORMATION_SCHEMA diferenciam maiúsculas e minúsculas.

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 é obrigatória para consultas INFORMATION_SCHEMA.

Para executar a consulta, insira:

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

Os resultados terão o seguinte formato:

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

Os resultados das consultas na visualização INFORMATION_SCHEMA.TABLE_OPTIONS contêm uma linha para cada tabela ou visualização do conjunto de dados.

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

Nome da coluna	Tipo de dados	Valor
TABLE_CATALOG	STRING	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 datasetId
TABLE_NAME	STRING	O nome da tabela ou visualização, também conhecido como 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>>	Um array de STRUCTs que representa as identificações na tabela
require_partition_filter	BOOL	Se as consultas na tabela exigem um filtro de partição

Exemplos

Exemplo 1:

O exemplo a seguir recupera os prazos de validade da tabela padrão para todas as tabelas em mydataset no seu projeto padrão (myproject) consultando a visualização INFORMATION_SCHEMA.TABLE_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`.dataset.INFORMATION_SCHEMA.view. Veja um 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 Cloud.

   Acesse 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
    mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
   WHERE
    option_name="expiration_timestamp"
   

   Observação: os nomes da visualização INFORMATION_SCHEMA diferenciam maiúsculas e minúsculas.

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 é obrigatória para consultas INFORMATION_SCHEMA.

Para executar a consulta, insira:

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

Observação: tabelas sem prazo de validade são excluídas dos resultados da consulta.

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 da opção description para encontrar tabelas que contenham "teste" em qualquer parte da descrição. mydataset está no projeto padrão (myproject).

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

   Acesse 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
    mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
   WHERE
    option_name="description" AND option_value LIKE "%test%"
   

   Observação: os nomes da visualização INFORMATION_SCHEMA diferenciam maiúsculas e minúsculas.

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 é obrigatória para consultas INFORMATION_SCHEMA.

Para executar a consulta, insira:

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 o seguinte formato:

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

Os resultados das consultas na visualização INFORMATION_SCHEMA.COLUMNS contêm uma linha para cada coluna (campo) da tabela.

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

Nome da coluna	Tipo de dados	Valor
TABLE_CATALOG	STRING	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 datasetId
TABLE_NAME	STRING	O nome da tabela ou visualização, também conhecido como tableId
COLUMN_NAME	STRING	O nome da coluna
ORDINAL_POSITION	INT64	O deslocamento de índice 1 da coluna na tabela. Se for uma pseudocoluna, como _PARTITIONTIME ou _PARTITIONDATE, o valor será NULL
IS_NULLABLE	STRING	YES ou NO, dependendo do modo da coluna permitir valores NULL
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 se a coluna é uma coluna de particionamento ou não
CLUSTERING_ORDINAL_POSITION	STRING	O deslocamento de índice 1 da coluna nas colunas de cluster da tabela. O valor será NULL se a tabela não for uma tabela em cluster

Exemplos

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

Como a tabela que você está consultando está em outro projeto, bigquery-public-data, adicione o código do projeto 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

Para executar a consulta, faça o seguinte:

Console

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

   Acesse 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(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"
   

   Observação: os nomes da visualização INFORMATION_SCHEMA diferenciam maiúsculas e minúsculas.

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 é obrigatória para consultas INFORMATION_SCHEMA.

Para executar a consulta, insira:

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 facilitar a leitura, 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

Os resultados das consultas na visualização INFORMATION_SCHEMA.COLUMN_FIELD_PATHS contêm uma linha para cada coluna aninhada dentro de uma coluna RECORD (ou STRUCT).

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

Nome da coluna	Tipo de dados	Valor
TABLE_CATALOG	>STRING	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 datasetId
TABLE_NAME	STRING	O nome da tabela ou visualização, também conhecido como tableId
COLUMN_NAME	STRING	O nome da coluna
FIELD_PATH	STRING	O caminho para uma coluna aninhada em 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 metadados da visualização INFORMATION_SCHEMA.COLUMN_FIELD_PATHS para a tabela commits no conjunto de dados github_repos. Ele faz parte do programa de conjunto de dados públicos do BigQuery.

Como a tabela que você está consultando está em outro projeto, bigquery-public-data, adicione o código do projeto 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 vai recuperar os metadados sobre as colunas author e difference.

Para executar a consulta, faça o seguinte:

Console

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

   Acesse 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
    `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
   WHERE
    table_name="commits"
    AND column_name="author"
    OR column_name="difference"
   

   Observação: os nomes da visualização INFORMATION_SCHEMA diferenciam maiúsculas e minúsculas.

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 é obrigatória para consultas INFORMATION_SCHEMA.

Para executar a consulta, insira:

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 facilitar a leitura, 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

É possível listar tabelas em conjuntos de dados:

• usando o Console do Cloud ou a IU da Web clássica do BigQuery;
• Use o comando bq ls da CLI.
• chamando o método da API tables.list;
• usando as bibliotecas de cliente.

Permissões necessárias

Para listar tabelas em um conjunto de dados, é preciso ter pelo menos as permissões bigquery.tables.list. Os papéis predefinidos do Cloud IAM a seguir incluem permissões bigquery.tables.list:

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

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

Como listar tabelas

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

Console

1. No Console do Cloud, no painel de navegação, clique no seu conjunto de dados para expandi-lo. Isso exibe as tabelas e visualizações do conjunto de dados.

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

IU clássica

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

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

   

CLI

Emita o comando bq ls. A sinalização --format pode ser usada para controlar a saída. Se estiver listando tabelas em um projeto diferente do projeto padrão, adicione a ID do projeto ao conjunto de dados no seguinte formato: project_id:dataset.

Veja a seguir algumas outras sinalizações:

• --max_results ou -n: um número inteiro que indica o valor máximo de resultados. O número padrão é 50.

bq ls \
--format=pretty \
--max_results integer \
project_id:dataset

Em que:

• integer é um número inteiro que representa o número de tabelas a serem listadas.
• project_id é o ID do projeto.
• dataset é o nome do conjunto de dados.

Quando você executa 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 tabelas no conjunto de dados mydataset no seu projeto padrão.

bq ls --format=pretty mydataset

Digite o comando a seguir para retornar mais do que a saída padrão de 50 tabelas de mydataset. mydataset está em seu projeto padrão.

bq ls --format=pretty --max_results 60 mydataset

Digite o comando a seguir para listar 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 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 C#.

Ver no GitHub Feedback

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

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

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

// listTables demonstrates iterating through the collection of tables in a given dataset.
func listTables(w io.Writer, projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}

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

Java

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

Ver no GitHub Feedback

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 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 listTables() {
  // Lists tables in 'my_dataset'.

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

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

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

PHP

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

Ver no GitHub Feedback

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

Ver no GitHub Feedback

# TODO(developer): Import the client library.
# 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)  # Make an API request.

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 este exemplo, siga as instruções de configuração do Ruby 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 Ruby.

Ver no GitHub Feedback

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

• Para mais informações sobre conjuntos de dados, consulte Introdução aos conjuntos de dados.
• Para saber mais sobre o gerenciamento de dados da tabela, consulte esta página.
• Para mais informações sobre como especificar esquemas de tabela, consulte Como especificar um esquema.
• Para mais informações sobre como modificar esquemas de tabelas, consulte Como modificar esquemas de tabelas.
• Para mais informações sobre gerenciamento de tabelas, consulte esta página.
• Acesse Introdução ao BigQuery INFORMATION_SCHEMA para uma visão geral de INFORMATION_SCHEMA.