Neste documento, você verá como gerenciar tabelas particionadas no BigQuery. Tanto tabelas particionadas por tempo de ingestão quanto particionadas são gerenciadas da mesma maneira. Execute as seguintes tarefas de gerenciamento:
- Em uma tabela particionada por tempo, atualize:
- Descrição
- o prazo de validade da tabela;
- o prazo de validade da partição;
- os requisitos de filtro de partição;
- a definição do esquema;
- Marcadores
- renomeie (copiar) uma tabela particionada por tempo;
- copie uma tabela particionada por tempo;
- copie partições;
- exclua uma tabela particionada por tempo;
- Excluir partições de uma tabela particionada por tempo.
Para saber mais sobre como criar e usar tabelas particionadas, incluindo informações de tabelas, listagem e controle de acesso aos dados, consulte Como criar e usar tabelas particionadas por tempo de ingestão ou Como criar e usar tabelas particionadas.
Como atualizar propriedades da tabela particionada
Em uma tabela particionada, você pode atualizar:
- a descrição;
- o prazo de validade da tabela;
- o prazo de validade da partição;
- a definição do esquema;
- os rótulos.
Permissões necessárias
Para atualizar uma tabela, é necessário ter pelo menos as permissões bigquery.tables.update
e bigquery.tables.get
. Os papéis predefinidos do IAM a seguir incluem as permissões bigquery.tables.update
e bigquery.tables.get
:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
Além disso, quando um usuário tem permissões bigquery.datasets.create
e cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner
ao conjunto.
O usuário com acesso bigquery.dataOwner
pode atualizar as propriedades nas tabelas desse conjunto de dados.
Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.
Como atualizar a descrição de uma tabela particionada
O processo para atualizar a descrição de uma tabela particionada é igual ao de uma tabela padrão. Para saber mais sobre como adicionar ou alterar a descrição de uma tabela, consulte Como atualizar a descrição de uma tabela.
No momento, não é possível criar descrições para partições individuais.
Como atualizar a expiração da tabela
O processo para atualizar a expiração de uma tabela particionada é igual ao de uma tabela padrão. Para saber mais sobre como adicionar ou alterar a expiração de uma tabela, consulte esta página.
Como atualizar a validade da partição
Ao criar uma tabela particionada por tempo de ingestão ou coluna de data/timestamp, é possível especificar uma expiração de partição. Se especificado, esse valor substitui a validade da partição padrão no nível do conjunto de dados. As tabelas particionadas por variação em números inteiros não são compatíveis com prazos de validade da partição. Para mais informações, consulte Como criar e usar tabelas particionadas por tempo de ingestão e Como criar e usar tabelas particionadas por data e carimbo de data/hora.
A qualquer momento após a criação da tabela, você pode atualizar o prazo de validade da partição da tabela usando o comando bq update
da ferramenta de linha de comando bq
ou o método tables.patch
da API.
No momento, não é possível atualizar a validade da partição no Console do Cloud. No entanto, é possível usar uma instrução DDL para atualizar a expiração da partição no Console do Cloud.
Ao atualizar a validade da partição de uma tabela, a configuração se aplica a todas as partições, independentemente de quando elas foram criadas.
Ao atualizar o prazo de validade da partição de uma tabela, é preciso calcular o prazo de validade da partição a partir da meia-noite UTC da data da partição.
Se a tabela particionada também tiver um prazo de validade de tabela configurado, a tabela e todas as partições nela serão excluídas de acordo com as configurações de validade da tabela. A expiração da tabela tem prioridade sobre a da partição.
Por exemplo, se a expiração de uma tabela particionada for definida para cinco dias, e o tempo de expiração da partição estiver definido para sete dias, a tabela e todas as partições dela serão excluídas após cinco dias.
Para projetos com tabelas particionadas que foram criadas antes de 13 de dezembro de 2016, a expiração da partição se baseia na última data em que a partição foi modificada. Esse comportamento também se aplica a novas tabelas criadas nesses projetos. Para migrar seu projeto para o novo comportamento, abra uma solicitação no Rastreador de problemas do BigQuery.
Para atualizar a validade da partição de uma tabela particionada:
SQL
Com as instruções de linguagem de definição de dados (DDL), é 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 atualizar a expiração de partição de uma tabela particionada usando uma declaração DDL:
Abra a página do BigQuery no Console do Cloud.
Clique em Escrever nova consulta.
Digite a instrução DDL na área de texto do Editor de consultas.
ALTER TABLE mydataset.mytable SET OPTIONS ( -- Sets partition expiration to 5 days partition_expiration_days=5 )
Clique em Executar.
bq
Use o comando bq update
com a sinalização
--time_partitioning_expiration
. Se você estiver atualizando uma tabela particionada em um projeto diferente
do projeto padrão, adicione o ID do projeto ao nome do conjunto de dados
no seguinte formato: project_id:dataset
.
bq update \ --time_partitioning_expiration integer \ project_id:dataset.table
Em que:
- integer é a vida útil padrão (em segundos) para as partições da tabela. Não há valor mínimo. O prazo de validade é avaliado para a data da partição acrescida deste valor. Se você especificar
0
, a expiração da partição será removida e a partição nunca expirará. As partições sem expiração precisam ser excluídas manualmente; - project_id é o ID do projeto;
- dataset é o nome do conjunto de dados que contém a tabela que você está atualizando;
- table é o nome da tabela que você está atualizando.
Exemplos:
Insira o seguinte comando para atualizar o prazo de validade das partições em mydataset.mytable
para 5 dias (432.000 segundos). mydataset
está no
projeto padrão.
bq update --time_partitioning_expiration 432000 mydataset.mytable
Insira o seguinte comando para atualizar o prazo de validade das partições em mydataset.mytable
para 5 dias (432.000 segundos). mydataset
está em
myotherproject
, e não no projeto padrão.
bq update \
--time_partitioning_expiration 432000 \
myotherproject:mydataset.mytable
API
Chame o método tables.patch
e use a propriedade timePartitioning.expirationMs
para atualizar a
expiração da partição em milissegundos. Como o método tables.update
substitui todo o recurso da tabela, é melhor usar o método tables.patch
.
Como atualizar os requisitos do filtro de partição
Ao criar uma tabela particionada, é possível exigir o uso de filtros de predicado. Basta ativar a opção Exigir filtro de partição. Quando essa opção
é usada, as tentativas de consultar a tabela particionada sem especificar uma
cláusula WHERE
produzem o erro a seguir:
Cannot query over table 'project_id.dataset.table' without a
filter that can be used for partition elimination
.
Para mais informações sobre como adicionar a opção Exigir filtro de partição ao criar uma tabela particionada, consulte Como criar tabelas particionadas.
Se você não ativar a opção Exigir filtro de partição ao criar uma tabela particionada, será possível atualizá-la para adicionar a opção.
Como atualizar a opção de exigir filtro de partição
Para atualizar uma tabela particionada de maneira que sejam exigidas consultas que tenham uma cláusula WHERE
que remove partições:
Console
Não é possível usar o Console do Cloud para exigir filtros de partição depois que uma tabela particionada é criada.
bq
Para atualizar uma tabela particionada para exigir filtros de partição usando a ferramenta de linha de comando bq
, digite o comando bq update
e forneça a sinalização --require_partition_filter
.
Para atualizar uma tabela particionada em um projeto que não seja o padrão, adicione o ID do projeto ao conjunto de dados no seguinte formato: project_id:dataset.
Exemplo:
Para atualizar mypartitionedtable
em mydataset
no seu projeto padrão,
insira:
bq update --require_partition_filter mydataset.mytable
Para atualizar mypartitionedtable
em mydataset
em myotherproject
,
insira:
bq update --require_partition_filter myotherproject:mydataset.mytable
API
Chame o método tables.patch
e use a propriedade requirePartitionFilter
para true
para exigir
filtros de partição. Como o método tables.update
substitui todo o recurso da tabela, é melhor usar o método tables.patch
.
Java
Antes de testar essa amostra, siga as instruções de configuração para Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.
Como atualizar a definição do esquema
O processo para atualizar a definição de esquema para uma tabela particionada é igual ao de atualizar a definição de esquema de uma tabela padrão. Para saber mais, consulte Como modificar os esquemas das tabelas.
Como renomear uma tabela particionada
Ainda não é possível alterar o nome de uma tabela particionada. Porém, caso seja preciso, siga as etapas para copiar a tabela. Ao especificar a tabela de destino na operação de cópia, use o novo nome da tabela.
Como copiar tabelas particionadas
Como copiar uma única tabela particionada
O processo para copiar uma tabela particionada é igual ao de uma tabela padrão. Para saber mais, consulte Como copiar uma tabela.
Ao copiar uma tabela particionada, lembre-se destas observações:
Os conjuntos de dados de origem e destino precisam estar no mesmo local.
- Copiar uma tabela particionada para uma nova tabela de destino particionada
- Se você copiar uma tabela particionada por tempo para uma nova tabela, todas as informações de particionamento serão copiadas com ela. Isso significa que essas duas tabelas terão partições idênticas.
- Como copiar uma tabela não particionada para uma tabela particionada
- Se você copiar uma tabela não particionada para uma tabela particionada, o BigQuery copia os dados de origem para a partição que representa a data atual.
- Como copiar uma tabela particionada para outra tabela particionada
- Para copiar uma tabela particionada para outra tabela desse tipo, as especificações de partição delas precisam ser iguais. Especifique se pretende anexar ou substituir a tabela de destino.
- Como copiar uma tabela particionada para uma tabela não particionada
- Se você copiar uma tabela particionada para uma tabela não particionada, a tabela de destino permanecerá não particionada. Os dados serão anexados à tabela ou utilizados para substituir a tabela não particionada, dependendo das suas configurações.
Como copiar várias tabelas particionadas
O processo para copiar várias tabelas particionadas é igual ao de copiar várias tabelas padrão. Para saber mais, consulte Como copiar várias tabelas de origem.
Ao copiar várias tabelas particionadas, lembra-se destas observações:
- Só será possível copiar várias tabelas de origem para uma tabela particionada no mesmo job se elas forem do mesmo tipo.
- Se todas as tabelas de origem forem particionadas, as especificações de partição delas precisarão corresponder à especificação da tabela de destino. Suas configurações determinam se a tabela de destino será anexada ou substituída.
- Os conjuntos de dados de origem e destino precisam estar no mesmo local.
Como copiar partições
Copie uma ou mais partições da seguinte maneira:
- Use o comando
bq cp
da ferramenta de linha de comandobq
. - fazendo uma chamada do método de API jobs.insert e configurando um job
copy
; - Como usar bibliotecas de cliente
Atualmente, não é possível copiar partições pelo Console do Cloud.
Permissões necessárias
Para copiar tabelas e partições, é necessário ter pelo menos as permissões a seguir:
No conjunto de dados de origem:
bigquery.tables.get
bigquery.tables.getData
No conjunto de dados de destino:
bigquery.tables.create
para criar a cópia da tabela ou da partição no conjunto de dados de destino
Os papéis predefinidos do IAM a seguir incluem as permissões bigquery.tables.create
, bigquery.tables.get
e bigquery.tables.getData
:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
Além disso, para executar o job copy, é necessário ter permissões bigquery.jobs.create
.
Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.jobs.create
:
bigquery.user
bigquery.jobUser
bigquery.admin
Além disso, quando um usuário tem permissões bigquery.datasets.create
e cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner
ao conjunto.
Com o acesso de bigquery.dataOwner
, o usuário consegue copiar tabelas e partições no conjunto de dados. No entanto, se o usuário não for o criador do conjunto de dados de destino, precisará receber acesso a ele.
Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.
Como copiar uma única partição
Console
Não é possível copiar partições pelo Console do Cloud.
bq
Para copiar uma partição, use o comando bq
(copiar) da ferramenta de linha de comando bq cp
com um decorador de partições ($date
copiar), como $20160201
.
É possível usar sinalizações opcionais para controlar a disposição de gravação da partição de destino:
-a
ou--append_table
anexa os dados da partição de origem para uma tabela ou partição atual no conjunto de dados de destino.-f
ou--force
substitui uma tabela ou partição atual no conjunto de dados de destino e não solicita confirmação.-n
ou--no_clobber
retorna a seguinte mensagem de erro se a tabela ou a partição existir no conjunto de dados de destino:Table '<var>project_id:dataset.table</var> or <var>table$date</var>' already exists, skipping.
Se-n
não é especificado, o comportamento padrão é solicitar que o usuário escolha se quer substituir a tabela ou a partição de destino.--destination_kms_key
é a chave do Cloud KMS gerenciada pelo cliente que é usada para criptografar a tabela ou partição de destino.
O comando cp
não aceita sinalizações --time_partitioning_field
ou
--time_partitioning_type
. Não é possível usar um job de cópia para converter uma tabela particionada por tempo de ingestão em uma tabela particionada.
--destination_kms_key
não é demonstrado aqui. Para saber mais, consulte Como proteger dados com chaves Cloud KMS.
Se o conjunto de dados de origem ou de destino estiver em um projeto diferente do padrão, adicione o ID do projeto aos nomes dos conjuntos de dados no seguinte formato: project_id:dataset
.
Opcional: forneça a sinalização --location
e defina o valor do
local.
bq --location=location cp \ -a -f -n \ project_id:dataset.source_table$source_partition \ project_id:dataset.destination_table$destination_partition
Em que:
- location é o nome do local. A sinalização
--location
é opcional. Por exemplo, se estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização comoasia-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 de origem ou de destino;
- source_table é a tabela que você está copiando;
- source_partition é o decorador da partição de origem;
- destination_table é o nome da tabela no conjunto de dados de destino;
- destination_partition é o decorador da partição de destino.
Exemplos:
Como copiar uma partição para uma nova tabela
Insira o seguinte comando para copiar a partição de 30 de janeiro de 2018
de mydataset.mytable
para uma nova tabela - mydataset.mytable2
. mydataset
está em seu projeto padrão.
bq cp -a 'mydataset.mytable$20180130' mydataset.mytable2
Como copiar uma partição para uma tabela não particionada
Insira o seguinte comando para copiar a partição de 30 de janeiro de 2018
de mydataset.mytable
para uma tabela não particionada -
mydataset2.mytable2
. O atalho -a
é usado para anexar dados da partição à tabela
de destino não particionada. Os dois conjuntos de dados estão no projeto padrão.
bq cp -a 'mydataset.mytable$20180130' mydataset2.mytable2
Insira o seguinte comando para copiar a partição de 30 de janeiro de 2018
de mydataset.mytable
para uma tabela não particionada -
mydataset2.mytable2
. O atalho -f
é usado para substituir a
tabela de destino não particionada sem enviar solicitação.
bq --location=US cp -f 'mydataset.mytable$20180130' mydataset2.mytable2
Como copiar uma partição para outra tabela particionada
Insira o seguinte comando para copiar a partição de 30 de janeiro de 2018
de mydataset.mytable
para outra tabela particionada -
mydataset2.mytable2
. O atalho -a
é usado para anexar os dados da
partição à tabela de destino. Como não é especificado nenhum decorador de partição na tabela de destino, a chave da partição de origem é mantida e os dados são copiados para a partição de 30 de janeiro de 2018 na tabela de destino. Também é possível
especificar um decorador de partições na tabela de destino para copiar
dados para uma partição específica. mydataset
está no projeto padrão. mydataset2
está em myotherproject
, e não no projeto padrão.
bq --location=US cp \
-a \
'mydataset.mytable$20180130' \
myotherproject:mydataset2.mytable2
Insira o seguinte comando para copiar a partição de 30 de janeiro de 2018
de mydataset.mytable
para a partição de 20 de fevereiro de 2018 de outra
tabela particionada - mydataset2.mytable2
. O atalho -f
é usado para substituir a partição de 20 de fevereiro de 2018 na tabela de destino sem solicitar. Se nenhum decorador de partições for usado,
todos os dados na tabela de destino serão sobrescritos. mydataset
está no projeto padrão.
mydataset2
está em myotherproject
, e não no projeto padrão.
bq cp \
-f \
'mydataset.mytable$20180130' \
'myotherproject:mydataset2.mytable2$20180220'
Insira o seguinte comando para copiar a partição de 30 de janeiro de 2018
de mydataset.mytable
para outra tabela particionada -
mydataset2.mytable2
. mydataset
está no projeto padrão. mydataset2
está em myotherproject
, e não no projeto padrão. Se houver dados na tabela de destino, o comportamento padrão é solicitar que você sobrescreva.
bq cp \
'mydataset.mytable$20180130' \
myotherproject:mydataset2.mytable2
API
Chame o método jobs.insert
e configure um job copy
. (Opcional) Especifique sua região na property
location
da seção jobReference
do
recurso do job.
Na configuração do job, especifique as propriedades a seguir:
- Insira o conjunto de dados, a tabela e a partição de origem na propriedade
sourceTables
. - Insira o conjunto de dados e a tabela de destino na propriedade
destinationTable
. - Use a propriedade
writeDisposition
para especificar se pretende anexar ou substituir a tabela ou a partição de destino.
Como copiar várias partições
Para copiar várias partições:
Console
Atualmente, não é possível copiar partições pelo Console do Cloud.
bq
O processo de copiar várias partições é igual ao de copiar uma única partição, mas você especifica várias partições de origem como uma lista separada por vírgulas:
bq cp \ 'mydataset.mytable$20180130,mydataset.mytable$20180131' \ myotherproject:mydataset.mytable2
API
Chame o método jobs.insert
e configure um job copy
. Especifique sua região na property
location
da seção jobReference
do
recurso do job.
Na configuração do job, especifique as propriedades a seguir:
- Insira várias partições de origem na propriedade
sourceTables
, incluindo os nomes do conjunto de dados e da tabela. - Insira o conjunto de dados e a tabela de destino na propriedade
destinationTable
. - Use a propriedade
writeDisposition
para especificar se pretende anexar ou substituir a tabela ou a partição de destino.
Como excluir uma tabela particionada
O processo para excluir uma tabela particionada por tempo e todas as partições nela é igual ao de uma tabela padrão. Para saber mais sobre como excluir uma tabela, consulte Como excluir tabelas.
Como excluir partições em tabelas particionadas
É possível excluir partições em tabelas particionadas usando o comando bq
da ferramenta de linha de comando bq rm
ou chamando o método tables.delete
da API.
Use o decorador de partição para excluir uma partição específica. Por exemplo,
a partição de 1º de março de 2016 ($20160301
) em uma tabela particionada
denominada mydataset.mytable
pode ser excluída usando o comando:
bq rm 'mydataset.mytable$20160301'
Para recuperar uma lista das partições em uma tabela particionada, consulte Como listar partições em tabelas particionadas por tempo de ingestão ou Como listar partições em tabelas particionadas.
No momento, só é possível excluir uma partição por vez.
Permissões necessárias
Para excluir uma partição, você precisa ter pelo menos as permissões bigquery.tables.delete
e bigquery.tables.get
. Os papéis predefinidos do IAM a seguir incluem as permissões bigquery.tables.delete
e bigquery.tables.get
:
bigquery.dataOwner
bigquery.dataEditor
bigquery.admin
Além disso, quando um usuário tem permissões bigquery.datasets.create
e cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner
ao conjunto.
Com o acesso bigquery.dataOwner
, o usuário consegue excluir tabelas e
partições no conjunto de dados.
Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.
Como excluir uma partição em uma tabela particionada
Para excluir uma partição, especifique o decorador da partição, a menos que
seja uma das duas
partições especiais.
Atualmente, não é possível excluir as partições __NULL__
ou __UNPARTITIONED__
.
Para excluir uma partição em uma tabela particionada:
Console
Não é possível excluir partições com o Console do Cloud.
bq
Use o comando bq rm
com a sinalização --table
(ou o atalho -t
) e consulte o decorador de partições ($date
) para excluir uma partição específica em uma tabela particionada. Quando você usa a ferramenta de linha de comando bq
para remover uma partição, é necessário confirmar a ação. É possível usar a sinalização --force
(ou atalho -f
) para pular a confirmação.
Se a tabela particionada estiver em um conjunto de dados em um projeto
diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados
no formato a seguir: project_id:dataset
.
bq rm -f -t project_id:dataset.table$date
Em que:
- project_id é o ID do projeto;
- dataset é o nome do conjunto de dados que contém a tabela;
- table é o nome da tabela.
- $date é o decorador da partição que você está excluindo.
Exemplos:
Insira o seguinte comando para excluir a partição de 1º de março de 2016
($20160301
) em uma tabela particionada denominada mydataset.mytable
. mydataset
está em seu projeto padrão.
bq rm 'mydataset.mytable$20160301'
Insira o seguinte comando para excluir a partição para 1º de janeiro de 2017
($20170101
) em uma tabela particionada denominada mydataset.mytable
. mydataset
está em myotherproject
, e não no projeto padrão.
bq rm 'myotherproject:mydataset.mytable$20170101'
Insira o seguinte comando para excluir a partição para 18 de janeiro de 2018
($20180118
) em uma tabela particionada denominada mydataset.mytable
. mydataset
está em myotherproject
, e não no projeto padrão. O atalho -f
é usado
para ignorar a confirmação.
bq rm -f 'myotherproject:mydataset.mytable$20180118'
API
Chame o método tables.delete
e especifique o decorador de tabelas e partições usando o parâmetro
tableId
.