MongoDB $function Operator

What Is $function?

$function is a MongoDB aggregation expression that runs custom JavaScript for each document. You pass inputs through args, write logic in body, and set lang to "js". Prefer built-in operators when they can do the same job.

$function = custom JS inside aggregation

{
  $function: {
    body: function(score) { ... },
    args: [ "$score" ],
    lang: "js"
  }
}

args → function parameters (in order)
body → return a value
lang → must be "js"

prefer $cond / $switch when possible

How to Use $function in MongoDB

Write a small function, feed it values through args, and emit the return value.

1. Choose an expression stage ($addFields or $project).
2. List inputs in args (field paths or expressions).
3. Write body as a function whose parameters match that order.
4. Set lang: "js" and return the value you want stored.

Pseudocode

for each document:
    values = evaluate each expression in args
    result = run JavaScript body(values...)
    emit { ..., field: result }

Cheat Sheet

Keep these facts handy while writing custom pipeline functions.

Live Preview

Watch a small grading function turn a score into a letter—the same idea as $function below.

score = 85
$function → "B"

{ grade: "B" }

Worked Walkthrough — Letter Grade

Asha scored 85. We want a letter grade with a tiny JavaScript function.

Document:
  { name: "Asha", score: 85 }

args: [ 85 ]
body(score):
  if score >= 90 → "A"
  if score >= 80 → "B"
  if score >= 70 → "C"
  else → "F"

85 >= 80 → "B" ✓

MongoDB Examples

We use one student document. First compute a letter grade from score, then build a short message from name and score. Run these in mongosh after inserting the sample data once.

db.students.insertOne({
  _id: 1,
  name: "Asha",
  score: 85
});

db.students.find()

[
  {
    _id: 1,
    name: "Asha",
    score: 85
  }
]

Pipeline passes values into JS:

  args: ["$score"]  →  function(score)
  score = 85
       |
       v
  grade = "B"

db.students.aggregate([
  {
    $addFields: {
      grade: {
        $function: {
          body: function (score) {
            if (score >= 90) return "A";
            if (score >= 80) return "B";
            if (score >= 70) return "C";
            return "F";
          },
          args: ["$score"],
          lang: "js"
        }
      }
    }
  }
]);

{
  _id: 1,
  name: "Asha",
  score: 85,
  grade: "B"
}

db.students.aggregate([
  {
    $addFields: {
      summary: {
        $function: {
          body: function (name, score) {
            return name + " scored " + score;
          },
          args: ["$name", "$score"],
          lang: "js"
        }
      }
    }
  }
]);

{
  _id: 1,
  name: "Asha",
  score: 85,
  summary: "Asha scored 85"
}

Performance Notes

Filter early with $match so JavaScript runs on fewer documents.

Key Takeaways