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

1. Abra a página do BigQuery no Console do Cloud.

   Acesse a página do BigQuery

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

Ver no GitHub Feedback

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;

// Sample to update require partition filter on a table.
public class UpdateTableRequirePartitionFilter {

  public static void runUpdateTableRequirePartitionFilter() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    updateTableRequirePartitionFilter(datasetName, tableName);
  }

  public static void updateTableRequirePartitionFilter(String datasetName, String tableName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      Table table = bigquery.getTable(datasetName, tableName);
      table.toBuilder().setRequirePartitionFilter(true).build().update();

      System.out.println("Table require partition filter updated successfully");
    } catch (BigQueryException e) {
      System.out.println("Table require partition filter was not updated \n" + e.toString());
    }
  }
}

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 comando bq.
• 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 ($datecopiar), 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 como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
• project_id é o ID do projeto;
• dataset é o nome do conjunto de dados 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:

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.

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:

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.