$toObjectId (Convert to ObjectId)
Last updated: 2026-10-09
$toObjectId (Convert to ObjectId)
$toObjectId converts a 24-character hexadecimal string into an ObjectId, the most common conversion for joins. Typical uses: casting string IDs imported from CSV or APIs into ObjectIds for $lookup, or comparing string _id values with ObjectIds in $match. The string must be a valid ObjectId literal or the conversion throws; null stays null. Prefer $convert with onError to guard invalid input.
| Category | Set, Condition & Conversion |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $toObjectId: <expression> }⚙️ Parameters
| expression | A 24-character hexadecimal string. |
|---|
Returns：An ObjectId; null when the input is null
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $toObjectId: cast a string ID for joining
db.orders.aggregate([
{ $project: {
uid: { $toObjectId: '$userIdStr' }
} }
])Output：
{ '_id': 1, 'uid': { '$oid': '64b7f1c2e4b0a1b2c3d4e5f6' } }📌 Notes
- The string must be 24 hexadecimal characters; anything else throws
- null stays null
- For $lookup, both sides must share a type — convert before joining
🏷️ Related Tags
💡 Related Cases
More hands-on cases coming soon.
📚 Related Tutorials
❓ FAQ
QWhat happens with an invalid string?
AIt throws; $convert onError returns a fallback instead.
QWhy does my $lookup fail to match?
AUsually a type mismatch — one side string, the other ObjectId; unify with $toObjectId first.
QWhat about an empty string?
AIt throws rather than yielding null; handle with $ifNull first.
