The $toString operator converts any value to a string in MongoDB aggregation pipelines. Use it to build text labels with $concat, display ObjectIds, format numbers for export, and combine mixed-type fields.
Any value to text.
One expression.
Build labels.
ID to hex text.
Export, display.
String ↔ ID.
In MongoDB’s aggregation framework, the $toString operator converts an expression to its string representation. Numbers become text like "42", ObjectIds become 24-character hex strings, and booleans become "true" or "false". This is essential when you need to combine values of different types using $concat or display them in reports.
$toString is shorthand for { $convert: { input: <expression>, to: "string" } }. It is the reverse of operators like $toInt and $toObjectId, which parse strings into typed values.
$concat only works with strings. Wrap numeric or ObjectId fields in $toString before concatenating them with text labels.
The $toString operator takes one expression:
{ $toString: <expression> }{ $toString: 42 }
// Result: "42"
{ $toString: true }
// Result: "true"
{ $toString: "$_id" }
// ObjectId → "507f1f77bcf86cd799439011"
{ $toString: "$score" }
// Number field → stringnull — returns null.42 → "42").true → "true", false → "false".$dateToString for custom date formats).$project, $addFields, or $set.$toString for general conversion; use specialized operators when you need specific formats| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (type conversion) |
| Syntax | { $toString: <expression> } |
| Output type | String |
| Equivalent | { $convert: { input: <expr>, to: "string" } } |
| Common pairing | $concat for building text labels |
| Common stages | $project, $addFields, $set |
{
$toString: "$score"
}42 → "42"
{
$toString: "$_id"
}ID to hex text
{
$concat: [
"Score: ",
{ $toString: "$score" }
]
}Build label
{
$toString: "$active"
}true → "true"
Convert numbers and ObjectIds to strings, build labels with $concat, and format values for export and display.
Start with a products collection and convert numeric fields to strings for display labels.
Suppose you have a products collection:
[
{
"_id": ObjectId("507f1f77bcf86cd799439011"),
"name": "Widget",
"price": 29.99,
"stock": 150
},
{
"_id": ObjectId("507f191e810c19729de860ea"),
"name": "Gadget",
"price": 49.50,
"stock": 75
}
]Turn the numeric stock field into a string:
db.products.aggregate([
{
$project: {
name: 1,
stock: 1,
stockText: { $toString: "$stock" }
}
}
])$toString converts the number 150 to the string "150". The original numeric field is unchanged.
Build composite labels with $concat, display ObjectIds, and format for export.
Combine text and numbers into a readable label:
db.products.aggregate([
{
$project: {
name: 1,
label: {
$concat: [
"$name",
" — $",
{ $toString: "$price" },
" (",
{ $toString: "$stock" },
" in stock)"
]
}
}
}
])
// "Widget — $29.99 (150 in stock)"
// "Gadget — $49.5 (75 in stock)"$concat requires all parts to be strings. Wrap numeric fields in $toString before concatenating with text.
Convert _id to a readable hex string for export or APIs:
db.products.aggregate([
{
$project: {
name: 1,
idString: { $toString: "$_id" }
}
}
])
// _id: ObjectId("507f1f77bcf86cd799439011")
// → idString: "507f1f77bcf86cd799439011"This is the reverse of $toObjectId. Use $toString when sending IDs to external systems that expect text, and $toObjectId when parsing them back.
Turn boolean flags into readable text for reports:
db.users.aggregate([
{
$project: {
name: 1,
active: 1,
activeText: { $toString: "$active" }
}
}
])
// active: true → activeText: "true"
// active: false → activeText: "false"Booleans become the strings "true" or "false". For user-friendly labels, consider $cond instead (e.g. "Yes" / "No").
Combine a prefix, category code, and numeric ID into a SKU string:
db.products.aggregate([
{
$project: {
name: 1,
sku: {
$concat: [
"SKU-",
"$category",
"-",
{ $toString: "$productNum" }
]
}
}
}
])
// category: "WGT", productNum: 42
// → sku: "SKU-WGT-42"String fields can be used directly in $concat, but numeric fields like productNum must be wrapped in $toString first.
Group documents by stringified _id for cross-collection reporting:
db.orders.aggregate([
{
$group: {
_id: { $toString: "$customerId" },
orderCount: { $sum: 1 },
total: { $sum: "$amount" }
}
}
])Converting ObjectId group keys to strings makes output easier to read in reports and JSON exports.
$concat for display strings.$toString WorksThe input resolves from a field path, literal, or nested expression of any BSON type.
MongoDB applies type-specific string formatting (decimal for numbers, hex for ObjectIds, ISO for dates).
The output can be used in $concat, displayed in reports, or exported as text.
Use in labels, exports, display fields, and string operations.
The $toString operator converts any BSON value to a string in MongoDB aggregation pipelines. It is essential for building text labels with $concat, displaying ObjectIds, and formatting data for export.
For the reverse conversion (string to ObjectId), use $toObjectId. For custom date formatting, use $dateToString. Next in the series: $toUpper.
$toString before $concat$toString on ObjectIds for API and export formats$dateToString when you need custom date formatting$toObjectId for round-trip ID conversion$concat without $toString$toString on dates when you need a specific format (use $dateToString)"true"/"false" strings are user-friendly (use $cond for labels)null input returns null$toStringUse these points when converting values to strings in MongoDB.
Any → text.
PurposeOne argument.
SyntaxBuild labels.
PairingID to hex.
UsageDates: use that.
CompareMove on to $toUpper for uppercase conversion, or review $concat for building text labels.
5 people found this page helpful