Criar e consultar uma coleção de séries temporais

Nesta página

Crie uma coleção de séries temporais

Inserir medições em uma Coleção de séries temporais
Consultar uma Coleta de Seqüência Temporal
Execute agregações em uma Coleção de séries temporais

Esta página mostra como criar e consultar uma coleção de séries temporais, com exemplos de código.

Importante

Requisitos da versão de compatibilidade de recursos

Você só pode criar coleções de séries temporais em um sistema com featureCompatibilityVersion definido como 5.0 ou superior.

Crie uma coleção de séries temporais

Defina o timeField como o campo que contém dados de tempo e o metaField como o campo que contém metadados:

{
   timeField: "timestamp",
   metaField: "metadata"
}

Neste exemplo, timestamp é o nome do timeField e metadata é o nome do metaField. O valor do campo timestamp deve ser do tipo data.

Importante

Escolher o metaField certo para sua coleção otimiza o desempenho do armazenamento e da consulta. Para obter mais informações sobre a seleção de metaField e as melhores práticas, consulte MetaFields.

Defina o intervalo de tempo de cada bucket de dados utilizando uma das duas abordagens abaixo:

Importante

Alterando intervalos de série temporal

Após a criação, você pode modificar a granularidade ou as definições de bucket usando o método collMod. No entanto, você só pode aumentar o intervalo de tempo coberto por cada bucket. Você não pode diminuí-lo.

Definir um campo granularity:
```
{
   granularity: "seconds"
}
```
Para obter informações mais detalhadas sobre a seleção de um valor granularity, consulte Considerações sobre granularidade.

No MongoDB 6.3 e superior, você pode definir os campos bucketMaxSpanSeconds e bucketRoundingSeconds. Ambos os valores devem ser iguais:
```
{
   bucketMaxSpanSeconds: "300",
   bucketRoundingSeconds: "300"
}
```

Opcionalmente, defina expireAfterSeconds para expirar documentos quando o valor de timeField for pelo menos aquele antigo:

{
   expireAfterSeconds: 86400
}

Crie a collection utilizando o método db.createCollection() ou o comando create. O exemplo a seguir utiliza o método db.createCollection() para criar uma coleção de séries temporais weather:

db.createCollection(
   "weather",
   {
      timeseries: {
         timeField: "timestamp",
         metaField: "metadata",
         granularity: "seconds"
      },
      expireAfterSeconds: 86400
   }
)

Time Series Field Reference

Uma coleção de séries temporais inclui os seguintes campos:

Campo	Tipo	Descrição
`timeseries.timeField`	string	Obrigatório. O nome do campo que contém a data em cada documento da série temporal. Os documentos em uma collection de séries temporais devem ter uma data BSON válida como o valor do `timeField`.
`timeseries.metaField`	string	Opcional. O nome do campo que contém metadados em cada documento de série temporal. Os metadados no campo especificado devem ser dados utilizados para rotular uma série exclusiva de documentos. Os metadados raramente devem mudar. O nome do campo especificado não pode ser `_id` ou o mesmo que o `timeseries.timeField`. O campo pode ser de qualquer tipo de dados. Embora o campo `metaField` seja opcional, o uso de metadados pode melhorar a otimização da query. Por exemplo, o MongoDB cria automaticamente um índice composto nos campos `metaField` e `timeField` para novas collections. Se você não fornecer um valor para este campo, os dados serão agrupados exclusivamente com base no tempo.
`timeseries.granularity`	inteiro	Opcional. Não use se estiver configurando `bucketRoundingSeconds` e `bucketMaxSpanSeconds`. Os valores possíveis são `seconds` (padrão), `minutes` e `hours`. Defina `granularity` como o valor que mais se aproxima do tempo entre carimbos de data/hora consecutivos de entrada. Isso melhora o desempenho otimizando a forma como o MongoDB armazena dados na collection. Para obter mais informações sobre granularidade e intervalos de bucket, consulte Definir granularidade para dados de séries temporais.
`timeseries.bucketMaxSpanSeconds`	inteiro	Opcional. Use com `bucketRoundingSeconds` como alternativa a `granularity`. Define o tempo máximo entre os carimbos de data/hora no mesmo bloco. Os valores possíveis são 1-31536000. Novidades na versão 6.3.
`timeseries.bucketRoundingSeconds`	inteiro	Opcional. Use com `bucketMaxSpanSeconds` como alternativa a `granularity`. Deve ser igual a `bucketMaxSpanSeconds`. Quando um documento requer um novo bucket, o MongoDB arredonda para baixo o valor de carimbo de data/hora do documento por esse intervalo para definir o tempo mínimo para o bucket. Novidades na versão 6.3.
`expireAfterSeconds`	inteiro	Opcional. Ative a exclusão automática de documentos em uma coleção de séries temporais especificando o número de segundos após os quais os documentos expiram. O MongoDB exclui documentos expirados automaticamente. Consulte Configurar remoção automática para Coleções de séries temporais (TTL) para obter mais informações.

Outras opções permitidas que não são específicas para coleções de séries temporais são:

storageEngine
indexOptionDefaults
collation
writeConcern
comment

Dica

Consulte:

db.createCollection() e create.

Inserir medições em uma Coleção de séries temporais

Cada documento inserido deve conter uma única medida. Para inserir vários documentos de uma só vez, emita o seguinte comando:

db.weather.insertMany( [
   {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: ISODate("2021-05-18T00:00:00.000Z"),
      temp: 12
   },
   {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: ISODate("2021-05-18T04:00:00.000Z"),
      temp: 11
   },
   {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: ISODate("2021-05-18T08:00:00.000Z"),
      temp: 11
   },
   {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: ISODate("2021-05-18T12:00:00.000Z"),
      temp: 12
   },
   {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: ISODate("2021-05-18T16:00:00.000Z"),
      temp: 16
   },
   {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: ISODate("2021-05-18T20:00:00.000Z"),
      temp: 15
   },
   {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: ISODate("2021-05-19T00:00:00.000Z"),
      temp: 13
   },
   {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: ISODate("2021-05-19T04:00:00.000Z"),
      temp: 12
   },
   {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: ISODate("2021-05-19T08:00:00.000Z"),
      temp: 11
   },
   {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: ISODate("2021-05-19T12:00:00.000Z"),
      temp: 12
   },
   {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: ISODate("2021-05-19T16:00:00.000Z"),
      temp: 17
   },
   {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: ISODate("2021-05-19T20:00:00.000Z"),
      temp: 12
   }
] )

Para inserir um único documento, use o método db.collection.insertOne().

Dica

Otimize o desempenho da inserção

Para saber como otimizar inserções para grandes operações, consulte as melhores práticas de inserções.

Consultar uma Coleta de Seqüência Temporal

Você consulta uma coleção de séries temporais da mesma maneira que consulta uma coleção MongoDB padrão.

Para retornar um documento de uma coleção de séries temporais, execute:

db.weather.findOne( {
   timestamp: ISODate("2021-05-18T00:00:00.000Z")
} )

Saída de exemplo:

{
   timestamp: ISODate("2021-05-18T00:00:00.000Z"),
   metadata: { sensorId: 5578, type: 'temperature' },
   temp: 12,
   _id: ObjectId("62f11bbf1e52f124b84479ad")
}

Para obter mais informações sobre queries de série temporal, consulte Práticas recomendadas de query.

Execute agregações em uma Coleção de séries temporais

Para funcionalidade de query adicional, use um aggregation pipeline como:

db.weather.aggregate( [
   {
      $project: {
         date: {
            $dateToParts: { date: "$timestamp" }
         },
         temp: 1
      }
   },
   {
      $group: {
         _id: {
            date: {
               year: "$date.year",
               month: "$date.month",
               day: "$date.day"
            }
         },
         avgTmp: { $avg: "$temp" }
      }
   }
] )

O exemplo de aggregation pipeline grupos todos os documentos pela data da medição e, em seguida, retorna a média de todas as medições de temperatura daquele dia:

 {
  "_id" : {
    "date" : {
      "year" : 2021,
      "month" : 5,
      "day" : 18
    }
  },
  "avgTmp" : 12.714285714285714
}
{
  "_id" : {
    "date" : {
      "year" : 2021,
      "month" : 5,
      "day" : 19
    }
  },
  "avgTmp" : 13
}

Voltar

Criar e configurar

Definir granularidade