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 di durata (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 tempo di scadenza per i 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 scadenza.

Prezzi

Le operazioni di eliminazione TTL utilizzano unità di eliminazione gestite. Per i prezzi, consulta la pagina dei prezzi dell'edizione Enterprise 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. TTL scambia la tempestività dell'eliminazione a vantaggio di un costo totale di proprietà ridotto per le eliminazioni. In genere, i dati vengono eliminati entro 24 ore dalla 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 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 dalla fine della configurazione e dall'attivazione dell'indice TTL.

  • 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 lo stesso tempo 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 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 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.

  • TTL è progettato per ridurre al minimo l'impatto sulle altre attività del database. Le eliminazioni basate su TTL vengono trattate con una priorità inferiore. Sono in vigore 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 i timestamp, l'aggiunta di questi campi a un indice non TTL potrebbe causare hotspot. Gli hotspot si verificano quando le velocità di scrittura ed eliminazione elevate sono concentrate in un intervallo ristretto di documenti, il che può influire negativamente sulle prestazioni di scalabilità durante i periodi di traffico di scrittura elevato.

Autorizzazioni

L'entità 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 gli indici TTL è necessaria 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 Cloud Firestore Ruoli di Identity and Access Management.

Creare un indice TTL

Quando crei un indice TTL, designi un campo del documento come tempo di scadenza per i documenti in 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'ora futura, attuale o passata. Se il valore è un'ora passata, 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 l'impostazione del valore del campo TTL disattiverà il TTL per il singolo documento.

Per creare un indice TTL:

API MongoDB

Includi l'opzione dell'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 il tempo di scadenza. Se expireAfterSeconds è impostato su 0, il tempo di scadenza viene fornito 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.
  • I log di audit 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.

  4. Fai clic su Crea criterio.

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

  6. Fai clic su Crea.

La console torna alla pagina Durata. 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 firestore fields ttls update comando per configurare un indice TTL. Aggiungi il --async flag 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

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.

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 sia gli indici 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.

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

gcloud

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

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

    gcloud firestore fields ttls list

    Per elencare gli indici TTL in una raccolta specifica:

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

Visualizzare dettagli operazione

Puoi utilizzare gcloud CLI per visualizzare ulteriori dettagli su un indice TTL 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 dropIndex() metodo 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 i log di audit 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.

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

  5. Conferma facendo clic su Elimina.

La console torna alla pagina Durata. Se l'operazione ha 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 firestore fields ttls update comando per configurare un indice TTL. Aggiungi il --async flag 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 su TTL. Cloud Firestore fornisce le seguenti metriche per TTL:

Tipo di metrica Nome metrica Descrizione metrica
firestore.googleapis.com/document/ttl_deletion_count Conteggio eliminazioni durata

Conteggio totale dei documenti eliminati dagli indici TTL.
firestore.googleapis.com/document/ttl_expiration_to_deletion_delays Ritardi tra la scadenza e l'eliminazione della durata

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

Per configurare una dashboard con le metriche Cloud Firestore, consulta Gestire le dashboard personalizzate e aggiungere widget alla dashboard.