Matches or joins data from query results with a table, similar to the match() function. 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 as an ad-hoc table Using Ad-hoc Tables.

Note

Both the matchAsArray() and match() functions search for matches in the data and join query results with a table, but they structure the results differently.

Unlike match() (match()), matchAsArray() adds matching rows to the original event rather than creating new events for each match and only supports exact matching mode.

ParameterTypeRequiredDefault ValueDescription
asArraystringoptional[a] _now Name of the output array.
columnstring or arrayoptional[a] field parameter Which column in the file to use for the match. A single column or an array of 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.
filestringrequired   Specifies the source file (when using Lookup Files) or the name of the ad-hoc table. The file name should be specified with a .csv or .json suffix. In case of ad-hoc tables, you can alternatively use table as an alias of the file parameter, for example match(table="tablename", field=fieldname, column=name).
ignoreCasebooleanoptional[a] false If true, ignore case when matching against the CSV data.
   Values
   falsePerform a case-sensitive match of the event values with the lookup table
   trueIgnore the case of the event values with the lookup table
includestring or arrayoptional[a]   The columns to include. If no argument is given, include all columns from the corresponding row in the output event.
strictbooleanoptional[a] true If true (the default) selects only the events 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.

The argument name for array can be omitted.

A specific syntax applies for this query function, see Array Syntax for details.

matchAsArray() Function Operation

The matchAsArray() function operates and matches events similar to match(), with these key differences:

  • The function supports only exact matching mode, therefore, the mode parameter is omitted.

  • For multiple matches, matchAsArray() combines all matching rows into structured arrays within a single event. This differs from match(), which creates separate events for each matching row

  • The structured arrays have a maximum length of nrows. If matches exceed nrows, the arrays contain only the latest nrows matches.

  • You can customize the structured array name by using the asArray parameter.

All other parameters of the matchAsArray() function match the match() function.

For more information about the operation of the matchAsArray() function, see match() and ad-hoc table.

matchAsArray() Syntax Examples

This example shows how to match multiple field values from events against multiple columns in an external CSV file and return the multiple matches as array fields.

logscale Syntax
matchAsArray(host_inventory.csv, field=["hostname","os"], column=["hostname","os_type"], nrows=2, asArray="host_details[]")

If event data looks like this:

@timestamphostnameosstatus
2025-10-14T10:00:00ZWKST-001Windowsonline
2025-10-14T10:05:00ZWKST-002Linuxoffline
2025-10-14T10:10:00ZSRV-DB01Linuxonline

and the reference CSV file (host_inventory.csv) contains:

csv
hostname,ip_address,os_type,department,
WKST-001,192.168.1.100,Windows,Finance,
WKST-001,10.0.1.50,Windows,Finance,
WKST-002,192.168.1.101,Linux,Engineering,
SRV-DB01,10.0.2.10,Linux,IT

it would return:

host_details[0].departmenthost_details[0].ip_addresshost_details[1].departmenthost_details[1].ip_addresshostnameosstatus
Finance10.0.1.50Finance192.168.1.100WKST-001Windowsonline
Engineering192.168.1.101<no value><no value>WKST-002Linuxoffline
IT10.0.2.10<no value><no value>SRV-DB01Linuxonline

The example above demonstrates that matchAsArray():

  • Returns multiple matches in array notation (as seen with host_details[0].ip_address=10.0.1.50 and host_details[1].ip_address=192.168.1.100 for WKST-001), though match order may vary.

  • Uses empty values in array fields when fewer matches exist (shown by empty host_details[1] fields for WKST-002 and SRV-DB01).

  • Preserves original event fields (hostname, os, status) while adding matched data from the CSV (department, ip_address).

Click + next to an example below to get the full details.

Return Multiple Matches as Array Fields

Enrich events with user context from external CSV file using the matchAsArray() function

Query
logscale
matchAsArray(file="falconUserIdentityContext.csv", field=["user.email"], column="user.email", ignoreCase=true, include=["entityID","displayName","user.active_directory.domain"], nrows=2, asArray="_result[]")
Introduction

In this example, the matchAsArray() function is used to look up user information by matching email addresses from events against a CSV file containing user identity data, returning up to two matching rows per event.

Example incoming data might look like this:

@timestampuser.emailuser.id
2025-10-14T10:00:00Ztest1@gmail.com1
2025-10-14T10:05:00Ztest2@gmail.com2

The reference CSV file (falconUserIdentityContext.csv) contains:

csv
user.email,entityID,displayName,user.active_directory.domain
test1@gmail.com,123,Testy McTestington,DET23.TEST
test2@gmail.com,456,Tester2,DET23.TEST2
test1@gmail.com,789,Testy McTestington,DET23.IDPRO
Step-by-Step

  1. Starting with the source repository events.

  2. logscale
    matchAsArray(file="falconUserIdentityContext.csv", field=["user.email"], column="user.email", ignoreCase=true, include=["entityID","displayName","user.active_directory.domain"], nrows=2, asArray="_result[]")

    Matches the user.email field from events against the user.email column in the CSV file.

    For each match:

    • Returns up to 2 matching rows (specified by nrows=2).

    • Includes only the specified columns: entityID, displayName, and user.active_directory.domain.

    • Creates array fields prefixed with _result[0] for the first match and _result[1] for the second match.

    • Performs case-insensitive matching (ignoreCase=true).

    The ignoreCase=true parameter ensures case-insensitive matching.

  3. Event Result set.

Summary and Results

The query is used to enrich event data with user context information by matching email addresses against a reference CSV file, supporting multiple matches per email address. The query creates separate fields for each matching row with array index notation.

This query is useful, for example, to identify users with multiple organizational contexts or to enrich security events with all relevant user identity information.

Sample output from the incoming example data:

_result[0].displayName_result[0].entityID_result[0].user.active_directory.domain_result[1].displayName_result[1].entityID_result[1].user.active_directory.domainuser.emailuser.id
Testy McTestington789DET23.IDPROTesty McTestington123DET23.TESTtest1@gmail.com1
Tester2456DET23.TEST2<no value><no value><no value>test2@gmail.com2

Note that each matching row creates separate fields with array index notation (_result[0], _result[1]) and that the original event fields are also preserved in the output.

When fewer than 2 matches are found (as with test2@gmail.com), the second set of fields (_result[1]) contains empty values.

Note

While both matchAsArray() and match() join query results with a table, matchAsArray() differs in two important ways:

  • matchAsArray() adds all matching rows as an object array to the original event instead of creating separate events for each match.

  • matchAsArray() only supports exact matching mode.