match() Query Function

Search using a CSV or JSON file and enrich entries.

To use this function, you can use the UI to upload a file using the Files menu, or can upload a CSV or JSON file using the lookup api.

You can use it to do something like field IN xxx, where xxx is really all the values in a column=Name in the CSV file=File.CSV you specify.

The default behavior (when strict=true) this function works like an INNER JOIN. With strict=false, this function works like the deprecated lookup() function (i.e., it just enriches events that match), but let all events pass through even if they don’t match.

If using glob=true, the underlying CSV is limited to 20000 rows/lines. It is configurable using the config parameter MAX_STATE_LIMIT. For exact matching glob=false the file is limited to 1000000 rows/lines by default and can be configured using the parameter EXACT_MATCH_LIMIT.

Parameters

Name

Type

Required

Default

Description

file

string

Yes

Specifies the source file.

strict

boolean

No

true

If true (default) only yield events that match a key in the file; if false let all events through (works like the lookup() function).

include

string

No

Specifies columns to include. If no argument given, include all columns from the corresponding row in the output event.

column

string

No

Specifies which column in the file to use for the match. Defaults to the value of the field parameter.

field

string

Yes

Specifies which field in the event (log line) that must match the given column value.

glob

boolean

No

false

If true, the key column in the underlying file is interpreted as a globbing pattern with *.

ignoreCase

boolean

No

false

If true, ignore case when matching against the CSV data.

mode

string

No

string

What function to use when matching against keys. This can either be:
  • string: The matching is done using exact string matching. This is the default.

  • glob: The key is interpreted as a globbing pattern with * and matched accordingly.

  • cidr: The key is interpreted as a CIDR subnet and the event is matched if the field contains an IP within the subnet. If multiple subnets match, the most specific one is selected or an arbitrary one if there are multiple equally specific subnets.

The implied parameter is file.

Examples

Matches events for which the id field matches the value of the column in the table “users.csv”. Does not add any columns.

humio
match(file="users.csv", column=userid, field=id, include=[])

Matches events for which the id field is matched case-insensitive by the glob-pattern in the column userid in the table users.csv, and add all other columns of the first matching row to those events.

humio
id =~ match(file="users.csv", column=userid, mode=glob, ignoreCase=true)

Let all events pass through, but events for which the id field matches the value of the userid column in the table users.csv will be enriched with all other columns of the matching row.

humio
id =~ match(file="users.csv", column=userid, strict=false)

Matches events for which the ip field matches the CIDR subnet of the cidr-block column in the table cidr-file.csv. Only adds the columns info and type from the first matching row.

humio
match(file="cidrfile.csv", column="cidr-block", field=ip, mode=cidr, include=["info","type"])