/ /

Operadores

Operadores de tuberías de agregación

Docs Home

Manual de base de datos

Referencia

Operadores

Operadores de tuberías de agregación

$dateAdd (operador de agregación)

Esta versión de la documentación está archivada y ya no recibe soporte. Para actualizar su implementación 6.0, consulte Procedimientos de actualización de MongoDB.7.0

Definición

$dateAdd

Nuevo en la versión 5.0.

Incrementa a Objeto de fecha por un número específico de unidades de tiempo.

La expresión $dateAdd tiene la siguiente sintaxis:

{
   $dateAdd: {
      startDate: <Expression>,
      unit: <Expression>,
      amount: <Expression>,
      timezone: <tzExpression>
   }
}

Devuelve una fecha.startDate puede ser cualquier expresión que se resuelva en tipo Fecha, Marca de tiempo u ObjectId. Independientemente del tipo de dato utilizado como entrada, el valor devuelto será un objeto Fecha.

Campo

Obligatorio/Opcional

Descripción

startDate

Requerido

La fecha de inicio, en UTC, de la operación de suma. El startDate puede ser cualquier expresión que se resuelva en una fecha, una marca de tiempo o un ID de objeto.

unit

Requerido

El unit se utiliza para medir el amount de tiempo añadido startDate al. El unit es una expresión que se resuelve en una de las siguientes cadenas:

year
quarter
week
month
day
hour
minute
second
millisecond

amount

Requerido

El número de units sumado startDate a.amount es una expresión que se resuelve en un entero o long.amount también puede resolverse en un decimal entero o double si ese valor se puede convertir a long sin pérdida de precisión.

timezone

Opcional

La zona horaria para realizar la operación. <tzExpression> debe ser una expresión válida que se resuelva en una cadena formateada como un identificador de zona horaria de Olsono una diferencia UTC. Si no timezone se proporciona, el resultado se muestra UTC en.

Formato

Ejemplos

Identificador de zona horaria de Olson

"America/New_York"
"Europe/London"
"GMT"

Desplazamiento UTC

+/-[hh]:[mm], e.g. "+04:45"
+/-[hh][mm], e.g. "-0530"
+/-[hh], e.g. "+03"

Para obtener más información sobre expresiones y tipos, consulte Expresiones y tipos BSON.

Comportamiento

Medición del tiempo

MongoDB sigue el uso prevalente de bases de datos y trabaja con el tiempo en UTC. La expresión dateAdd siempre toma un startDate en UTC y devuelve un resultado en UTC. Si se especifica el timezone, el cálculo se realizará utilizando el timezone especificado. La zona horaria es especialmente importante cuando un cálculo implica el horario de verano (DST).

Si el unit es un month o mayor, la operación se ajusta para tener en cuenta el último día del mes. Añadir un month el último día de octubre, por ejemplo, demuestra el ajuste del "último día del mes".

{
   $dateAdd:
      {
         startDate: ISODate("2020-10-31T12:10:05Z"),
         unit: "month",
         amount: 1
      }
}

Tenga en cuenta que la fecha devuelta, ISODate("2020-11-30T12:10:05Z"), es la 30y no la 31ya que noviembre tiene menos días que octubre.

Zona horaria

Al utilizar un identificador de zona horaria de Olson en el campo <timezone>, MongoDB aplica el Desplazamiento del horario de verano, si corresponde para la zona horaria especificada.

Por ejemplo, considera una colección sales con el siguiente documento:

 db.sales.insertOne(
  {
   "_id" : 1,
   "item" : "abc",
   "price" : 10,
   "quantity" : 2,
   "date" : ISODate("2014-01-01T08:15:39.736Z")
  }
)

La siguiente agregación ilustra cómo MongoDB gestiona la diferencia horaria del identificador de zona horaria Olson. El ejemplo utiliza los operadores $hour y para devolver las partes correspondientes del $minute date campo:

db.sales.aggregate([
{
   $project: {
      "nycHour": {
         $hour: { date: "$date", timezone: "-05:00" }
       },
       "nycMinute": {
          $minute: { date: "$date", timezone: "-05:00" }
       },
       "gmtHour": {
          $hour: { date: "$date", timezone: "GMT" }
       },
       "gmtMinute": {
          $minute: { date: "$date", timezone: "GMT" } },
       "nycOlsonHour": {
          $hour: { date: "$date", timezone: "America/New_York" }
       },
       "nycOlsonMinute": {
          $minute: { date: "$date", timezone: "America/New_York" }
       }
   }
}])

La operación devuelve el siguiente resultado:

{
   "_id": 1,
   "nycHour" : 5,
   "nycMinute" : 24,
   "gmtHour" : 10,
   "gmtMinute" : 24,
   "nycOlsonHour" : 6,
   "nycOlsonMinute" : 24
}

Ejemplos

Agregar una fecha futura

Considere una colección de pedidos de clientes con estos documentos:

db.shipping.insertMany(
  [
     { custId: 456, purchaseDate: ISODate("2020-12-31") },
     { custId: 457, purchaseDate: ISODate("2021-02-28") },
     { custId: 458, purchaseDate: ISODate("2021-02-26") }
  ]
)

El plazo de envío normal es de 3 días. Puede usar $dateAdd en una secuencia de agregación para establecer un plazo de expectedDeliveryDate 3 días en el futuro.

db.shipping.aggregate(
   [
      {
         $project:
            {
               expectedDeliveryDate:
                  {
                     $dateAdd:
                        {
                           startDate: "$purchaseDate",
                           unit: "day",
                           amount: 3
                        }
                  }
            }
       },
       {
          $merge: "shipping"
       }
    ]
 )

Después de agregar 3 días a purchaseDate con $dateAdd en la $project etapa, la etapa actualiza los documentos $merge originales expectedDeliveryDate con.

Los documentos resultantes se ven así:

{
   "_id" : ObjectId("603dd4b2044b995ad331c0b2"),
   "custId" : 456,
   "purchaseDate" : ISODate("2020-12-31T00:00:00Z"),
   "expectedDeliveryDate" : ISODate("2021-01-03T00:00:00Z")
}
{
   "_id" : ObjectId("603dd4b2044b995ad331c0b3"),
   "custId" : 457,
   "purchaseDate" : ISODate("2021-02-28T00:00:00Z"),
   "expectedDeliveryDate" : ISODate("2021-03-03T00:00:00Z")
}
{
    "_id" : ObjectId("603dd4b2044b995ad331c0b4"),
   "custId" : 458,
   "purchaseDate" : ISODate("2021-02-26T00:00:00Z"),
   "expectedDeliveryDate" : ISODate("2021-03-01T00:00:00Z")
}

Filtrar por rango de fechas

Actualice la colección shipping del último ejemplo con este código para agregar fechas de entrega a los documentos:

db.shipping.updateOne(
   { custId: 456 },
   { $set: { deliveryDate: ISODate( "2021-01-10" ) } }
)
db.shipping.updateOne(
  { custId: 457 },
  { $set: { deliveryDate:  ISODate( "2021-03-01" ) } }
)
db.shipping.updateOne(
   { custId: 458 },
   { $set: { deliveryDate:  ISODate( "2021-03-02" ) } }
)

Quieres encontrar envíos retrasados. Usa $dateAdd en una etapa $match para crear un filtro que coincida con documentos en un rango de fechas definido por un punto de partida ($purchaseDate) y un período de tiempo dado por $dateAdd.

db.shipping.aggregate(
   [
      {
         $match:
            {
               $expr:
                  {
                     $gt:
                        [ "$deliveryDate",
                          {
                             $dateAdd:
                                {
                                   startDate: "$purchaseDate",
                                   unit: "day",
                                   amount: 5
                                }
                           }
                        ]
                  }
            }
       },
       {
          $project:
             {
                _id: 0,
                custId: 1,
                purchased:
                   {
                       $dateToString:
                          {
                             format: "%Y-%m-%d",
                             date: "$purchaseDate"
                          }
                   },
                delivery:
                   {
                      $dateToString:
                         {
                            format: "%Y-%m-%d",
                            date: "$deliveryDate"
                         }
                   }
             }
       }
   ]
)

La $match etapa utiliza $gt y $dateAdd en una expresión () para comparar$expr la deliveryDate fecha real con la fecha prevista. Los documentos con fechas de entrega 5 posteriores a días a la purchaseDate fecha se $project pasan a la etapa.

La etapa $project utiliza la expresión para convertir las fechas a un formato $dateToString más legible. Sin la conversión, MongoDB devolvería la fecha en formato ISODate.

En este ejemplo solo se devuelve un registro:

{ "custId" : 456, "purchased" : "2020-12-31", "delivery" : "2021-01-10" }

Adaptarse al horario de verano

Todas las fechas se almacenan internamente en hora UTC. Cuando se especifica timezone, $dateAdd utiliza la hora local para realizar los cálculos. Los resultados se muestran en UTC.

Tiene clientes en varias zonas horarias y desea ver qué efecto podría tener el horario de verano en sus períodos de facturación si factura antes del day o del hour.

Crea esta colección de tiempos de conexión:

db.billing.insertMany(
   [
      {
         location: "America/New_York",
         login: ISODate("2021-03-13T10:00:00-0500"),
         logout: ISODate("2021-03-14T18:00:00-0500")
      },
      {
         location: "America/Mexico_City",
         login: ISODate("2021-03-13T10:00:00-00:00"),
         logout: ISODate("2021-03-14T08:00:00-0500")
      }
   ]
)

Primero agregue 1 día, luego agregue 24 horas a las login fechas en cada documento.

db.billing.aggregate(
   [
      {
         $project:
            {
               _id: 0,
               location: 1,
               start:
                  {
                     $dateToString:
                        {
                           format: "%Y-%m-%d %H:%M",
                           date: "$login"
                        }
                  },
               days:
                  {
                     $dateToString:
                        {
                           format: "%Y-%m-%d %H:%M",
                           date:
                              {
                                 $dateAdd:
                                    {
                                       startDate: "$login",
                                       unit: "day",
                                       amount: 1,
                                       timezone: "$location"
                                    }
                              }
                        }
                  },
               hours:
                  {
                     $dateToString:
                        {
                           format: "%Y-%m-%d %H:%M",
                           date:
                              {
                                 $dateAdd:
                                 {
                                    startDate: "$login",
                                    unit: "hour",
                                    amount: 24,
                                    timezone: "$location"
                                 }
                              }
                        }
                  },
               startTZInfo:
                  {
                     $dateToString:
                        {
                           format: "%Y-%m-%d %H:%M",
                           date: "$login",
                           timezone: "$location"
                        }
                  },
               daysTZInfo:
                  {
                     $dateToString:
                        {
                           format: "%Y-%m-%d %H:%M",
                           date:
                              {
                                 $dateAdd:
                                    {
                                       startDate: "$login",
                                       unit: "day",
                                       amount: 1,
                                       timezone: "$location"
                                    }
                              },
                           timezone: "$location"
                        }
                  },
               hoursTZInfo:
                  {
                     $dateToString:
                        {
                           format: "%Y-%m-%d %H:%M",
                           date:
                              {
                                 $dateAdd:
                                    {
                                       startDate: "$login",
                                       unit: "hour",
                                       amount: 24,
                                       timezone: "$location"
                                    }
                              },
                           timezone: "$location"
                        }
                  },
            }
      }
   ]
).pretty()

La expresión reformatea la salida para facilitar su lectura. Los resultados se resumen a $dateToString continuación:

Campo	New York	Ciudad de México
Inicio	2021-03-13 15:00	2021-03-13 10:00
Inicio, información de TZ	2021-03-13 10:00	2021-03-13 04:00
1 día	2021-03-14 14:00	2021-03-14 10:00
1 Día, Información de TZ	2021-03-14 10:00	2021-03-14 04:00
24 Horas	2021-03-14 15:00	2021-03-14 10:00
24 Horas, Información TZ	2021-03-14 11:00	2021-03-14 04:00

El gráfico destaca varios puntos:

Las fechas sin formato se muestran en UTC. El $login de Nueva York es UTC -5; sin embargo, las filas start, days y hours muestran la hora en UTC.
El 14de marzo marca el inicio del horario de verano en Nueva York, pero no en México. La hora calculada se ajusta cuando una ubicación cambia al horario de verano y pasa de un day a otro.
El horario de verano (DST) modifica la duración de day, no de hour. No hay horario de verano (DST) para hours. Solo hay un ajuste por horario de verano (DST) cuando la medición unit es de day o más y el cálculo cruza un cambio de horario en el timezone especificado.

Tip

$dateSubtract, $dateDiff

Volver

$covarianceSamp

$dateDiff