Return Multiple Matches as Array Fields

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

Query

flowchart LR; %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%% repo{{Events}} 1["Expression"] result{{Result Set}} repo --> 1 1 --> result
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

The matchAsArray() function can be used to match field values from events against rows in an external CSV file and return multiple columns from matching rows as separate fields in an array format. Unlike the match() function, matchAsArray() adds matching rows to the original event rather than creating new events for each match.

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. flowchart LR; %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%% repo{{Events}} 1["Expression"] result{{Result Set}} repo --> 1 1 --> result style 1 fill:#ff0000,stroke-width:4px,stroke:#000;
    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.