The $convert operator changes a value from one BSON type to another during aggregation. Use it when imported data stores numbers as strings, dates as text, or when you need safe fallbacks for bad values.
String → int, etc.
input, to, onError.
Handle missing data.
Clean field types.
Imports, math, dates.
Flexible vs shorthand.
In MongoDB’s aggregation framework, the $convert operator converts an expression to a specified BSON type. For example, turn a string price "29.99" into a number for sorting and arithmetic, or parse an ISO date string into a proper date type.
If conversion fails and you did not set onError, the aggregation may error. Always add onError and onNull when working with messy or imported data.
The $convert operator takes an object with at least input and to:
{
$convert: {
input: <expression>,
to: <type>,
onError: <expression>,
onNull: <expression>
}
}input — the value to convert (field reference, literal, or nested expression).to — target type as a string: "int", "double", "string", "date", "bool", "objectId", "long", "decimal", "timestamp", or "regex".onError — optional fallback when conversion fails (invalid format).onNull — optional fallback when input is null or missing.$project, $addFields, $set, or $group.$toInt wrap common cases.onError and onNull{ $toInt: "$price" } (errors on failure)$convert for safe ETL; use $toInt when data is already clean| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (type conversion) |
| Required fields | input, to |
| Optional fields | onError, onNull |
| Common targets | int, double, string, date, bool |
| Common stages | $project, $addFields, $set |
{
$convert: {
input: "$qty",
to: "int"
}
}Parse numeric strings
{
$convert: {
input: "$price",
to: "double",
onError: 0
}
}Fallback on bad data
{
$convert: {
input: "$score",
to: "int",
onNull: 0
}
}Default for missing
{
$convert: {
input: "$createdAt",
to: "date"
}
}Parse date strings
Convert string prices to numbers, handle invalid imports safely, and parse date strings with $convert.
Use an orders collection where some numeric fields were imported as strings.
Suppose you have an orders collection with string quantities and prices:
[
{ "_id": ObjectId("609c26812e9274a86871bc6a"), "item": "Widget", "qty": "5", "price": "19.99" },
{ "_id": ObjectId("609c26812e9274a86871bc6b"), "item": "Gadget", "qty": "12", "price": "8.50" },
{ "_id": ObjectId("609c26812e9274a86871bc6c"), "item": "Cable", "qty": "bad", "price": "4.99" }
]Turn the qty string into an integer for math and sorting:
db.orders.aggregate([
{
$project: {
item: 1,
qtyInt: {
$convert: {
input: "$qty",
to: "int"
}
}
}
}
])"5" and "12" convert cleanly to integers."bad" cannot convert to int — add onError to handle this safely.Use onError and onNull when data quality is uncertain.
Convert price to double and use 0 when conversion fails:
db.orders.aggregate([
{
$project: {
item: 1,
qtyInt: {
$convert: {
input: "$qty",
to: "int",
onError: 0,
onNull: 0
}
},
priceNum: {
$convert: {
input: "$price",
to: "double",
onError: 0,
onNull: 0
}
},
lineTotal: {
$multiply: [
{
$convert: {
input: "$qty",
to: "int",
onError: 0,
onNull: 0
}
},
{
$convert: {
input: "$price",
to: "double",
onError: 0,
onNull: 0
}
}
]
}
}
}
])onError catches invalid strings like "bad". onNull handles missing fields. Both fall back to 0 so the pipeline continues and lineTotal can still be computed.
Format a numeric score as a string for display or concatenation:
db.students.aggregate([
{
$project: {
name: 1,
scoreLabel: {
$convert: {
input: {
$concat: [
"Score: ",
{
$convert: {
input: "$score",
to: "string"
}
}
]
},
to: "string"
}
}
}
}
])
// Or simply: { $convert: { input: "$score", to: "string" } }Converting numbers to strings is useful before $concat, export formatting, or when downstream systems expect text.
Parse ISO date strings stored as text into BSON dates for range queries:
db.events.aggregate([
{
$project: {
title: 1,
eventDate: {
$convert: {
input: "$dateString",
to: "date",
onError: null,
onNull: null
}
}
}
}
])
// dateString: "2024-06-15T10:30:00Z" → ISODate(...)Once converted to date, you can sort chronologically, filter by year, or group by month. Invalid date strings return null via onError.
$multiply, $sum, or $avg.$convert WorksThe input expression is resolved per document. If null or missing, onNull applies.
MongoDB tries to convert to the to type. On failure, onError is returned (or the pipeline errors).
The result is written to the field you define in $project or $addFields.
Ready for math, sorting, date ranges, and type-safe downstream stages.
The $convert operator is essential for cleaning and transforming data types inside MongoDB aggregation pipelines. It gives you explicit control over target types and safe fallbacks through onError and onNull.
For clean data, shorthand operators like $toInt and $toDouble are fine. For imports, legacy schemas, or ETL jobs, prefer $convert with error handling so one bad field does not break the entire pipeline.
onError and onNull for messy or imported dataint vs double) for your use case$multiply or $sum$toInt / $toString when data is already validated"null", and non-numeric textonErroronNull (missing input) with onError (invalid value)date without checking the string format first$convertUse these points when casting types in MongoDB.
Change BSON types.
PurposeRequired fields.
SyntaxInvalid value fallback.
SafetyMissing field fallback.
SafetyFull vs shorthand.
ImportantMove on to $cos for trigonometry, or review $cond for conditional logic.
5 people found this page helpful