$convert (aggregation)
On this page
Definition
Compatibility
You can use $convert
for deployments hosted in the following
environments:
MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
MongoDB Enterprise: The subscriptionbased, selfmanaged version of MongoDB
MongoDB Community: The sourceavailable, freetouse, and selfmanaged version of MongoDB
Syntax
$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 Expression Operators.  
to  The argument can be any valid expression that resolves to one of the following numeric or string identifiers:
 
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 If unspecified, 
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. 
Timestamp  Returns true. 
The following table lists some conversion to boolean examples:
Example  Results  

 true  
 false  
 true  
 true  
 false  
 true  
 true  
 true  
 true  
 true  
 null 
Tip
See also:
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  
 5000  
 Error  
 2  
 Error  
 null 
Tip
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 Decimal128( "0" ) for false .Returns Decimal128( "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  

 Decimal128("1")  
 Decimal128("0")  
 Decimal128( "2.50000000000000" )  
 Decimal128("5")  
 Decimal128("10000")  
 Decimal128("5.5")  
 Decimal128("1522039108044") 
Tip
See also:
Converting to a Double
The following table lists the input types that can be converted to a double:
Input Type  Behavior 

Boolean  Returns NumberDouble(0) for false .Returns NumberDouble(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  
 1522039108044 
Tip
See also:
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  

 Long("1")  
 Long("0")  
 Long("2")  
 Long("5")  
 Error  
 Long("8")  
 Long("1522039108044")  
 Long("2")  
 Error  
 null 
Tip
See also:
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. 
Timestamp  Returns a date that corresponds to the timestamp. 
The following table lists some conversion to date examples:
Example  Results  

 ISODate("19731020T21:20:00.000Z")  
 ISODate("20090919T14:53:56.000Z")  
 ISODate("20041109T11:33:20.000Z")  
 ISODate("19350222T12:26:40.000Z")  
 ISODate("20180327T04:08:58.000Z")  
 ISODate("20180303T00:00:00.000Z")  
 ISODate("20180320T06:00:06.000Z")  
 Error  
 ISODate("20211123T17:21:58.000Z") 
Tip
See also:
$toDate
operator
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 
Tip
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  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" 
Tip
See also:
$toString
operator
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: 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") } ] )
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: 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 ])
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' }