$regex

$regex vs. /pattern/ Syntax

{ name: { $in: [ /^acme/i, /^ack/ ] } }

{ name: { $regex: /acme.*corp/i, $nin: [ 'acmeblahcorp' ] } }
{ name: { $regex: /acme.*corp/, $options: 'i', $nin: [ 'acmeblahcorp' ] } }
{ name: { $regex: 'acme.*corp', $options: 'i', $nin: [ 'acmeblahcorp' ] } }

{ name: { $regex: /acme.*corp/, $options: "si" } }
{ name: { $regex: 'acme.*corp', $options: "si" } }

{ name: { $regex: "(?i)a(?-i)cme" } }

Index Use

For case sensitive regular expression queries, if an index exists for the field, then MongoDB matches the regular expression against the values in the index, which can be faster than a collection scan.

Further optimization can occur if the regular expression is a "prefix expression", which means that all potential matches start with the same string. This allows MongoDB to construct a "range" from that prefix and only match against those values from the index that fall within that range.

A regular expression is a "prefix expression" if it starts with a caret (^) or a left anchor (\A), followed by a string of simple symbols. For example, the regex /^abc.*/ will be optimized by matching only against the values from the index that start with abc.

Additionally, while /^a/, /^a.*/, and /^a.*$/ match equivalent strings, they have different performance characteristics. All of these expressions use an index if an appropriate index exists; however, /^a.*/, and /^a.*$/ are slower. /^a/ can stop scanning after matching the prefix.

Case insensitive regular expression queries generally cannot use indexes effectively. The $regex implementation is not collation-aware and is unable to utilize case-insensitive indexes.

Perform a LIKE Match

The following example matches all documents where the sku field is like "%789":

db.products.find( { sku: { $regex: /789$/ } } )

The example is analogous to the following SQL LIKE statement:

SELECT * FROM products
WHERE sku like "%789";

Example output:

[
   { _id: 101, sku: 'abc789', description: 'First line\nSecond line' },
   { _id: 103, sku: 'xyz789', description: 'Multiple\nline description' },
   { _id: 104, sku: 'Abc789', description: 'SKU starts with A' }
]

Perform Case-Insensitive Regular Expression Match

The following example uses the i option perform a case-insensitive match for documents with sku value that starts with ABC.

db.products.find( { sku: { $regex: /^ABC/i } } )

Example output:

[
   { _id: 100, sku: 'abc123', description: 'Single line description.' },
   { _id: 101, sku: 'abc789', description: 'First line\nSecond line' },
   { _id: 104, sku: 'Abc789', description: 'SKU starts with A' }
]

Multiline Match for Lines Starting with Specified Pattern

The following example uses the m option to match lines starting with the letter S for multiline strings:

db.products.find( { description: { $regex: /^S/, $options: 'm' } } )

Example output:

[
   { _id: 100, sku: 'abc123', description: 'Single line description.' },
   { _id: 101, sku: 'abc789', description: 'First line\nSecond line' },
   { _id: 104, sku: 'Abc789', description: 'SKU starts with A' }
]

Without the m option, the example output is:

[
   { _id: 100, sku: 'abc123', description: 'Single line description.' },
   { _id: 104, sku: 'Abc789', description: 'SKU starts with A' }
]

If the $regex pattern does not contain an anchor, the pattern matches against the string as a whole, as in the following example:

db.products.find( { description: { $regex: /S/ } } )

Example output:

[
   { _id: 100, sku: 'abc123', description: 'Single line description.' },
   { _id: 101, sku: 'abc789', description: 'First line\nSecond line' },
   { _id: 104, sku: 'Abc789', description: 'SKU starts with A' }
]

Use the . Dot Character to Match New Line

The following example uses the s option to allow the dot character (i.e. .) to match all characters including new line as well as the i option to perform a case-insensitive match:

db.products.find( { description: { $regex: /m.*line/, $options: 'si' } } )

Example output:

[
   { _id: 102, sku: 'xyz456', description: 'Many spaces before     line' },
   { _id: 103, sku: 'xyz789', description: 'Multiple\nline description' }
]

Without the s option, the example output is:

[
   { _id: 102, sku: 'xyz456', description: 'Many spaces before     line' }
]

Ignore White Spaces in Pattern

The following example uses the x option ignore white spaces and the comments, denoted by the # and ending with the \n in the matching pattern:

var pattern = "abc #category code\n123 #item number"
db.products.find( { sku: { $regex: pattern, $options: "x" } } )

Example output:

[
   { _id: 100, sku: 'abc123', description: 'Single line description.' }
]

Use a Regular Expression to Match Case in Strings

The following example uses the regular expression "(?i)a(?-i)bc" to match sku field strings that contain:

• "abc"

• "Abc"

db.products.find( { sku: { $regex: "(?i)a(?-i)bc" } } )

Example output:

[
   { _id: 100, sku: 'abc123', description: 'Single line description.' },
   { _id: 101, sku: 'abc789', description: 'First line\nSecond line' },
   { _id: 104, sku: 'Abc789', description: 'SKU starts with A' }
]

Extend Regex Options to Match Characters Outside of ASCII

By default, certain regex options (such as /b and /w) only recognize ASCII characters. This can cause unexpected results when performing regex matches against UTF-8 characters.

Starting in MongoDB 6.1, you can specify the *UCP regex option to match UTF-8 characters.

For example, consider the following documents in a songs collection:

db.songs.insertMany( [
   { _id: 0, "artist" : "Blue Öyster Cult", "title": "The Reaper" },
   { _id: 1, "artist": "Blue Öyster Cult", "title": "Godzilla" },
   { _id: 2, "artist" : "Blue Oyster Cult", "title": "Take Me Away" }
] )

The following regex query uses the \b option in a regex match. The \b option matches a word boundary.

db.songs.find( { artist: { $regex: /\byster/ } } )

Example output:

[
   { _id: 0, artist: 'Blue Öyster Cult', title: 'The Reaper' },
   { _id: 1, artist: 'Blue Öyster Cult', title: 'Godzilla' }
]

The previous results are unexpected because none of the words in the returned artist fields begin with the matched string (yster). The Ö character in documents _id: 0 and _id: 1 is ignored when performing the match because it is a UTF-8 character.

The expected result is that the query does not return any documents.

To allow the query to recognize UTF-8 characters, specify the *UCP option before the pattern:

db.songs.find( { artist: { $regex: "(*UCP)/\byster/" } } )

The previous query does not return any documents, which is the expected result.