$regex

On this page本页内容

For data hosted on MongoDB Atlas, MongoDB offers a full-text search solution, MongoDB Atlas Search. 对于托管在MongoDB Atlas上的数据，MongoDB提供了全文搜索解决方案MongoDB Attlas search。If you frequently run case-insensitive regex queries (utilizing the i option), MongoDB recommends Atlas Search queries that use the $search aggregation pipeline stage.如果您经常运行不区分大小写的regex查询（利用i选项），MongoDB建议使用$search聚合管道阶段的Atlas Search查询。

Atlas Search queries significiantly improve the performance of text queries and offer more options for customizing query parameters. Atlas Search查询大大提高了文本查询的性能，并提供了更多自定义查询参数的选项。To learn more, see MongoDB Atlas Search.要了解更多信息，请参阅MongoDB Atlas Search。

For self-managed deployments, you can find information on our regex capability below.对于自我管理的部署，您可以在下面找到有关regex功能的信息。

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 vs./pattern/语法。

$options

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

Option选项Description描述Syntax Restrictions语法限制
iCase 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. 此外，它会忽略介于未转义哈希/磅（#）字符和下一新行之间的字符，以便在复杂模式中包含注释。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
sAllows 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 Optionsx选项和s选项

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 JavaScriptPCRE与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. 要在regex模式中使用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及更早版本中，可以将$not运算符用于正则表达式对象（即/pattern/），但不能用于$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.例如，正则表达式/^abc.*/将通过仅匹配以abc开头的索引中的值来优化。

Additionally, while /^a/, /^a.*/, and /^a.*$/ match equivalent strings, they have different performance characteristics. 此外，当/^a/，/^a.*/，和/^a.*$/匹配等效字符串时，它们具有不同的性能特征。All of these expressions use an index if an appropriate index exists; however, /^a.*/, and /^a.*$/ are slower. 如果存在适当的索引，所有这些表达式都使用索引；然而，/^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 LIKE语句：

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." }
←  $mod$text →