match()

The match() function converts the target value to a string and returns true if the specified regular expression matches any part of that string.

Syntax

Parameters

VALUE_EXPR

The expression to evaluate. If the result is not a string, it is automatically converted to a string before matching.

REGEX

The regular expression string to match against. Specify the value enclosed in double quotes.

ENGINE

(Optional) The regular expression engine to use. Specify one of the following values.

• jdk-re2j-lax — (Default) Uses the JDK engine first and automatically switches to the RE2/J engine if the matching step limit is exceeded due to excessive backtracking. If RE2/J does not support the given pattern, only the JDK engine is used.
• jdk — Uses only the JDK regular expression engine.
• re2j — Uses only the RE2/J engine. An error is raised if the pattern is not supported by RE2/J.
• jdk-re2j — Enables both JDK and RE2/J engines. Switches to RE2/J when the JDK engine exceeds the matching step limit. An error is raised if RE2/J does not support the pattern.

Description

The match() function evaluates VALUE_EXPR and checks whether the regular expression matches any part of the resulting value. It performs a partial match in the same way as java.util.regex.Matcher.find(), not a full-string match. To check for a full match, use the ^ and $ anchors in the regular expression.

If VALUE_EXPR is null, the function returns false.

The return type is always boolean.

By default, the function operates in jdk-re2j-lax mode, which uses the JDK engine first and automatically switches to the RE2/J engine if the matching step limit is exceeded due to excessive backtracking.

Error codes

Usage examples

To prepare the WEB_APACHE_SAMPLE table used in these examples, refer to Preparing sample data.

1. Check whether a URI matches a specific path pattern

   table limit=5 WEB_APACHE_SAMPLE | eval result = match(uri, "^/archives/") | fields uri, result
   

2. Filter records that match a pattern

   table limit=5 WEB_APACHE_SAMPLE | search match(uri, "^/archives/")
   | # Only records whose URI starts with /archives/ are returned.
   

3. Check whether a User-Agent is a crawler

   table limit=5 WEB_APACHE_SAMPLE | eval is_bot = match(agent, "(?i)bot|crawler|spider") | fields agent, is_bot
   

4. Full match using anchors — with ENGINE option specified

   table limit=5 WEB_APACHE_SAMPLE | eval result = match(method, "^GET$", "re2j") | fields method, result
   

5. NULL input

   json "{'val': null}" | eval result = match(val, "\\d+")
   | # result: false
   

Compatibility

The match() function is available since before Sonar 4.0.