$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:FieldDescriptioninput
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 IdentifierNumeric IdentifierNotes"double"1For more information on the conversion to double, see Converting to a Double."string"2For more information on the conversion to string, see Converting to a String."objectId"7For more information on the conversion to objectId, see Converting to an ObjectId."bool"8For more information on the conversion to boolean, see Converting to a Boolean."date"9For more information on the conversion to date, see Converting to a Date."int"16For more information on the conversion to integer, see Converting to an Integer."long"18For more information on the conversion to long, see Converting to a Long."decimal"19For 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 theinput
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  Noop. 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  

 true  
 false  
 true  
 true  
 false  
 true  
 true  
 true  
 true  
 true  
 null 
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  Noop. 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 _{10} integer (e.g.
You cannot convert a string value of a float or decimal or
nonbase _{10} number (e.g. 
The following table lists some conversion to integer examples:
Example  Results  

 1  
 0  
 1  
 5  
 Error  
 "Could not convert to type integer."  
 5000  
 Error  
 2  
 Error  
 null 
$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  Noop. 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 _{10} numeric value (e.g.
You cannot convert a string value of a nonbase _{10}
number (e.g. 
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  

 NumberDecimal("1")  
 NumberDecimal("0")  
 NumberDecimal("2.50000000000000")  
 NumberDecimal("5")  
 NumberDecimal("10000")  
 NumberDecimal("5.5")  
 NumberDecimal("1522127087890") 
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  Noop. 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 _{10} numeric value (e.g.
You cannot convert a string value of a nonbase _{10}
number (e.g. 
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  

 1  
 0  
 2.5  
 5  
 10000  
 5.5  
 50000000000  
 "Could not convert to type double."  
 1522127087890 
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  Noop. Returns the long value. 
String  Returns the numerical value of the string. The string value must be of a base _{10} long (e.g.
You cannot convert a string value of a float or decimal or
nonbase _{10} number (e.g. 
Date  Converts the Date into the number of milliseconds since the
epoch. 
The following table lists some conversion to long examples:
Example  Results  

 NumberLong("1")  
 NumberLong("0")  
 NumberLong("1")  
 NumberLong("5")  
 Error  
 "Could not convert to type long."  
 NumberLong(8)  
 NumberLong("1522039108044")  
 NumberLong("2")  
 Error  
 null 
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:

ObjectId  Returns a date that corresponds to the timestamp of the
ObjectId. 
The following table lists some conversion to date examples:
Example  Results  

 ISODate("19731020T21:20:00Z")  
 ISODate("20090919T14:53:56Z")  
 ISODate("20041109T11:33:20Z")  
 ISODate("19350222T12:26:40Z")  
 ISODate("20180327T04:08:58Z")  
 ISODate("20180303T00:00:00Z")  
 ISODate("20180320T06:00:06Z")  
 Error  
 "Could not convert to type date." 
$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  

 ObjectId("5ab9cbfa31c2ab715d42129e")  
 Error  
 "Could not convert to type ObjectId." 
$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  Noop. Returns the string value. 
Date  Returns the date as a string. 
The following table lists some conversion to string examples:
Example  Results  

 "true"  
 "false"  
 "2.5"  
 "2"  
 "1000"  
 "5ab9c3da31c2ab715d421285"  
 "20180327T16:58:51.538Z" 
$toString
operator$dateToString
Example
Create a collection orders
with the following documents:
db.orders.insertMany( [ { _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: Decimal128("50") }, { _id: 2, totalPrice: Decimal128("200.0") }, { _id: 3, totalPrice: Decimal128("9.98") }, { _id: 4, totalPrice: Decimal128("0") }, { _id: 5, totalPrice: 'NaN' }
The legacy mongo
shell stores decimals as
NumberDecimal. In mongo
shell, 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" }