Regular expressions in Neptune

In Neptune, you can use regular expressions to do the following:

• Filter which attributes are displayed in Charts, Side-by-side, and Reports.
• Configure a chart widget to dynamically display matching metrics in a dashboard or report.
• Match names or string attributes when building queries in the runs table or via API.

Regex engine details

Neptune uses the RE2 library to handle regular expressions.

For performance and security reasons, RE2 doesn't implement some common regex features, such as backreferences or look-around assertions. To work around this limitation, Neptune implements its own text-based extended syntax.

Using regex search

To use regular expressions in the Neptune web app:

• In the search bar, ensure that the icon is active.
• Use the Ctrl/Cmd + / key shortcut to togle between regex and text mode.

Extended regular expressions

When the search bar has the special icon, you can use Neptune's extended regex syntax. This syntax supports additional operators for regex patterns: & (AND) and | (OR).

For the full reference, see Extended syntax.

The extended syntax isn't supported in the Side-by-side view, attribute selection dropdown menus, or the Fetcher API.

Examples:

Valid queries

Concatenation and alternation

pattern-A & pattern-B | pattern-C & !pattern-D

Resulting query: pattern-A AND pattern-B OR pattern-C AND NOT pattern-D

Concatenation and escaping special characters

pattern-A & \x21hola\x20amigos!

Resulting query: pattern-A AND !hola amigos!

If operator characters aren't preceded by spaces, they're matched literally

pattern-A & !patt!ern&|-B!

Resulting query: pattern-A AND NOT patt!ern&|-B!

Invalid queries

Negation isn't supported at the beginning of a query

!pattern-A

The OR NOT operator isn't supported

pattern-A | !pattern-B

Runs table filters

You can use regular expressions in runs table filters. To match any String attribute against a regex:

1. To open the query builder, click next to the search bar.

2. Select a string attribute from the list.

   For example, sys/description is an auto-generated string attribute. For how to create custom string attributes, see Log metadata: Text.

3. Select the matches or not matches operator.

4. Enter a regular expression.

For details, see Runs table: Searching and filtering runs.

NQL query in Fetcher API

To match a logged string against a regular expression, use the MATCHES or NOT MATCHES operator in the query argument:

Matches regex

project.fetch_runs_df(
    query=r'`parameters/optimizer`:string MATCHES "Ada\\w+"'
)

For details, see NQL reference: String.

Syntax reference

The following tables list some of the most common syntax. For the full reference, see the RE2 syntax guide.

Single-character expressions

Expression	Description	Example pattern	Example match	Doesn't match
.	Any one character, except newline	metrics/./loss	metrics/a/loss	metrics/test/loss
[abc]	Any one of the characters a, b, c	metrics/[abc]	metrics/a	metrics/d
[^abc]	Any one character except a, b, c	metrics/[^abc]	metrics/e	metrics/a
\d	Any one digit	metrics/\d	metrics/3	metrics/a
\w	Any one word character (digit, letter, or underscore)	metrics/\w+/loss	metrics/estimated/loss	metrics/loss

Repetitions

Expression	Description	Example pattern	Example match	Doesn't match
+	One or more of the preceding element	metrics/a+	metrics/a, metrics/aaa	metrics/b
?	Zero or one of the preceding element	loss(_a)?/final	loss/final, loss_a/final	loss_final
*	Zero or more of the preceding element	metrics/a*/loss	metrics//loss, metrics/a/loss, metrics/aaaaa/loss	metrics/loss
{n}	Exactly n of the preceding element	loss_a{2}	loss_aa	loss_a

Empty strings

Expression	Description	Example pattern	Matches	Doesn't match
^	Beginning of text	^metrics/	metrics/loss	test/metrics/loss
$	End of text	loss$	metrics/loss	metrics/loss/estimated
\b	At ASCII word boundary	metrics\b	metrics/loss	metric/loss

Extended syntax

For usage examples, see Extended regular expressions.

Operators

Expression	Description	Example query	Meaning	Example match
&	AND	pred & _loss$	pred AND loss$	predicted/ah6kj/loss
|	OR	pred | _loss$	pred OR loss$	predicted/loss/ah6kj
& !	AND NOT	pred & !_loss$	pred AND NOT loss$	predicted/loss/ah6kj

note

The symbols must be preceded by a space. Otherwise they are treated as literal characters, not operators.

• The concatenation operator (AND) takes precedence over alternation (OR).
• For expressions alternated with OR, the first match from the left is preferred.

Special entities

Entity	Description	Example query	Example match
\x20	Literal space	my\x20spacious\x20string	my spacious string
\x21	Literal exclamation point in pattern-initial position	\x21hola!	!hola!