match( ) Query Function

Search using a CSV or JSON file and enrich entries.

To use this function, you need to 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 bool 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 bool No false If true, the key column in the underlying file is interpreted as a globbing pattern with *.
ignoreCase bool No false If true, ignore case when matching against the CSV data.

file is the unnamed parameter.

Examples

matches events for which the ‘id’ field matches the value of ‘userid’ in the table “users.csv”.

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

matches events for which the ‘id’ field is matched by the glob-pattern of ‘userid’ in the table “users.csv”, and add all other columns of the first matching row to those events.

id =~ match(file="users.csv", column=userid, glob=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 columns of the matching row.

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