MongoDB $literal Operator

What You’ll Learn

The $literal operator returns a constant value in an aggregation expression. MongoDB does not treat it as a field path, which matters when your value starts with $ or when you need a fixed array or object inside another operator.

Definition and Usage

In MongoDB’s aggregation framework, the $literal operator evaluates to the value you provide — exactly as written. Unlike a plain string in an expression, $literal prevents MongoDB from interpreting $-prefixed strings as field references.

For example, "$price" in $project normally reads the price field from the document. Wrapping it as { $literal: "$price" } outputs the string "$price" instead.

📝 Syntax

The $literal operator wraps a single constant value:

{ $literal: <value> }

Common Patterns

// String constant
{ $literal: "USD" }

// Number constant
{ $literal: 100 }

// Prevent field-path parsing
{ $literal: "$price" }

// Literal array
{ $literal: [ "draft", "published" ] }

// Literal object
{ $literal: { role: "admin", active: true } }

Syntax Rules

• Single argument — $literal takes one value: string, number, boolean, null, array, or object.
• No field parsing — MongoDB returns the value as-is; strings starting with $ are not treated as paths.
• Expression operator — use inside $project, $addFields, $set, and nested expressions.
• Not a pipeline stage — $literal is an expression, not a stage like $match.
• Arrays and objects — wrap full arrays or objects when an operator requires an expression form.

Examples Gallery

Walk through a sample products collection and see when plain values work, when $literal is required, and how to combine literals with other operators.

[
  { "_id": ObjectId("609c26812e9274a86871bc6a"), "name": "Notebook", "price": 12.50, "tags": [ "stationery" ] },
  { "_id": ObjectId("609c26812e9274a86871bc6b"), "name": "Pen Pack", "price": 8.99, "tags": [ "stationery", "writing" ] },
  { "_id": ObjectId("609c26812e9274a86871bc6c"), "name": "Stapler", "price": 15.00, "tags": [ "office" ] }
]

db.products.aggregate([
  {
    $project: {
      name: 1,
      price: 1,
      currency: { $literal: "USD" }
    }
  }
])

// Every document gets currency: "USD"
// { name: "Notebook", price: 12.5, currency: "USD" }
// { name: "Pen Pack", price: 8.99, currency: "USD" }
// { name: "Stapler", price: 15, currency: "USD" }

db.products.aggregate([
  {
    $project: {
      name: 1,
      fieldRef: "$price",
      literalString: { $literal: "$price" }
    }
  }
])

// Notebook:
//   fieldRef: 12.5        ← reads the price field
//   literalString: "$price" ← outputs the string "$price"

db.products.aggregate([
  {
    $project: {
      name: 1,
      price: 1,
      tier: {
        $cond: [
          { $gte: [ "$price", 12 ] },
          { $literal: "premium" },
          { $literal: "budget" }
        ]
      }
    }
  }
])

// Notebook (12.50) → tier: "premium"
// Pen Pack (8.99)  → tier: "budget"
// Stapler (15.00)  → tier: "premium"

db.products.aggregate([
  {
    $project: {
      name: 1,
      allTags: {
        $concatArrays: [
          "$tags",
          { $literal: [ "in-stock", "catalog" ] }
        ]
      }
    }
  }
])

// Notebook → allTags: [ "stationery", "in-stock", "catalog" ]
// Pen Pack → allTags: [ "stationery", "writing", "in-stock", "catalog" ]
// Stapler  → allTags: [ "office", "in-stock", "catalog" ]

db.products.aggregate([
  {
    $project: {
      name: 1,
      price: 1,
      meta: {
        $literal: {
          source: "catalog-import",
          version: 1,
          active: true
        }
      }
    }
  }
])

🚀 Use Cases

• Fixed labels — add currency codes, status strings, or category names to output.
• $-prefixed strings — output template tokens like "$price" without field lookup.
• Default values in expressions — supply constants inside $cond, $switch, or $ifNull branches.
• Literal arrays/objects — pass fixed collections to $concatArrays, $setUnion, or $in.

💡 Best Practices