Docs Home

/ /

Operadores de pipeline de agregación

Docs Home

/ /

Operadores

Operadores de pipeline de agregación

Docs Home

Manual de base de datos

Referencia

Operadores

Operadores de pipeline de agregación

$convert (operador de expresión)

Esta versión de la documentación se archivó y ya no se admite. Para actualizar tu implementación de 6.0, consulta el Procedimientos de actualización de MongoDB.7.0

Definición

$convert: Convierte un valor a un tipo especificado.

Compatibilidad

Puedes usar $convert para implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

Sintaxis

$convert tiene la siguiente sintaxis:

{
 $convert:
     {
        input: <expression>,
        to: <type expression>,
        onError: <expression>,  // Optional.
        onNull: <expression>    // Optional.
      }
}

El $convert procesa un documento con los siguientes campos:

Campo

Descripción

input

El argumento puede ser cualquier expresión válida. Para obtener más información sobre las expresiones, consulta Expresiones.

to

El argumento puede ser cualquier expresión válida que se resuelva en uno de los siguientes identificadores numéricos o de cadena:

Identificador de cadena	Identificador númerico	notas
"double"	1	Para más información sobre la conversión a doble, consulte Conversión a double.
"string"	2	Para obtener más información sobre la conversión a string, consulta Conversión a una string.
"objectId"	7	Para obtener más información sobre la conversión a objectId, consulta Conversión a ObjectId.
"bool"	8	Para obtener más información sobre la conversión a booleano, consulta Conversión a booleano.
"date"	9	Para obtener más información sobre la conversión a fecha, consulta Conversión a fecha.
"int"	16	Para obtener más información sobre la conversión a números enteros, consulta Conversión a un número entero.
"long"	18	Para obtener más información sobre la conversión a long, consulte Conversión a un Long.
"Decimal"	19	Para obtener más información sobre la conversión a decimal, consulta Conversión a decimal.

onError

Opcional. El valor que se debe devolver al producirse un error durante la conversión, incluidas las conversiones de tipos no admitidas. Los argumentos pueden ser cualquier expresiónválida.

Si no se especifica, la operación arroja un error al encontrar un error y se detiene.

onNull

Opcional. El valor a devolver si input es nulo o falta. Los argumentos pueden ser cualquier expresión válida.

Si no se especifica, $convert devuelve nulo si input está nulo o no está presente.

Además de $convert, MongoDB proporciona los siguientes operadores de agregación como atajo cuando el comportamiento por defecto "onError" y "onNull" es aceptable:

Comportamiento

Conversión a un booleano

La siguiente tabla enumera los tipos de entrada que se pueden convertir a un valor booleano:

Tipo de entrada	Comportamiento
Arreglo	Devuelve verdadero
Datos binarios	Devuelve verdadero
Booleano	Sin-op. Devuelve el valor booleano.
Código	Devuelve verdadero
fecha	Devuelve verdadero
Decimal	Returns true if not zero Return false if zero
Double	Returns true if not zero Return false if zero
entero	Returns true if not zero Return false if zero
JavaScript	Devuelve verdadero
Long	Returns true if not zero Return false if zero
Clave máxima	Devuelve verdadero
MinKey	Devuelve verdadero
Nulo	Devuelve el valor especificado para la opción `onNull`. Por defecto, devuelve null.
Objeto	Devuelve verdadero
ObjectId	Devuelve verdadero
Expresión regular	Devuelve verdadero
String	Devuelve verdadero
Marca de tiempo	Devuelve verdadero

Para obtener más información sobre los tipos de datos en MongoDB, consulta BSON Types.

La siguiente tabla enumera algunos ejemplos de conversión a valores booleanos:

Ejemplo

Resultados

{ input: true, to: "bool" }

true

{ input: false, to: "bool" }

false

{ input: 1.99999, to: "bool" }

true

{ input: Decimal128( "5" ), to: "bool" }

true

{ input: Decimal128( "0" ), to: "bool" }

false

{ input: 100, to: "bool" }

true

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "bool"
}

true

{ input: "hello", to: "bool" }

true

{ input: "false", to: "bool" }

true

{ input: "", to: "bool" }

true

{ input: null, to: "bool" }

Nulo

Tip

$toBool

Conversión a un entero

La siguiente tabla enumera los tipos de entrada que se pueden convertir a un número entero:

Tipo de entrada	Comportamiento
Booleano	Returns `0` for `false`. Returns `1` for `true`.
Double	Retorna un valor truncado. El valor double truncado debe estar dentro del valor mínimo y máximo para un número entero. No se puede convertir un valor doble cuyo valor truncado sea menor que el valor entero mínimo o mayor que el valor entero máximo.
Decimal	Retorna un valor truncado. El valor decimal truncado debe encontrarse dentro del valor mínimo y máximo de un entero. No puedes convertir un valor decimal cuyo valor truncado sea menor que el valor entero mínimo o mayor que el valor entero máximo.
entero	Sin operación. Devuelve el valor entero.
Long	Devuelve el valor largo como un entero. El valor largo debe estar dentro del valor mínimo y máximo para un entero. No se puede convertir un valor largo que sea menor que el valor entero mínimo o mayor que el valor entero máximo.
String	Devuelve el valor numérico de la cadena como un entero. El valor de la string debe ser un número entero en base ₁₀ (por ejemplo, `"-5"`, `"123456"`) y se ajusta al valor mínimo y máximo de un entero. No se puede convertir un valor string de un número decimal o de punto flotante, ni tampoco de un número que no sea en base ₁₀ (por ejemplo, `"-5.0"`, `"0x6400"`) o un valor que está fuera del valor mínimo y máximo para un número entero.

La siguiente tabla enumera algunos ejemplos de conversión a números enteros:

Ejemplo

Resultados

{ input: true, to: "int" }

{ input: false, to: "int" }

{ input: 1.99999, to: "int" }

{ input: Decimal128( "5.5000" ), to: "int" }

{
   input: Decimal128( "9223372036000.000" ),
   to: "int"
}

Error

{ input: Long( "5000" ), to: "int" }

5000

{ input: Long( "922337203600" ), to: "int" }

Error

{ input: "-2", to: "int" }

-2

{ input: "2.5", to: "int" }

Error

{ input: null, to: "int" }

Nulo

Tip

$toInt operador.

Conversión a decimal

La siguiente tabla enumera los tipos de entrada que se pueden convertir a decimal:

Tipo de entrada	Comportamiento
Booleano	Returns `Decimal128( "0" )` for `false`. Returns `Decimal128( "1" )` for `true`.
Double	Devuelve el valor double como un decimal.
Decimal	Sin-op. Devuelve el decimal.
entero	Devuelve el valor int como decimal.
Long	Devuelve el valor largo como decimal.
String	Devuelve el valor numérico de la string como un número decimal. El valor de la cadena debe ser un valor numérico base _{10 (por} `"-5.5"` `"123456"`ejemplo,,). No puedes convertir un valor de string de un número que no sea de ₁₀ como base (por ejemplo, `"0x6400"`)
fecha	Devuelve la cantidad de milisegundos desde la Unix epoch que corresponde al valor de la fecha.

La siguiente tabla enumera algunos ejemplos de conversión a decimales:

Ejemplo

Resultados

{ input: true, to: "decimal" }

Decimal128("1")

{ input: false, to: "decimal" }

Decimal128("0")

{ input: 2.5, to: "decimal" }

Decimal128( "2.50000000000000" )

{ input: Int32( 5 ), to: "decimal" }

Decimal128("5")

{ input: Long( 10000 ), to: "decimal" }

Decimal128("10000")

{ input: "-5.5", to: "decimal" }

Decimal128("-5.5")

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "decimal"
}

Decimal128("1522039108044")

Tip

$toDecimal

Conversión a Double

La siguiente tabla enumera los tipos de entrada que se pueden convertir a doble:

Tipo de entrada	Comportamiento
Booleano	Returns NumberDouble(0) for `false`. Returns NumberDouble(1) for `true`.
Double	Sin operación. Devuelve el double.
Decimal	Devuelve el valor decimal como un double. El valor decimal debe estar dentro del valor mínimo y máximo para un double. No se puede convertir un valor decimal cuyo valor sea menor que el valor doble mínimo o mayor que el valor doble máximo.
entero	Devuelve el valor int como un double.
Long	Devuelve el valor largo como un double.
String	Retorna el valor numérico de la string como un doble. El valor de cadena debe ser un valor numérico en base ₁₀ (ejemplo, `"-5.5"`, `"123456"`) y debe estar en el rango del valor mínimo al máximo para un double. No se puede convertir un valor de cadena de un número que no sea de _{base 10 (por} `"0x6400"` ejemplo,) o un valor que esté fuera del valor mínimo y máximo para un doble.
fecha	Devuelve la cantidad de milisegundos desde la Unix epoch que corresponde al valor de la fecha.

La siguiente tabla enumera algunos ejemplos de conversión a doble:

Ejemplo

Resultados

{ input: true, to: "double" }

{ input: false, to: "double" }

{ input: 2.5, to: "double" }

2.5

{ input: Int32( 5 ), to: "double" }

{ input: Long( "10000" ), to: "double" }

10000

{ input: "-5.5", to: "double" }

-5.5

{ input: "5e10", to: "double" }

50.000.000.000

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "double"
}

1522039108044

Tip

$toDouble

Conversión a un Long

La siguiente tabla enumera los tipos de entrada que pueden convertirse a un "long":

Tipo de entrada	Comportamiento
Booleano	Returns `0` for `false`. Returns `1` for `true`.
Double	Retorna un valor truncado. El valor double truncado debe estar dentro del valor mínimo y máximo para un largo. No se puede convertir un valor double cuyo valor truncado es inferior al valor mínimo de long o superior al valor máximo de long.
Decimal	Retorna un valor truncado. El valor decimal truncado debe estar dentro del valor mínimo y máximo para un entero largo. No puedes convertir un valor decimal cuyo valor truncado sea inferior al valor mínimo de long o supere el valor máximo de long.
entero	Devuelve el valor int como un long.
Long	No opera. Devuelve el valor largo.
String	Devuelve el valor numérico de la string. El valor de la string debe ser un entero largo decimal ₁₀ (p. ej. `"-5"`, `"123456"`) y se encuentra dentro del valor mínimo y máximo para un long. No se puede convertir un valor en string de un flotante, decimal o número que no sea base ₁₀ (por ejemplo, `"-5.0"`, `"0x6400"`) o un valor que caiga fuera del valor mínimo y máximo para un long.
fecha	Convierte la fecha en el número de milisegundos transcurridos desde la Unix epoch.

La siguiente tabla enumera algunos ejemplos de conversión a largos:

Ejemplo

Resultados

{ input: true, to: "long" }

Long("1")

{ input: false, to: "long"  }

Largo("0")

{ input: 2.5, to: "long"  }

Largo("2")

{ input: Decimal128( "5.5000" ), to: "long" }

Prolongado ("5")

{
   input: Decimal128( "9223372036854775808.0" ),
   to: "long"
}

Error

{ input: Int32( 8 ), to: "long" }

Largo("8")

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "long"
}

Long("1522039108044")

{ input: "-2", to: "long" }

large("-2")

{ input: "2.5", to: "long" }

Error

{ input: null, to: "long" }

Nulo

Tip

$toLong

Conversión a una fecha

La siguiente tabla enumera los tipos de entrada que se pueden convertir a una fecha:

Tipo de entrada	Comportamiento
Double	Devuelve una fecha que corresponde a la cantidad de milisegundos representados por el valor doble truncado. Un número positivo corresponde al número de milisegundos desde el 1 de enero de 1970. El número negativo corresponde al número de milisegundos antes del 1 de enero de 1970.
Decimal	Devuelve una fecha que corresponde a la cantidad de milisegundos representados por el valor decimal truncado. Un número positivo corresponde al número de milisegundos desde el 1 de enero de 1970. El número negativo corresponde al número de milisegundos antes del 1 de enero de 1970.
Long	Devuelve una fecha que corresponde al número de milisegundos representados por el valor long. Un número positivo corresponde al número de milisegundos desde el 1 de enero de 1970. El número negativo corresponde al número de milisegundos antes del 1 de enero de 1970.
String	Devuelve una fecha que corresponde a la string de fecha. La string debe ser una string de fecha válida, como: "03-03-2018" "2018-03-03T12:00:00Z" "2018-03-03T12:00:00+0500"
ObjectId	Devuelve una fecha que corresponde a la marca de tiempo del ObjectId.
Marca de tiempo	Devuelve una fecha que corresponde a la marca de tiempo.

La siguiente tabla enumera algunos ejemplos de conversión a fecha:

Ejemplo

Resultados

{
   input: 120000000000.5,
   to: "date"
}

ISODate("1973-10-20T21:20:00.000Z")

{
   input: Decimal128( "1253372036000.50" ),
   to: "date"
}

ISODate("2009-09-19T14:53:56.000Z")

{
   input: Long( "1100000000000" ),
   to: "date
}

Fecha ISO("2004-11-09T11:33:20.000Z")

{
   input:  Long( "-1100000000000" ),
   to: "date"
}

Fecha ISO("1935-02-22T12:26:40.000Z")

{
   input: ObjectId( "5ab9c3da31c2ab715d421285" ),
   to: "date"
}

ISODate("2018-03-27T04:08:58.000Z")

{ input:  "2018-03-03", to: "date" }

ISODate("2018-03-03T00:00:00.000Z")

{
   input: "2018-03-20 11:00:06 +0500",
   to: "date"
}

ISODate("2018-03-20T06:00:06.000Z")

{ input: "Friday", to: "date" }

Error

{
   input: Timestamp( { t: 1637688118, i: 1 } ),
   to: "date"
}

Fecha ISO("2021-11-23T17:21:58.000Z")

Tip

$toDate operador
$dateFromString

Convirtiendo a un ObjectId

La siguiente tabla enumera los tipos de entrada que se pueden convertir en un ObjectId:

Tipo de entrada	Comportamiento
String	Devuelve un ObjectId para la string hexadecimal de 24 caracteres. No puedes convertir un valor de string que no sea una string hexadecimal de longitud 24.

La siguiente tabla enumera algunos ejemplos de conversión a fecha:

Ejemplo

Resultados

{
   input: "5ab9cbfa31c2ab715d42129e",
   to: "objectId"
}

ObjectId("5ab9cbfa31c2ab715d42129e")

{
   input: "5ab9cbfa31c2ab715d42129",
   to: "objectId"
}

Error

Tip

$toObjectId operador.

Convertir a un String

La siguiente tabla enumera los tipos de entrada que se pueden convertir en una cadena:

Tipo de entrada	Comportamiento
Booleano	Devuelve el valor booleano como una cadena.
Double	Devuelve el valor double como una string.
Decimal	Devuelve el valor decimal como una string.
entero	Devuelve el valor entero como una string.
Long	Devuelve el valor largo como una cadena.
ObjectId	Devuelve el valor de ObjectId como una string hexadecimal.
String	Sin-op. Devuelve el valor de string.
fecha	Devuelve la fecha como una string.

La siguiente tabla enumera algunos ejemplos de conversión a string:

Ejemplo

Resultados

{ input: true, to: "string" }

"true"

{ input: false, to: "string" }

"FALSO"

{ input: 2.5, to: "string" }

"2,5"

{ input: Int32( 2 ), to: "string" }

"2"

{ input:  Long( 1000 ), to: "string" }

"1000"

{
   input: ObjectId( "5ab9c3da31c2ab715d421285" ),
   to: "string"
}

"5ab9c3da31c2ab715d421285"

{
   input:  ISODate( "2018-03-27T16:58:51.538Z" ),
   to: "string"
}

"2018-03-27T16:58:51.538Z"

Tip

$toString operador
$dateToString

Ejemplo

Cree una colección orders con los siguientes documentos:

db.orders.insertMany( [
   { _id: 1, item: "apple", qty: 5, price: 10 },
   { _id: 2, item: "pie", qty: 10, price: Decimal128("20.0") },
   { _id: 3, item: "ice cream", qty: 2, price: "4.99" },
   { _id: 4, item: "almonds" },
   { _id: 5, item: "bananas", qty: 5000000000, price: Decimal128("1.25") }
] )

La siguiente operación de agregación en la colección orders convierte el price en decimal:

// Define stage to add convertedPrice and convertedQty fields with
//    the converted price and qty values.
// If price or qty values are missing, the conversion returns a
//    value of decimal value or int value of 0.
// If price or qty values cannot be converted, the conversion returns
//    a string
priceQtyConversionStage = {
   $addFields: {
      convertedPrice: { $convert:
         {
            input: "$price",
            to: "decimal",
            onError: "Error",
            onNull: Decimal128("0")
         } },
      convertedQty: { $convert:
         {
            input: "$qty",
            to: "int",
            onError:{ $concat:
               [
                  "Could not convert ",
                  { $toString:"$qty" },
                  " to type integer."
               ]
            },
         onNull: Int32("0")
      } },
   }
};
totalPriceCalculationStage = {
   $project: { totalPrice: {
     $switch: {
        branches: [
          { case:
             { $eq: [ { $type: "$convertedPrice" }, "string" ] },
             then: "NaN"
          },
          { case:
             { $eq: [ { $type: "$convertedQty" }, "string" ] },
             then: "NaN"
          },
        ],
        default: { $multiply: [ "$convertedPrice", "$convertedQty" ] }
     }
} } };
db.orders.aggregate( [
   priceQtyConversionStage,
   totalPriceCalculationStage
])

La operación devuelve los siguientes documentos:

{ _id: 1, totalPrice: Decimal128("50") },
{ _id: 2, totalPrice: Decimal128("200.0") },
{ _id: 3, totalPrice: Decimal128("9.98") },
{ _id: 4, totalPrice: Decimal128("0") },
{ _id: 5, totalPrice: 'NaN' }

Nota

Estos ejemplos utilizan mongosh. Los tipos por defecto son diferentes en la shell heredada mongo.

Volver

$cond

$cos