MongoDB $regexFind Operator

What Is $regexFind?

$regexFind is a MongoDB aggregation expression that finds the first regex match inside a string and returns an object with the matched text, start index, and capture groups—or null if nothing matches.

$regexFind = extract first match (+ metadata)

{ $regexFind: {
    input: <string>,
    regex: <pattern>,
    options: "<flags>"   // optional
  }
}

success → { match, idx, captures }
no match → null

$regex      → filter documents
$regexFind  → extract from a string
$regexFindAll → every match (array)

How to Use $regexFind in MongoDB

Point at a string field, give a pattern, then read match / captures.

1. Choose an expression stage ($addFields or $project).
2. Set input to the string (for example "$note").
3. Set regex to the pattern (string or RegExp).
4. Optionally add options (such as "i") and read .match or .captures.

Pseudocode

text = evaluate(input)
if text is null or missing:
    result = null
else:
    m = first_regex_match(text, pattern, options)
    if no match:
        result = null
    else:
        result = {
          match: matched_text,
          idx: start_index,
          captures: [ group1, group2, ... ]
        }
emit { ..., field: result }

Cheat Sheet

Keep these facts handy while extracting matches in pipelines.

Live Preview

Watch $regexFind pull the first match from a sample note string.

input = "Order #A42 shipped today"
regex = /#[A-Z0-9]+/

→ {
  match: "#A42",
  idx: 6,
  captures: []
}

Worked Walkthrough — Order Code

A shipping note says Order #A42 shipped today. We want the first order code that looks like # plus letters/digits.

note = "Order #A42 shipped today"
                 ↑
              index 6

pattern = /#[A-Z0-9]+/

first match:
  match    = "#A42"
  idx      = 6
  captures = []     // no ( ) groups

with /#([A-Z0-9]+)/:
  match    = "#A42"
  captures = ["A42"]  // group 1

MongoDB Examples

We use one shipping note. First insert it, then extract the order code with $regexFind, then pull a capture group. Run these in mongosh after inserting the sample data once.

db.notes.insertOne({
  _id: 1,
  note: "Order #A42 shipped today"
});

db.notes.find()

{
  _id: 1,
  note: "Order #A42 shipped today"
}

Order #A42 shipped today
      ^^^^
      match "#A42" at idx 6

db.notes.aggregate([
  {
    $addFields: {
      found: {
        $regexFind: {
          input: "$note",
          regex: "#[A-Z0-9]+"
        }
      }
    }
  }
]);

{
  _id: 1,
  note: "Order #A42 shipped today",
  found: {
    match: "#A42",
    idx: 6,
    captures: []
  }
}

db.notes.aggregate([
  {
    $addFields: {
      found: {
        $regexFind: {
          input: "$note",
          regex: "#([A-Z0-9]+)"
        }
      }
    }
  },
  {
    $addFields: {
      code: { $arrayElemAt: ["$found.captures", 0] }
    }
  }
]);

{
  _id: 1,
  note: "Order #A42 shipped today",
  found: {
    match: "#A42",
    idx: 6,
    captures: ["A42"]
  },
  code: "A42"
}

Performance Notes

Regex work is heavier than plain field reads. Filter early with $match when only some documents need extraction.

Key Takeaways