Criando uma coleção de séries temporais

O MongoDB 5.0 introduziu collections nativas de séries temporais — um tipo especializado de collection otimizado para armazenar e consultar medições que mudam ao longo do tempo. Os casos de uso comuns incluem leituras de sensores de IoT, métricas de aplicações, cotações financeiras e dados de monitoramento de servidores. Diferentemente das collections comuns, as collections de séries temporais usam internamente um formato de armazenamento colunar, reduzindo significativamente o espaço ocupado e melhorando o desempenho das consultas com filtros por intervalo de tempo.

Toda collection de séries temporais exige três opções principais ao ser criada. O timeField é o campo do documento que contém o carimbo de data e hora (deve ser uma data BSON). O metaField identifica a série — por exemplo, o ID de um sensor ou o nome de um dispositivo. A indicação de granularidade ('seconds', 'minutes' ou 'hours') informa ao MongoDB com que frequência as medições chegam, permitindo otimizar internamente o tamanho dos buckets.

Use db.createCollection() com um objeto de opções timeseries para criar uma collection de séries temporais. Não é possível converter uma collection comum existente em uma collection de séries temporais — é necessário criá-la do zero. A collection aparecerá em show collections com um indicador especial de tipo timeseries.

A opção de granularidade controla como o MongoDB agrupa as medições em documentos de bucket internos. Com 'seconds', os buckets abrangem uma hora (3.600 medições por bucket). Com 'minutes', abrangem 24 horas. Com 'hours', abrangem 30 dias. Escolher a granularidade incorreta resulta em mais documentos de bucket e em uma compressão pior — sempre corresponda a granularidade à taxa real de chegada dos seus dados.

Os documentos inseridos em uma collection de séries temporais devem incluir o timeField como uma data BSON válida. O valor de metaField identifica a série à qual essa medição pertence (por exemplo, o ID de um dispositivo). Todos os outros campos são chamados de campos de medição e podem conter qualquer valor BSON. O MongoDB rejeitará documentos cujo timeField esteja ausente ou não seja uma data.

Insira dados em uma collection de séries temporais exatamente como faria em uma collection comum — usando insertOne() ou insertMany(). O MongoDB gerencia automaticamente a criação interna dos buckets. É uma boa prática agrupar as inserções com insertMany() ao carregar dados históricos, pois isso distribui o custo de criação dos buckets entre muitas medições.

As collections de séries temporais permitem a expiração automática de dados por meio da opção expireAfterSeconds. Depois de definida, a thread TTL em segundo plano do MongoDB exclui buckets inteiros quando todas as medições neles são mais antigas que o limite. Isso é mais eficiente do que um índice TTL comum, pois documentos de bucket internos inteiros são removidos de uma vez, em vez de documentos de medição individuais.

As consultas em collections de séries temporais são idênticas às consultas find() comuns. O MongoDB usa automaticamente a estrutura interna de buckets para ignorar buckets irrelevantes ao filtrar por intervalo de tempo. Filtrar pelo metaField também é altamente eficiente. Evite consultar apenas campos de medição sem um filtro de tempo ou de meta, pois isso força uma varredura completa da collection em todos os buckets.

Você pode aumentar a granularidade de uma collection de séries temporais existente (por exemplo, de 'seconds' para 'minutes') usando o comando collMod. No entanto, não é possível reduzi-la — o MongoDB retornará um erro se você tentar passar de 'minutes' para 'seconds'. Também é possível atualizar a configuração expireAfterSeconds por meio de collMod, sem recriar a collection.

As collections de séries temporais têm algumas restrições importantes em comparação com collections comuns. Não é possível fragmentar uma collection de séries temporais usando apenas o timeField — é necessário um componente metaField com hash. As atualizações e exclusões são limitadas: antes do MongoDB 5.1, só eram permitidas exclusões por metaField ou por intervalo de tempo. Além disso, as collections de séries temporais não oferecem suporte a índices exclusivos, índices esparsos ou collections limitadas.

Depois de criar uma collection de séries temporais, inspecione-a usando db.getCollectionInfos() para confirmar que as opções timeseries foram armazenadas corretamente. Você também pode executar db.sensorReadings.stats() para ver as estatísticas de armazenamento, incluindo o número de documentos de bucket internos que o MongoDB mantém nos bastidores.

Nesta lição, você aprendeu que: as collections de séries temporais usam um formato colunar de buckets para cargas de trabalho com alta compressão e muitas operações de acréscimo, três opções principais (timeField, metaField e granularidade) controlam como as medições são organizadas e agrupadas em buckets, e expireAfterSeconds permite a limpeza automática eficiente de dados antigos no nível do bucket. A seguir, vamos explorar em detalhes a inserção e a consulta de dados de séries temporais.