VACUUM

Aplica-se a: SQL do Databricks Databricks Runtime

Remova arquivos não utilizados de um diretório de tabela.

Observação

Esse comando funciona de forma diferente dependendo se você está trabalhando em uma tabela Delta, Apache Spark ou Apache Iceberg.

Executar vácuo em uma tabela Delta

Faz limpeza recursiva nos diretórios associados à tabela Delta. Para obter detalhes e limitações completos, consulte Remover arquivos de dados não utilizados com vácuo.

VACUUM remove todos os arquivos do diretório de tabela que não são gerenciados pela Delta, bem como arquivos de dados que não estão mais no estado mais recente do log de transações da tabela e são mais antigos que um limite de retenção. VACUUM ignorará todos os diretórios que começam com sublinhado (_), o que inclui o _delta_log. Particionar sua tabela em uma coluna que começa com um sublinhado é uma exceção a essa regra; VACUUM verifica todas as partições válidas incluídas na tabela Delta de destino. Os arquivos de dados da tabela Delta são excluídos com base no momento em que foram removidos logicamente do log de transações da Delta, somado às horas de retenção, e não nos carimbos de data/hora de modificação no sistema de armazenamento. O limite padrão é sete dias.

Se você executar VACUUM em uma tabela Delta, perderá a capacidade de voltar para uma versão anterior ao período de retenção de dados especificado.

Se a otimização preditiva estiver habilitada, o Azure Databricks disparará automaticamente a VACUUM operação como parte de seu processo de otimização. Não é necessário executar VACUUM manualmente na maioria dos casos.

Aviso

É recomendável que você defina um intervalo de retenção de pelo menos 7 dias, porque instantâneos antigos e arquivos não confirmados ainda podem estar em uso por leitores ou gravadores simultâneos. Se VACUUM limpa arquivos ativos, os leitores simultâneos podem experimentar falhas ou, pior, as tabelas podem ser corrompidas quando VACUUM exclui arquivos que ainda não foram confirmados. Você deve escolher um intervalo maior do que a transação simultânea em execução mais longa, e o período mais longo que os fluxos de dados podem ficar atrasados em relação à atualização mais recente da tabela.

O Delta Lake tem uma verificação de segurança para impedir que você execute um comando perigoso VACUUM. No Databricks Runtime, se você tiver certeza de que nenhuma operação em execução nessa tabela demorará mais do que o intervalo de retenção que você planeja especificar, desative essa verificação de segurança definindo a propriedade spark.databricks.delta.retentionDurationCheck.enabled da configuração do Spark como false.

Compactar uma tabela do Apache Iceberg

Remove recursivamente arquivos não referenciados dos diretórios associados à tabela Apache Iceberg.

• Somente VACUUM sem uma cláusula RETAIN é permitido para tabelas Iceberg.
• O período de retenção é fixado em 7 dias.

Se a otimização preditiva estiver habilitada, o Azure Databricks disparará automaticamente a VACUUM operação como parte de seu processo de otimização. Você não precisa executar VACUUM manualmente na maioria dos casos.

Sintaxe

VACUUM table_name { { FULL | LITE } |  RETAIN num HOURS | DRY RUN } [...]

Nas versões 16.0 e anteriores do Databricks Runtime, RETAIN num HOURS deve preceder DRY RUN na sintaxe.

Parâmetros

• table_name

  Identifica uma tabela do Delta existente. O nome não deve incluir uma especificação temporal ou uma especificação de opções.

• RETAIN num HOURS

  O limite de retenção. Se o período de retenção especificado exceder delta.deletedFileRetentionDuration, o período de retenção da tabela será usado.

• DRY RUN

  Retorna uma lista de até 1.000 arquivos a serem excluídos.

• FULL ou LITE

  Aplica-se ao: Databricks SQL Databricks Runtime 16.1 e versões posteriores

  FULL executa a operação de compactação no modo Completo. Isso exclui arquivos de dados fora da duração da retenção e todos os arquivos no diretório de tabela não referenciados pela tabela.

  LITE executa a operação de compactação no modo Lite. Em vez de localizar todos os arquivos no diretório da tabela, VACUUM usa o log de transações Delta para identificar e remover arquivos não mais referenciados por nenhuma versão de tabela dentro da duração da retenção. Se VACUUM LITE não puder concluir porque o log da Delta foi removido, uma exceção DELTA_CANNOT_VACUUM_LITE será gerada.

  O padrão é FULL.

Importante

A janela de retenção do comando VACUUM é determinada pela propriedade da tabela delta.deletedFileRetentionDuration, que tem como padrão 7 dias. Isso significa que VACUUM remove os arquivos de dados que não são mais referenciados por uma versão da tabela Delta nos últimos 7 dias. Para reter dados por um período mais longo, como dar suporte a viagens de tempo por durações mais longas, defina essa propriedade de tabela como um valor mais alto. O exemplo a seguir mostra a configuração desse limite como 30 dias:

ALTER TABLE table_name SET TBLPROPERTIES ('delta.deletedFileRetentionDuration' = '30 days');

Compactar outras tabelas

Executa limpeza recursiva de diretórios associados a tabelas que não são Delta nem Iceberg, removendo arquivos não confirmados que ultrapassem o limite de retenção. O limite padrão é sete dias.

Nessas tabelas, o Azure Databricks dispara automaticamente operações VACUUM na medida em que os dados são gravados.

Sintaxe

VACUUM table_name [RETAIN num HOURS]

Parâmetros

• table_name

  Identifica uma tabela existente por nome ou caminho.

• RETAIN num HOURS

  O limite de retenção.