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

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 délai d'expiration des documents d'une collection donnée. Avec la valeur 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 délai d'expiration.

Tarifs

Les opérations de suppression TTL utilisent des unités de suppression gérées. Pour connaître les tarifs, consultez la page Tarifs de l'édition Enterprise Cloud Firestore.

Limites et contraintes

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

Suppression TTL

Notez les comportements clés suivants de la suppression basée sur la valeur TTL :

• La suppression via la valeur 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. La valeur TTL échange la rapidité de suppression au profit d'une réduction du coût total de possession pour les suppressions. Les données sont généralement supprimées dans les 24 heures suivant leur délai 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 un délai d'expiration dans le passé et que vous ajoutez un nouvel 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.

• La valeur 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 le même délai 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 le délai d'expiration. Par exemple, si le champ TTL d'un document expiré mais non encore supprimé est mis à jour à une date ultérieure, le document n'expirera pas et la nouvelle date sera utilisée.

• Cloud Firestore ne fait expirer 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 absent ou défini sur une valeur telle que null pour désactiver les expirations par document.

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

Différences avec les index TTL

Contrairement aux autres index Firestore, les index TTL ne sont pas utilisés lors de la planification des requêtes pour améliorer les performances. Pour améliorer les performances des requêtes sur un champ utilisé avec la valeur TTL, vous devez l'ajouter à un index non TTL distinct.

Il est important de noter que, comme les champs TTL utilisent des codes temporels, leur ajout à un index non TTL peut entraîner des hotspots. Les hotspots se produisent lorsque des taux d'écriture et de suppression élevés sont concentrés dans une plage de documents restreinte, ce qui peut avoir un impact négatif sur les performances de scaling pendant les périodes de trafic d'écriture élevé.

Autorisations

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

• L'affichage des index TTL nécessite les autorisations datastore.indexes.list et datastore.indexes.get.
• La création ou la suppression d'index TTL nécessite l'autorisation datastore.indexes.update.
• La vérification de l'état des opérations TTL nécessite datastore.operations.list et datastore.operations.get.

Pour connaître les rôles qui attribuent ces autorisations, consultez la section Cloud Firestore Rôles de gestion de l'authentification et des accès.

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.

La valeur TTL utilise un champ spécifié pour identifier les documents éligibles à la suppression. 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.

Remarque : Certains index TTL créés avant février 2026 ne s'appliquent pas aux valeurs Timestamp/BSON Date dans les valeurs Array. Pour mettre à jour l'index TTL afin qu'il s'applique aux valeurs Array, supprimez l'index et recréez-le.

Tenez compte des points suivants avant de définir la valeur du champ TTL :

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

• L'utilisation de tout autre type de données ou la non-définition de la valeur du champ TTL désactiveront la valeur TTL pour le document individuel.

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 la valeur TTL comme index TTL et correspond au décalage entre la valeur du code temporel 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 du code temporel du champ TTL.

Prenez note des restrictions suivantes :

• Les index TTL ne doivent inclure qu'un seul champ.
• Les index TTL ne sont pas utilisés dans la planification des requêtes et n'améliorent pas les performances des 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 Bases 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 Time to live (Valeur TTL).

4. Cliquez sur Create Policy (Créer une règle).

5. Saisissez un nom de collection et un nom de champ de code temporel.

6. Cliquez sur Create (Créer).

La console revient à la page Time to live (Valeur TTL). 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 l'interface de ligne de commande gcloud CLI.

2. Utilisez la firestore fields ttls update commande pour configurer un index TTL. Ajoutez l'indicateur --async pour empêcher 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

La création d'un index TTL peut prendre au moins dix minutes. Une fois que vous avez démarré une opération, la fermeture du terminal ne l'annule pas.

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 la sortie 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 Bases 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 Time to live (Valeur TTL).

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

gcloud

1. Installez et initialisez l'interface de ligne de commande gcloud CLI.

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

   gcloud firestore fields ttls list
   

   Pour lister les index TTL sous 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 l'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 d'exécution et celles qui ont été récemment effectuées :

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 dropIndex() méthode pour supprimer un index TTL. Exemple :

Supprimer un index TTL à l'aide du nom d'index

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.

Remarque : La suppression d'une collection à l'aide de la commande MongoDB drop() supprime automatiquement l'index TTL configuré pour cette collection. La suppression de collection est disponible en version bêta.

Console Google Cloud

1. Dans la console Google Cloud, accédez à la page Bases 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 Time to live (Valeur TTL).

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

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

La console revient à la page Time to live (Valeur TTL). En cas de réussite, Cloud Firestore supprime l'index TTL du tableau.

gcloud

1. Installez et initialisez l'interface de ligne de commande gcloud CLI.

2. Utilisez la firestore fields ttls update commande pour configurer un index TTL. Ajoutez l'indicateur --async pour empêcher 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 des métriques sur les suppressions basées sur la valeur TTL. Cloud Firestore fournit les métriques suivantes pour la valeur 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 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 et la suppression TTL	Temps écoulé entre l'expiration d'un document sous un index TTL et sa suppression effective.

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