/ /

Crear y ejecutar un query en una colección de series de tiempo

Esta página muestra cómo crear y consultar una colección de series de tiempo, con ejemplos de código.

Importante

Requisito de compatibilidad de características entre versiones

Solo se pueden crear colecciones de series temporales en un sistema con featureCompatibilityVersion establecida 5.0 en o mayor.

Crear una colección de series de tiempo

Definir el timeField como el campo que contiene datos de tiempo y metaField como el campo que contiene metadatos:

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

En este ejemplo, timestamp es el nombre del timeField y metadata es el nombre del metaField. El valor del campo timestamp debe ser de tipo fecha.

Importante

Elegir el metaField correcto para la colección optimiza tanto el almacenamiento como el rendimiento del query. Para obtener más información sobre la selección de metaField y las mejores prácticas, se puede consultar metaFields.

Defina el intervalo de tiempo para cada grupo de datos utilizando uno de los dos enfoques siguientes:

Importante

Cambiar los intervalos de las series de tiempo

Tras la creación, puede modificar la granularidad o las definiciones de los buckets mediante el collMod método. Sin embargo, solo puede aumentar el intervalo de tiempo que abarca cada bucket. No puede reducirlo.

Definir un campo granularity:
```
{
   granularity: "seconds"
}
```
Para obtener información más detallada sobre cómo seleccionar un valor granularity, se puede consultar Consideraciones sobre la granularidad.

Define los campos bucketMaxSpanSeconds y bucketRoundingSeconds. Ambos valores deben ser iguales:
```
{
   bucketMaxSpanSeconds: 300,
   bucketRoundingSeconds: 300
}
```

Opcionalmente, configure expireAfterSeconds para que los documentos caduquen cuando el valor de timeField tenga al menos esa antigüedad:

{
   expireAfterSeconds: 86400
}

Cree la colección con el métododb.createCollection()o el comandocreate. El siguiente ejemplo utiliza el métododb.createCollection()para crear una colección de series temporales weather:

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

Referencia de campo de series de tiempo

Una colección de series de tiempo incluye los siguientes campos:

Campo	Tipo	Descripción
`timeseries.timeField`	string	Requerido. El nombre del campo que contiene la fecha en cada documento de serie de tiempo. Los documentos en una colección de series de tiempo deben tener una fecha BSON válida como valor para el `timeField`.
`timeseries.metaField`	string	Opcional. El nombre del campo que contiene los metadatos en cada documento de serie de tiempo. Los metadatos del campo especificado deben ser datos que se utilicen para etiquetar una serie única de documentos. Los metadatos difícilmente cambien. El nombre del campo especificado no puede ser `_id` ni el mismo que el `timeseries.timeField`. El campo puede ser de cualquier tipo de dato. Aunque el campo `metaField` es opcional, el uso de metadatos puede mejorar la optimización de query. Por ejemplo, MongoDB crea un índice compuesto automáticamente en los campos `metaField` y `timeField` para las nuevas colecciones. Si no proporcionas un valor para este campo, los datos se agrupan únicamente en función del tiempo.
`timeseries.granularity`	entero	Opcional. No utilice si se configuran `bucketRoundingSeconds` y `bucketMaxSpanSeconds`. Los valores posibles son `seconds` (por defecto), `minutes` y `hours`. Configure `granularity` al valor que más se asemeje al intervalo de tiempo entre las marcas de tiempo entrantes consecutivas. Esto mejora el rendimiento al optimizar cómo MongoDB almacena los datos en la colección. Para obtener más información sobre la granularidad y los intervalos de agrupación, consulta Configurar granularidad para datos de series de tiempo.
`timeseries.bucketMaxSpanSeconds`	entero	Opcional. Utilice con `bucketRoundingSeconds` como alternativa a `granularity`. Establece el tiempo máximo entre marcas de tiempo en el mismo bucket. Los valores posibles son de 1 a 31536000. Nuevo en la versión 6.3.
`timeseries.bucketRoundingSeconds`	entero	Opcional. Utilice con `bucketMaxSpanSeconds` como alternativa a `granularity`. Debe ser igual a `bucketMaxSpanSeconds`. Cuando un documento requiere un nuevo bucket, MongoDB redondea hacia abajo el valor de la marca de tiempo del documento según este intervalo para establecer el tiempo mínimo para el bucket. Nuevo en la versión 6.3.
`expireAfterSeconds`	entero	Opcional. Activa la eliminación automática de los documentos en una colección de series de tiempo y especifica la cantidad de segundos tras los cuales caducan los documentos. MongoDB borra automáticamente los documentos caducados. Consulta Configurar la eliminación automática para las colecciones de series de tiempo (TTL) para obtener más información.

Estas son otras opciones permitidas que no son específicas de las colecciones de series de tiempo:

storageEngine
indexOptionDefaults
collation
writeConcern
comment

Tip

Consulte:

db.createCollection() y.create

Inserta medidas en una colección de series de tiempo

Cada documento que inserte debe contener una sola medida. Para insertar varios documentos a la vez, ejecute el siguiente 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 insertar un solo documento, utiliza el método db.collection.insertOne().

Tip

Optimiza el rendimiento de inserción

Para aprender cómo optimizar las inserciones para grandes operaciones, se puede consultar Mejores prácticas sobre inserciones.

Realiza queries a una colección de series de tiempo

Realizas un query en una colección de series de tiempo de la misma manera que realizas un query en una colección de MongoDB estándar.

Para devolver un documento de una colección de series de tiempo, ejecute:

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

Ejemplo de salida:

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

Para obtener más información sobre los queries de serie de tiempo, se puede consultar Mejores prácticas sobre queries.

Ejecuta agregaciones en una colección de series de tiempo

Para obtener una funcionalidad de consulta adicional, utilice una canalización de agregación 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" }
      }
   }
] )

La canalización de agregación de ejemplo agrupa todos los documentos por la fecha de la medición y luego devuelve el promedio de todas las mediciones de temperatura de ese día:

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

Volver

Crear y Configurar

Configurar la granularidad