Eliminazione automatica delle righe con time-to-live automatico

Il time-to-live automatico (Auto-TTL) elimina automaticamente le righe dalle tabelle gestite di Unity Catalog dopo un periodo di tempo configurabile, in base al valore di una colonna timestamp. Definire un periodo di scadenza in giorni e specificare una colonna timestamp per il confronto. Databricks esegue le operazioni DELETE, PURGE e VACUUM in background per rimuovere le righe scadute e rimuoverle dall'archiviazione.

Di seguito sono riportati due esempi di come utilizzare il time-to-live automatico:

• È possibile rimuovere i dati precedenti a 1 anno per ridurre i costi di archiviazione. Imposta la scadenza delle righe a 1 anno dalla creazione specificando un periodo di scadenza di 365 giorni su una colonna timestamp created_at.
• È possibile rimuovere i dati contrassegnati per l'eliminazione da un altro processo aziendale. Imposta la scadenza delle righe 20 giorni dopo l'elaborazione di una richiesta di eliminazione, specificando un periodo di scadenza di 20 giorni su una colonna timestamp personalizzata del_request_approved.

Importante

La tempistica esatta dell'eliminazione non è garantita e può variare in base al carico di sistema. Per verificare l'eliminazione, eseguire una query sulla tabella del sistema di ottimizzazione predittiva o eseguire DESCRIBE HISTORY nella tabella. Vedere Tabelle di sistema.

Il tempo di buffer compreso tra la scadenza della riga e l'eliminazione permanente può essere fino a 6 giorni più il valore della proprietà della tabella di conservazione dei dati, che per impostazione predefinita è di 7 giorni. Per informazioni su come configurare il time-to-live automatico per eliminare i dati entro un intervallo di tempo specifico, vedere Calcolare i valori di configurazione per un periodo di scadenza target e Configurare la conservazione dei dati per le query Time Travel.

Il time-to-live automatico è disponibile per le tabelle Delta Lake gestite da Unity Catalog, le tabelle Apache Iceberg e le tabelle di streaming con pipeline Lakeflow.

Requisiti

• È necessario attivare l'ottimizzazione predittiva. Consulta Ottimizzazione predittiva per le tabelle gestite di Unity Catalog.
  • La disattivazione dell'ottimizzazione predittiva su una tabella con time-to-live automatico (TTL) abilitato impedisce l'esecuzione del time-to-live automatico.
• È necessario disporre delle autorizzazioni MODIFY per una tabella per impostare o eliminare un criterio di scadenza automatica. Vedere Autorizzazioni di tabella di base.
• Databricks Runtime 17.3 e versioni successive.
  • Databricks Runtime 17.2 e versioni successive possono leggere e scrivere in tabelle con durata automatica.

Attiva il time-to-live automatico

Attivare il time-to-live automatico in modo diverso a seconda della tabella di origine:

Tabelle gestite di Delta Lake e Apache Iceberg

Per impostare un criterio di durata automatica in una nuova tabella, specificare un numero intero non negativo per <expiration_days> e una colonna con un tipo di DATE, TIMESTAMPo TIMESTAMP_NTZ per <time_column_name>:

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

Per impostare un criterio di durata automatica in una tabella esistente:

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

Ad esempio, per eliminare le righe 30 giorni dopo il created_at timestamp:

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

Tabelle di streaming con pipeline Lakeflow

Per impostare un criterio di scadenza automatica su una nuova tabella di streaming in una pipeline, specificare due valori. Specificare un numero intero non negativo per <expiration_days> e una colonna di tipo DATE, TIMESTAMPo TIMESTAMP_NTZ per <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)

La modifica di una tabella di streaming per utilizzare il time-to-live automatico tramite SQL non è supportata. Per modificare il time-to-live automatico di una tabella di streaming esistente, aggiornare il codice della pipeline e ripubblicare.

Streaming di letture da tabelle con durata automatica

Se si utilizza Structured Streaming, le pipeline Lakeflow o le tabelle di streaming per leggere da una tabella con il time-to-live automatico abilitato, impostare skipChangeCommits per la lettura in streaming. Le operazioni di eliminazione automatica in tempo reale vengono visualizzate come modifiche ai dati. Senza questa impostazione, la lettura in streaming non riesce quando il time-to-live automatico elimina le righe.

Vedere gli esempi seguenti:

Streaming Strutturato

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

Pipeline di 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")

Tabelle di 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);

Verificare che il time-to-live automatico sia abilitato

Usa DESCRIBE TABLE EXTENDED per confermare che il time-to-live automatico sia configurato. Se sono impostate le proprietà autottl.expireInDays e autottl.timestampColumn, il time-to-live automatico è abilitato.

Le impostazioni automatiche del time-to-live vengono visualizzate nella riga Proprietà tabella:

DESCRIBE TABLE EXTENDED table_name;

In alternativa, usare SHOW TBLPROPERTIES per visualizzare le proprietà auto time-to-live:

SHOW TBLPROPERTIES table_name;

Disattiva il tempo di vita automatico

Per eliminare da una tabella Delta Lake o Apache Iceberg gestita una policy automatica time-to-live:

ALTER TABLE table_name DROP ROW DELETION;

Per eliminare un criterio time-to-live automatico su una tabella di streaming, impostare auto_ttl su None nel codice della pipeline e ripubblicare:

from pyspark import pipelines as dp

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

Ciclo di vita dei dati

La durata automatica consente di automatizzare la gestione del ciclo di vita dei dati per le tabelle con requisiti di conservazione basati sul tempo.

Il time-to-live automatico ha un ciclo di vita dei dati articolato in più fasi. Dopo la scadenza di una riga, l'ottimizzazione predittiva esegue in modo asincrono i comandi DELETE e VACUUM. Se i vettori di eliminazione sono abilitati nella tabella, l'ottimizzazione predittiva viene eseguita PURGE anche prima VACUUM di riscrivere i file di dati e rimuovere le righe eliminate. Per forzare la riscrittura dei dati, vedere Eliminare solo i metadati.

La tempistica esatta dell'eliminazione non è garantita e può variare in base al carico di sistema. Per informazioni su come verificare che i dati siano stati eliminati, vedere Tabelle di sistema.

Per configurare correttamente il time-to-live (TTL) automatico in base ai requisiti di conservazione dei dati, consulta i passaggi seguenti:

Stage	Durata	Description
Periodo di scadenza	L'utente specifica quando attiva il time-to-live automatico.	Numero di giorni dopo il valore della colonna temporale quando una riga diventa idonea per l'eliminazione. Imposta questo quando attivi il time-to-live automatico.
Tempo di buffer	Fino a 3 giorni per comando (DELETE, VACUUM)	Ritardo tra quando le righe diventano idonee per l'eliminazione e quando vengono eliminate dall'ottimizzazione predittiva. Possono verificarsi ritardi tra la scadenza di una riga e ciascun comando asincrono, DELETE e VACUUM. Ogni ritardo è in genere inferiore a 3 giorni, fino a un totale di 6 giorni.
Durata della conservazione dei dati	L'utente definisce con una proprietà di tabella.	Il periodo di tempo per cui le righe eliminate rimangono memorizzate e accessibili tramite Time Travel. Per le tabelle Delta Lake, configurare con delta.deletedFileRetentionDuration. Per le tabelle di Apache Iceberg, configurare con iceberg.deletedFileRetentionDuration. Se la proprietà non è impostata, il valore predefinito è 7 giorni. Vedere Configurare la conservazione dei dati per le query di spostamento cronologico.

Dopo l'eliminazione definitiva tramite VACUUM, le righe eliminate non sono più accessibili durante il viaggio nel tempo. Vedi Eliminazione dei file di dati inutilizzati con vacuum.

Ecco una cronologia visiva del ciclo di vita dei dati, in cui una riga con un valore della colonna temporale pari a t attraversa quattro fasi prima che i suoi file vengano rimossi fisicamente da VACUUM:

Calcolare i valori di configurazione per un periodo di scadenza di destinazione

Importante

Il TTL automatico (time-to-live) elimina i dati in modo asincrono. Vedere Ciclo di vita dei dati.

Per configurare l'ottimizzazione predittiva in modo da rimuovere le righe dall'archiviazione entro un numero target di giorni, sottrai il tempo massimo di buffer (6 giorni) e la durata di conservazione dei file eliminati dal valore target:

target_expiration_days = target_days - 6 - deletedFileRetentionDuration

Ad esempio, per rimuovere le righe entro 30 giorni con il periodo di conservazione predefinito di 7 giorni, impostare su expiration_days17 DAYS:

target_expiration_days = 30 - 6 - 7 = 17 days

Per eliminare le righe nell'arco di 90 giorni con un periodo di conservazione di 30 giorni, impostare expiration_days su 54 DAYS:

target_expiration_days = 90 - 6 - 30 = 54 days

Monitorare la durata automatica

Con le tabelle di sistema è possibile verificare gli eventi automatici di time-to-live, monitorare i costi e impostare avvisi per i malfunzionamenti.

Tabelle di sistema

Verificare gli eventi auto time-to-live con la tabella del sistema di ottimizzazione predittiva. L'ottimizzazione predittiva viene eseguita DELETE per rimuovere le righe scadute, eliminarle dall'archiviazione e, facoltativamenteVACUUM, PURGE per le tabelle con vettori di eliminazione abilitati per creare nuovi file senza righe eliminate.

Esegui la query seguente per verificare le operazioni automatiche di time-to-live su tutte le tabelle negli ultimi 7 giorni:

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;

Impostare un avviso per gli errori del time-to-live automatico

Per ricevere notifiche quando le operazioni in tempo reale automatico hanno esito negativo, creare un avviso SQL di Databricks con una query che verifica le operazioni non riuscite nella tabella del sistema di ottimizzazione predittiva. Vedere Avviso SQL di Databricks per istruzioni su come creare avvisi e documentazione sulle tabelle di sistema per esempi di query.

Stima dei costi del time-to-live automatico

Utilizza la query seguente per vedere quante DBU hanno consumato le operazioni di time-to-live automatico negli ultimi 30 giorni:

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;

Esaminare le operazioni su una tabella specifica

Usare DESCRIBE HISTORY per visualizzare le operazioni recenti eseguite in una tabella specifica:

DESCRIBE HISTORY table_name;

Limitations

Le seguenti limitazioni si applicano al time-to-live automatico:

Importante

La tempistica esatta dell'eliminazione non è garantita e può variare in base al carico di sistema. Per informazioni su come verificare che i dati siano stati eliminati, vedere Tabelle di sistema.

• Il time-to-live automatico non è supportato per le viste materializzate.
• La sintassi ALTER TABLE e ALTER STREAMING TABLE non è supportata per modificare il time-to-live automatico nelle tabelle di streaming. Per aggiungere o modificare un criterio auto time-to-live in una tabella di streaming esistente, aggiornare il auto_ttl parametro nel codice della pipeline e ripubblicare la pipeline.
• La ridenominazione delle colonne non è supportata per le colonne temporali definite in criteri di durata automatica. Se il mapping delle colonne è attivato, questa limitazione viene comunque applicata. Vedi Rinominare ed eliminare colonne con la mappatura delle colonne di Delta Lake.
• In casi rari, le operazioni automatiche di time-to-live possono causare conflitti nelle transazioni. Per ridurre il rischio di conflitti di transazione, usare il clustering liquido, che riduce i conflitti associati alla concorrenza a livello di riga. Vedere Usare clustering liquido per le tabelle.

• Se l'ambiente di calcolo serverless non riesce ad accedere ad ADLS a causa di un collegamento privato, le operazioni auto time-to-live potrebbero non riuscire. Vedere _