Gestire la conservazione dei dati con gli indici TTL

Questa pagina descrive come utilizzare l'API MongoDB, la console Google Cloud e Google Cloud CLI per configurare gli indici TTL (Time to Live).

Panoramica della durata (TTL)

Utilizza gli indici TTL per rimuovere automaticamente i dati inattivi dai tuoi database. Un indice TTL designa un determinato campo come data di scadenza dei documenti in una determinata raccolta. Con TTL, puoi ridurre i costi di archiviazione eliminando i dati obsoleti. In genere i dati vengono eliminati entro 24 ore dalla data di scadenza.

Prezzi

Le operazioni di eliminazione TTL utilizzano unità di eliminazione gestite. Per i prezzi, consulta Prezzi della versione Enterprise di Cloud Firestore.

Limiti e vincoli

  • Puoi creare un solo indice TTL per raccolta.
  • Puoi avere un massimo di 500 indici TTL.

Eliminazione TTL

Tieni presente i seguenti comportamenti chiave dell'eliminazione basata su TTL:

  • L'eliminazione tramite TTL non è un processo istantaneo. I documenti scaduti continuano a essere visualizzati nelle query e nelle richieste di ricerca finché il processo TTL non li elimina effettivamente. Il TTL scambia la tempestività dell'eliminazione con il vantaggio di un costo totale di proprietà ridotto per le eliminazioni. In genere i dati vengono eliminati entro 24 ore dalla data di scadenza.

  • La creazione di un indice TTL su una raccolta esistente comporta l'eliminazione collettiva di tutti i dati scaduti in base al nuovo indice TTL. Tieni presente che anche questa eliminazione collettiva non è istantanea e dipende dalla quantità di dati presenti nella raccolta.

  • Se un documento ha una data di scadenza nel passato e aggiungi un nuovo indice TTL alla raccolta, il documento verrà eliminato entro 24 ore dal momento in cui la configurazione dell'indice TTL viene completata e l'indice diventa attivo.

  • Il TTL non elimina necessariamente i documenti nello stesso ordine dei relativi timestamp di scadenza.

  • Le eliminazioni non vengono eseguite in modo transazionale. I documenti con la stessa data di scadenza non vengono necessariamente eliminati contemporaneamente. Se hai bisogno di questo comportamento, esegui le eliminazioni utilizzando una libreria client.

  • Cloud Firestore rispetterà sempre l'ultimo campo TTL per determinare la scadenza. Ad esempio, se un documento scaduto ma non ancora eliminato ha il campo TTL aggiornato a una data successiva, il documento non scadrà e verrà utilizzata la nuova data.

  • Cloud Firestore fa scadere un documento solo quando il campo TTL è impostato su un valore Date and time/BSON Date o su un valore Array contenente un valore Date and time/BSON Date. Lascia il campo vuoto o impostalo su un valore come null per disattivare le scadenze per ogni documento.

  • Il TTL è progettato per ridurre al minimo l'impatto su altre attività del database. Le eliminazioni basate su TTL vengono trattate con una priorità inferiore. Sono in atto anche altre strategie per attenuare i picchi di traffico dovuti alle eliminazioni basate su TTL.

Differenze con gli indici TTL

A differenza di altri indici Firestore, gli indici TTL non vengono utilizzati durante la pianificazione delle query per migliorare le prestazioni. Per migliorare le prestazioni delle query su un campo utilizzato con TTL, devi aggiungerlo a un indice non TTL separato.

È importante notare che, poiché i campi TTL utilizzano timestamp, aggiungerli a un indice non TTL potrebbe causare hotspot. Gli hotspot si verificano quando frequenze elevate di scritture ed eliminazioni sono concentrate in un intervallo ristretto di documenti, il che può influire negativamente sulle prestazioni di scalabilità durante i periodi di traffico di scrittura intenso.

Autorizzazioni

L'entità che crea o elimina un indice TTL deve disporre della seguente autorizzazione nel progetto:

  • Per visualizzare gli indici TTL sono necessarie le autorizzazioni datastore.indexes.list e datastore.indexes.get.
  • La creazione o l'eliminazione degli indici TTL richiede l'autorizzazione datastore.indexes.update.
  • Per controllare lo stato delle operazioni TTL sono necessarie le autorizzazioni datastore.operations.list e datastore.operations.get.

Per i ruoli che assegnano queste autorizzazioni, consulta Ruoli di Identity and Access Management di Cloud Firestore.

Crea un indice TTL

Quando crei un indice TTL, designi un campo del documento come ora di scadenza per i documenti di una raccolta.

Il TTL utilizza un campo specificato per identificare i documenti idonei per l'eliminazione. Il campo TTL deve essere impostato su un valore Timestamp/BSON Date o su un valore Array contenente un valore Timestamp/BSON Date. Puoi selezionare un campo già esistente o designare un campo che prevedi di aggiungere in un secondo momento.

Prima di impostare il valore del campo TTL, tieni presente quanto segue:

  • Il valore del campo TTL può essere un'ora futura, attuale o passata. Se il valore è un'ora nel passato, il documento è immediatamente idoneo per l'eliminazione. Ad esempio, puoi creare un indice TTL con il campo expireAt, che poi aggiungi ai documenti esistenti.

  • Se utilizzi un altro tipo di dati o non imposti il valore del campo TTL, il TTL verrà disattivato per il singolo documento.

Per creare un indice TTL, segui questi passaggi:

API MongoDB

Includi l'opzione di indice expireAfterSeconds quando chiami il metodo createIndex():

db.COLLECTION_NAME.createIndex({"TTL_FIELD": 1, "expireAfterSeconds": EXPIRATION_OFFSET_SECONDS})

Ad esempio:

db.restaurants.createIndex({"ts": 1, "expireAfterSeconds": 3600})

expireAfterSeconds identifica il TTL come indice TTL ed è l'offset tra il valore del timestamp del campo TTL e la data e l'ora di scadenza. Se expireAfterSeconds è impostato su 0, la data e l'ora di scadenza vengono fornite direttamente dal valore del timestamp del campo TTL.

Tieni presente le seguenti limitazioni:

  • Gli indici TTL devono includere esattamente un campo.
  • Gli indici TTL non vengono utilizzati nella pianificazione delle query e non migliorano le prestazioni delle query.
  • Puoi creare un solo indice TTL per raccolta.
  • Gli audit log per la creazione di indici TTL con l'API MongoDB utilizzano il nome del metodo google.firestore.admin.v1.FirestoreAdmin.UpdateField.

Google Cloud Console

  1. Nella console Google Cloud, vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Durata (TTL).

  4. Fai clic su Crea criterio.

  5. Inserisci il nome di una raccolta e il nome di un campo timestamp.

  6. (Facoltativo) Configura un offset di scadenza. Inserisci un valore e seleziona un'unità (giorni, ore, minuti o secondi). Per impostazione predefinita, l'offset è 0.

  7. Fai clic su Crea.

La console torna alla pagina Time to live. Se l'operazione viene avviata correttamente, la pagina aggiunge una voce alla tabella degli indici TTL. In caso di errore, la pagina visualizza un messaggio di errore.

gcloud

  1. Installa e inizializza l'interfaccia a riga di comando gcloud CLI.

  2. Utilizza il comando firestore fields ttls update per configurare un indice TTL. Aggiungi il flag --async per impedire a gcloud CLI di attendere il completamento dell'operazione.

     gcloud firestore fields ttls update \
  ttl_field \
  --collection-group=collection_name \
  --enable-ttl

    Per attivare un indice TTL con un offset di scadenza, aggiungi il flag --expiration-offset:

     gcloud firestore fields ttls update \
  ttl_field \
  --collection-group=collection_name \
  --enable-ttl \
  --expiration-offset=expiration_offset

    Sostituisci expiration_offset con una durata, ad esempio 7d per 7 giorni o 24h per 24 ore. Se ometti questo flag, l'offset di scadenza viene impostato su 0 per impostazione predefinita.

Durata della creazione dell'indice TTL

La creazione di un indice TTL può richiedere almeno dieci minuti o più. Una volta avviata un'operazione, la chiusura del terminale non la annulla.

Visualizza gli indici TTL

Per visualizzare gli indici TTL, segui questi passaggi:

API MongoDB

Utilizza il metodo listIndexes() per visualizzare gli indici TTL. Ad esempio:

db.restaurants.listIndexes()

Tieni presente che l'output includerà sia gli indici TTL che quelli non TTL. Gli indici TTL includeranno l'opzione expireAfterSeconds.

Google Cloud Console

  1. Nella console Google Cloud, vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Durata (TTL).

La console elenca gli indici TTL del database e include lo stato di ogni indice.

gcloud

  1. Installa e inizializza l'interfaccia a riga di comando gcloud CLI.

  2. Utilizza il comando firestore fields ttls list per configurare un indice TTL. Il comando seguente elenca tutti gli indici TTL.

    gcloud firestore fields ttls list

    Per elencare gli indici TTL in una raccolta specifica, utilizza il seguente comando:

    gcloud firestore fields ttls list  --collection-group=collection_name

Visualizza dettagli operazione

Puoi utilizzare gcloud CLI per visualizzare ulteriori dettagli su un indice TTL che si trova nello stato CREATING.

Utilizza il comando operations list per visualizzare tutte le operazioni in esecuzione e quelle completate di recente:

gcloud firestore operations list

La risposta include una stima dell'avanzamento dell'operazione.

Elimina un indice TTL

Per eliminare un indice TTL:

API MongoDB

Utilizza il metodo dropIndex() per eliminare un indice TTL. Ad esempio:

Elimina un indice TTL utilizzando il nome dell'indice

db.restaurants.dropIndex("ts_1")

Elimina un indice TTL utilizzando la definizione dell'indice

db.restaurants.dropIndex({"ts": 1})

Tieni presente che gli audit log per l'eliminazione di un indice TTL con l'API MongoDB utilizzano il nome del metodo google.firestore.admin.v1.FirestoreAdmin.UpdateField.

Google Cloud Console

  1. Nella console Google Cloud, vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Durata (TTL).

  4. Nella tabella degli indici TTL, individua la riga corrispondente all'indice TTL. In questa riga della tabella, fai clic sul pulsante Elimina (cestino).

  5. Conferma facendo clic su Elimina.

La console torna alla pagina Time to live. In caso di esito positivo, Cloud Firestore rimuove l'indice TTL dalla tabella.

gcloud

  1. Installa e inizializza l'interfaccia a riga di comando gcloud CLI.

  2. Utilizza il comando firestore fields ttls update per configurare un indice TTL. Aggiungi il flag --async per impedire a gcloud CLI di attendere il completamento dell'operazione.

    gcloud firestore fields ttls update ttl_field --collection-group=collection_name --disable-ttl

Monitora le eliminazioni TTL

Puoi utilizzare Cloud Monitoring per visualizzare le metriche relative alle eliminazioni basate su TTL. Cloud Firestore fornisce le seguenti metriche per il TTL:

Tipo di metrica Nome metrica Descrizione metrica
firestore.googleapis.com/document/ttl_deletion_count Conteggio eliminazioni per durata (TTL)

Numero totale di documenti eliminati dagli indici TTL.
firestore.googleapis.com/document/ttl_expiration_to_deletion_delays Ritardi tra la scadenza della durata (TTL) e l'eliminazione

Tempo trascorso tra la scadenza di un documento in base a un indice TTL e la sua effettiva eliminazione.

Per configurare una dashboard con le metriche Cloud Firestore, consulta Gestisci la dashboard personalizzata e Aggiungi widget della dashboard.