Administra la retención de datos con índices de TTL

En esta página, se describe cómo usar la API de MongoDB, la Google Cloud consola y la Google Cloud CLI para configurar los índices de tiempo de actividad (TTL).

Descripción general del tiempo de actividad

Usa índices de TTL para quitar automáticamente los datos inactivos de tus bases de datos. Un índice de TTL designa un campo determinado como la fecha de vencimiento de los documentos en una colección determinada. Con el TTL, puedes disminuir los costos de almacenamiento borrando los datos obsoletos. Por lo general, los datos se borran en un plazo de 24 horas después de su fecha de vencimiento.

Precios

Las operaciones de eliminación de TTL usan unidades de eliminación administradas. Para conocer los precios, consulta los precios de la edición Enterprise de Firestore .

Límites y restricciones

  • Solo puedes crear un índice de TTL por colección.
  • Puedes tener un máximo de 500 índices de TTL.

Eliminación del TTL

Ten en cuenta los siguientes comportamientos clave de la eliminación basada en el TTL:

  • La eliminación mediante el TTL no es un proceso instantáneo. Los documentos vencidos seguirán apareciendo en consultas y solicitudes de búsqueda hasta que el proceso del TTL los borre. El TTL cambia la puntualidad de la eliminación por el beneficio de un costo total de propiedad disminuido para las eliminaciones. Por lo general, los datos se borran en un plazo de 24 horas después de su fecha de vencimiento.

  • Crear un índice de TTL en una colección existente genera una eliminación masiva de todos los datos vencidos de acuerdo con el nuevo índice de TTL. Ten en cuenta que esta eliminación masiva no es instantánea y depende de la cantidad de datos que existen para esa colección.

  • Si un documento tiene una fecha de vencimiento en el pasado y agregas un índice de TTL nuevo a la colección, el documento se borrará en un plazo de 24 horas después de que el índice de TTL finalice la configuración y esté activa.

  • El TTL no necesariamente borra los documentos en el mismo orden que sus marcas de tiempo de vencimiento.

  • Las eliminaciones no se realizan de forma transaccional. Los documentos con el mismo tiempo de vencimiento no necesariamente se borran a la vez. Si necesitas este comportamiento, realiza las eliminaciones mediante una biblioteca cliente.

  • Firestore compatible con MongoDB siempre respetará el último campo TTL para determinar el vencimiento. Por ejemplo, si se actualiza a una fecha posterior el campo TTL de un documento caducado, pero que aún no se borró, el documento no caducará y se utilizará la fecha nueva.

  • Firestore compatible con MongoDB hace que venza un documento solo cuando el campo TTL se configura en un valor Date and time/BSON Date o en un valor Array que contenga un valor Date and time/BSON Date. Deja el campo ausente o establécelo en un valor como null, para inhabilitar los vencimientos de forma individual en cada documento.

  • El TTL está diseñado para minimizar el impacto en otras actividades de la base de datos. Las eliminaciones que genera el TTL se tratan con una prioridad más baja. También se implementaron otras estrategias para limitar los aumentos repentinos de tráfico provenientes de las eliminaciones basadas en el TTL.

Diferencias con los índices de TTL

A diferencia de otros índices de Firestore, los índices de TTL no se usan durante la planificación de consultas para mejorar el rendimiento. Para mejorar el rendimiento de las consultas en un campo que se usa con el TTL, debes agregarlo a un índice independiente que no sea de TTL.

Es importante tener en cuenta que, como los campos TTL usan marcas de tiempo, agregarlos a un índice que no sea de TTL puede generar hotspots. Los hotspots se producen cuando las tasas altas de escritura y eliminación se concentran en un rango pequeño de documentos, lo que puede afectar negativamente el rendimiento del escalamiento durante los períodos de tráfico de escritura intenso.

Permisos

La entidad que crea o borra un índice de TTL requiere el siguiente permiso en el proyecto:

  • La visualización de los índices de TTL requiere los permisos datastore.indexes.list y datastore.indexes.get.
  • La creación o eliminación de índices de TTL requiere el permiso datastore.indexes.update.
  • Verificar el estado de las operaciones del TTL requiere datastore.operations.list y datastore.operations.get.

Para conocer los roles que asignan estos permisos, consulta Roles de Identity and Access Management de Firestore.

Crea un índice de TTL

Cuando creas un índice de TTL, designas un campo de documento como la hora de vencimiento para los documentos de una colección.

El TTL usa un campo especificado a fin de identificar los documentos aptos para borrarse. El campo TTL debe establecerse en un valor Timestamp/BSON Date o en un valor Array que contenga un valor Timestamp/BSON Date. Puedes seleccionar un campo que ya exista o designar un campo que planeas agregar más adelante.

Antes de configurar el valor del campo de TTL, ten en cuenta lo siguiente:

  • El valor del campo del TTL puede ser una hora actual, del futuro o del pasado. Si el valor es una hora del pasado, el documento es apto de inmediato para su eliminación. Por ejemplo, puedes crear un índice de TTL con el campo expireAt, para luego agregarlo a los documentos existentes.

  • Si usas cualquier otro tipo de datos o no configuras el valor del campo del TTL, se inhabilitará el TTL del documento individual.

Para crear un nuevo índice de TTL, sigue estos pasos:

API de MongoDB

Incluye la opción de índice expireAfterSeconds cuando llames al método createIndex():

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

Por ejemplo:

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

expireAfterSeconds identifica el TTL como un índice de TTL y es la compensación entre el valor de la marca de tiempo del campo TTL y la hora de vencimiento. Si expireAfterSeconds se establece en 0, la hora de vencimiento se proporciona directamente con el valor de la marca de tiempo del campo TTL.

Ten en cuenta las siguientes limitaciones:

  • Los índices de TTL deben incluir exactamente un campo.
  • Los índices de TTL no se usan en la planificación de consultas y no mejoran el rendimiento de las consultas.
  • Solo puedes crear un índice de TTL por colección.
  • Los registros de auditoría para la creación de índices de TTL con la API de MongoDB usan el nombre del método google.firestore.admin.v1.FirestoreAdmin.UpdateField.

Google Cloud Console

  1. En la Google Cloud consola, ve a la página Bases de datos.

    Ir a Bases de datos

  2. Selecciona la base de datos requerida de la lista.

  3. En el menú de navegación, haz clic en Tiempo de actividad.

  4. Haz clic en Crear política.

  5. Ingresa un nombre para la colección y otro para el campo de la marca de tiempo.

  6. Haz clic en Crear.

La consola regresa a la página Tiempo de actividad. Si la operación se inicia correctamente, la página agrega una entrada a la tabla de índices de TTL. Si se produce un error, la página muestra un mensaje de error.

gcloud

  1. En la Google Cloud consola, activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la Google Cloud consola, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. Usa el firestore fields ttls update comando para configurar un índice de TTL. Agrega la marca --async para evitar que la gcloud CLI espere a que se complete la operación.

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

Duración de la creación del índice de TTL

La creación de un índice de TTL puede tardar un mínimo de diez minutos o más. Una vez que inicias una operación, cerrar la terminal no la cancela.

Visualiza los índices de TTL

Para ver los índices de TTL, sigue estos pasos:

API de MongoDB

Usa el método listIndexes() para ver los índices de TTL. Por ejemplo:

db.restaurants.listIndexes()

Ten en cuenta que el resultado incluirá tanto los índices de TTL como los que no son de TTL. Los índices de TTL incluirán la opción expireAfterSeconds.

Google Cloud Console

  1. En la Google Cloud consola, ve a la página Bases de datos.

    Ir a Bases de datos

  2. Selecciona la base de datos requerida de la lista.

  3. En el menú de navegación, haz clic en Tiempo de actividad.

La consola enumera los índices de TTL para tu base de datos y, además, incluye el estado de cada índice.

gcloud

  1. En la Google Cloud consola, activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la Google Cloud consola, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. Usa el firestore fields ttls list comando para configurar un índice de TTL. El siguiente comando enumera todos los índices de TTL.

    gcloud firestore fields ttls list

    Para enumerar los índices de TTL de una colección específica, usa el siguiente código:

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

Ve los detalles de la operación

Puedes usar la gcloud CLI para ver más detalles sobre un índice de TTL en estado CREATING.

Para ver todas las operaciones en ejecución y las que se completaron recientemente, usa el comando operations list:

gcloud firestore operations list

La respuesta incluye una estimación del progreso de la operación.

Descarta un índice de TTL

Para descartar un índice de TTL, sigue estos pasos:

API de MongoDB

Usa el método dropIndex() para descartar un índice TTL. Por ejemplo:

Descarta un índice de TTL con su nombre

db.restaurants.dropIndex("ts_1")

Descarta un índice de TTL con su definición

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

Ten en cuenta que los registros de auditoría para descartar un índice de TTL con la API de MongoDB usan el nombre del método google.firestore.admin.v1.FirestoreAdmin.UpdateField.

Google Cloud Console

  1. En la Google Cloud consola, ve a la página Bases de datos.

    Ir a Bases de datos

  2. Selecciona la base de datos requerida de la lista.

  3. En el menú de navegación, haz clic en Tiempo de actividad.

  4. En la tabla de índices de TTL, busca la fila correspondiente. En esta fila de la tabla, haz clic en el botón Borrar (papelera).

  5. Haz clic en Borrar para confirmar la acción.

La consola regresa a la página Tiempo de actividad. Si se ejecuta de forma correcta, Firestore compatible con MongoDB quita el índice de TTL de la tabla.

gcloud

  1. En la Google Cloud consola, activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la Google Cloud consola, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. Usa el firestore fields ttls update comando para configurar un índice de TTL. Agrega la marca --async para evitar que la gcloud CLI espere a que se complete la operación.

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

Supervisa las eliminaciones del TTL

Puedes usar Cloud Monitoring para ver las métricas sobre las eliminaciones basadas en el TTL. Firestore compatible con MongoDB proporciona las siguientes métricas para el TTL:

Tipo de métrica Nombre de la métrica Descripción de la métrica
firestore.googleapis.com/document/ttl_deletion_count Recuento de eliminaciones del tiempo de actividad

Recuento total de documentos borrados por los índices de TTL.
firestore.googleapis.com/document/ttl_expiration_to_deletion_delays Retrasos entre el vencimiento del tiempo de actividad y la eliminación

Tiempo transcurrido entre el vencimiento de un documento conforme al índice de TTL y el momento en que se borró.

Para configurar un panel con las métricas de Firestore compatible con MongoDB, revisa Administra paneles personalizados y Agrega widgets al panel.