$convert (aggregation)¶

On this page

Definition
Behavior
Example

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 base₁₀ 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-base₁₀ 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 base₁₀ numeric value (e.g. `"-5.5"`, `"123456"`). You cannot convert a string value of a non-base₁₀ 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 base₁₀ 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-base₁₀ 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 base₁₀ 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-base₁₀ 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:

copy

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:

copy

// 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:

copy

{ "_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" }

← $cond (aggregation) $cos (aggregation) →