$regex (query predicate operator)

$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

Index use and performance for $regex queries depends on whether the query is case-sensitive or case-insensitive.

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 similar 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 to perform a case-insensitive match for sku values that start 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' }
]

Match Whole Words Only

Use the \b word boundary anchor to match whole words only. A word boundary matches the position between a word character and a non-word character, or at the start or end of a string.

The following example matches documents where the description field contains the word line as a complete word, but not as part of another word like multiline:

db.products.find( { description: { $regex: /\bline\b/ } } )

[
   { _id: 100, sku: 'abc123', description: 'Single line description.' },
   { _id: 101, sku: 'abc789', description: 'First line\nSecond line' },
   { _id: 102, sku: 'xyz456', description: 'Many spaces before     line' }
]

MongoDB does not return the document with _id: 103 because its description field contains line only as part of the word Multiple\nline. The \n (newline) acts as a word boundary for the second occurrence.

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 doesn't contain an anchor, the pattern matches against the whole string. For 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 (.) to match all characters including new line, and 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 query returns:

[
   { _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, some 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 whole 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 Ö is a UTF-8 character.

The expected result is the query doesn't 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 doesn't return any documents, which is the expected result because none of the whole words in the artist fields begin with the string yster.