MongoDB $literal Operator

What Is $literal?

$literal is a MongoDB aggregation expression that returns a constant value as written. MongoDB will not treat it as a field path or operator—even if the value is a string that starts with $.

$literal = keep this value as-is

{ $literal: <value> }

"$price"              → read field price
{ $literal: "$price" } → string "$price"

{ $literal: "active" } → constant "active"
{ $literal: 0 }        → constant 0

How to Use $literal in MongoDB

Wrap any constant you want MongoDB to leave untouched.

1. Choose an expression stage ($addFields or $project).
2. Pass the constant to { $literal: <value> }.
3. Use it when the value starts with $, or when you want an obvious fixed constant.
4. Skip $literal for plain numbers and normal strings that have no $ ambiguity.

Pseudocode

for each document:
    // without $literal
    "$price"  → look up document.price

    // with $literal
    { $literal: "$price" } → the string "$price"
    { $literal: "active" } → the string "active"

    emit { ..., field: that constant }

Cheat Sheet

Keep these facts handy when embedding constants in pipelines.

Live Preview

Compare a field path with $literal on the same Notebook document ({ price: 50 }.

document = { price: 50 }

expression = "$price"
→ reads field price
result → 50

Worked Walkthrough — Field vs Literal

A Notebook costs 50. Writing "$price" reads that field. Wrapping the same characters in $literal keeps them as text.

Document:
  { item: "Notebook", price: 50 }

"$price"
  → look up price
  → 50

{ $literal: "$price" }
  → do not look up
  → string "$price"

{ $literal: "active" }
  → constant label
  → "active"

MongoDB Examples

We use one product document. First store the sample, then add a constant status, then show how $literal protects a $ string. Run these in mongosh after inserting the sample data once.

db.products.insertOne({
  _id: 1,
  item: "Notebook",
  price: 50
});

db.products.find()

{
  _id: 1,
  item: "Notebook",
  price: 50
}

"$price"                 → 50   (field)
{ $literal: "$price" }   → "$price" (text)
{ $literal: "active" }   → "active" (label)

db.products.aggregate([
  {
    $addFields: {
      status: { $literal: "active" }
    }
  }
]);

{
  _id: 1,
  item: "Notebook",
  price: 50,
  status: "active"
}

db.products.aggregate([
  {
    $addFields: {
      asField: "$price",
      asText: { $literal: "$price" }
    }
  }
]);

{
  _id: 1,
  item: "Notebook",
  price: 50,
  asField: 50,
  asText: "$price"
}

Performance Notes

$literal is extremely cheap. Prefer it for clarity when a value could be misread as a field path; otherwise a plain constant is fine.

Key Takeaways