Como criar e usar tabelas particionadas

Neste documento, descreveremos como criar e usar tabelas particionadas no BigQuery. Para informações sobre tabelas particionadas por tempo de ingestão, consulte Como criar e usar tabelas particionadas por tempo de ingestão.

Depois de criar uma tabela particionada, é possível:

controlar o acesso aos dados de sua tabela;
receber informações sobre as tabelas particionadas;
listar as tabelas particionadas em um conjunto de dados;
receber metadados das tabelas particionadas usando metatabelas.

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

Limitações

Tabelas particionadas estão sujeitas às limitações a seguir:

A coluna de particionamento precisa ser DATE ou TIMESTAMP escalar. O modo da coluna pode ser REQUIRED ou NULLABLE, mas não pode ser REPEATED (baseado em matriz). Além disso, a coluna de particionamento precisa ser um campo de nível superior. Não é possível usar um campo de folha de um RECORD (STRUCT) como a coluna de particionamento.
Não é possível usar SQL legado para consultar tabelas particionadas ou gravar resultados de consulta nesse tipo de tabela.

Como criar tabelas particionadas

Você pode criar uma tabela particionada no BigQuery:

usando uma instrução DDL CREATE TABLE com uma cláusula PARTITION BY contendo uma partition expression;
manualmente, usando o comando bq mk da ferramenta de linha de comando;
de maneira programática, ao chamar o método de API tables.insert;
a partir dos resultados da consulta
ao carregar dados.

Ao criar uma tabela particionada por tempo baseada em colunas 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.

Permissões exigidas

Para criar uma tabela particionada, é necessário ter acesso WRITER no nível do conjunto de dados ou um papel de 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 a função bigquery.user tem permissões bigquery.datasets.create, um usuário atribuído ao papel bigquery.user pode criar tabelas particionadas em qualquer conjunto de dados que o usuário criar. Quando um usuário com papel bigquery.user cria um conjunto de dados, recebe acesso de OWNER ao conjunto. O acesso OWNER a um conjunto de dados concede ao usuário o controle total sobre ele 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 criar uma tabela particionada vazia com definição de esquema

Não é possível criar uma tabela particionada vazia que não tenha uma definição de esquema. O esquema é necessário para identificar a coluna usada para criar as partições.

Ao criar uma tabela particionada vazia com uma definição de esquema, você pode:

fornecer o esquema in-line usando a ferramenta de linha de comando;
especificar 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 particionada, é possível:

carregar dados nela;
gravar os resultados da consulta nela;
copiar dados para ela.

Para criar uma tabela particionada vazia com definição de esquema:

Console

Abra a IU da Web do BigQuery no Console do GCP.
Acessar a IU da Web do BigQuery
Clique em Criar uma nova consulta.
Digite sua instrução CREATE TABLE DDL na área de texto do editor de consultas.

A consulta a seguir cria uma tabela denominada newtable que é particionada pela coluna transaction_date DATE e tem uma expiração de partição de três dias.
```
 #standardSQL
 CREATE TABLE mydataset.newtable (transaction_id INT64, transaction_date DATE)
 PARTITION BY transaction_date
 OPTIONS(
   partition_expiration_days=3,
   description="a table partitioned by transaction_date"
 )
```
Clique em Mais e selecione Configurações de consulta.
Em Local de processamento, clique em Seleção automática e escolha o local dos seus dados. Caso os dados estejam no local multirregional US ou EU, deixe a região de processamento definida como não especificada. Quando os dados estão na região US ou EU, o local de processamento é detectado automaticamente.
Clique em Executar. Quando a consulta for concluída, a tabela será exibida no painel Recursos.

IU clássica

Acesse a IU da Web do BigQuery.

Acessar a IU da Web do BigQuery
Clique em Escrever consulta.

Digite a instrução CREATE TABLE DDL na área de texto Nova consulta.

A consulta a seguir cria uma tabela denominada newtable que é particionada pela coluna transaction_date DATE e tem uma expiração de partição de três dias.

 #standardSQL
 CREATE TABLE mydataset.newtable (transaction_id INT64, transaction_date DATE)
 PARTITION BY transaction_date
 OPTIONS(
   partition_expiration_days=3,
   description="a table partitioned by transaction_date"
 )

Clique em Mostrar opções.
Em Local de processamento, clique em Não especificado e escolha o local dos seus dados. Caso os dados estejam no local multirregional US ou EU, deixe a região de processamento definida como não especificada. Quando os dados estão na região US ou EU, o local de processamento é detectado automaticamente.
Clique em Executar consulta. Quando a consulta é concluída, a tabela aparece no painel de navegação.

Linha de comando

Use o comando mk com as sinalizações --table (ou atalho -t), --schema e --time_partitioning_field. Você pode fornecer a definição de esquema da tabela in-line ou por meio de um arquivo de esquema JSON.

Os parâmetros opcionais incluem --expiration, --description, --time_partitioning_expiration, --destination_kms_key e --label. Atualmente, DAY é o único valor compatível com --time_partitioning_type, de modo que essa sinalização não é necessária.

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 formato a seguir: [PROJECT_ID]:[DATASET].

--destination_kms_key não é demonstrado aqui. Para mais informações sobre como usar essa sinalização, consulte as chaves de criptografia gerenciadas pelo cliente.

Digite o comando a seguir para criar uma tabela particionada vazia com uma definição de esquema:

bq mk --table --expiration [INTEGER1] --schema [SCHEMA] --time_partitioning_field [COLUMN] --time_partitioning_expiration [INTEGER2] --description "[DESCRIPTION]" --label [KEY:VALUE, KEY:VALUE] [PROJECT_ID]:[DATASET].[TABLE]

Onde:

[INTEGER1] é 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. Se você definir o tempo de expiração ao criar uma tabela particionada por tempo, a configuração padrão de expiração da tabela do conjunto de dados será ignorada. Definir esse valor exclui a tabela e todas as partições após o tempo especificado;
[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 na máquina local;
[COLUMN] é o nome da coluna TIMESTAMP ou DATE usada para criar as partições;
[INTEGER2] é a vida útil padrão (em segundos) para as partições da tabela. Não há valor mínimo. A data de validade é avaliada para a data da partição acrescida deste valor. A expiração da partição é independente da expiração da tabela, mas não a substitui. Se você definir uma expiração de partição mais longa do que a expiração da tabela, a expiração da tabela terá precedência;
[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] é o código do projeto;
[DATASET] é um conjunto de dados no projeto;
[TABLE] é o nome da tabela particionada que você está criando.

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 descrições, modos e tipos RECORD, forneça um arquivo de esquema JSON.

Exemplos:

Digite o seguinte comando para criar uma tabela particionada chamada mypartitionedtable em mydataset no projeto padrão. A expiração do particionamento é definida para 86.400 segundos (um dia), a expiração da tabela é definida para 2.592.000 (um mês de 30 dias), a descrição é definida para This is my partitioned table e o rótulo é definido como organization:development. O comando usa o atalho -t em vez de --table.

O esquema é especificado in-line como: ts:TIMESTAMP,column1:STRING,column2:INTEGER,coumn4:STRING. O campo TIMESTAMP ts especificado é usado para criar as partições.

bq mk -t --expiration 2592000 --schema 'ts:TIMESTAMP,column1:STRING,column2:INTEGER,coumn4:STRING' --time_partitioning_field ts --time_partitioning_expiration 86400  --description "This is my partitioned table" --label org:dev mydataset.mypartitionedtable

Digite o seguinte comando para criar uma tabela particionada chamada mypartitionedtable em myotherproject, e não no projeto padrão. A expiração do particionamento é configurada para 259.200 segundos (três dias), a descrição é definida como This is my partitioned table e o rótulo é definido como organization:development. O comando usa o atalho -t em vez de --table. Esse comando não especifica uma expiração de tabela. Se o conjunto de dados tiver uma expiração de tabela padrão, ela será aplicada. Se o conjunto de dados não tiver uma expiração de tabela padrão, a tabela nunca expirará, mas as partições expirarão em três dias.

O esquema é especificado em um arquivo JSON local: /tmp/myschema.json. A definição do esquema inclui um campo TIMESTAMP chamado ts que é usado para criar as partições.

bq mk -t --expiration 2592000 --schema /tmp/myschema.json --time_partitioning_field ts --time_partitioning_expiration 86400  --description "This is my partitioned table" --label org:dev myotherproject:mydataset.mypartitionedtable

Depois da criação da tabela, atualize a validade da tabela, a validade da partição, a descrição e os rótulos da tabela particionada.

API

Chame o método tables.insert com um recurso de tabela definido que especifica as propriedades timePartitioning e schema.

Go

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

Ver no GitHub Feedback

// 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")
sampleSchema := bigquery.Schema{
	{Name: "name", Type: bigquery.StringFieldType},
	{Name: "post_abbr", Type: bigquery.IntegerFieldType},
	{Name: "date", Type: bigquery.DateFieldType},
}
metadata := &bigquery.TableMetadata{
	TimePartitioning: &bigquery.TimePartitioning{
		Field:      "date",
		Expiration: 90 * 24 * time.Hour,
	},
	Schema: sampleSchema,
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, metadata); err != nil {
	return err
}

Python

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

Ver no GitHub Feedback

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')

table_ref = dataset_ref.table("my_partitioned_table")
schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
    bigquery.SchemaField("date", "DATE"),
]
table = bigquery.Table(table_ref, schema=schema)
table.time_partitioning = bigquery.TimePartitioning(
    type_=bigquery.TimePartitioningType.DAY,
    field="date",  # name of column to use for partitioning
    expiration_ms=7776000000,
)  # 90 days

table = client.create_table(table)

print(
    "Created table {}, partitioned on column {}".format(
        table.table_id, table.time_partitioning.field
    )
)

Como criar uma tabela particionada com base em um resultado de consulta

Para criar uma tabela particionada de um resultado de consulta, grave os resultados em uma nova tabela de destino. Você pode criar uma tabela particionada consultando uma tabela particionada ou não particionada. Não é possível alterar uma tabela padrão existente para uma tabela particionada usando os resultados da consulta.

Quando você cria uma tabela particionada de um resultado de consulta, é necessário usar o SQL padrão. Atualmente, SQL legado não é aceito para consultar tabelas particionadas ou para gravar resultados de consulta em tabelas particionadas.

Os decoradores de partição permitem que você grave os resultados da consulta em uma partição específica. Para ajustar os fusos horários, use um decorador para gravar os dados em uma partição com base no fuso horário da sua preferência. Por exemplo, se você estiver no Horário padrão do Pacífico (PST, na sigla em inglês), grave todos os dados gerados em 1º de maio de 2016 PST na partição dessa data usando o decorador de partição correspondente:

[TABLE_NAME]$20160501

Ao gravar resultados de consulta em uma partição específica usando um decorador de partição, os dados que estão sendo gravados na partição precisam estar de acordo com o esquema de particionamento da tabela. Todas as linhas escritas na partição precisam ter valores que se enquadrem na data dela.

Por exemplo:

A consulta a seguir grava dados na partição de 1º de fevereiro de 2018 da tabela T. A tabela tem duas colunas: uma coluna TIMESTAMP, chamada TS, e uma coluna INT64, chamada a. Como a consulta grava o carimbo de data/hora 2018-02-01 na partição $20180201, o comando é concluído com êxito. A consulta é executada na multirregião US.

bq --location=US query --nouse_legacy_sql  --destination_table=T$20180201 'SELECT TIMESTAMP("2018-02-01") as TS, 2 as a'

A consulta a seguir também tenta gravar dados na tabela T, mas grava o carimbo de data/hora 2018-01-31 na partição $20180201. Essa consulta apresenta falha porque o valor que você está tentando gravar não se enquadra na data da partição.

bq --location=US query --nouse_legacy_sql  --destination_table=T$20180201 'SELECT TIMESTAMP("2018-01-31") as TS, 2 as a'

Para saber como anexar ou redefinir (substituir) dados em tabelas particionadas, consulte Como anexar e substituir dados de tabela particionada por tempo. Para mais informações sobre como consultar tabelas particionadas, veja o artigo relacionado.

Console

Não é possível especificar opções de particionamento para uma tabela de destino quando você consulta dados usando a IU da Web do BigQuery.

IU clássica

Não é possível especificar opções de particionamento para uma tabela de destino quando você consulta dados usando a IU da Web do BigQuery.

CLI

Digite o comando bq query, especifique a sinalização --destination_table para criar uma tabela permanente com base nos resultados da consulta e especifique a sinalização --time_partitioning_field para criar uma tabela de destino particionada. Atualmente, DAY é o único valor compatível com --time_partitioning_type, de modo que essa sinalização não é necessária.

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 em seu 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 do local.

Digite o comando a seguir para criar uma nova tabela de destino particionada com base em um resultado de consulta:

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

Onde:

[LOCATION] é o nome do seu local. A sinalização --location será opcional se os dados estiverem no local multirregional US ou EU. 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 código do projeto;
[DATASET] é o nome do conjunto de dados que conterá a nova tabela particionada;
[TABLE] é o nome da tabela particionada que você está criando com os resultados da consulta;
[QUERY] é uma consulta na sintaxe SQL padrão. No momento, não é possível usar SQL legado para consultar tabelas particionadas ou gravar os resultados da consulta em tabelas particionadas.

Exemplos:

Digite o comando a seguir para gravar os resultados da consulta em uma tabela de destino particionada denominada mypartitionedtable em mydataset. mydataset está no projeto padrão. A consulta recupera dados de uma tabela não particionada, o conjunto de dados públicos NHTSA Traffic Fatality. A coluna timestamp_of_crash TIMESTAMP da tabela é usada para criar as partições.

bq --location=US query --destination_table mydataset.mypartitionedtable --time_partitioning_field timestamp_of_crash --use_legacy_sql=false 'SELECT state_number, state_name, day_of_crash, month_of_crash, year_of_crash, latitude, longitude, manner_of_collision, number_of_fatalities, timestamp_of_crash FROM `bigquery-public-data.nhtsa_traffic_fatalities.accident_2016` LIMIT 100'

Digite o comando a seguir para gravar os resultados da consulta em uma tabela de destino particionada chamada mypartitionedtable em mydataset. mydataset está em myotherproject, e não no projeto padrão. A consulta recupera dados de uma tabela não particionada, o conjunto de dados públicos NHTSA Traffic Fatality. A coluna timestamp_of_crash TIMESTAMP da tabela é usada para criar as partições.

bq --location=US query --destination_table myotherproject:mydataset.mypartitionedtable --time_partitioning_field timestamp_of_crash --use_legacy_sql=false 'SELECT state_number, state_name, day_of_crash, month_of_crash, year_of_crash, latitude, longitude, manner_of_collision, number_of_fatalities, timestamp_of_crash FROM `bigquery-public-data.nhtsa_traffic_fatalities.accident_2016` LIMIT 100'

API

Para salvar os resultados da consulta em uma tabela particionada permanente, chame o método jobs.insert, configure um job query e inclua um valor para as propriedades configuration.query.destinationTable e timePartitioning.field.

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

Como criar uma tabela particionada ao carregar dados

Você pode criar uma tabela particionada especificando opções de particionamento ao carregar dados em uma nova tabela. Você não precisa criar uma tabela particionada vazia antes de carregar dados nela. Você pode criar a tabela particionada e carregar seus dados ao mesmo tempo.

Ao carregar dados no BigQuery, você pode fornecer o esquema da tabela ou, para formatos de dados compatíveis, usar a detecção automática de esquema.

Os decoradores de partição permitem que você carregue os dados em uma partição específica. Para ajustar os fusos horários, use um decorador para carregar os dados em uma partição com base no fuso horário da sua preferência. Por exemplo, se você estiver no Horário padrão do Pacífico (PST, na sigla em inglês), carregue todos os dados gerados em 1º de maio de 2016 PST na partição dessa data usando o decorador de partição correspondente:

[TABLE_NAME]$20160501

Ao carregar dados em uma partição específica usando um decorador de partição, os dados que estão sendo carregados na partição precisam estar em conformidade com o esquema de particionamento da tabela. Todas as linhas escritas na partição precisam ter valores que se enquadrem na data dela.

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

API

Para definir a configuração de particionamento ao criar uma tabela por meio de um job de carregamento, preencha a mensagem configuration.load.timePartitioning com a configuração de particionamento relacionada e inclua configuration.load.timePartitioning.expirationMs para que as partições expirem ao longo do tempo. O preenchimento de configuration.load.timePartitioning.field determina se essa tabela é particionada por pseudocoluna ou coluna de dados do usuário.

Go

Ver no GitHub Feedback

// 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")
gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states-by-date.csv")
gcsRef.SkipLeadingRows = 1
gcsRef.Schema = bigquery.Schema{
	{Name: "name", Type: bigquery.StringFieldType},
	{Name: "post_abbr", Type: bigquery.StringFieldType},
	{Name: "date", Type: bigquery.DateFieldType},
}
loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
loader.TimePartitioning = &bigquery.TimePartitioning{
	Field:      "date",
	Expiration: 90 * 24 * time.Hour,
}
loader.WriteDisposition = bigquery.WriteEmpty

job, err := loader.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}

if status.Err() != nil {
	return fmt.Errorf("Job completed with error: %v", status.Err())
}

Python

Ver no GitHub Feedback

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'
table_id = "us_states_by_date"

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
    bigquery.SchemaField("date", "DATE"),
]
job_config.skip_leading_rows = 1
job_config.time_partitioning = bigquery.TimePartitioning(
    type_=bigquery.TimePartitioningType.DAY,
    field="date",  # name of column to use for partitioning
    expiration_ms=7776000000,
)  # 90 days
uri = "gs://cloud-samples-data/bigquery/us-states/us-states-by-date.csv"

load_job = client.load_table_from_uri(
    uri, dataset_ref.table(table_id), job_config=job_config
)  # API request

assert load_job.job_type == "load"

load_job.result()  # Waits for table load to complete.

table = client.get_table(dataset_ref.table(table_id))
print("Loaded {} rows to table {}".format(table.num_rows, table_id))

Como controlar o acesso a tabelas particionadas

Não é possível atribuir controles de acesso diretamente a tabelas ou partições. Você pode controlar o acesso à tabela configurando controles de acesso no nível do conjunto de dados ou no nível do projeto.

Os controles de acesso no nível do conjunto de dados especificam quais 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:

Noções básicas dos papéis na documentação do IAM
Controles de acesso do BigQuery
Como controlar o acesso a conjuntos de dados

Como usar tabelas particionadas

Como conseguir informações sobre tabelas particionadas

Para mais informações sobre tabelas, use o Console do GCP, a IU da Web clássica do BigQuery, o comando bq show da CLI ou chame o método tables.get da API.

Permissões exigidas

Para criar uma tabela particionada, é necessário ter acesso READER no nível do conjunto de dados ou um papel de 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 de IAM predefinidos para envolvidos no projeto incluem permissões bigquery.tables.get, exceto bigquery.user e bigquery.jobUser.

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.

Como conseguir informações da tabela particionada

Para ver informações sobre uma tabela particionada:

Console

Abra a IU da Web do BigQuery no Console do GCP.
Acessar a IU da Web do BigQuery
No painel de navegação, na seção Recursos, expanda seu projeto e conjunto de dados, depois clique no nome da tabela na lista.
Clique em Detalhes abaixo da opção Editor de consultas. Essa guia exibe a descrição da tabela e as informações da tabela.
Clique na guia Esquema para visualizar a definição do esquema da tabela. Observe que tabelas particionadas não incluem a pseudocoluna _PARTITIONTIME.

IU clássica

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 dele. Isso exibe as tabelas e visualizações no conjunto de dados.
Clique no nome da tabela.
Clique em Detalhes. A página Detalhes da tabela exibe a descrição e as informações da tabela.
Clique na guia Esquema para visualizar a definição do esquema da tabela. Observe que tabelas particionadas não incluem a pseudocoluna _PARTITIONTIME.

Linha de comando

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 código 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, não no projeto padrão.

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

API

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

Como listar tabelas particionadas em um conjunto de dados

Para listar tabelas em conjuntos de dados (incluindo tabelas particionadas), use o Console do GCP, a IU da Web clássica do BigQuery, o comando bq ls da CLI ou chame o método da 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 papel de IAM para envolvidos no projeto que inclua permissões bigquery.tables.list. Se você tiver permissões bigquery.tables.list para envolvidos no projeto, poderá listar as tabelas em qualquer conjunto de dados do projeto. Todos os papéis do IAM predefinidos para envolvidos no projeto incluem permissões bigquery.tables.list, exceto bigquery.jobUser.

Como listar tabelas particionadas

Para listar as tabelas em um conjunto de dados (inclusive as particionadas):

Console

Abra a IU da Web do BigQuery no Console do GCP.
Acessar a IU da Web do BigQuery
No painel de navegação, na seção Recursos, expanda seu projeto e selecione um conjunto de dados.
Percorra a lista para ver as tabelas no conjunto de dados. Tabelas, tabelas particionadas, modelos e visualizações são identificados por diferentes ícones.

IU clássica

No painel de navegação da IU da Web do BigQuery, clique no ícone de seta para baixo , à esquerda do conjunto de dados, para expandi-lo ou clique duas vezes no nome dele. Isso exibe as tabelas e visualizações no conjunto de dados.
Percorra a lista para ver as tabelas no conjunto de dados. Tabelas e visualizações são identificadas por diferentes ícones.

CLI

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 código do projeto;
[DATASET] é o nome do conjunto de dados.

Quando você executa o comando, o campo Type exibe TABLE ou VIEW. Em tabelas particionadas, o campo Time Partitioning exibe DAY, a coluna usada para criar as partições e o tempo de expiração da partição em milissegundos (se houver).

Por exemplo:

+-------------------------+-------+----------------------+---------------------------------------------------+
|         tableId         | Type  |        Labels        | Time Partitioning                                 |
+-------------------------+-------+----------------------+---------------------------------------------------+
| mytable                 | TABLE | department:shipping  |  DAY (field: source_date, expirationMs: 86400000) |
| 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.

Como listar partições em tabelas particionadas

Para listar as partições em uma tabela particionada, consulte a metatabela __PARTITIONS_SUMMARY__ usando o SQL legado.

Para executar a consulta no Console do GCP ou na IU da Web clássica do BigQuery, use o comando bq query ou chame o método jobs.insert e configure um job query.

Permissões exigidas

Para executar um job de consulta que usa a metatabela __PARTITIONS_SUMMARY__, é preciso ter permissões bigquery.jobs.create. Os seguintes papéis predefinidos do IAM para envolvidos no projeto incluem permissões bigquery.jobs.create:

Também é preciso ter o papel READER no nível do conjunto de dados ou um papel do IAM para envolvidos no projeto que inclua permissões bigquery.tables.getData. Todos os papéis do IAM predefinidos para envolvidos no projeto incluem permissões bigquery.tables.getData, exceto bigquery.user, bigquery.jobUser e bigquery.metadataViewer.

Como listar partições em uma tabela particionada

Você pode listar partições em uma tabela particionada usando SQL legado. Para listar partições em uma tabela particionada:

Console

Abra a IU da Web do BigQuery no Console do GCP.
Acessar a IU da Web do BigQuery
Clique no botão Escrever nova consulta.
Digite o seguinte texto na caixa Editor de consultas para consultar a metatabela __PARTITIONS_SUMMARY__:
```
#legacySQL
SELECT
  partition_id
FROM
  [[DATASET].[TABLE]$__PARTITIONS_SUMMARY__]
```
em que:
- [DATASET] é o conjunto de dados que contém a tabela;
- [TABLE] é o nome da tabela.
Clique em Mais e selecione Configurações de consulta.
Em Local de processamento, clique em Seleção automática e escolha o local dos seus dados. Você pode deixar o local de processamento definido como Seleção automática se seus dados estiverem no local multirregional US ou EU. Quando os dados estão na região US ou EU, o local de processamento é detectado automaticamente.
Clique em Executar.

IU clássica

Acesse a IU da Web do BigQuery.

Acessar a IU da Web do BigQuery
Clique no botão Escrever consulta.
Digite o texto abaixo na caixa Nova consulta para consultar a metatabela __PARTITIONS_SUMMARY__:
```
#legacySQL
SELECT
  partition_id
FROM
  [[DATASET].[TABLE]$__PARTITIONS_SUMMARY__]
```
Onde:
- [DATASET] é o conjunto de dados que contém a tabela;
- [TABLE] é o nome da tabela.
Clique em Mostrar opções.
Em Local de processamento, clique em Não especificado e escolha o local dos seus dados. Caso os dados estejam no local multirregional US ou EU, deixe a região de processamento definida como não especificada. Quando os dados estão na região US ou EU, o local de processamento é detectado automaticamente.
Clique em Executar consulta.

CLI

Digite a consulta abaixo usando o comando bq query:

bq --location=[LOCATION] query --use_legacy_sql=true '
SELECT
  partition_id
FROM
  [[DATASET].[TABLE]$__PARTITIONS_SUMMARY__]'

Where:

  + `[LOCATION]` is the name of your location. The `--location` flag is
    optional if your data is in the `US` or the `EU` multi-region
    location. For example, if you are using BigQuery in
    the Tokyo region, set the flag's value to `asia-northeast1`. You can
    set a default value for the location using the [.bigqueryrc file](/bigquery/docs/bq-command-line-tool#setting_default_values_for_command-line_flags).
  + `[DATASET]` is the dataset that contains the table.
  + `[TABLE]` is the name of the table.

API

Chame o método jobs.insert e configure um job query que consulte a metatabela __PARTITIONS_SUMMARY__.

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

Como receber metadados de tabelas usando metatabelas

Para mais informações sobre tabelas particionadas, use tabelas especiais chamadas metatabelas. Metatabelas contêm metadados, como a lista de tabelas e exibições em um conjunto de dados. As metatabelas são somente leitura.

Como conseguir metadados de partição usando metatabelas

A metatabela __PARTITIONS_SUMMARY__ é uma tabela especial cujos conteúdos representam metadados sobre partições em uma tabela particionada por tempo. A metatabela __PARTITIONS_SUMMARY__ é somente leitura.

Para acessar metadados sobre as partições em uma tabela particionada por tempo, use a metatabela __PARTITIONS_SUMMARY__ na instrução SELECT de uma consulta. É possível executar a consulta, basta usar o console, a IU da Web clássica do BigQuery, o comando bq query da ferramenta de linha de comando ou chamar o método de API jobs.insert e configurar um job de consulta.

Atualmente, como o SQL padrão não é compatível com o separador do decorador de partição ($), não é possível consultar __PARTITIONS_SUMMARY__ no SQL padrão. Uma consulta de SQL legado que use a metatabela __PARTITIONS_SUMMARY__ terá esta aparência:

    SELECT [COLUMN] FROM [[DATASET].[TABLE]$__PARTITIONS_SUMMARY__]

em que:

[DATASET] é o nome do conjunto de dados;
[TABLE] é o nome da tabela particionada por tempo;
[COLUMN] é uma destas:

Valor	Descrição
`project_id`	Nome do projeto.
`dataset_id`	Nome do conjunto de dados.
`table_id`	Nome da tabela particionada por tempo.
`partition_id`	Nome (data) da partição.
`creation_time`	O momento em que a partição foi criada, em milissegundos, desde 1º de janeiro de 1970 UTC.
`last_modified_time`	O momento em que a partição foi modificada pela última vez, em milissegundos, desde 1º de janeiro de 1970 UTC.

Permissões de metatabela da partição

Exemplo de metatabela da partição

A consulta a seguir recupera todos os metadados da partição para uma tabela particionada por tempo denominada mydataset.mytable.

Console

#legacySQL
SELECT
  *
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]

IU clássica

#legacySQL
SELECT
  *
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]

Linha de comando

bq query --use_legacy_sql=true '
SELECT
  *
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]'

A saída tem esta aparência:

+----------------+------------+----------------+--------------+---------------+--------------------+
|   project_id   | dataset_id |    table_id    | partition_id | creation_time | last_modified_time |
+----------------+------------+----------------+--------------+---------------+--------------------+
| myproject      | mydataset  | mytable        | 20160314     | 1517190224120 | 1517190224997      |
| myproject      | mydataset  | mytable        | 20160315     | 1517190224120 | 1517190224997      |
+----------------+------------+----------------+--------------+---------------+--------------------+

A consulta a seguir lista os horários em que as partições em mydataset.mytable foram modificadas pela última vez.

Console

#legacySQL
SELECT
  partition_id,
  last_modified_time
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]

IU clássica

#legacySQL
SELECT
  partition_id,
  last_modified_time
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]

Linha de comando

bq query --use_legacy_sql=true '
SELECT
  partition_id,
  last_modified_time
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]'

A saída tem esta aparência:

+--------------+--------------------+
| partition_id | last_modified_time |
+--------------+--------------------+
| 20160102     |      1471632556179 |
| 20160101     |      1471632538142 |
| 20160103     |      1471632570463 |
+--------------+--------------------+

Para exibir o campo last_modified_time em formato legível, use a função FORMAT_UTC_USEC: Por exemplo:

Console

#legacySQL
SELECT
  partition_id,
  FORMAT_UTC_USEC(last_modified_time*1000) AS last_modified
FROM
  [mydataset.table1$__PARTITIONS_SUMMARY__]

IU clássica

#legacySQL
SELECT
  partition_id,
  FORMAT_UTC_USEC(last_modified_time*1000) AS last_modified
FROM
  [mydataset.table1$__PARTITIONS_SUMMARY__]

Linha de comando

bq query --use_legacy_sql=true '
SELECT
  partition_id,
  FORMAT_UTC_USEC(last_modified_time*1000) AS last_modified
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]'

A saída tem esta aparência:

+--------------+----------------------------+
| partition_id |       last_modified        |
+--------------+----------------------------+
| 20160103     | 2016-08-19 18:49:30.463000 |
| 20160102     | 2016-08-19 18:49:16.179000 |
| 20160101     | 2016-08-19 18:48:58.142000 |
+--------------+----------------------------+

A seguir

Para uma visão geral do suporte a tabelas particionadas no BigQuery, consulte Introdução às tabelas particionadas.
Para saber como criar e usar tabelas particionadas por tempo de ingestão, veja o artigo relacionado.
Para saber como gerenciar e atualizar tabelas particionadas, consulte Como gerenciar tabelas particionadas.
Para mais informações sobre como consultar tabelas particionadas, confira o artigo relacionado.

Limitações

Como criar tabelas particionadas

Permissões exigidas

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

Console

IU clássica

Linha de comando

API

Go

Python

Como criar uma tabela particionada com base em um resultado de consulta

Console

IU clássica

CLI

API

Como criar uma tabela particionada ao carregar dados

API

Go

Python

Como controlar o acesso a tabelas particionadas

Como usar tabelas particionadas

Como conseguir informações sobre tabelas particionadas

Permissões exigidas

Como conseguir informações da tabela particionada

Console

IU clássica

Linha de comando

API

Como listar tabelas particionadas em um conjunto de dados

Permissões exigidas

Como listar tabelas particionadas

Console

IU clássica

CLI

API

Como listar partições em tabelas particionadas

Permissões exigidas

Como listar partições em uma tabela particionada

Console

IU clássica

CLI

API

Como receber metadados de tabelas usando metatabelas

Como conseguir metadados de partição usando metatabelas

Permissões de metatabela da partição

Exemplo de metatabela da partição

Console

IU clássica

Linha de comando

Console

IU clássica

Linha de comando

Console

IU clássica

Linha de comando

A seguir

Enviar comentários sobre…