MongoDB $toUpper Operator

What You’ll Learn

The $toUpper operator converts string values to uppercase in MongoDB aggregation pipelines. Use it to standardize country codes, status labels, category names, and display text for consistent formatting.

Definition and Usage

In MongoDB’s aggregation framework, the $toUpper operator converts a string expression to uppercase. For example, "john doe" becomes "JOHN DOE". This is useful when you need consistent formatting for country codes, status values, SKU prefixes, or report headers.

$toUpper is the counterpart of $toLower. Both are string transformation operators — they change letter casing without changing the BSON type. Numbers and symbols in the string are not affected.

📝 Syntax

The $toUpper operator takes one string expression:

{ $toUpper: <expression> }

Literal Examples

{ $toUpper: "hello world" }
// Result: "HELLO WORLD"

{ $toUpper: "$name" }
// Uppercase the name field

{ $toUpper: "$countryCode" }
// "us" → "US"

Syntax Rules

• $toUpper — returns the uppercase version of the string expression.
• <expression> — a field path, literal string, or nested string expression.
• null — returns null.
• Only letter casing changes; numbers, spaces, and symbols stay the same.
• Use inside $project, $addFields, or $set.
• Unicode letters are uppercased according to MongoDB’s string rules.

Examples Gallery

Uppercase employee names, standardize country codes and status labels, and group categories case-insensitively with $toUpper.

[
  { "_id": 1, "name": "john doe",   "department": "engineering" },
  { "_id": 2, "name": "alice smith", "department": "marketing" },
  { "_id": 3, "name": "bob jones",  "department": "Engineering" }
]

db.employees.aggregate([
  {
    $project: {
      name: 1,
      upperName: { $toUpper: "$name" }
    }
  }
])

{ "_id": 1, "name": "john doe",    "upperName": "JOHN DOE" }
{ "_id": 2, "name": "alice smith", "upperName": "ALICE SMITH" }
{ "_id": 3, "name": "bob jones",   "upperName": "BOB JONES" }

db.customers.aggregate([
  {
    $addFields: {
      countryCode: { $toUpper: "$country" }
    }
  }
])

// country: "us"  → countryCode: "US"
// country: "In"  → countryCode: "IN"
// country: "gb"  → countryCode: "GB"

db.orders.aggregate([
  {
    $project: {
      orderId: 1,
      status: 1,
      statusUpper: { $toUpper: "$status" }
    }
  }
])

// status: "pending"  → statusUpper: "PENDING"
// status: "Shipped"  → statusUpper: "SHIPPED"
// status: "CANCELLED" → statusUpper: "CANCELLED"

db.employees.aggregate([
  {
    $group: {
      _id: { $toUpper: "$department" },
      count: { $sum: 1 },
      employees: { $push: "$name" }
    }
  },
  {
    $sort: { count: -1 }
  }
])

// "engineering" + "Engineering" → grouped under "ENGINEERING"

{ "_id": "ENGINEERING", "count": 2, "employees": ["john doe", "bob jones"] }
{ "_id": "MARKETING",   "count": 1, "employees": ["alice smith"] }

db.products.aggregate([
  {
    $project: {
      name: 1,
      displayHeader: {
        $concat: [
          { $toUpper: "$category" },
          ": ",
          "$name"
        ]
      }
    }
  }
])

// category: "widget", name: "Pro Model"
// → displayHeader: "WIDGET: Pro Model"

db.articles.aggregate([
  {
    $project: {
      title: 1,
      tagsUpper: {
        $map: {
          input: "$tags",
          as: "tag",
          in: { $toUpper: "$$tag" }
        }
      }
    }
  }
])

// tags: ["mongodb", "Tutorial", "aggregation"]
// → tagsUpper: ["MONGODB", "TUTORIAL", "AGGREGATION"]

🚀 Use Cases

• Country and region codes — standardize ISO codes to uppercase (US, IN, GB).
• Status and enum labels — normalize order status, role names, and category values.
• Report headers — display section titles and labels in uppercase for readability.
• Case-insensitive grouping — merge department or category values regardless of casing.
• SKU and code prefixes — ensure product codes follow an uppercase convention.

💡 Best Practices