The $toObjectId operator converts string values to ObjectId in MongoDB aggregation pipelines. Use it when foreign keys are stored as text but need to match ObjectId _id fields in joins and lookups.
String to ObjectId.
One expression.
Valid ID format.
Join by ObjectId.
Imports, joins.
Shorthand vs safe.
In MongoDB’s aggregation framework, the $toObjectId operator converts an expression to a BSON ObjectId. MongoDB’s default _id type is ObjectId, but imported or API data often stores IDs as strings like "507f1f77bcf86cd799439011". Without conversion, a $lookup or equality match between a string field and an ObjectId _id will fail silently or return no results.
$toObjectId is shorthand for { $convert: { input: <expression>, to: "objectId" } }. It is part of the type-conversion family alongside $toString, $toDate, and $toInt.
A valid ObjectId string is exactly 24 hexadecimal characters (0–9, a–f). Shorter IDs, UUIDs, or numeric IDs cannot be converted with $toObjectId.
The $toObjectId operator takes one expression:
{ $toObjectId: <expression> }{ $toObjectId: "507f1f77bcf86cd799439011" }
// Result: ObjectId("507f1f77bcf86cd799439011")
{ $toObjectId: "$userId" }
// Convert the userId string field
{ $toObjectId: "$productRef" }
// Convert before a $lookup join$toObjectId — returns a BSON ObjectId from a valid hex string.<expression> — a 24-character hex string (field path or literal).null — returns null.$convert with onError for safety).$project, $addFields, $lookup pipelines, or $match.onError when IDs may be invalid| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (type conversion) |
| Syntax | { $toObjectId: <expression> } |
| Required format | 24-character hexadecimal string |
| Equivalent | { $convert: { input: <expr>, to: "objectId" } } |
| null input | Returns null |
| Common stages | $project, $addFields, $lookup |
{
$toObjectId: "$userId"
}Convert a field
{
$toObjectId:
"507f1f77bcf86cd799439011"
}Fixed ObjectId
localField:
"userIdObj"
foreignField: "_id"Join after convert
$convert: {
input: "$id",
to: "objectId",
onError: null
}Invalid → null
Convert string foreign keys, join collections with $lookup, match by ObjectId, and handle invalid IDs safely.
Start with an orders collection where userId is stored as a string and convert it with $toObjectId.
Suppose you have these collections:
// orders collection (userId stored as string)
[
{
"_id": 1,
"product": "Widget",
"userId": "507f1f77bcf86cd799439011"
},
{
"_id": 2,
"product": "Gadget",
"userId": "507f191e810c19729de860ea"
}
]
// users collection (_id is ObjectId)
[
{
"_id": ObjectId("507f1f77bcf86cd799439011"),
"name": "Alice"
},
{
"_id": ObjectId("507f191e810c19729de860ea"),
"name": "Bob"
}
]Convert the userId string to an ObjectId field:
db.orders.aggregate([
{
$project: {
product: 1,
userId: 1,
userIdObj: { $toObjectId: "$userId" }
}
}
])The string userId becomes a proper ObjectId in userIdObj. This typed field can now match ObjectId _id values in other collections.
Use converted ObjectIds in $lookup joins and $match filters.
Join orders to users by converting the string foreign key first:
db.orders.aggregate([
{
$addFields: {
userIdObj: { $toObjectId: "$userId" }
}
},
{
$lookup: {
from: "users",
localField: "userIdObj",
foreignField: "_id",
as: "userInfo"
}
},
{
$project: {
product: 1,
userName: { $arrayElemAt: [ "$userInfo.name", 0 ] }
}
}
])$lookup requires matching types on localField and foreignField. Converting the string to ObjectId enables the join to work correctly.
Find orders for a specific user by converting the search ID:
db.orders.aggregate([
{
$addFields: {
userIdObj: { $toObjectId: "$userId" }
}
},
{
$match: {
userIdObj: ObjectId("507f1f77bcf86cd799439011")
}
},
{
$project: { product: 1, userId: 1 }
}
])
// Returns only Alice's ordersConvert the stored string ID, then match against an ObjectId literal. Without conversion, string "507f..." would not equal ObjectId 507f....
Transform each string in an array to ObjectId with $map:
db.posts.aggregate([
{
$project: {
title: 1,
tagIdsObj: {
$map: {
input: "$tagIds",
as: "tagId",
in: { $toObjectId: "$$tagId" }
}
}
}
}
])
// tagIds: ["507f1f77bcf86cd799439011", "507f191e810c19729de860ea"]
// → tagIdsObj: [ObjectId(...), ObjectId(...)]$map applies $toObjectId to each element, useful when a document stores multiple string references to other collections.
After conversion, extract the embedded timestamp with $toDate:
db.orders.aggregate([
{
$project: {
product: 1,
userIdObj: { $toObjectId: "$userId" },
userCreatedAt: {
$toDate: { $toObjectId: "$userId" }
}
}
}
])
// ObjectId embeds a creation timestamp
// $toDate extracts it as ISODateObjectIds contain a 4-byte timestamp. After converting a string to ObjectId, you can use $toDate to read when that ID was generated.
When some IDs may be invalid, use $convert with onError:
db.orders.aggregate([
{
$project: {
product: 1,
userIdObj: {
$convert: {
input: "$userId",
to: "objectId",
onError: null,
onNull: null
}
}
}
}
])
// "507f1f77bcf86cd799439011" → ObjectId(...)
// "not-a-valid-id" → null
// null → null$toObjectId errors on invalid strings and stops the pipeline. $convert with onError: null lets bad rows continue with a null value.
_id fields.$match.$map for batch lookups.$toObjectId WorksThe input resolves from a field path or a 24-character hex string literal.
MongoDB checks that the string is exactly 24 hex characters, then builds a 12-byte ObjectId.
The result matches ObjectId _id fields for joins, filters, and comparisons.
Use in $lookup, $match, and cross-collection pipelines.
The $toObjectId operator converts 24-character hex strings to BSON ObjectId values in MongoDB aggregation pipelines. It is essential for $lookup joins and matching when foreign keys are stored as text instead of ObjectId.
For the reverse conversion (ObjectId to string), use $toString. For invalid IDs in messy data, use $convert with onError. Next in the series: $toString.
$lookup when _id is ObjectId$convert with onError for imported or messy data$toDate to extract creation time from ObjectIds$toObjectId_id without converting$toObjectId)null input returns null$toObjectId (string → ObjectId) with $toString (ObjectId → string)$toObjectIdUse these points when converting strings to ObjectId in MongoDB.
String → ID.
PurposeOne argument.
SyntaxValid format.
InputJoin collections.
UsageSafe convert.
SafetyMove on to $toString for the reverse conversion, or review $convert for flexible type transforms.
5 people found this page helpful