$regex

On this page本页内容

Definition定义

$regex

Provides regular expression capabilities for pattern matching strings in queries. MongoDB uses Perl compatible regular expressions (i.e. “PCRE” ) version 8.42 with UTF-8 support.为查询中的模式匹配字符串提供正则表达式功能。MongoDB使用Perl兼容的正则表达式（即“PCRE”）版本8.42，支持UTF-8。

To use $regex, use one of the following syntaxes:要使用$regex，请使用以下语法之一：

{ <field>: { $regex: /pattern/, $options: '<options>' } }
{ <field>: { $regex: 'pattern', $options: '<options>' } }
{ <field>: { $regex: /pattern/<options> } }

In MongoDB, you can also use regular expression objects (i.e. /pattern/) to specify regular expressions:在MongoDB中，还可以使用正则表达式对象（即/pattern/）来指定正则表达式：

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

For restrictions on particular syntax use, see $regex vs. /pattern/ Syntax.有关特定语法使用的限制，请参阅$regex与/pattern/syntax的对比。

$options

The following <options> are available for use with regular expression.以下<options>可用于正则表达式。

Option选项Description描述Syntax Restrictions语法限制
i Case insensitivity to match upper and lower cases. 大小写不敏感，无法匹配大小写。For an example, see Perform Case-Insensitive Regular Expression Match.有关示例，请参阅执行不区分大小写的正则表达式匹配。  
m

For patterns that include anchors (i.e. ^ for the start, $ for the end), match at the beginning or end of each line for strings with multiline values. 对于包含锚定的图案（即^表示开始，$表示结束），请在每行的开头或结尾匹配具有多行值的字符串。Without this option, these anchors match at beginning or end of the string. 如果没有此选项，这些锚定将在字符串的开头或结尾匹配。For an example, see Multiline Match for Lines Starting with Specified Pattern.例如，请参阅以指定模式开头的行的多行匹配。

If the pattern contains no anchors or if the string value has no newline characters (e.g. \n), the m option has no effect.如果模式不包含锚，或者字符串值没有换行符（例如\n），则m选项无效。

  
x

“Extended” capability to ignore all white space characters in the $regex pattern unless escaped or included in a character class.“扩展”功能可以忽略$regex模式中的所有空白字符，除非转义或包含在字符类中。

Additionally, it ignores characters in-between and including an un-escaped hash/pound (#) character and the next new line, so that you may include comments in complicated patterns. 此外，它会忽略中间的字符，包括一个未转义的hash/pound（#）字符和下一个新行，这样您就可以在复杂的模式中包含注释。This only applies to data characters; white space characters may never appear within special character sequences in a pattern.这只适用于数据字符；空白字符可能永远不会出现在图案中的特殊字符序列中。

The x option does not affect the handling of the VT character (i.e. code 11).x选项不影响VT字符（即代码11）的处理。

 Requires $regex with $options syntax需要带有$options语法的$regex
s Allows the dot character (i.e. .) to match all characters including newline characters. 允许点字符（即.）匹配所有字符，包括换行符。For an example, see Use the . Dot Character to Match New Line.有关示例，请参阅使用.点字符以匹配新行。 Requires $regex with $options syntax需要带有$options语法的$regex

Note

The $regex operator does not support the global search modifier g.$regex运算符不支持全局搜索修饰符g。

Behavior行为

$regex vs. /pattern/ Syntax$regex与/pattern/语法的对比

$in Expressions表达式

To include a regular expression in an $in query expression, you can only use JavaScript regular expression objects (i.e. /pattern/ ). 要在$in查询表达式中包含正则表达式，只能使用JavaScript正则表达式对象（即/pattern/）。For example:例如：

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

You cannot use $regex operator expressions inside an $in.不能在$in中使用$regex运算符表达式。

Implicit AND Conditions for the Field字段的隐式AND条件

To include a regular expression in a comma-separated list of query conditions for the field, use the $regex operator. 要在字段查询条件的逗号分隔列表中包含正则表达式，请使用$regex运算符。For example:例如：

{ name: { $regex: /acme.*corp/i, $nin: [ 'acmeblahcorp' ] } }
{ name: { $regex: /acme.*corp/, $options: 'i', $nin: [ 'acmeblahcorp' ] } }
{ 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 $options operator. 要使用x选项或s选项，必须将$regex运算符表达式与$options运算符一起使用。For example, to specify the i and the s options, you must use $options for both:例如，要指定i和s选项，必须同时使用$options：

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

PCRE vs JavaScript

To use PCRE supported features in the regex pattern that are unsupported in JavaScript, you must use the $regex operator expression with the pattern as a string. 要在正则表达式模式中使用JavaScript中不支持的PCRE支持的功能，必须使用$regex运算符表达式，并将该模式作为字符串。For example, to use (?i) in the pattern to turn case-insensitivity on for the remaining pattern and (?-i) to turn case-sensitivity on for the remaining pattern, you must use the $regex operator with the pattern as a string:例如，要在模式中使用(?i)为剩余模式启用大小写不敏感，以及使用(?-i)为剩余模式启用大小写敏感，必须将$regex运算符作为字符串与模式一起使用：

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

$regex and 和$not

Starting in 4.0.7, $not operator can perform logical NOT operation on both:从4.0.7开始，$not运算符可以对以下两种情况执行逻辑NOT操作：

  • regular expression objects (i.e. /pattern/)正则表达式对象（即/pattern/）

    For example:例如：

    db.inventory.find( { item: { $not: /^p.*/ } } )
  • $regex operator expressions (starting in MongoDB 4.0.7).运算符表达式（从MongoDB 4.0.7开始）。

    For example:例如：

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

In 4.0.6 and earlier, you could use $not operator with regular expression objects (i.e. /pattern/) but not with $regex operator expressions.在4.0.6及更早版本中，可以对正则表达式对象（即/pattern/）使用$not运算符，但不能对$regex运算符表达式使用。

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. 对于区分大小写的正则表达式查询，如果字段存在索引，则MongoDB将正则表达式与索引中的值进行匹配，这可能比集合扫描更快。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.这允许MongoDB根据该前缀构造一个“范围”，并仅与该范围内的索引值匹配。

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. 如果正则表达式以插入符号（^）或左锚（\A）开头，后跟一组简单符号，则它是“前缀表达式”。For example, the regex /^abc.*/ will be optimized by matching only against the values from the index that start with abc.例如，regex/^abc.*/将仅通过匹配以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/、/^a.*/和/^a.*$/匹配等效字符串，但它们具有不同的性能特征。如果存在适当的索引，所有这些表达式都使用索引；但是，/^a.*/和/^a.*$/速度较慢。/^a/ can stop scanning after matching the prefix./^a/匹配前缀后可以停止扫描。

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.$regex实现不支持排序规则，无法使用不区分大小写的索引。

Examples示例

The following examples use a collection products with the following documents:以下示例使用带有以下文档的集合products：

{ "_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" }
{ "_id" : 103, "sku" : "xyz789", "description" : "Multiple\nline description" }

Perform a LIKE Match执行LIKE匹配

The following example matches all documents where the sku field is like "%789":以下示例匹配sku字段类似于"%789"的所有文档：

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

The example is analogous to the following SQL LIKE statement:该示例类似于以下类似SQL的语句：

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

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.以下示例使用i选项对sku值以ABC开头的文档执行不区分大小写的匹配。

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

The query matches the following documents:该查询与以下文档匹配：

{ "_id" : 100, "sku" : "abc123", "description" : "Single line description." }
{ "_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 starting with the letter S for multiline strings:以下示例使用m选项匹配多行字符串中以字母S开头的行：

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

The query matches the following documents:该查询与以下文档匹配：

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

Without the m option, the query would match just the following document:如果没有m选项，查询将只匹配以下文档：

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

If the $regex pattern does not contain an anchor, the pattern matches against the string as a whole, as in the following example:如果$regex模式不包含锚点，则该模式将与整个字符串匹配，如下例所示：

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

Then, the $regex would match both documents:然后，$regex将匹配两个文档：

{ "_id" : 100, "sku" : "abc123", "description" : "Single line description." }
{ "_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 dot character (i.e. .) to match all characters including new line as well as the i option to perform a case-insensitive match:以下示例使用s选项允许点字符（即.）要匹配包括新行在内的所有字符，以及执行不区分大小写匹配的i选项，请执行以下操作：

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

The query matches the following documents:该查询与以下文档匹配：

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

Without the s option, the query would have matched only the following document:如果没有s选项，查询将只匹配以下文档：

{ "_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:下面的示例使用x选项忽略空格和注释，以#表示，并在匹配模式中以\n结尾：

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

The query matches the following document:该查询与以下文档匹配：

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