Pular para o conteúdo principal
Última atualização em

Exclusão automática de linhas com tempo de vida automático

Auto time-to-live (Auto-TTL) exclui automaticamente linhas de tabelas gerenciadas do Unity Catalog após um período configurável com base no valor em uma coluna de carimbo de data/hora. Um período de expiração é definido em dias e uma coluna de timestamp é especificada para comparação. Databricks executa as operações DELETE, PURGE e VACUUM em segundo plano para remover linhas expiradas e limpá-las do armazenamento.

A seguir, dois exemplos de como utilizar o tempo de vida automático:

  • Para manter os custos de armazenamento baixos, pode ser útil remover dados com mais de 1 ano. Para expirar as linhas 1 ano após a criação, especifique um período de expiração de 365 dias em uma coluna de registro de data/hora created_at.
  • Você pode querer remover dados que foram marcados para exclusão por outro processo de negócios. Para que as linhas expirem 20 dias após o processamento de uma solicitação de exclusão, especifique um período de expiração de 20 dias em uma coluna de timestamp personalizada del_request_approved.
importante

O momento exato da exclusão não é garantido e pode variar de acordo com a carga do sistema. Para verificar a exclusão, consulte a tabela do sistema de otimização preditiva ou execute DESCRIBE HISTORY na tabela. Consulte tabelas do sistema.

O tempo de buffer entre a expiração da linha e a exclusão permanente pode ser de até 6 dias mais o valor da propriedade da tabela de retenção de dados, que, por padrão, é de 7 dias. Para obter informações sobre como configurar o tempo de vida automático para exclusão dentro de um período específico, consulte Calcular valores de configuração para um período de expiração de destino e Configurar a retenção de dados para consultas de viagem do tempo.

O tempo de vida automático está disponível para tabelas Delta Lake gerenciadas pelo Unity Catalog, tabelas Apache Iceberg e tabelas de transmissão com os pipelines declarativos Spark do LakeFlow.

Requisitos​

  • Você deve ativar a otimização preditiva. Consulte Otimização preditiva para tabelas gerenciadas do Unity Catalog.

    • Desativar a otimização preditiva em uma tabela com o tempo de vida automático ativado impede a execução do tempo de vida automático.

  • Você deve ter permissão para MODIFY em uma tabela para definir ou excluir uma política de tempo de vida automático. Consulte Permissões básicas da tabela.

  • Databricks Runtime 17.3 e acima.

    • O Databricks Runtime 17.2 e abaixo podem ler e gravar em tabelas com tempo de vida automático.

Ativar o tempo de vida automático​

Ativar o tempo de vida automático diferentemente dependendo da tabela de origem:

Tabelas gerenciadas do Delta Lake e do Apache Iceberg​

Para definir uma política automática de tempo de vida em uma nova tabela, especifique um número inteiro não negativo para <expiration_days> e uma coluna com um tipo de DATE, TIMESTAMP ou TIMESTAMP_NTZ para <time_column_name>:

SQL
CREATE TABLE table_name DELETE ROWS <expiration_days> DAYS AFTER <time_column_name>;

Para definir uma política de tempo de vida automático em uma tabela existente:

SQL
ALTER TABLE table_name DELETE ROWS <expiration_days> DAYS AFTER <time_column_name>;

Por exemplo, para excluir linhas 30 dias após seu carimbo de data/hora de created_at:

SQL
ALTER TABLE my_catalog.my_schema.my_table DELETE ROWS 30 DAYS AFTER created_at;

Tabelas de transmissão com Pipelines Declarativos do LakeFlow Spark​

Para definir uma política de tempo de vida automático em uma nova tabela de transmissão em um pipeline Lakeflow Spark Declarative Pipelines, especifique um inteiro não negativo para <expiration_days> e uma coluna com um tipo de DATE, TIMESTAMP ou TIMESTAMP_NTZ para <time_column_name>:

SQL
CREATE STREAMING TABLE table_name
DELETE ROWS <expiration_days> DAYS AFTER <time_column_name>
AS SELECT * FROM STREAM(source);

A alteração de uma tabela de transmissão para usar o tempo de vida automático usando SQL não é compatível. Para alterar o tempo de vida automático em uma tabela de transmissão existente, atualizar o código do pipeline e republicar.

Leituras de transmissão de tabelas com tempo de vida automático​

Se usar Transmissão estructurada, Pipelines Declarativos do LakeFlow Spark ou tabelas de transmissão para ler de uma tabela com tempo de vida automático habilitado, defina skipChangeCommits na leitura de transmissão. As operações de exclusão automática de tempo de vida aparecem como alterações de dados. Sem essa configuração, a leitura de transmissão falha quando o tempo de vida automático exclui linhas.

Veja os exemplos a seguir:

Python
# Source table with auto time-to-live
spark.sql("ALTER TABLE source_table DELETE ROWS <expiration_days> DAYS AFTER <time_column_name>")

# Structured Streaming read
spark.readStream.format("delta").option("skipChangeCommits", "true").table("source_table")

Verificar se o tempo de vida automático está ativado​

Use DESCRIBE TABLE EXTENDED para confirmar que o tempo de vida automático está configurado. Se as propriedades autottl.expireInDays e autottl.timestampColumn estiverem definidas, o tempo de vida automático será ativado.

As configurações de tempo de vida automático aparecem na linha **Propriedades da Tabela**:

SQL
DESCRIBE TABLE EXTENDED table_name;

Alternativamente, use SHOW TBLPROPERTIES para ver as propriedades de tempo de vida automático:

SQL
SHOW TBLPROPERTIES table_name;

Desative a expiração automática​

Para excluir uma política de tempo de vida automático de uma tabela Delta Lake ou Apache Iceberg gerenciada:

SQL
ALTER TABLE table_name DROP ROW DELETION;

Para excluir uma política de tempo de vida automático em uma tabela de transmissão, defina auto_ttl como None no código do pipeline e republique:

Python
from pyspark import pipelines as dp

@dp.table(
  auto_ttl=None
)
def function_name():
  return (query)

Ciclo de vida dos dados​

O tempo de vida automático pode auxiliar a automatizar o gerenciamento do ciclo de vida dos dados para tabelas com requisitos de retenção baseados em tempo.

O tempo de vida automático tem um ciclo de vida de dados em várias fases. Após uma linha expirar, a otimização preditiva executa a execução assincronamente os comandos DELETE e VACUUM. Se os vetores de exclusão estiverem ativados na tabela, a otimização preditiva também executa PURGE antes de VACUUM para reescrever os arquivos de dados e remover as linhas excluídas. Consulte Limpar exclusões somente de metadados para forçar a reescrita de dados.

O momento exato da exclusão não é garantido e pode variar de acordo com a carga do sistema. Para obter informações sobre como verificar se os dados foram excluídos, consulte Tabelas do sistema.

Para configurar o tempo de vida automático corretamente para seus requisitos de retenção de dados, revise as etapas abaixo:

Etapa

Duração

Descrição

Período de expiração

O usuário define ao ativar o tempo de vida automático.

O número de dias após o valor da coluna de tempo quando uma linha se torna elegível para exclusão. Defina esta opção ao ativar o tempo de vida automático.

Tempo de buffer

Até 3 dias por comando (DELETE, VACUUM)

O atraso entre o momento em que as linhas se tornam elegíveis para exclusão e o momento em que a otimização preditiva as exclui. Podem ocorrer atrasos entre a expiração da linha e cada comando assíncrono, DELETE e VACUUM. Cada atraso geralmente é de menos de 3 dias, até um total de 6 dias.

Duração da retenção de dados

O usuário define com uma propriedade da tabela.

O período de tempo em que as linhas excluídas permanecem no armazenamento e acessíveis por viagem do tempo. Para tabelas Delta Lake, configure com delta.deletedFileRetentionDuration. Para tabelas Apache Iceberg, configure com iceberg.deletedFileRetentionDuration. Se a propriedade não for definida, o default é 7 dias. Consulte Configure a retenção de dados para consultas de viagem do tempo.

Após a exclusão permanente via VACUUM, as linhas excluídas não são mais acessíveis através da viagem do tempo. Consulte Remover arquivos de dados não utilizados com vacuum.

Aqui está uma linha do tempo visual do ciclo de vida dos dados, onde uma linha gravada no horário t passa por quatro fases antes que seus arquivos sejam fisicamente removidos por VACUUM:

Diagrama do ciclo de vida de dados com tempo de vida automático, mostrando o período de expiração, o tempo de buffer, o período de retenção de dados e as fases de exclusão permanente ao longo de uma linha do tempo diária.

Calcular valores de configuração para um período de expiração de destino​

importante

O tempo de vida automático exclui dados assincronamente. Consulte ciclo de vida dos dados.

Para configurar a otimização preditiva para remover linhas do armazenamento dentro de um número alvo de dias, subtraia o tempo máximo de buffer (6 dias) e a duração de retenção do arquivo excluído do seu alvo:

Text
target_expiration_days = target_days - 6 - deletedFileRetentionDuration

Por exemplo, para remover linhas dentro de 30 dias com o período de retenção default de 7 dias, defina expiration_days para 17 DAYS:

Text
target_expiration_days = 30 - 6 - 7 = 17 days

Para remover linhas dentro de 90 dias com um período de retenção de 30 dias, defina expiration_days para 54 DAYS:

Text
target_expiration_days = 90 - 6 - 30 = 54 days

Monitore auto time-to-live​

Com as tabelas do sistema, você pode verificar eventos de expiração automática, monitorar custos e definir alertas para falhas.

Tabelas do sistema​

Verifique os eventos automáticos de tempo de vida com a tabela do sistema de otimização preditiva. A otimização preditiva executa DELETE para remover linhas expiradas, VACUUM para excluí-las do armazenamento e, opcionalmente, PURGE para tabelas com vetores de exclusão ativados para criar novos arquivos sem linhas excluídas.

Execute a seguinte consulta para revisar as operações de tempo de vida automático em todas as tabelas nos últimos 7 dias:

SQL
WITH tables_with_deletes AS (
  SELECT DISTINCT catalog_name, schema_name, table_name
  FROM system.storage.predictive_optimization_operations_history
  WHERE
    operation_type = 'DELETE'
    AND timestampdiff(day, start_time, now()) < 7
)
SELECT hist.*
FROM system.storage.predictive_optimization_operations_history AS hist
INNER JOIN tables_with_deletes AS t
  ON hist.catalog_name = t.catalog_name
  AND hist.schema_name = t.schema_name
  AND hist.table_name = t.table_name
WHERE
  hist.operation_type IN ('DELETE', 'PURGE', 'VACUUM')
  AND timestampdiff(day, hist.start_time, now()) < 7
ORDER BY hist.start_time DESC;

Definir um alerta para falhas de tempo de vida automático​

Para receber notificações quando operações de tempo de vida automático falham, crie um alerta do Databricks SQL com uma consulta que verifica operações com falha na tabela do sistema de otimização preditiva. Consulte Alerta do Databricks SQL para obter instruções sobre como criar alertas, e documentação das tabelas do sistema para exemplos de consulta.

Estimativa de custos de TTL automático​

Use a seguinte consulta para ver quantas DBUs as operações de tempo de vida automático consumiram nos últimos 30 dias:

SQL
WITH tables_with_deletes AS (
  SELECT DISTINCT table_name
  FROM system.storage.predictive_optimization_operations_history
  WHERE
    operation_type = 'DELETE'
    AND timestampdiff(day, start_time, now()) < 30
)
SELECT SUM(usage_quantity) AS total_estimated_dbu
FROM system.storage.predictive_optimization_operations_history AS hist
INNER JOIN tables_with_deletes AS t
  ON hist.table_name = t.table_name
WHERE
  hist.operation_type IN ('DELETE', 'PURGE', 'VACUUM')
  AND hist.usage_unit = 'ESTIMATED_DBU'
  AND timestampdiff(day, hist.start_time, now()) < 30;

Análise de operações em uma tabela específica​

Use DESCRIBE HISTORY para ver operações recentes executadas em uma tabela específica:

SQL
DESCRIBE HISTORY table_name;

Limitações​

Aplicam-se as seguintes limitações ao tempo de vida automático:

importante

O momento exato da exclusão não é garantido e pode variar de acordo com a carga do sistema. Para obter informações sobre como verificar se os dados foram excluídos, consulte Tabelas do sistema.

  • O Auto Time-to-live não é suportado em visualizações materializadas.

  • ALTER TABLE e a sintaxe ALTER STREAMING TABLE não é suportada para modificar o tempo de vida automático em tabelas de transmissão. Para adicionar ou alterar uma política de tempo de vida automático em uma tabela de transmissão existente, atualize o parâmetro auto_ttl no código do pipeline e republique o pipeline.

  • A renomeação de colunas não é suportada para colunas de tempo que são definidas em uma política de tempo de vida automático. Se o mapeamento de coluna estiver ativado, esta limitação ainda se aplica. Consulte Renomear e eliminar colunas com o mapeamento de colunas do Delta Lake.

  • Em casos raros, operações automáticas de tempo de vida podem causar conflitos de transação. Para reduzir o risco de conflitos de transação, utilize o clustering líquido, que minimiza conflitos com simultaneidade em nível de linha. Consulte Usar clustering líquido para tabelas.

  • Se o compute serverless não conseguir acessar o GCS devido à conectividade de serviço privada, as operações automáticas de tempo de vida poderão falhar. Consulte Ative o Private Service Connect para seu workspace.

Nesta página