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:

<expression><comparison><expression>

Field names can use dot notation to match nested object values:

object.field="value"

The format accepts comparison operators to indicate whether the left expression should match the right expression. = and != are supported for all expression types. Numeric and field comparisons can also use <, <=, > and >=.

Both sides of a comparison can be field references, dotted paths, literals, or eval expressions. Pattern expressions such as regular expressions, globs, wildcards, IP functions, and IN groups are used on the right side.

The expression can be any of the following:

• A string, denominated 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
  

• An eval expression, which can be used to compare against a calculated value:

  field1=field2+1
  field1=(field2 * 2)
  field1+10>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 exactly 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=*
  

• An IP function, which can be used to match IP addresses against various criteria:

  • cidr("network") - matches IP addresses within a CIDR range
  • privateip() - matches private IP addresses
  • linkip() - matches link-local IP addresses
  • globalip() - matches globally routable IP addresses

  field=cidr("192.168.0.0/16")
  field=privateip()
  field=linkip()
  field=globalip()
  

• A group expression using the in operator, which allows matching against multiple values:

  field IN ("value1", "value2", /regex/)
  field IN (cidr("192.168.0.0/16"), privateip())
  

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.

Precedence is not, and/implicit and, xor, then or; binary operators are left-associative. Use parentheses () to override it.

Example

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

| match foo="bar" OR foo=baz

field left is lower than field right:

| match left<right

the sum of bytes_in and bytes_out is greater than limit:

| match bytes_in+bytes_out>limit

field foo.bar in a nested object contains the string baz:

| match foo.bar="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/

| match foo!=/bar/

field foo matches exactly one of two values:

| match foo="bar" ^ foo="baz"

field foo matches a CIDR range:

| match foo=cidr("192.168.0.0/16")

field foo contains one of several values:

| match foo IN ("value1", "value2", /regex/)