TTL Indexes

Criar um Índice TTL

Para criar um índice TTL, utilize createIndex(). Especifique um campo de índice que seja um tipo de data ou um array que contenha valores de tipo de data. Use a opção expireAfterSeconds para especificar um valor de TTL em segundos.

O valor expireAfterSeconds do índice TTL deve estar dentro de 0 e 2147483647 inclusive.

Por exemplo, para criar um índice TTL no campo lastModifiedDate da collection eventlog com um valor TTL de 3600 segundos, use a seguinte operação em mongosh:

db.eventlog.createIndex(
   { "lastModifiedDate": 1 },
   { expireAfterSeconds: 3600 }
)

A partir do MongoDB 6.3, você pode criar índices TTL parciais em coleções de séries temporais. Esses índices usam a collection timeField como campo chave e exigem uma expressão de filtro parcial em metaField.

As coleções de séries temporais incluem um campo expireAfterSeconds opcional. Se você não definir expireAfterSeconds, um índice TTL com partialFilterExpression permitirá definir um período de expiração para documentos que correspondem ao filtro. Se você definir expireAfterSeconds, um índice TTL parcial permitirá que você defina um período de expiração diferente e mais curto para documentos correspondentes. Você só pode criar um partialFilterExpression no metaField.

Se uma coleção de séries temporais contiver documentos com timeField registros de data e hora anteriores a 1970-01-01T00:00:00.000Z ou posteriores a 2038-01-19T03:14:07.000Z, nenhum documento será excluído da coleção pelo recurso TTL "time to live".

Esta coleção de séries temporais de dados climáticos exclui documentos após 24 horas:

db.createCollection(
   "weather24h",
   {
      timeseries: {
         timeField: "timestamp",
         metaField: "sensor",
         granularity: "hours"
      },
      expireAfterSeconds: 86400
   }
)

Este índice TTL exclui documentos do sensor climático da sede do MongoDB NYC após 1 hora, em vez de 24 horas:

db.eventlog.createIndex(
  { "timestamp": 1 },
  { partialFilterExpression: { "sensor": { $eq: "40.761873, -73.984287" } } },
  { expireAfterSeconds: 3600 } )

Converter um índice de campo único não TTL em um índice TTL

A partir do MongoDB 5.1, você pode adicionar a opção expireAfterSeconds a um índice de campo único existente. Para alterar um índice de campo único não TTL para um índice TTL, utilize o comando de banco de dados collMod:

db.runCommand({
  "collMod": <collName>,
  "index": {
    "keyPattern": <keyPattern>,
    "expireAfterSeconds": <number>
  }
})

O exemplo a seguir converte um índice de campo único não TTL com o padrão { "lastModifiedDate": 1 } em um índice TTL:

db.runCommand({
  "collMod": "tickets",
  "index": {
    "keyPattern": { "lastModifiedDate": 1 },
    "expireAfterSeconds": 100
  }
})

Altere o valor expireAfterSeconds para um índice TTL

To change the expireAfterSeconds value for a TTL Index, use the collMod database command:

db.runCommand({
  "collMod": <collName>,
  "index": {
    "keyPattern": <keyPattern>,
    "expireAfterSeconds": <number>
  }
})

O exemplo a seguir altera o valor expireAfterSeconds de um índice com o padrão { "lastModifiedDate": 1 } na collection tickets:

db.runCommand({
  "collMod": "tickets",
  "index": {
    "keyPattern": { "lastModifiedDate": 1 },
    "expireAfterSeconds": 100
  }
})

Comportamento

Restrições

• Os índices TTL são índices de campo único. Índices compostos não suportam TTL e ignoram a opção expireAfterSeconds.

• O campo _id não suporta índices TTL.

• Não é possível criar um índice TTL em uma capped collection.

• A partir do MongoDB 7.0, você pode criar um índice TTL parcial em metaField de uma coleção de séries temporais. Nas versões anteriores do MongoDB, você só pode criar um índice TTL para timeField de uma coleção de séries temporais.

• Você não pode usar createIndex() para alterar o valor de expireAfterSeconds de um índice existente. Em vez disso, use o comando de banco de dados collMod. Para obter detalhes, consulte Alterar o valor expireAfterSeconds para um índice TTL.

• Se já existir um índice de campo único não TTL para um campo, você não poderá criar um índice TTL no mesmo campo, pois não poderá criar índices que tenham a mesma especificação de chave e difiram apenas pelas opções. Para alterar um índice de campo único não TTL para um índice TTL, utilize o comando de banco de dados collMod.