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 Time To Live (TTL).

Panoramica della durata

Utilizza gli indici TTL per rimuovere automaticamente i dati inattivi dai tuoi database. Un indice TTL designa un determinato campo come l'ora di scadenza dei documenti in una determinata raccolta. Con il 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 vengono conteggiate ai fini dei costi di eliminazione dei documenti. Per i prezzi delle operazioni di eliminazione, vedi Prezzi della versione Cloud Firestore Enterprise.

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 sul 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. 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 in 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 esistenti per la raccolta.

  • Se un documento ha un tempo di scadenza nel passato e aggiungi un nuovo indice TTL alla raccolta, il documento verrà eliminato entro 24 ore dal termine della configurazione e dall'attivazione dell'indice TTL.

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

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

  • Cloud Firestore rispetterà sempre il campo TTL più recente per determinare la scadenza. Ad esempio, se il campo TTL di un documento scaduto ma non ancora eliminato viene aggiornato a una data successiva, il documento non scadrà e verrà utilizzata la nuova data.

  • Cloud Firestore scade 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 sulle altre attività del database. Le eliminazioni basate sul TTL vengono trattate con una priorità inferiore. Sono in atto anche altre strategie per attenuare i picchi di traffico dovuti alle eliminazioni basate sul TTL.

Campi TTL e indici non TTL

Un campo TTL può essere indicizzato o non indicizzato. Tuttavia, poiché un campo TTL è un timestamp, l'inclusione del campo in un indice non TTL può influire sul rendimento a tassi di traffico più elevati. L'inclusione di un campo timestamp in un indice non TTL può creare hotspot, il che non è consigliato. Gli hotspot sono tassi elevati di lettura, scrittura ed eliminazione in un intervallo di documenti ristretto.

Autorizzazioni

Il principal che crea o elimina un indice TTL richiede la seguente autorizzazione nel progetto:

  • Per visualizzare gli indici TTL sono necessarie le autorizzazioni datastore.indexes.list e datastore.indexes.get.
  • Per creare o eliminare indici TTL è necessaria l'autorizzazione datastore.indexes.update.
  • Il controllo dello stato delle operazioni TTL richiede datastore.operations.list e datastore.operations.get.

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

Prima di iniziare

Prima di utilizzare gcloud CLI per gestire gli indici TTL, utilizza il comando gcloud components update per aggiornare i componenti all'ultima versione disponibile:

gcloud components update

Crea un indice TTL

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

TTL utilizza un campo specificato per identificare i documenti idonei all'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 orario nel futuro, attuale o nel passato. Se il valore è un'ora nel passato, il documento è immediatamente idoneo all'eliminazione. Ad esempio, puoi creare un indice TTL con il campo expireAt, che poi aggiungi ai documenti esistenti.

  • L'utilizzo di qualsiasi altro tipo di dati o la mancata impostazione del valore del campo TTL disattiverà il TTL per il singolo documento.

Per creare un indice TTL:

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 l'ora di scadenza. Se expireAfterSeconds è impostato su 0, la scadenza viene fornita direttamente dal valore del timestamp del campo TTL.

Tieni presenti le seguenti limitazioni:

  • Gli indici TTL devono includere esattamente un campo.
  • Gli indici TTL non sono utilizzabili nelle query.
  • Puoi creare un solo indice TTL per raccolta.
  • Gli audit log per la creazione dell'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.

  3. Nel menu di navigazione, fai clic su Time to live.

  4. Fai clic su Crea criterio.

  5. Inserisci un nome per la raccolta e un nome per il campo timestamp.

  6. 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, nella pagina viene visualizzato un messaggio di errore.

gcloud

  1. Installa e inizializza la CLI 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

Durata della creazione dell'indice TTL

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

Visualizzare gli indici TTL

Per visualizzare gli indici TTL:

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.

  3. Nel menu di navigazione, fai clic su Time to live.

La console elenca gli indici TTL per il tuo database e include lo stato di ciascun indice.

gcloud

  1. Installa e inizializza la CLI 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 quanto segue:

    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.

Eliminare un indice TTL

Per eliminare un indice TTL:

API MongoDB

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

Eliminare un indice TTL utilizzando il nome dell'indice

db.restaurants.dropIndex("ts_1")

Eliminare 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.

  3. Nel menu di navigazione, fai clic su Time to live.

  4. Nella tabella dell'indice TTL, individua la riga relativa all'indice TTL. All'interno di questa riga della tabella, fai clic sul pulsante Elimina (cestino).

  5. Conferma l'operazione 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 la CLI 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

Monitorare le eliminazioni TTL

Puoi utilizzare Cloud Monitoring per visualizzare le metriche relative alle eliminazioni basate sul 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 in base alla durata

Conteggio totale dei documenti eliminati dagli indici TTL.
firestore.googleapis.com/document/ttl_expiration_to_deletion_delays Scadenza del time to live per i ritardi di 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 metriche Cloud Firestore, consulta Gestisci dashboard personalizzate e Aggiungi widget alla dashboard.