$convert (aggregation)

Definition

• $convert

New in version 4.0.

Converts a value to a specified type.

$convert has the following syntax:

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

The $convert takes a document with the following fields:

FieldDescriptioninputThe argument can be any valid expression. For more information onexpressions, see Expressions.toThe argument can be any valid expression that resolves to one of the following numericor string identifiers:

String IdentifierNumeric IdentifierNotes“double”1For more information on the conversion to double, seeConverting to a Double.“string”2For more information on the conversion to string, seeConverting to a String.“objectId”7For more information on the conversion to objectId, seeConverting to an ObjectId.“bool”8For more information on the conversion to boolean, seeConverting to a Boolean.“date”9For more information on the conversion to date, seeConverting to a Date.“int”16For more information on the conversion to integer, seeConverting to an Integer.“long”18For more information on the conversion to long, seeConverting to a Long.“decimal”19For more information on the conversion to decimal, seeConverting to a Decimal.

onErrorOptional. The value to return on encountering an error duringconversion, including unsupported type conversions. Thearguments can be any valid expression.

If unspecified, the operation throws an error uponencountering an error and stops.onNullOptional. The value to return if the input is null or missing.The arguments can be any valid expression.

If unspecified, $convert returns null if theinput is null or missing.

In addition to $convert, MongoDB provides thefollowing aggregation operators as shorthand when the default“onError” and “onNull” behavior is acceptable:

• $toBool
• $toDate
• $toDecimal
• $toDouble
• $toInt
• $toLong
• $toObjectId
• $toString

Behavior

Converting to a Boolean

The following table lists the input types that can be converted to aboolean:

The following table lists some conversion to boolean examples:

{ input: true, to: "bool"}

{ input: false, to: "bool" }

{ input: 1.99999, to: "bool" }

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

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

{ input: 100, to: "bool" }

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

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

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

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

{ input: null, to: "bool" }

See also

$toBool

Converting to an Integer

The following table lists the input types that can be converted to aninteger:

The following table lists some conversion to integer examples:

{ input: true, to: "int"}

{ input: false, to: "int" }

{ input: 1.99999, to: "int" }

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

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

{   input: NumberDecimal("9223372036000.000"),   to: "int",   onError: "Could not convert to type integer."}

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

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

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

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

{ input: null, to: "int" }

See also

$toInt operator.

Converting to a Decimal

The following table lists the input types that can be converted to adecimal:

The following table lists some conversion to decimal examples:

{ input: true, to: "decimal"}

{ input: false, to: "decimal" }

{ input: 2.5, to: "decimal" }

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

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

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

{ input: ISODate("2018-03-27T05:04:47.890Z"), to: "decimal" }

See also

$toDecimal

Converting to a Double

The following table lists the input types that can be converted to adouble:

The following table lists some conversion to double examples:

{ input: true, to: "double"}

{ input: false, to: "double" }

{ input: 2.5, to: "double" }

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

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

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

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

{   input: "5e550",   to: "double",   onError: "Could not convert to type double."}

{ input: ISODate("2018-03-27T05:04:47.890Z"), to: "double" }

See also

$toDouble

Converting to a Long

The following table lists the input types that can be converted to along:

The following table lists some conversion to long examples:

{ input: true, to: "long" }

{ input: false, to: "long"  }

{ input: 1.99999, to: "long"  }

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

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

{   input: NumberDecimal("9223372036854775808.000"),   to: "long",   onError: "Could not convert to type long."}

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

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

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

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

{ input: null, to: "long" }

See also

$toLong

Converting to a Date

The following table lists the input types that can be converted to adate:

The following table lists some conversion to date examples:

{ input: 120000000000.5, to: "date"}

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

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

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

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

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

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

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

{   input: "Friday",   to: "date",   onError: "Could not convert to type date."}

See also

$toDate operator, $dateFromString

Converting to an ObjectId

The following table lists the input types that can be converted to anObjectId:

The following table lists some conversion to date examples:

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

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

{   input: "5ab9cbfa31c2ab715d42129",   to: "objectid",   onError: "Could not convert to type ObjectId."}

See also

$toObjectId operator.

Converting to a String

The following table lists the input types that can be converted to astring:

The following table lists some conversion to string examples:

{ input: true, to: "string" }

{ input: false, to: "string"  }

{ input: 2.5, to: "string"}

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

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

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

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

See also

$toString operator. $dateToString

Example

Create a collection orders with the following documents:

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

The following aggregation operation on the orders collectionconverts the price to a 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: NumberDecimal("0") } },
      convertedQty: { $convert: {
         input: "$qty", to: "int",
         onError:{$concat:["Could not convert ", {$toString:"$qty"}, " to type integer."]},
         onNull: NumberInt("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
])

The operation returns the following documents:

{ "_id" : 1, "totalPrice" : NumberDecimal("50.0000000000000") }
{ "_id" : 2, "totalPrice" : NumberDecimal("200.0") }
{ "_id" : 3, "totalPrice" : NumberDecimal("9.98") }
{ "_id" : 4, "totalPrice" : NumberDecimal("0") }
{ "_id" : 5, "totalPrice" : "NaN" }