Edit

RegexMatch (NoSQL query)

  • Article

APPLIES TO: NoSQL

This function provides regular expression capabilities. Regular expressions are a concise and flexible notation for finding patterns of text.

Note

Azure Cosmos DB for NoSQL uses PERL compatible regular expressions (PCRE).

Syntax

RegexMatch(<string_expr_1>, <string_expr_2>, [, <string_expr_3>])

Arguments

Description
string_expr_1 A string expression to be searched.
string_expr_2 A string expression with a regular expression defined to use when searching string_expr_1.
string_expr_3 (Optional) An optional string expression with the selected modifiers to use with the regular expression (string_expr_2). If not provided, the default is to run the regular expression match with no modifiers.

Note

Providing an empty string for string_expr_3 is functionally equivalent to omitting the argument.

Return types

Returns a boolean expression.

Examples

The following example illustrates regular expression matches using a few different modifiers.

SELECT VALUE {
    noModifiers: RegexMatch("abcd", "ABC"), 
    caseInsensitive: RegexMatch("abcd", "ABC", "i"), 
    wildcardCharacter: RegexMatch("abcd", "ab.", ""),
    ignoreWhiteSpace: RegexMatch("abcd", "ab c", "x"), 
    caseInsensitiveAndIgnoreWhiteSpace: RegexMatch("abcd", "aB c", "ix"),
    containNumberBetweenZeroAndNine: RegexMatch("03a", "[0-9]"),
    containPrefix: RegexMatch("salt3824908", "salt{1}"),
    containsFiveLetterWordStartingWithS: RegexMatch("shame", "s....", "i")
}

[
  {
    "noModifiers": false,
    "caseInsensitive": true,
    "wildcardCharacter": true,
    "ignoreWhiteSpace": true,
    "caseInsensitiveAndIgnoreWhiteSpace": true,
    "containNumberBetweenZeroAndNine": true,
    "containPrefix": true,
    "containsFiveLetterWordStartingWithS": true
  }
]

The next example assumes that you have a container with items including a name field.

[
  {
    "name": "Tecozow coat",
    "category": "winter-coats"
  },
  {
    "name": "Bladnick coat",
    "category": "winter-coats"
  },
  {
    "name": "Anidin heavy jacket",
    "category": "winter-coats"
  }
]

This example uses a regular expression match as a filter to return a subset of items.

SELECT VALUE
    p.name
FROM
    products p
WHERE
    p.category = "winter-coats" AND    
    RegexMatch(p.name, " coat{1}")

[
  "Tecozow coat",
  "Bladnick coat"
]

Remarks

  • This function benefits from a range index only if the regular expression can be broken down into either StartsWith, EndsWith, Contains, or StringEquals equivalent system functions.
  • Returns undefined if the string expression to be searched (string_expr_1), the regular expression (string_expr_2), or the selected modifiers (string_expr_3) are invalid.
  • This function supports the following four modifiers: | | Format | Description | | --- | --- | --- | | Multiple lines | m | Treat the string expression to be searched as multiple lines. Without this option, the characters ^ and $ match at the beginning or end of the string and not each individual line. | | Match any string | s | Allow "." to match any character, including a newline character. | | Ignore case | i | Ignore case when pattern matching. | | Ignore whitespace | x | Ignore all whitespace characters. |
  • If you'd like to use a meta-character in a regular expression and don't want it to have special meaning, you should escape the metacharacter using \.

Related content