The $regexFind operator finds the first regular expression match in a string and returns match details. Use it in aggregation pipelines to extract emails, hashtags, codes, or any substring without filtering entire documents.
First regex hit.
Text and position.
Capture groups.
$project / $addFields.
Parse, validate.
Extract vs filter.
In MongoDB’s aggregation framework, the $regexFind operator searches a string for a regular expression pattern and returns metadata about the first match. The result is an object with match (matched text), idx (start index), and captures (parenthesized groups). If nothing matches, the result is null.
Unlike query $regex, which filters documents, $regexFind transforms data inside pipelines. It is ideal for parsing log messages, extracting domains from emails, or pulling SKU prefixes into separate fields.
Access the matched text with $matchResult.match after projecting the full $regexFind result, or use dot notation in a nested $project. Need all matches? Use $regexFindAll instead.
The $regexFind operator takes an object with input, regex, and optional options:
{
$regexFind: {
input: <string expression>,
regex: <pattern expression>,
options: <options expression> // optional
}
}// On match:
{
match: "matched substring",
idx: 12, // zero-based start index
captures: [] // capture group strings
}
// No match:
nullinput — the string to search (field path or expression).regex — the pattern string or BSON regex literal.options — optional flags like "i" (case insensitive).null when there is no match or when input is null.$project, $addFields, or $set (MongoDB 4.2+).| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (string / regex) |
| Syntax | { $regexFind: { input, regex, options? } } |
| Output | { match, idx, captures } or null |
| Matches returned | First match only |
| Common stages | $project, $addFields, $set |
{
$regexFind: {
input: "$text",
regex: "#\\w+"
}
}Find hashtag
{
options: "i"
}Ignore case
"$result.match"Matched text
nullPattern not found
Extract hashtags from posts, parse email domains, pull capture groups, and check whether a pattern exists with $cond.
Extract the first hashtag from a body field with $regexFind.
Suppose you have a posts collection:
[
{
"_id": 1,
"author": "Alice",
"body": "Learning MongoDB #database today!"
},
{
"_id": 2,
"author": "Bob",
"body": "No hashtags here."
},
{
"_id": 3,
"author": "Carol",
"email": "carol.smith@gmail.com"
}
]Find the first hashtag in each post body:
db.posts.aggregate([
{
$project: {
author: 1,
body: 1,
hashtag: {
$regexFind: {
input: "$body",
regex: "#\\w+"
}
}
}
}
])The pattern #\w+ matches a hash symbol followed by word characters. Only the first hashtag is returned. Posts without a match get null.
Parse domains, use capture groups, and project just the matched text.
Pull the domain portion from an email address:
db.posts.aggregate([
{
$match: { email: { $exists: true } }
},
{
$project: {
author: 1,
email: 1,
domain: {
$let: {
vars: {
found: {
$regexFind: {
input: "$email",
regex: "@(.+)$"
}
}
},
in: {
$arrayElemAt: [ "$$found.captures", 0 ]
}
}
}
}
}
])
// carol.smith@gmail.com → domain: "gmail.com"The capture group (.+) stores text after @ in captures[0]. $let stores the match result so you can read the capture group cleanly.
Store just the matched substring, not the full result object:
db.posts.aggregate([
{
$project: {
author: 1,
firstTag: {
$getField: {
field: "match",
input: {
$regexFind: {
input: "$body",
regex: "#\\w+"
}
}
}
}
}
}
])
// firstTag: "#database" or null$getField safely reads match from the result object. You can also use $ifNull when the field might be missing.
Use $cond to set a boolean flag from the match result:
db.posts.aggregate([
{
$project: {
author: 1,
hasHashtag: {
$cond: [
{
$ne: [
{
$regexFind: {
input: "$body",
regex: "#\\w+"
}
},
null
]
},
true,
false
]
}
}
}
])Compare the $regexFind result to null. For a simple true/false check without match text, consider $regexMatch instead.
Parse a product code prefix from a SKU string:
db.products.aggregate([
{
$project: {
sku: 1,
category: {
$regexFind: {
input: "$sku",
regex: "^(PRO|DEV|TEST)-",
options: "i"
}
}
}
}
])
// sku: "PRO-1001" → match: "PRO-", idx: 0Alternation (PRO|DEV|TEST) matches any of those prefixes. The i option allows case-insensitive matching.
$regexFind WorksThe pipeline resolves the string (input) and compiles the pattern (regex) with any options.
MongoDB scans the string left to right and stops at the first substring that satisfies the pattern.
On success: match, idx, and captures. On failure: null.
Use .match or captures in downstream pipeline stages.
The $regexFind operator extracts the first regular expression match from a string inside MongoDB aggregation pipelines. It returns match, idx, and captures — or null when nothing matches.
Use it for parsing and enrichment; use query $regex to filter documents. For all matches, switch to $regexFindAll. Next in the series: $regexFindAll.
null results with $ifNull or $cond.match or captures[0] in a follow-up projection$regexMatch when you only need true/false$regexFindAll for that$regexFind as a query filter (it is expression-only)captures is always non-empty (depends on groups)$regexFind with query $regex$regexFindUse these points when extracting regex matches in pipelines.
One result only.
PurposeString and pattern.
SyntaxText + position.
OutputGroup extraction.
GroupsNo match found.
Edge caseMove on to $regexFindAll for every match in a string, or review $regex for document filtering.
5 people found this page helpful