Navigation

$convert (aggregation)

On this page

  • Definition
  • Behavior
  • Example
$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:

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
Tip
See also:

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 10 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 10 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

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 10 numeric value (e.g. "-5.5", "123456").

You cannot convert a string value of a non-base 10 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")

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 10 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 10 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

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 10 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 10 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

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."

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."

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"

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" }
Give Feedback

On this page

  • Definition
  • Behavior
  • Example