MongoDB $toLower Operator

Beginner
5 min read
Updated: Oct 2026
3 examples
Live preview
MongoDB $toLower tutorial — convert strings to lowercase in aggregation
Definition

What Is $toLower?

$toLower is a MongoDB aggregation expression that converts a string to lowercase. It is commonly used to normalize text before comparing or displaying values.

Remember
$toLower = String.toLowerCase for aggregation

{ $toLower: <expression> }

"ABC1" → "abc1"
"Product 2" → "product 2"
null → ""   (empty string, not null)

ASCII behavior is well-defined
Pair with $toUpper for the opposite
UsePrefer
Force lowercase text$toLower
Force uppercase text$toUpper
Case-insensitive compare$strcasecmp
Approach

How to Use $toLower in MongoDB

Lowercase the field, then project, match, or compare the normalized value.

  1. Choose an expression stage ($addFields or $project).
  2. Pass a string field (or expression) to $toLower.
  3. Optional: match or group on the lowercase result.
  4. Remember: null becomes "", not null.
PieceRequired?Role
$toLowerYesConvert string → lowercase
ExpressionYesMust resolve to a string (or null → "")

Pseudocode

Pseudocode
for each document:
    x = evaluate(expression)
    if x is null:
        result = ""
    else:
        result = lowercase(x)   // ASCII letters
    emit { ..., field: result }
Reference

Cheat Sheet

Keep these facts handy while normalizing strings.

TopicDetail
TypeAggregation expression (not a find filter)
Syntax{ $toLower: <expression> }
Sample"ABC1" → "abc1"
Nullnull → "" (empty string)
Charset noteWell-defined for ASCII characters
Opposite$toUpper
Try it

Live Preview

Pick a string and see the lowercase result (browser demo of the same idea).

Simulates $toLower (same idea as the mongosh examples below). Null becomes "".

Result
input = "ABC1"
$toLower → "abc1"

{ lower: "abc1" }
Trace

Worked Walkthrough — Normalize Item Codes

Inventory codes arrive in mixed case. Lowercasing makes them consistent for display and matching.

Calculation
Documents:
  { item: "ABC1", description: "PRODUCT 1" }
  { item: "abc2", description: "Product 2" }

$toLower("ABC1")      → "abc1"
$toLower("PRODUCT 1") → "product 1"
$toLower("abc2")      → "abc2"   (already lower)
$toLower(null)        → ""
Code

MongoDB Examples

Insert sample inventory, lowercase fields, then keep only a target code. Run these in mongosh in order.

Example 1 — Sample Data

Two products with mixed-case item and description values (like the MongoDB docs sample).

mongosh
db.inventory.insertMany([
  { _id: 1, item: "ABC1", description: "PRODUCT 1" },
  { _id: 2, item: "abc2", description: "Product 2" }
]);

How the Data Is Stored in MongoDB

After the insert, MongoDB keeps two documents in inventory. Run find() to see them:

mongosh
db.inventory.find()

Read the rows like this:

FieldExamplesPlain English
_id1, 2Document id
item"ABC1", "abc2"Product code (mixed case)
description"PRODUCT 1", …Label text (mixed case)

How It Works

  1. Insert two products. insertMany stores the mixed-case strings as written.
  2. Case is preserved. MongoDB does not auto-lowercase on insert.
  3. Ready to normalize. The next example applies $toLower.

Example 2 — Lowercase Fields

Goal: project lowercase item and description for every document.

mongosh
db.inventory.aggregate([
  {
    $project: {
      item: { $toLower: "$item" },
      description: { $toLower: "$description" }
    }
  }
]);

How It Works

  1. Read each string. Values come from Example 1.
  2. Lowercase item. "ABC1" becomes "abc1"; "abc2" stays "abc2".
  3. Lowercase description. "PRODUCT 1" → "product 1".
  4. Project replaces the fields. Output shows the normalized versions (originals are not kept in this stage).

Example 3 — Match Normalized Code

Lowercase first, then keep only the document whose item is "abc1"—even though it was stored as "ABC1".

mongosh
db.inventory.aggregate([
  {
    $addFields: {
      itemLower: { $toLower: "$item" }
    }
  },
  {
    $match: { itemLower: "abc1" }
  }
]);

How It Works

  1. Normalize in a new field. $addFields keeps the original item and adds itemLower.
  2. Match the lowercase value. Searching for "abc1" finds the stored "ABC1" row.
  3. Case no longer blocks the match. You compare against a known lowercase target.
  4. Alternative. For compare-only (no stored lower field), see $strcasecmp.

Edge Cases & Pitfalls

Check these before using $toLower in production pipelines.

null

Null becomes ""

$toLower: null returns an empty string, not null. Plan for that in filters and exports.

ascii

ASCII behavior is the documented safe zone

MongoDB notes well-defined behavior for ASCII. Test carefully with accented or non-Latin text.

index

Lowercasing in a query may skip indexes

If you often search case-insensitively, consider storing a normalized field or using a collation suited to your language.

compare

Need only a compare? Try $strcasecmp

$strcasecmp compares two strings without building a permanent lowercase copy.

Analysis

Performance Notes

ApproachCostBest for
$toLower per queryPer-document string workOccasional normalization
Store lowercase fieldCheapest at read timeFrequent case-insensitive search
$strcasecmpCompare onlyEquality checks without rewriting text

String case conversion is cheap for small docs. For large collections with heavy search, normalize on write or use a collation instead of lowercasing every document on every query.

Remember

Key Takeaways

  • Role: convert a string to lowercase.
  • Null: becomes "", not null.
  • Use for: normalizing codes and labels before match/display.
  • Opposite: $toUpper.

One line: $toLower answers “give me this string in all lowercase”—and turns null into "".

Frequently Asked Questions

$toLower converts a string to lowercase inside an aggregation pipeline. Use it in stages such as $project and $addFields.
$toLower makes all letters lowercase. $toUpper makes all letters uppercase. Both help normalize text for comparisons and display.
Unlike many math operators, $toLower returns an empty string "" when the argument is null—not null.
$toLower normalizes values in aggregation. For case-insensitive matching you can lowercase both sides and compare, use $strcasecmp, or use $regex with the i option.
MongoDB documents that $toLower has well-defined behavior for ASCII characters. Be careful with non-ASCII case folding.
Similar for ASCII text. Think of $toLower as MongoDB’s aggregation version of toLowerCase—run it in the pipeline, not as a standalone find() filter by itself.

Next: $toObjectId

Convert hex strings to ObjectId values in an aggregation pipeline.

$toObjectId tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

9 people found this page helpful

MongoDB $toLong Operator MongoDB $toObjectId Operator