Matches or joins data from query results with a table. The table can be provided either as a LookUp file — CSV file or through a limited form of JSON file, uploaded using Lookup Files — or, from LogScale 1.163, as an ad-hoc table Using Ad-hoc Tables.

If you are looking for match expressions, see Match Statements.

ParameterTypeRequiredDefault ValueDescription
columnstring or arrayoptional[a] field parameter Which column in the file to use for the match. A single column or an array or columns can be specified.
fieldstring or arrayrequired   Which field in the event (log line) must match the given column value. A single field or an array of fields can be specified. Field and column must have the same length, are matched in order and must all match.
file[b]stringrequired   Specifies the source file (when using Look Up files) or the name of the ad-hoc table. The file name should be specified with .csv or .json suffix.
glob (deprecated)booleanoptional[a] false This parameter is deprecated. Use mode=glob instead. (deprecated in 1.23.0)
ignoreCasebooleanoptional[a] false If true, ignore case when matching against the CSV data.
includestring or arrayoptional[a]   The columns to include. If no argument is given, include all columns from the corresponding row in the output event.
modestringoptional[a] string The function to use when matching against keys.
   Valid Values
   cidrThe 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.
   globThe key is interpreted as a globbing pattern with * and matched accordingly, for example, a CSV key value of *thisMatch* would match the field value of 123thisMatch456.
   stringThe matching is done using exact string matching.
strictbooleanoptional[a] true If true (the default) selects only the fields that match a key in the file; if false lets all events through (works like the deprecated lookup()).

[a] Optional parameters use their default value unless explicitly set.

[b] The parameter name file can be omitted.

Hide omitted argument names for this function

Show omitted argument names for this function

Hide negatable operation for this function

Show negatable operation for this function

When lookup information from files are loaded from a package, the package name should be specified in addition to the filename. For example:

logscale
match("falcon/investigate/logoninfo.csv",field="loookupname")

For more information on referring to package resources, see Referencing Package Assets.

The default behavior of this function — when strict is set to true — works like an INNER JOIN. When strict is set to false the function enriches events.

Note

Up until LogScale version 1.140, the file is limited to 1,000,000 rows/lines for exact matching using mode=string.

When using mode=glob, the underlying CSV is limited to 20,000 rows/lines.

For self-hosted customers, the maximum value for glob matches is configurable using GLOB_MATCH_LIMIT.