Exclusão automática de linha com vida útil automática

A vida útil automática (Auto-TTL) excluirá automaticamente linhas de tabelas gerenciadas pelo Unity Catalog depois de um período configurável com base no valor de uma coluna do carimbo de data/hora. Você define um período de expiração em dias e especifica uma coluna de timestamp usada na comparação. O Databricks executa operações DELETE, PURGE e VACUUM em segundo plano para remover linhas expiradas e removê-las do armazenamento.

Veja a seguir dois exemplos de como usar o tempo de vida útil automático:

• Talvez você queira remover dados com mais de 1 ano para manter os custos de armazenamento baixos. Defina a expiração das linhas para 1 ano após a criação, especificando um período de expiração de 365 dias em uma coluna created_at de timestamp.
• Talvez você queira remover dados marcados para exclusão por outro processo de negócios. Defina a expiração das linhas para 20 dias após o processamento de uma solicitação de exclusão, especificando um período de expiração de 20 dias em uma coluna de carimbo de data/hora personalizada del_request_approved.

O TTL automático está disponível para tabelas Delta Lake gerenciadas pelo Unity Catalog, tabelas Apache Iceberg e tabelas de streaming com pipelines do Lakeflow.

Requirements

• 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 vida útil automática (TTL) habilitada impede que ela seja executada.
• Você deve ter a permissão MODIFY em uma tabela para definir ou excluir uma política de vida útil automática. Consulte as permissões básicas da tabela.
• Databricks Runtime 17.3 e superiores.
  • O Databricks Runtime 17.2 e abaixo podem ler e gravar em tabelas com vida útil automática.

Ativar vida útil automática

Ative o tempo de vida automático de maneira diferente dependendo da tabela de origem:

Tabelas gerenciadas pelo Delta Lake e pelo Apache Iceberg

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

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

Para definir uma política de vida útil automática em uma tabela existente:

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

Por exemplo, para excluir linhas 30 dias após o timestamp created_at delas:

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

Tabelas de streaming com pipelines do Lakeflow

Para definir uma política de vida útil automática em uma nova tabela de streaming em um pipeline, especifique dois valores. Forneça um inteiro não negativo para <expiration_days> e uma coluna do tipo DATE, TIMESTAMPou 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);

Python

from pyspark import pipelines as dp

@dp.table(
  auto_ttl={"timestamp_column": <time_column_name>, "expire_in_days": <expiration_days>}
)
def function_name():
  return (query)

Não há suporte à alteração da tabela de streaming para usar a vida útil automática usando o SQL. Para modificar a TTL automática em uma tabela de streaming existente, atualize o código do pipeline e o republique.

Leitura em streaming de tabelas com TTL automática

Se você usar streaming estruturado, pipelines do Lakeflow ou tabelas de streaming para ler de uma tabela com tempo de vida útil automático habilitado, defina skipChangeCommits na leitura de streaming. As operações de exclusão de vida útil automática são exibidas à medida que os dados são alterados. Sem essa configuração, a leitura em streaming falha quando a TTL automática exclui linhas.

Veja os seguintes exemplos:

Streaming estruturado

# 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")

Pipelines Lakeflow

from pyspark import pipelines as dp

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

# Lakeflow pipelines streaming read
@dp.table
def my_table():
  return spark.readStream.format("delta").option("skipChangeCommits", "true").table("source_table")

Tabelas de streaming

-- Source table with auto time-to-live
ALTER TABLE source_table DELETE ROWS <expiration_days> DAYS AFTER <time_column_name>;

-- Lakeflow pipelines streaming read
CREATE OR REFRESH STREAMING TABLE my_table AS
SELECT * FROM STREAM(source_table) OPTIONS (skipChangeCommits);

Verificar se o tempo de vida útil automático está habilitado

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

As configurações de vida útil automática aparecem na linha Propriedades da Tabela :

DESCRIBE TABLE EXTENDED table_name;

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

SHOW TBLPROPERTIES table_name;

Desativar vida útil automática

Para excluir uma política automática de vida útil automática de uma tabela do Delta Lake ou do Apache Iceberg gerenciada:

ALTER TABLE table_name DROP ROW DELETION;

Para excluir uma política de vida útil automática em uma tabela de streaming, defina auto_ttl como None no código do pipeline e republique:

from pyspark import pipelines as dp

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

Ciclo de vida de dados

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

A vida útil automática tem um ciclo de vida de dados de vários estágios. Após a expiração de uma linha, a otimização preditiva executa os comandos DELETE e VACUUM de forma assíncrona. Se os vetores de exclusão estiverem habilitados na tabela, a otimização preditiva também será executada PURGE antes VACUUM para reescrever arquivos de dados e remover linhas excluídas. Confira Limpar exclusões somente de metadados para forçar a regeneração de dados.

O tempo exato de exclusão não é garantido e pode variar com base na 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, examine os estágios abaixo:

Após a exclusão permanente via VACUUM, as linhas excluídas não podem mais ser acessadas por viagem no tempo. Veja Remova arquivos de dados não utilizados usando o vacuum.

Aqui está uma linha do tempo visual do ciclo de vida dos dados, em que uma linha com um valor na coluna de tempo de t percorre quatro fases antes que seus arquivos sejam fisicamente removidos por VACUUM:

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

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 da retenção de arquivo excluído do valor de destino:

target_expiration_days = target_days - 6 - deletedFileRetentionDuration

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

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 como 54 DAYS:

target_expiration_days = 90 - 6 - 30 = 54 days

Monitorar vida útil automática

Com as tabelas do sistema, você pode verificar eventos de vida útil automática, monitore custos e defina alertas para falhas.

Tabelas do sistema

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

Execute a consulta a seguir para revisar as operações automáticas de time-to-live em todas as tabelas nos últimos 7 dias:

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 na vida útil automática

Para receber notificações quando as operações de vida útil automática falharem, crie um alerta do Databricks SQL com uma consulta que verifique operações com falha na tabela do sistema de otimização preditiva. Consulte o alerta do SQL do Databricks para obter instruções sobre como criar alertas e a documentação de tabelas do sistema para obter exemplos de consulta.

Estimar custos de vida útil automática

Use a consulta a seguir para ver quantas operações de vida útil automática de DBUs foram consumidas nos últimos 30 dias:

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;

Revisar operações em uma tabela específica

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

DESCRIBE HISTORY table_name;

Limitações

As seguintes limitações se aplicam ao tempo de vida útil automático:

• Não há suporte para a vida útil automática em exibições materializadas.
• As sintaxes ALTER TABLE e ALTER STREAMING TABLE não são compatíveis com a modificação de vida útil automática em tabelas de streaming. Para adicionar ou alterar uma política de vida útil automática em uma tabela de streaming existente, atualize o parâmetro auto_ttl no código do pipeline e republique o pipeline.
• A renomeação de coluna não é compatível para colunas de tempo definidas em uma política de vida útil automática. Se o mapeamento de coluna estiver ativado, essa limitação ainda se aplicará. Confira Renomear e remover colunas usando o mapeamento de colunas do Delta Lake.
• Em casos raros, operações de vida útil automática podem causar conflitos de transações. Para reduzir o risco de conflitos de transação, use a clusterização líquida, o que reduz conflitos com a simultaneidade no nível de linha. Consulte Usar clustering líquido para tabelas.

• Se a computação sem servidor não puder acessar o ADLS por causa do Link Privado, as operações automáticas de vida útil automática poderão falhar. Consulte a mensagem de erro de link privado