Navigation

$convert (aggregation)

On this page

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:

Field Description
input The argument can be any valid expression. For more information on expressions, see Expressions.
to

The argument can be any valid expression that resolves to one of the following numeric or string identifiers:

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

Optional. The value to return on encountering an error during conversion, including unsupported type conversions. The arguments can be any valid expression.

If unspecified, the operation throws an error upon encountering an error and stops.

onNull

Optional. The value to return if the input is null or missing. The arguments can be any valid expression.

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

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

Behavior

Converting to a Boolean

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

Input Type Behavior
Boolean No-op. Returns the boolean value.
Double
Returns true if not zero.
Return false if zero.
Decimal
Returns true if not zero.
Return false if zero.
Integer
Returns true if not zero.
Return false if zero.
Long
Returns true if not zero.
Return false if zero.
ObjectId
Returns true.
String
Returns true.
Date
Returns true.

The following table lists some conversion to boolean examples:

Example Results
{ input: true, to: "bool"}
true
{ input: false, to: "bool" }
false
{ input: 1.99999, to: "bool" }
true
{ input: NumberDecimal("5"), to: "bool"}
true
{ input: NumberDecimal("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" }
null

See also

$toBool

Converting to an Integer

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

Input Type Behavior
Boolean
Returns 0 for false.
Returns 1 for true.
Double

Returns truncated value.

The truncated double value must fall within the minimum and maximum value for an integer.

You cannot convert a double value whose truncated value is less than the minimum integer value or is greater than the maximum integer value.

Decimal

Returns truncated value.

The truncated decimal value must fall within the minimum and maximum value for an integer.

You cannot convert a decimal value whose truncated value is less than the minimum integer value or is greater than the maximum integer value.

Integer No-op. Returns the integer value.
Long

Returns the long value as an integer.

The long value must fall within the minimum and maximum value for an integer.

You cannot convert a long value that is less than the minimum integer value or is greater than the maximum integer value.

String

Returns the numerical value of the string as an integer.

The string value must be a base10 integer (e.g. "-5", "123456") and fall within the minimum and maximum value for an integer.

You cannot convert a string value of a float or decimal or non-base10 number (e.g. "-5.0", "0x6400") or a value that falls outside the minimum and maximum value for an integer.

The following table lists some conversion to integer examples:

Example Results
{ input: true, to: "int"}
1
{ input: false, to: "int" }
0
{ input: 1.99999, to: "int" }
1
{ input: NumberDecimal("5.5000"), to: "int"}
5
{ input: NumberDecimal("9223372036000.000"), to: "int"}
Error
{
   input: NumberDecimal("9223372036000.000"),
   to: "int",
   onError: "Could not convert to type integer."
}
“Could not convert to type integer.”
{ input: NumberLong("5000"), to: "int"}
5000
{ input: NumberLong("922337203600"), to: "int"}
Error
{ input: "-2", to: "int" }
-2
{ input: "2.5", to: "int" }
Error
{ input: null, to: "int" }
null

See also

$toInt operator.

Converting to a Decimal

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

Input Type Behavior
Boolean
Returns NumberDecimal("0") for false.
Returns NumberDecimal("1") for true.
Double Returns double value as a decimal.
Decimal No-op. Returns the decimal.
Integer Returns the int value as a decimal.
Long Returns the long value as a decimal.
String

Returns the numerical value of the string as a decimal.

The string value must be of a base10 numeric value (e.g. "-5.5", "123456").

You cannot convert a string value of a non-base10 number (e.g. "0x6400")

Date Returns the number of milliseconds since the epoch that corresponds to the date value.

The following table lists some conversion to decimal examples:

Example Results
{ input: true, to: "decimal"}
NumberDecimal(“1”)
{ input: false, to: "decimal" }
NumberDecimal(“0”)
{ input: 2.5, to: "decimal" }
NumberDecimal(“2.50000000000000”)
{ input: NumberInt(5), to: "decimal"}
NumberDecimal(“5”)
{ input: NumberLong(10000), to: "decimal"}
NumberDecimal(“10000”)
{ input: "-5.5", to: "decimal" }
NumberDecimal(“-5.5”)
{ input: ISODate("2018-03-27T05:04:47.890Z"), to: "decimal" }
NumberDecimal(“1522127087890”)

See also

$toDecimal

Converting to a Double

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

Input Type Behavior
Boolean
Returns NumberLong(0) for false.
Returns NumberLong(1) for true.
Double No-op. Returns the double.
Decimal

Returns the decimal value as a double.

The decimal value must fall within the minimum and maximum value for a double.

You cannot convert a decimal value whose value is less than the minimum double value or is greater than the maximum double value.

Integer Returns the int value as a double.
Long Returns the long value as a double.
String

Returns the numerical value of the string as a double.

The string value must be of a base10 numeric value (e.g. "-5.5", "123456") and fall within the minimum and maximum value for a double.

You cannot convert a string value of a non-base10 number (e.g. "0x6400") or a value that falls outside the minimum and maximum value for a double.

Date Returns the number of milliseconds since the epoch that corresponds to the date value.

The following table lists some conversion to double examples:

Example Results
{ input: true, to: "double"}
1
{ input: false, to: "double" }
0
{ input: 2.5, to: "double" }
2.5
{ input: NumberInt(5), to: "double"}
5
{ input: NumberLong(10000), to: "double"}
10000
{ input: "-5.5", to: "double" }
-5.5
{ input: "5e10", to: "double" }
50000000000
{
   input: "5e550",
   to: "double",
   onError: "Could not convert to type double."
}
“Could not convert to type double.”
{ input: ISODate("2018-03-27T05:04:47.890Z"), to: "double" }
1522127087890

See also

$toDouble

Converting to a Long

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

Input Type Behavior
Boolean
Returns 0 for false.
Returns 1 for true.
Double

Returns truncated value.

The truncated double value must fall within the minimum and maximum value for a long.

You cannot convert a double value whose truncated value is less than the minimum long value or is greater than the maximum long value.

Decimal

Returns truncated value.

The truncated decimal value must fall within the minimum and maximum value for a long.

You cannot convert a decimal value whose truncated value is less than the minimum long value or is greater than the maximum long value.

Integer Returns the int value as a long.
Long No-op. Returns the long value.
String

Returns the numerical value of the string.

The string value must be of a base10 long (e.g. "-5", "123456") and fall within the minimum and maximum value for a long.

You cannot convert a string value of a float or decimal or non-base10 number (e.g. "-5.0", "0x6400") or a value that falls outside the minimum and maximum value for a long.

Date Converts the Date into the number of milliseconds since the epoch.

The following table lists some conversion to long examples:

Example Results
{ input: true, to: "long" }
NumberLong(“1”)
{ input: false, to: "long"  }
NumberLong(“0”)
{ input: 1.99999, to: "long"  }
NumberLong(“1”)
{ input: NumberDecimal("5.5000"), to: "long" }
NumberLong(“5”)
{ input: NumberDecimal("9223372036854775808.0"), to: "long" }
Error
{
   input: NumberDecimal("9223372036854775808.000"),
   to: "long",
   onError: "Could not convert to type long."
}
“Could not convert to type long.”
{ input: NumberInt(8), to: "long" }
NumberLong(8)
{ input: ISODate("2018-03-26T04:38:28.044Z"), to: "long" }
NumberLong(“1522039108044”)
{ input: "-2", to: "long" }
NumberLong(“-2”)
{ input: "2.5", to: "long" }
Error
{ input: null, to: "long" }
null

See also

$toLong

Converting to a Date

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

Input Type Behavior
Double

Returns a date that corresponds to the number of milliseconds represented by the truncated double value.

Positive number corresponds to the number of milliseconds since Jan 1, 1970.

Negative number corresponds to the number of milliseconds before Jan 1, 1970.

Decimal

Returns a date that corresponds to the number of milliseconds represented by the truncated decimal value.

Positive number corresponds to the number of milliseconds since Jan 1, 1970.

Negative number corresponds to the number of milliseconds before Jan 1, 1970.

Long

Returns a date that corresponds to the number of milliseconds represented by the long value.

Positive number corresponds to the number of milliseconds since Jan 1, 1970.

Negative number corresponds to the number of milliseconds before Jan 1, 1970.

String

Returns a date that corresponds to the date string.

The string must be a valid date string, such as:

  • “2018-03-03”
  • “2018-03-03T12:00:00Z”
  • “2018-03-03T12:00:00+0500”
ObjectId Returns a date that corresponds to the timestamp of the ObjectId.

The following table lists some conversion to date examples:

Example Results
{ input: 120000000000.5, to: "date"}
ISODate(“1973-10-20T21:20:00Z”)
{ input: NumberDecimal("1253372036000.50"), to: "date"}
ISODate(“2009-09-19T14:53:56Z”)
{ input: NumberLong("1100000000000"), to: "date"}
ISODate(“2004-11-09T11:33:20Z”)
{ input:  NumberLong("-1100000000000"), to: "date"}
ISODate(“1935-02-22T12:26:40Z”)
{ input: ObjectId("5ab9c3da31c2ab715d421285"), to: "date" }
ISODate(“2018-03-27T04:08:58Z”)
{ input:  "2018-03-03", to: "date" }
ISODate(“2018-03-03T00:00:00Z”)
{ input: "2018-03-20 11:00:06 +0500", to: "date" }
ISODate(“2018-03-20T06:00:06Z”)
{ input: "Friday", to: "date" }
Error
{
   input: "Friday",
   to: "date",
   onError: "Could not convert to type date."
}
“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 an ObjectId:

Input Type Behavior
String

Returns an ObjectId for the hexadecimal string of length 24.

You cannot convert a string value that is not a hexadecimal string of length 24.

The following table lists some conversion to date examples:

Example Results
{ input: "5ab9cbfa31c2ab715d42129e", to: "objectId"}
ObjectId(“5ab9cbfa31c2ab715d42129e”)
{ input: "5ab9cbfa31c2ab715d42129", to: "objectId"}
Error
{
   input: "5ab9cbfa31c2ab715d42129",
   to: "objectId",
   onError: "Could not convert to type ObjectId."
}
“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 a string:

Input Type Behavior
Boolean Returns the boolean value as a string.
Double Returns the double value as a string.
Decimal Returns the decimal value as a string.
Integer Returns the integer value as a string.
Long Returns the long value as a string.
ObjectId Returns the ObjectId value as a hexadecimal string..
String No-op. Returns the string value.
Date Returns the date as a string.

The following table lists some conversion to string examples:

Example Results
{ input: true, to: "string" }
“true”
{ input: false, to: "string"  }
“false”
{ input: 2.5, to: "string"}
“2.5”
{ input: NumberInt(2), to: "string"}
“2”
{ input:  NumberLong(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”

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 collection converts 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" }