For Comma Separated Values (CSV) files, whitespace gets included in the keys and values. To include the separator "," in a value, quote using the " character. The following file is a valid CSV file:

userid,name
1,chr
2,krab
"4","p,m"
7,mgr

The first line is interpreted as the column title. When querying, the column in the field should be used to identify which column to match against.

When using match() with a single column:

match(test.csv, field=somefield, column=column1)

the last matching row in test.csv is used.

Since the function supports the selection of an array of columns, you can match multiple pairs of fields and columns against a CSV file. For example, with these events and fields:

{
field1: c,
field2: f
},
{
field1: c,
field2: e
}

and the following test.csv match file:

column1, column2, column3
a,        b,      d
c,        d,      a
c,        e,      f

The example query:

match(test.csv, field=[field1, field2], column=[column1, column2])

will produce the following output:

Similar to when matching against a single column, in the case of multiple columns, the function will use the last matching row in the file. This behavior is applied starting from version 1.145.

match() supports matching on multiple rows, meaning that you can match a single event with multiple rows. Each matching row will generate a separate event.

Example 1 with nrows=2. With event:

{
field1: c
}

and the following test.csv match file:

column1, column2, column3
c,        b,      a
a,        b,      d
c,        d,      a
c,        e,      f

The example query:

match(test.csv, field=field1, column=column1, nrows=2)

will generate the following output:

Example 2 with nrows=max. With event:

{
field1: c
}

and the following test.csv match file:

column1, column2, column3
c,        b,      a
a,        b,      d
c,        d,      a
c,        e,      f

The example query:

match(some.csv, field=field1, column=column1, nrows=max)

will generate the following output:

Example 3 with nrows=2. Given weblog data, HTTP methods could be matched to multiple rows for the type of output:

method=POST
| match(file="methods.csv",nrows=2,field=method,column="method")

The following methods.csv match file:

method,description
POST,Send Data
POST,Transfer Data in
GET,Retrieve Data
GET,Get Data

could be matched with a longer description, showing two different rows for each matching source row:

When matching multiple rows, multiple events, matching the number of matched nrows, will be generated for each corresponding event and matched lookup entry.

For JSON files, two formats are supported:

In the Object-based variant, the lookup values are declared as an object with a key and embedded fields, the key field does not have a name.

{
  "1": { "name": "chr" },
  "2": { "name": "krab" },
  "4": { "name": "pmm" },
  "7": { "name": "mgr" }
}

When matching against a file in this case, the name of the field in the JSON object does not need to be used; the key for each value is used instead. For example:

groupBy(@timezone)
| count(@timezone)
| match(file="short.json",field=_count)

In the above, the value of _count will be matched, outputting the match value:

In the array-based variant, the lookup values are declared as an array of objects, you select which field is the key using the field parameter in match().

[
  { "userid": "1", "name": "chr" },
  { "userid": "2", "name": "krab" },
  { "userid": "4", "name": "pmm" },
  { "userid": "7", "name": "mgr" }
]

When using this version, the name of the column to be matched must be specified using the column argument to match():

groupBy(@timezone)
| count(@timezone)
| match(file="long.json",field=_count,column="userid")

This behavior also means that any field in the JSON file can be used as the match value. For example:

...
| match(file="long.json",field=codename,column="name")

This can be useful if you have a JSON file that contains multiple possible lookup values for given records.

For