Como gerenciar tabelas particionadas

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 tempo de expiração da tabela;
  • o prazo de validade da partição;
  • os requisitos de filtro de partição;
  • definição do esquema
  • Rótulos
• Renomear (copiar) uma tabela particionada por tempo.
• Copiar uma tabela particionada por tempo.
• Copiar partições.
• Excluir 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 tempo de expiração da tabela;
• o tempo de expiração 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 seguintes papéis predefinidos do Cloud IAM incluem permissões bigquery.tables.update e bigquery.tables.get:

• bigquery.dataEditor
• bigquery.dataOwner
• 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 usuário com acesso bigquery.dataOwner pode atualizar as propriedades nas tabelas desse 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 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 expiração da partição

É possível especificar a expiração de partição para uma tabela particionada quando a tabela é criada das seguintes formas:

• usando uma instrução DDL ALTER TABLE
• usando o comando bq mk da ferramenta de linha de comando;
• chamando o método tables.insert da API;
• Como usar bibliotecas de cliente.

No momento, não é possível especificar a expiração de partição no Console do Cloud ou na IU da Web clássica do BigQuery.

Ao criar uma tabela, se você especificar uma expiração de partição, ela substituirá a expiração da partição padrão no nível do conjunto de dados. Ao definir uma expiração de partição em nível de tabela, todas as partições estão sujeitas à expiração. Partições individuais não podem ter prazos de validade diferentes.

Depois de criar a tabela, é possível atualizar o prazo de validade da partição dela a qualquer momento. Para isso, basta usar o comando bq update da CLI ou o método tables.patch da API. No momento, não é possível atualizar a expiração de partição no Console do Cloud ou na IU da Web clássica do BigQuery. No entanto, é possível usar uma instrução DDL para atualizar o prazo de validade da partição em qualquer das IUs.

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:

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 atualizar a expiração de partição de uma tabela particionada usando uma declaraçã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 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
    )
    

4. Clique em Run.

CLI

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) das 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 sendo atualizada;
• 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.

IU clássica

Não é possível usar a IU da Web para exigir filtros de partição depois que uma tabela particionada é criada.

CLI

Para atualizar uma tabela particionada para exigir filtros de partição usando a CLI, insira o comando bq update e forneça a sinalização --require_partition_filter.

Para atualizar uma tabela particionada em um projeto diferente do seu projeto padrão, adicione o ID do projeto ao conjunto de dados no seguinte formato: project_id:dataset.

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

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:

• Use o comando bq cp da ferramenta de linha de comando.
• chamando o método de API jobs.insert e configure um job copy;
• Como usar bibliotecas de cliente.

Atualmente, a cópia de partições não é compatível com o Console do Cloud ou com a IU da Web clássica do BigQuery.

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 seguintes papéis predefinidos do Cloud IAM 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 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. 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 os papéis e permissões do Cloud 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.

IU clássica

Não é possível copiar partições pela IU da Web clássica do BigQuery.

CLI

Para copiar uma partição, use o comando bq cp (copiar) da ferramenta de linha de comando com um decorador de partições ($date), 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ã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 como asia-northeast1. Defina um valor padrão para a unidade usando o arquivo .bigqueryr.
• 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 de partição 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:

Observação: o separador de decorador de partição ($) é uma variável especial no shell do unix. Pode ser necessário usar o escape para o decorador ao usar a ferramenta de linha de comando. Os exemplos a seguir inserem um caractere de escape do decorador de partições: mydataset.table\$20160519, 'mydataset.table$20160519'.

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.

IU clássica

No momento, não é possível copiar partições na IU da Web clássica do BigQuery.

CLI

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 rm da ferramenta de linha de comando ou chamando o método tables.delete da API. Ainda não é possível excluir partições pela IU clássica do BigQuery na Web.

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 seguintes papéis predefinidos do Cloud IAM incluem permissões bigquery.tables.delete e bigquery.tables.get:

• 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. Com o acesso bigquery.dataOwner, o usuário consegue excluir tabelas e partições 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 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.

IU clássica

Não é possível excluir partições pela IU clássica do BigQuery na Web.

CLI

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 CLI para remover uma partição, é preciso 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:

Observação: o separador de decorador de partição ($) é uma variável especial no shell do unix. Pode ser necessário usar o escape para o decorador ao usar a ferramenta de linha de comando. Os exemplos a seguir inserem um caractere de escape do decorador de partições: mydataset.table\$20160519, 'mydataset.table$20160519'.

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.