$regex

Definition

  • $regex
  • Provides regular expression capabilities for pattern matchingstrings in queries. MongoDB uses Perl compatible regularexpressions (i.e. “PCRE” ) version 8.41 with UTF-8 support.

To use $regex, use one of the following syntaxes:

  1. { <field>: { $regex: /pattern/, $options: '<options>' } }
  2. { <field>: { $regex: 'pattern', $options: '<options>' } }
  3. { <field>: { $regex: /pattern/<options> } }

In MongoDB, you can also use regular expression objects (i.e./pattern/) to specify regular expressions:

  1. { <field>: /pattern/<options> }

For restrictions on particular syntax use, see$regex vs. /pattern/ Syntax.

  • $options
  • The following <options> are available for use with regularexpression.

OptionDescriptionSyntax RestrictionsiCase insensitivity to match upper and lower cases.For an example, see Perform Case-Insensitive Regular Expression Match. mFor patterns that include anchors (i.e. ^ for the start,$ for the end), match at the beginning or end of eachline for strings with multiline values. Without this option,these anchors match at beginning or end of the string. For anexample, see Multiline Match for Lines Starting with Specified Pattern.

If the pattern contains no anchors or if the string value hasno newline characters (e.g. \n), the m option has noeffect. x“Extended” capability to ignore all white space characters inthe $regex pattern unless escaped or included in acharacter class.

Additionally, it ignores characters in-between and includingan un-escaped hash/pound (#) character and the next newline, so that you may include comments in complicatedpatterns. This only applies to data characters; white spacecharacters may never appear within special charactersequences in a pattern.

The x option does not affect the handling of the VTcharacter (i.e. code 11).Requires $regex with $options syntaxsAllows the dot character (i.e. .) to match allcharacters including newline characters. For an example,see Use the . Dot Character to Match New Line.Requires $regex with $options syntax

Behavior

$regex vs. /pattern/ Syntax

$in Expressions

To include a regular expression in an $in query expression, you canonly use JavaScript regular expression objects (i.e. /pattern/). For example:

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

You cannot use $regex operator expressions inside an$in.

Implicit AND Conditions for the Field

To include a regular expression in a comma-separated list of queryconditions for the field, use the $regex operator. For example:

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

x and s Options

To use either the x option or s options, you must use the$regex operator expression with the $optionsoperator. For example, to specify the i and the s options, youmust use $options for both:

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

PCRE vs JavaScript

To use PCRE supported features in the regex pattern that areunsupported in JavaScript, you must use the $regex operatorexpression with the pattern as a string. For example, to use (?i)in the pattern to turn case-insensitivity on for the remaining patternand (?-i) to turn case-sensitivity on for the remaining pattern, youmust use the $regex operator with the pattern as a string:

  1. { name: { $regex: '(?i)a(?-i)cme' } }

$regex and $not

Starting in 4.0.7, $not operator can perform logical NOToperation on both:

  • regular expression objects (i.e. /pattern/)

For example:

  1. db.inventory.find( { item: { $not: /^p.*/ } } )
  • $regex operator expressions (starting in MongoDB 4.0.7).

For example:

  1. db.inventory.find( { item: { $not: { $regex: "^p.*" } } } )
  2. db.inventory.find( { item: { $not: { $regex: /^p.*/ } } } )

In 4.0.6 and earlier, you could use $not operator with regularexpression objects (i.e. /pattern/) but not with $regexoperator expressions.

Index Use

For case sensitive regular expression queries, if an index exists forthe field, then MongoDB matches the regular expression against thevalues in the index, which can be faster than a collection scan.Further optimization can occur if the regular expression is a “prefixexpression”, which means that all potential matches start with the samestring. This allows MongoDB to construct a “range” from that prefix andonly match against those values from the index that fall within thatrange.

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

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

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

Examples

The following examples use a collection products with the followingdocuments:

  1. { "_id" : 100, "sku" : "abc123", "description" : "Single line description." }
  2. { "_id" : 101, "sku" : "abc789", "description" : "First line\nSecond line" }
  3. { "_id" : 102, "sku" : "xyz456", "description" : "Many spaces before     line" }
  4. { "_id" : 103, "sku" : "xyz789", "description" : "Multiple\nline description" }

Perform a LIKE Match

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

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

The example is analogous to the following SQL LIKE statement:

  1. SELECT * FROM products
  2. WHERE sku like "%789";

Perform Case-Insensitive Regular Expression Match

The following example uses the i option perform acase-insensitive match for documents with sku value that startswith ABC.

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

The query matches the following documents:

  1. { "_id" : 100, "sku" : "abc123", "description" : "Single line description." }
  2. { "_id" : 101, "sku" : "abc789", "description" : "First line\nSecond line" }

Multiline Match for Lines Starting with Specified Pattern

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

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

The query matches the following documents:

  1. { "_id" : 100, "sku" : "abc123", "description" : "Single line description." }
  2. { "_id" : 101, "sku" : "abc789", "description" : "First line\nSecond line" }

Without the m option, the query would match just the following document:

  1. { "_id" : 100, "sku" : "abc123", "description" : "Single line description." }

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

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

Then, the $regex would match both documents:

  1. { "_id" : 100, "sku" : "abc123", "description" : "Single line description." }
  2. { "_id" : 101, "sku" : "abc789", "description" : "First line\nSecond line" }

Use the . Dot Character to Match New Line

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

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

The query matches the following documents:

  1. { "_id" : 102, "sku" : "xyz456", "description" : "Many spaces before     line" }
  2. { "_id" : 103, "sku" : "xyz789", "description" : "Multiple\nline description" }

Without the s option, the query would have matched only the following document:

  1. { "_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 thecomments, denoted by the # and ending with the \n in thematching pattern:

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

The query matches the following document:

  1. { "_id" : 100, "sku" : "abc123", "description" : "Single line description." }