Gérer la conservation des données avec les index TTL

Cette page explique comment utiliser l'API MongoDB, la console Google Cloud et Google Cloud CLI pour configurer les index de durée de vie (TTL).

Présentation de la valeur TTL

Utilisez des index TTL pour supprimer automatiquement les données obsolètes de vos bases de données. Un index TTL désigne un champ donné comme heure d'expiration des documents d'une collection donnée. Avec le TTL, vous pouvez réduire les coûts de stockage en supprimant les données obsolètes. Les données sont généralement supprimées dans les 24 heures suivant leur heure d'expiration.

Tarifs

Les opérations de suppression TTL sont comptabilisées dans les coûts de suppression de vos documents. Pour connaître le prix des opérations de suppression, consultez la page Tarifs de l'édition Enterprise de Cloud Firestore.

Limites et contraintes

  • Vous ne pouvez créer qu'un seul index TTL par collection.
  • Vous pouvez avoir jusqu'à 500 index TTL.

Suppression TTL

Voici les principaux comportements de la suppression basée sur le TTL :

  • La suppression via le TTL n'est pas un processus instantané. Les documents expirés continuent d'apparaître dans les requêtes et les demandes de recherche jusqu'à ce que le processus TTL les supprime réellement. Le TTL échange la rapidité de suppression contre un coût total de possession réduit pour les suppressions. Les données sont généralement supprimées dans les 24 heures suivant leur heure d'expiration.

  • La création d'un index TTL sur une collection existante entraîne la suppression groupée de toutes les données expirées en fonction du nouvel index TTL. Notez que cette suppression groupée n'est pas non plus instantanée et dépend de la quantité de données existantes pour cette collection.

  • Si un document a une heure d'expiration passée et que vous ajoutez un index TTL à la collection, le document sera supprimé dans les 24 heures suivant la fin de la configuration et l'activation de l'index TTL.

  • Le TTL ne supprime pas nécessairement les documents dans le même ordre que leurs codes temporels d'expiration.

  • Les suppressions ne sont pas effectuées de manière transactionnelle. Les documents ayant la même date d'expiration ne sont pas nécessairement supprimés en même temps. Si vous avez besoin de ce comportement, effectuez les suppressions à l'aide d'une bibliothèque cliente.

  • Cloud Firestore respectera toujours le dernier champ TTL pour déterminer l'expiration. Par exemple, si le champ TTL d'un document expiré, mais pas encore supprimé, est mis à jour avec une date ultérieure, le document ne sera plus expiré et la nouvelle date sera utilisée.

  • Cloud Firestore n'expire un document que lorsque le champ TTL est défini sur une valeur Date and time/BSON Date ou sur une valeur Array contenant une valeur Date and time/BSON Date. Laissez le champ vide ou définissez-le sur une valeur telle que null pour désactiver les expirations au niveau du document.

  • La valeur TTL est conçue pour minimiser l'impact sur les autres activités de base de données. Les suppressions déclenchées par le TTL sont traitées avec une priorité plus faible. D'autres stratégies sont également en place pour lisser les pics de trafic dus aux suppressions basées sur la valeur TTL.

Champs TTL et index non TTL

Un champ TTL peut être indexé ou non. Toutefois, étant donné qu'un champ TTL est un code temporel, l'inclusion du champ dans un index non TTL peut affecter les performances à des taux de trafic plus élevés. Inclure un champ d'horodatage dans un index non TTL peut créer des points chauds, ce qui ne respecte pas les bonnes pratiques. Les hotspots correspondent à des taux de lecture, d'écriture et de suppression élevés pour une plage de documents restreinte.

Autorisations

Le compte principal qui crée ou supprime un index TTL doit disposer de l'autorisation suivante dans le projet :

  • Pour afficher les index TTL, vous devez disposer des autorisations datastore.indexes.list et datastore.indexes.get.
  • La création ou la suppression d'index TTL nécessite l'autorisation datastore.indexes.update.
  • Pour vérifier l'état des opérations TTL, vous devez disposer des autorisations datastore.operations.list et datastore.operations.get.

Pour connaître les rôles qui attribuent ces autorisations, consultez Cloud Firestore Rôles Identity and Access Management.

Avant de commencer

Avant d'utiliser gcloud CLI pour gérer les index TTL, exécutez la commande gcloud components update pour mettre à jour les composants vers la dernière version disponible :

gcloud components update

Créer un index TTL

Lorsque vous créez un index TTL, vous désignez un champ de document comme délai d'expiration des documents d'une collection.

Le TTL utilise un champ spécifié pour identifier les documents pouvant être supprimés. Le champ TTL doit être défini sur une valeur Timestamp/BSON Date ou sur une valeur Array contenant une valeur Timestamp/BSON Date. Vous pouvez sélectionner un champ qui existe déjà ou désigner un champ que vous prévoyez d'ajouter ultérieurement.

Avant de définir la valeur du champ "TTL", tenez compte des points suivants :

  • La valeur du champ TTL peut être une heure future, actuelle ou passée. Si la valeur est une heure passée, le document peut être supprimé immédiatement. Par exemple, vous pouvez créer un index TTL avec le champ expireAt, que vous ajoutez ensuite aux documents existants.

  • Si vous utilisez un autre type de données ou si vous ne définissez pas la valeur du champ TTL, le TTL sera désactivé pour le document concerné.

Pour créer un index TTL, procédez comme suit :

API MongoDB

Incluez l'option d'index expireAfterSeconds lorsque vous appelez la méthode createIndex() :

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

Exemple :

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

expireAfterSeconds identifie le TTL comme un index TTL et correspond au décalage entre la valeur d'horodatage du champ TTL et le délai d'expiration. Si expireAfterSeconds est défini sur 0, le délai d'expiration est directement indiqué par la valeur d'horodatage du champ TTL.

Prenez note des restrictions suivantes :

  • Les index TTL doivent inclure exactement un champ.
  • Les index TTL ne peuvent pas être utilisés dans les requêtes.
  • Vous ne pouvez créer qu'un seul index TTL par collection.
  • Les journaux d'audit pour la création d'index TTL avec l'API MongoDB utilisent le nom de méthode google.firestore.admin.v1.FirestoreAdmin.UpdateField.

Console Google Cloud

  1. Dans la console Google Cloud, accédez à la page Base de données.

    Accéder à la page "Bases de données"

  2. Sélectionnez la base de données requise dans la liste des bases de données.

  3. Dans le menu de navigation, cliquez sur Durée de vie.

  4. Cliquez sur Créer une règle.

  5. Saisissez un nom pour la collection et un nom pour le champ de code temporel.

  6. Cliquez sur Créer.

La console revient à la page Durée de vie. Si l'opération démarre correctement, la page ajoute une entrée au tableau des index TTL. En cas d'échec, la page affiche un message d'erreur.

gcloud

  1. Installez et initialisez la CLI gcloud CLI.

  2. Utilisez la commande firestore fields ttls update pour configurer un index TTL. Ajoutez l'indicateur --async pour empêcher l'outil gcloud CLI d'attendre la fin de l'opération.

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

Durée de création de l'index TTL

Même sur une base de données vide, la création d'un index TTL peut prendre 10 minutes ou plus. Lorsque vous lancez une opération, la fermeture du terminal n'annule pas l'opération.

Afficher les index TTL

Pour afficher les index TTL, procédez comme suit :

API MongoDB

Utilisez la méthode listIndexes() pour afficher les index TTL. Exemple :

db.restaurants.listIndexes()

Notez que le résultat inclura à la fois les index TTL et les index non TTL. Les index TTL incluront l'option expireAfterSeconds.

Console Google Cloud

  1. Dans la console Google Cloud, accédez à la page Base de données.

    Accéder à la page "Bases de données"

  2. Sélectionnez la base de données requise dans la liste des bases de données.

  3. Dans le menu de navigation, cliquez sur Durée de vie.

La console liste les index TTL de votre base de données et inclut l'état de chaque index.

gcloud

  1. Installez et initialisez la CLI gcloud CLI.

  2. Utilisez la commande firestore fields ttls list pour configurer un index TTL. La commande suivante liste tous les index TTL.

    gcloud firestore fields ttls list

    Pour lister les index TTL d'une collection spécifique, utilisez la commande suivante :

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

Afficher les détails de l'opération

Vous pouvez utiliser gcloud CLI pour afficher plus de détails sur un index TTL à l'état CREATING.

Utilisez la commande operations list pour afficher toutes les opérations en cours et terminées récemment :

gcloud firestore operations list

La réponse inclut une estimation de la progression de l'opération.

Supprimer un index TTL

Pour supprimer un index TTL, procédez comme suit :

API MongoDB

Utilisez la méthode dropIndex() pour supprimer un index TTL. Exemple :

Supprimer un index TTL à l'aide de son nom

db.restaurants.dropIndex("ts_1")

Supprimer un index TTL à l'aide de la définition d'index

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

Notez que les journaux d'audit pour la suppression d'un index TTL avec l'API MongoDB utilisent le nom de méthode google.firestore.admin.v1.FirestoreAdmin.UpdateField.

Console Google Cloud

  1. Dans la console Google Cloud, accédez à la page Base de données.

    Accéder à la page "Bases de données"

  2. Sélectionnez la base de données requise dans la liste des bases de données.

  3. Dans le menu de navigation, cliquez sur Durée de vie.

  4. Dans le tableau de l'index TTL, recherchez la ligne correspondant à l'index TTL. Dans cette ligne du tableau, cliquez sur le bouton Supprimer (icône en forme de corbeille).

  5. Confirmez l'opération en cliquant sur Supprimer.

La console revient à la page Durée de vie. En cas de réussite, Cloud Firestore supprime l'index TTL de la table.

gcloud

  1. Installez et initialisez la CLI gcloud CLI.

  2. Utilisez la commande firestore fields ttls update pour configurer un index TTL. Ajoutez l'indicateur --async pour empêcher l'outil gcloud CLI d'attendre la fin de l'opération.

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

Surveiller les suppressions TTL

Vous pouvez utiliser Cloud Monitoring pour afficher les métriques sur les suppressions basées sur le TTL. Cloud Firestore fournit les métriques suivantes pour le TTL :

Type de métrique Nom de la métrique Description de la métrique
firestore.googleapis.com/document/ttl_deletion_count Nombre de suppressions de la valeur TTL

Nombre total de documents supprimés par les index TTL.
firestore.googleapis.com/document/ttl_expiration_to_deletion_delays Délai entre l'expiration de la durée de vie et la suppression

Temps écoulé entre le moment où un document a expiré en vertu d'un index TTL et le moment où il a été réellement supprimé.

Pour configurer un tableau de bord avec des métriques Cloud Firestore, consultez Gérer les tableaux de bord personnalisés et Ajouter des widgets de tableau de bord.