Como gerenciar tabelas particionadas

Neste documento, você aprende como gerenciar tabelas particionadas no BigQuery. Tanto tabelas particionadas por tempo de ingestão quanto particionadas são gerenciadas da mesma maneira. Você pode executar as seguintes tarefas de gerenciamento:

Para saber mais sobre como criar e usar tabelas particionadas, incluindo como receber informações da tabela, listar tabelas e controlar o acesso a dados da tabela, 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

Você pode atualizar uma tabela particionada quanto a:

Permissões obrigatórias

Para atualizar as propriedades da tabela, é necessário ter acesso WRITER no nível do conjunto de dados ou um papel de IAM para envolvidos no projeto que inclua as permissões bigquery.tables.update exigidas. Os seguintes papéis do IAM predefinidos para envolvidos no projeto incluem permissões bigquery.tables.update:

Além disso, como o papel bigquery.user tem permissões bigquery.datasets.create, um usuário atribuído ao papel bigquery.user pode atualizar qualquer tabela criada por ele no conjunto de dados. Quando um usuário com papel bigquery.user cria um conjunto de dados, ele recebe acesso OWNER ao conjunto de dados. O acesso OWNER concede ao usuário o controle total sobre o conjunto de dados e de todas as tabelas e visualizações nele.

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

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

Ao criar uma tabela particionada, especifique a validade das partições usando a ferramenta de linha de comando bq mk ou chamando o método tables.insert da API. No momento, não é possível especificar a expiração de partição no Console do GCP 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, a atualização do prazo de validade da partição não tem suporte no Console do GCP nem 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 é baseada 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:

Console

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

  2. Clique em Escrever nova consulta.

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

     #standardSQL
 ALTER TABLE mydataset.mytable
 SET OPTIONS (
   -- Sets partition expiration to 5 days
   partition_expiration_days=5
 )

IU clássica

  1. Acesse a IU da Web do BigQuery.

    Acessar a IU da Web do BigQuery

  2. Clique em Escrever consulta.

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

     #standardSQL
 ALTER TABLE mydataset.mytable
 SET OPTIONS (
   -- Sets partition expiration to 5 days
   partition_expiration_days=5
 )

Linha de comando

Emita o comando bq update com o sinalizador --time_partitioning_expiration. Se você estiver atualizando uma tabela particionada em um projeto diferente do projeto padrão, adicione o código 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 ou um número negativo, a validade da partição será removida e a partição nunca expirará. As partições sem data de validade precisam ser excluídas manualmente;
  • [PROJECT_ID] é o código 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 comando a seguir para atualizar o tempo de expiração das partições no mydataset.mytable para cinco dias (432.000 segundos). mydataset está no projeto padrão.

bq update --time_partitioning_expiration 432000 mydataset.mytable

Insira o comando a seguir para atualizar o tempo de expiração das partições no mydataset.mytable para cinco dias (432.000 segundos). mydataset está em myotherproject, 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 validade da partição em milissegundos. Como tables.update substitui todo o recurso da tabela, recomendamos usar o 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 existente. 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.
  • Copiar uma tabela não particionada para uma tabela particionada
    Se você copiar uma tabela não particionada para uma tabela particionada, os dados de origem serão copiados para a partição que representa a data atual no BigQuery.
  • 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. Você pode especificar se pretende anexar ou substituir a tabela de destino.
  • 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:

  • usando manualmente o comando bq cp da ferramenta de linha de comando;
  • chamando o método jobs.insert da API e configurando um job de cópia.

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

Permissões obrigatórias

No nível do conjunto de dados, para copiar partições, é necessário ter acesso de READER ao conjunto de dados de origem que contém as partições a serem copiadas, além do acesso de WRITER ao conjunto de dados de destino.

Em vez de usar permissões no nível do conjunto de dados, é possível utilizar um papel do IAM para envolvidos no projeto que inclua permissões bigquery.tables.create e bigquery.tables.getData. As permissões bigquery.tables.create serão obrigatórias para criar a cópia da partição no conjunto de dados de destino se a tabela de destino for nova. Já as permissões bigquery.tables.getData são obrigatórias para ler os dados nas partições copiadas.

Os seguintes papéis de IAM predefinidos no nível do projeto incluem permissões bigquery.tables.create e bigquery.tables.getData para cada conjunto de dados no projeto:

Você também precisa ter permissões bigquery.jobs.create para executar jobs de cópia. Os seguintes papéis de IAM predefinidos no nível do projeto incluem permissões bigquery.jobs.create:

Além disso, como o papel bigquery.user tem permissões bigquery.datasets.create, um usuário atribuído ao papel bigquery.user pode ler ou copiar os dados em qualquer tabela ou partição criada por ele. Quando um usuário com papel bigquery.user cria um conjunto de dados, ele recebe acesso OWNER ao conjunto de dados. O acesso OWNER a um conjunto de dados dá ao usuário controle total sobre o conjunto e todas as tabelas e partições 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 copiar uma única partição

Console

Não é possível copiar partições pelo Console do GCP.

IU clássica

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

Linha de comando

Para copiar uma partição, use o comando bq cp (copiar) da ferramenta de linha de comando com um decorador de partição ($[DATE]), como $20160201.

Sinalizações opcionais podem ser usadas 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 a 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 retornará a mensagem de erro a seguir se a tabela ou partição existir no conjunto de dados de destino: Table '[PROJECT_ID]:[DATASET].[TABLE] or [TABLE]$[DATE]' already exists, skipping. Se -n não for especificado, o comportamento padrão será solicitar que você escolha entre substituir a tabela ou a partição de destino.
  • --destination_kms_key é a chave do Cloud KMS gerenciada pelo cliente 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 será 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 projeto padrão, adicione o código do projeto aos nomes dos conjuntos de dados no formato a seguir: [PROJECT_ID]:[DATASET].

Forneça a sinalização --location e defina o valor como o 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 você estiver usando o BigQuery na região de Tóquio, poderá definir 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 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:

Como copiar uma partição para uma nova tabela

Digite o comando a seguir para copiar a partição de 30 de janeiro de 2018 de mydataset.mytable para uma nova tabela, mydataset.mytable2. mydataset está no seu projeto padrão. mydataset foi criado no local multirregional US.

bq --location=US cp -a 'mydataset.mytable$20180130' mydataset.mytable2

Como copiar uma partição para uma tabela não particionada

Digite o comando a seguir 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 seu projeto padrão. Os dois conjuntos de dados foram criados na região asia-northeast1.

bq --location=asia-northeast1 cp -a 'mydataset.mytable$20180130' mydataset2.mytable2

Digite o comando a seguir 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. Os dois conjuntos de dados estão em seu projeto padrão e foram criados no local multirregional US.

bq --location=US cp -f 'mydataset.mytable$20180130' mydataset2.mytable2

Como copiar uma partição para outra tabela particionada

Insira o comando a seguir 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 nenhum decorador de partição é especificado 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. Você também pode especificar um decorador de partição na tabela de destino para copiar dados para uma partição específica. mydataset está no projeto padrão. mydataset2 está em myotherproject, não no projeto padrão. Os dois conjuntos de dados foram criados no local multirregional US.

bq --location=US cp -a 'mydataset.mytable$20180130' myotherproject:mydataset2.mytable2

Insira o comando a seguir para copiar a partição de 30 de janeiro de 2018 de mydataset.mytable para a 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 aviso. Se nenhum decorador de partição for usado, todos os dados na tabela de destino serão substituídos. mydataset está no projeto padrão. mydataset2 está em myotherproject, não no projeto padrão. Os dois conjuntos de dados foram criados no local multirregional US.

bq --location=US cp -f 'mydataset.mytable$20180130' 'myotherproject:mydataset2.mytable2$20180220'

Insira o comando a seguir 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, não no projeto padrão. Se houver dados na tabela de destino, o comportamento padrão será perguntar se você quer substituir. Os dois conjuntos de dados foram criados na região asia-northeast1.

bq --location=asia-northeast1 cp 'mydataset.mytable$20180130' myotherproject:mydataset2.mytable2

API

Chame o método jobs.insert e configure um job de cópia. Especifique a região na propriedade location da seção jobReference do recurso do job.

Especifique as propriedades a seguir na configuração do job:

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

IU clássica

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

Linha de comando

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 --location=[LOCATION] cp 'mydataset.mytable$20180130,mydataset.mytable$20180131' myotherproject:mydataset.mytable2

API

Chame o método jobs.insert e configure um job de cópia. Especifique a região na propriedade location da seção jobReference do recurso do job.

Especifique as propriedades a seguir na configuração do job:

  • 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

Para excluir partições em tabelas particionadas, use o comando bq rm da ferramenta de linha de comando ou chame o método tables.delete da API. Ainda não é possível excluir partições pela IU da web clássica do BigQuery.

É possível usar 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 chamada 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 obrigatórias

Para excluir uma partição, é preciso ter acesso de OWNER no nível do conjunto de dados ou um papel do IAM para envolvidos no projeto que inclua permissões bigquery.tables.delete. Os papéis predefinidos do IAM para envolvidos no projeto a seguir incluem permissões bigquery.tables.delete:

Os usuários com função predefinida no nível do projeto podem excluir partições em qualquer tabela particionada no projeto. Os usuários com permissões OWNER no nível do conjunto de dados podem excluir partições nas tabelas apenas nesse conjunto de dados.

Além disso, como o papel bigquery.user tem permissões bigquery.datasets.create, um usuário com a função bigquery.user pode excluir tabelas e partições em qualquer conjunto de dados criado por ele. Quando um usuário com papel bigquery.user cria um conjunto de dados, ele recebe acesso OWNER ao conjunto de dados. O acesso OWNER a um conjunto de dados fornece ao usuário controle total sobre o conjunto de dados, todas as tabelas nele e todas as partições da tabela.

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

IU clássica

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

CLI

Use o comando bq rm com o sinalizador --table (ou atalho -t) e faça referência ao decorador de partição ($[DATE]) para excluir uma partição específica em uma tabela particionada. Quando você usa a CLI para remover uma partição, é necessário confirmar a ação. É possível usar o indicador --force (ou atalho -f) para ignorar a confirmação.

Se a tabela particionada estiver em um conjunto de dados em um projeto diferente do projeto padrão, adicione o código do projeto ao nome do conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

bq rm -f -t [PROJECT_ID]:[DATASET].[TABLE]$[DATE]

Em que:

  • [PROJECT_ID] é o código 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:

Digite o comando a seguir para excluir a partição de 1 de março de 2016 ($20160301) em uma tabela particionada chamada mydataset.mytable. mydataset está no seu projeto padrão.

bq rm 'mydataset.mytable$20160301'

Digite o comando a seguir para excluir a partição de 1 de janeiro de 2017 ($20170101) em uma tabela particionada chamada mydataset.mytable. mydataset está em myotherproject, não no seu projeto padrão.

bq rm 'myotherproject:mydataset.mytable$20170101'

Digite o comando a seguir para excluir a partição de 18 de janeiro de 2018 ($20180118) em uma tabela particionada chamada mydataset.mytable. mydataset está em myotherproject, não no seu 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 a tabela e o decorador de partição usando o parâmetro tableId.

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

Enviar comentários sobre…

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