$toObjectId（转 ObjectId）
最后更新：2026-10-09
$toObjectId（转 ObjectId）
$toObjectId 把 24 位十六进制字符串转换为 ObjectId，是关联查询中最常用的类型转换。典型场景包括从 CSV 或 API 导入的字符串 ID 转成 ObjectId 以便 $lookup 关联、在 $match 里把字符串 _id 与文档 ObjectId 比较。字符串必须是合法 ObjectId 格式，否则报错；null 返回 null。推荐用 $convert onError 兜底非法输入。
| 分类 | 集合·条件·转换 |
|---|---|
| MongoDB 版本 | 1.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
{ $toObjectId: <表达式> }⚙️ 参数
| 表达式 | 24 位十六进制字符串。 |
|---|
返回值：ObjectId 类型；输入为 null 时返回 null
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// $toObjectId：字符串 ID 转 ObjectId 供关联用
db.orders.aggregate([
{ $project: {
uid: { $toObjectId: '$userIdStr' }
} }
])运行结果：
{ '_id': 1, 'uid': { '$oid': '64b7f1c2e4b0a1b2c3d4e5f6' } }📌 注意事项
- 字符串必须是 24 位十六进制，其他格式报错
- null 返回 null
- 配合 $lookup 关联时两侧类型必须一致，先转换再关联
🏷️ 相关标签
💡 相关案例
更多实战案例即将上线，敬请期待。
📚 相关教程
❓ 常见问题
Q字符串格式不对会怎样？
A报错；用 $convert onError 可返回兜底值。
Q为什么 $lookup 关联不上？
A常见原因是类型不一致，一侧字符串一侧 ObjectId，先 $toObjectId 统一。
Q空字符串会怎样？
A报错，不是 null，注意先 $ifNull 处理。
