The $function operator runs custom JavaScript inside MongoDB aggregation pipelines. When built-in operators are not enough, you can define your own logic with a body, pass values through args, and set lang to "js".
Write your own logic.
body, args, lang.
Pass field values in.
Add computed results.
Grades, formatting, rules.
Use built-ins when possible.
In MongoDB’s aggregation framework, the $function operator executes a JavaScript function for each document. You provide three parts: body (the function code), args (values passed as parameters), and lang (must be "js"). The return value of your function becomes the expression result — useful for custom grading rules, string formatting, or business logic that native operators cannot express cleanly.
Your function cannot read this or access the document directly. Pass everything you need through args, like [ "$score", "$name" ]. Parameter order matches the args array order.
The $function operator takes an object with body, args, and lang:
{
$function: {
body: <function or string>,
args: [ <expression1>, ... ],
lang: "js"
}
}{
$function: {
body: function(score) {
return score >= 70 ? "pass" : "fail";
},
args: [ "$score" ],
lang: "js"
}
}body — a JavaScript function or a string containing function code.args — array of expressions (field paths like "$score" or literals) passed as function parameters.lang — must be "js" (the only supported language).$project, $addFields, or $set.return a value compatible with BSON types.Custom JavaScript is slower and harder to maintain than native operators like $cond, $switch, or $map. Reach for $function only when built-ins cannot solve the problem. On self-hosted deployments, JavaScript execution may require additional server configuration.
| Question | Answer |
|---|---|
| Operator type | Aggregation custom expression operator |
| Syntax | { $function: { body, args, lang: "js" } } |
| Input | Values from args array |
| Output | Function return value |
| Common stages | $project, $addFields, $set |
{
$function: {
body: function(s) {
return s >= 70 ? "pass" : "fail";
},
args: ["$score"],
lang: "js"
}
}Grade from score
{
$function: {
body: "function(a,b){return a+b;}",
args: ["$x", "$y"],
lang: "js"
}
}Body as string
{
$function: {
body: function(f,l){
return f + " " + l;
},
args: ["$first","$last"],
lang: "js"
}
}Combine fields
lang: "js"Required; only "js"
Walk through sample data, an aggregation pipeline, and the output step by step.
Start with a students collection and compute pass/fail status with custom JavaScript.
Suppose you have a students collection with name and score fields:
[
{ "_id": ObjectId("609c26812e9274a86871bc6a"), "name": "Ana", "score": 85 },
{ "_id": ObjectId("609c26812e9274a86871bc6b"), "name": "Ben", "score": 62 },
{ "_id": ObjectId("609c26812e9274a86871bc6c"), "name": "Cara", "score": 74 }
]Use $addFields to add a result field with a custom function:
db.students.aggregate([
{
$addFields: {
result: {
$function: {
body: function(score) {
return score >= 70 ? "pass" : "fail";
},
args: [ "$score" ],
lang: "js"
}
}
}
}
])args: [ "$score" ] passes each document’s score as the first parameter."pass" when score ≥ 70, otherwise "fail".result field.$cond, but $function scales better for complex rules.Pass multiple arguments, format strings, and use a string-based function body.
Pass firstName and lastName through args:
db.users.aggregate([
{
$project: {
email: 1,
fullName: {
$function: {
body: function(first, last) {
return (first || "") + " " + (last || "");
},
args: [ "$firstName", "$lastName" ],
lang: "js"
}
}
}
}
])Parameter order matches args: first argument is firstName, second is lastName. Handle nulls inside your function when fields may be missing.
Loop over an array passed through args to compute a discounted total:
db.orders.aggregate([
{
$addFields: {
discountedTotal: {
$function: {
body: function(items, rate) {
let total = 0;
for (let i = 0; i < items.length; i++) {
total += items[i].price * items[i].qty;
}
return total * (1 - rate);
},
args: [ "$items", "$discountRate" ],
lang: "js"
}
}
}
}
])Arrays and numbers from the document are passed as regular JavaScript values. Your function can use loops, conditionals, and any JS logic MongoDB allows.
When storing pipelines in config files, a string body can be easier to serialize:
db.products.aggregate([
{
$project: {
name: 1,
priceTier: {
$function: {
body: "function(price) { if (price < 50) return 'budget'; if (price < 200) return 'standard'; return 'premium'; }",
args: [ "$price" ],
lang: "js"
}
}
}
}
])The body string must contain a valid JavaScript function definition. MongoDB parses and executes it the same way as an inline function. Both forms are equivalent at runtime.
$cond.$reduce or $map would be awkward.$function WorksEach expression in args is resolved — field paths like "$score" become actual values.
MongoDB calls your body function with those values as parameters, in order.
Whatever your function returns becomes the expression result in $project or $addFields.
Each document gets a value produced by your JavaScript logic.
The $function operator unlocks custom JavaScript in MongoDB aggregation pipelines. It is powerful for business rules, formatting, and array logic that native operators cannot express cleanly.
For beginners, remember the three parts: body (your function), args (inputs from fields), and lang: "js". Start simple with one argument, then expand as your logic grows — but always check if $cond or $switch can do the job first.
argsbody when storing pipelines in config$function for simple logic that $cond handlesargslang: "js" — it is required$functionUse these points when adding custom JavaScript to pipelines.
Your logic, your rules.
Purposebody, args, lang.
SyntaxPass field values in.
UsageGrades, tiers, totals.
Use caseUse built-ins first.
Edge caseContinue with $getField for dynamic field access, or review $cond for native conditionals.
5 people found this page helpful