$literal

The $literal operator returns the specified value without parsing it as an expression. This operator is useful when you need to include literal values that might otherwise be interpreted as field names, operators, or expressions in your aggregation pipeline. It ensures that the value is treated as a constant rather than being evaluated.

{
  $literal: <value>
}

Let's understand the usage with sample json from stores dataset.

{
  "_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f",
  "name": "First Up Consultants | Bed and Bath Center - South Amir",
  "location": {
    "lat": 60.7954,
    "lon": -142.0012
  },
  "staff": {
    "totalStaff": {
      "fullTime": 18,
      "partTime": 17
    }
  },
  "sales": {
    "totalSales": 37701,
    "salesByCategory": [
      {
        "categoryName": "Mattress Toppers",
        "totalSales": 37701
      }
    ]
  },
  "promotionEvents": [
    {
      "eventName": "Price Drop Palooza",
      "promotionalDates": {
        "startDate": {
          "Year": 2024,
          "Month": 9,
          "Day": 21
        },
        "endDate": {
          "Year": 2024,
          "Month": 9,
          "Day": 30
        }
      },
      "discounts": [
        {
          "categoryName": "Bath Accessories",
          "discountPercentage": 18
        },
        {
          "categoryName": "Pillow Top Mattresses",
          "discountPercentage": 17
        }
      ]
    }
  ]
}

The example demonstrates adding literal status information to store documents, including literal strings that might otherwise be interpreted as field names or operators.

db.stores.aggregate([
  { $match: {"_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f"} },
  {
    $project: {
      name: 1,
      totalSales: "$sales.salesByCategory.totalSales",
      status: { $literal: "Active" },
      reviewStatus: { $literal: "$pending" },
      priority: { $literal: 1 },
      metadata: {
        $literal: {
          lastUpdated: "2024-06-13",
          source: "automated-system"
        }
      }
    }
  }
])

The query adds literal values to each store document. Note how $pending is treated as a literal string rather than a field reference.

{
  "_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f",
  "name": "First Up Consultants | Bed and Bath Center - South Amir",
  "totalSales": 37701,
  "status": "Active",
  "reviewStatus": "$pending",
  "priority": 1,
  "metadata": {
    "lastUpdated": "2024-06-13",
    "source": "automated-system"
  }
}

This example shows how to use $literal with arrays and in conditional expressions to ensure values are not interpreted as operators.

db.stores.aggregate([
  { $match: {"_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74"} },
  {
    $project: {
      name: 1,
      totalSales: "$sales.salesByCategory.totalSales",
      performanceCategory: {
        $cond: {
          if: { $gte: ["$sales.totalSales", 100000] },
          then: { $literal: "High Performer" },
          else: { $literal: "Standard" }
        }
      },
      tags: { $literal: ["$featured", "$promoted", "$new"] },
      searchKeywords: {
        $literal: {
          "$or": ["electronics", "entertainment"],
          "$and": ["home", "theater"]
        }
      }
    }
  }
])

The query creates literal arrays and objects that contain strings starting with $, which would normally be interpreted as operators or field references.

{
  "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74",
  "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury",
  "totalSales": 160000,
  "performanceCategory": "High Performer",
  "tags": ["$featured", "$promoted", "$new"],
  "searchKeywords": {
    "$or": ["electronics", "entertainment"],
    "$and": ["home", "theater"]
  }
}

This example demonstrates using $literal with null values and booleans, especially useful when these values need to be explicitly set rather than computed.

db.stores.aggregate([
  { $match: {"_id": "e6895a31-a5cd-4103-8889-3b95a864e5a6"} },
  {
    $project: {
      name: 1,
      totalSales: "$sales.salesByCategory.totalSales",
      specialOffer: { $literal: null },
      isOnline: { $literal: false },
      hasInventory: { $literal: true },
      calculationFormula: { $literal: "$multiply: [price, quantity]" },
      ratingSystem: {
        $literal: {
          min: 0,
          max: 5,
          default: null
        }
      }
    }
  }
])

The query adds explicit literal values including null, booleans, and strings that look like MongoDB expressions.

{
  "_id": "e6895a31-a5cd-4103-8889-3b95a864e5a6",
  "name": "VanArsdel, Ltd. | Picture Frame Store - Port Clevelandton",
  "totalSales": 17676,
  "specialOffer": null,
  "isOnline": false,
  "hasInventory": true,
  "calculationFormula": "$multiply: [price, quantity]",
  "ratingSystem": {
    "min": 0,
    "max": 5,
    "default": null
  }
}

• Review options for migrating from MongoDB to Azure Cosmos DB for MongoDB (vCore).
• Read more about feature compatibility with MongoDB.