match

The match command is used to limit results to those that meet certain criteria. There can be multiple criterion, and all must be met for a result to be included in the output.

For fields that have multiple values, if any of the values match the criteria then the result will be included in the output.

Syntax

The match command accepts one or more expressions in the following format:

field=<expression>

The format accepts either = or != to indicate whether a field should match (or not) an expression.

The expression can be any of the following:

  • A string, denomiated by double quotes ("). This will match results where the field value is exactly equal to the provided string:
    field="value"
    
  • A regular expression, denoted by forward slashes (/):
    field=/regex/
    
    The regular expression must be in the format used by the rust regex crate here.
  • An identifier, which can be used to compare the values of two fields. This is useful for comparing a field with a value from another field in the same result:
    field1=field2
    
  • A glob expression, denoted as either an identifier or a string either appended or prepended with an asterisk (*). This will match results where the field value either begins or ends with the provided string. There must be exaclty one * in the expression and it can only appear at the beginning or end of the expression:
    field=*value
    field="*value"
    field=value*
    field="value*"
    
  • A wildcard (*), which will match any value for that field. This is useful when you want to check if the field exists, but don't care about its value:
    field=*
    

Combining expressions

Multiple expressions can be combined using common boolean operations via and, or, xor and not. If no operator is specified for multiple expressions then they will be combined with an implicit and operation.

Expressions also support grouping using parentheses () to specifiy the order or grouping of operations, there is no guarantee of order of evaluation otherwise.

Example

field foo contains either the string bar, or has the same value as field baz:

| match foo="bar" OR foo=baz

field foo starts with bar and ends with baz (note that and is implicit here):

| match foo="bar*" foo="*baz"

field foo contains the string bar or baz, or the field x exists:

| match (foo=/bar/ OR foo=/baz/) OR x=*

field foo does not contain the string bar:

| match NOT foo=/bar/
| match foo!=/bar/