$convert (Type Conversion)

Last updated: 2026-10-09

$convert (Type Conversion)

$convert casts a value to a target BSON type and is the master entry point for type conversions. The to parameter accepts double, string, objectId, bool, date, int, long and decimal. Conversion failures throw by default, but onError supplies a fallback; null input yields null by default and onNull overrides that. Typical uses: turning numeric strings into numbers for arithmetic or parsing date strings into dates. Compared with shortcuts like $toInt, $convert adds failure handling.

📝 Syntax

{ $convert: { input: <expression>, to: <type>, onError: <fallback>, onNull: <nullResult> } }

⚙️ Parameters

Returns：The converted value; onError/onNull apply on failure or null

▶ Example

Run the commands below in your local mongosh (requires a running mongod):

// $convert: parse string price to a number, fallback 0
db.products.aggregate([
  { $project: {
      priceNum: { $convert: { input: '$priceStr', to: 'double', onError: 0 } }
  } }
])

Output：

{ '_id': 1, 'priceNum': 19.9 }
{ '_id': 2, 'priceNum': 0 }

📌 Notes

• Failures throw by default; always provide onError in production
• null input yields null; override with onNull
• $toInt/$toDouble etc. are shortcuts for $convert but lack onError

🏷️ Related Tags

💡 Related Cases

📚 Related Tutorials

❓ FAQ

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

About Us