Skip to content
Content was updated:Nov 17, 2025
This is an archived version of the documentation downloaded from LogScale Documentation Archives. Up to date documentation, and documentation for later versions, is available on LogScale Documentation

## `match()`

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 as an ad-hoc table Using Ad-hoc Tables.

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

Parameter | Type | Required | Default Value | Description
--- | --- | --- | --- | ---
`column` | string or array | optional[a] | `field parameter` | Which column in the file to use for the match. A single column or an array of columns can be specified.
`field` | string or array | required |  | 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] | string | required |  | 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)`.
`glob` (deprecated) | boolean | optional[a] | `false` | This parameter is deprecated. Use `mode` parameter with the `glob` option instead. (deprecated in 1.23)
`ignoreCase` | boolean | optional[a] | `false` | If true, ignore case when matching against the CSV data.
|  |  | Values
|  |  | `false` | Perform a case-sensitive match of the event values with the lookup table
|  |  | `true` | Ignore the case of the event values with the lookup table
`include` | string or array | optional[a] |  | The columns to include. If no argument is given, include all columns, except the key columns, from the corresponding row in the output event.
`mode` | string | optional[a] | `string` | The function to use when matching against keys.
|  |  | Values
|  |  | `cidr` | The 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.
|  |  | `glob` | The key is interpreted as a globbing pattern with `*` appended to the beginning and end of the supplied string, and matched accordingly. For example, a CSV key value of `*thisMatch*` would match the field value of `123thisMatch456`. 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`.
|  |  | `string` | The matching is done using exact string matching.
|  | Controlling Variables
|  | `GLOB_MATCH_LIMIT` | Variable default: `20,000`
`strict` | boolean | optional[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. [b] The parameter name `file` can be omitted.

Hide omitted argument names for this function

Show omitted argument names for this function

> Omitted Argument Names

> The argument name for `file` can be omitted; the following forms of this function are equivalent:

> logscale Syntax

>     match("value",field="value")

> and:

> logscale Syntax

>     match(file="value",field="value")

> These examples show basic structure only.

Hide negatable operation for this function

Show negatable operation for this function

> Negatable Function Operation

> This function is negatable, implying the inverse of the result. For example:

> logscale Syntax

>     !match()

> Or:

> logscale Syntax

>     not match()

> For more information, see Negating the Result of Filter Functions.

### `match()` Function Operation

The `match()` function has specific implementation and operational considerations, outlined below.

- 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.

- 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`.

- When using `mode=glob`, the match will order the matches according to their Unicode (or lexicographical) order when there are multiple matches.

### Using `match()` with Lookup Files

When using `match()` for joining with Lookup Files, two file formats are supported:

- CSV. The recommended format, ensures better performance, allows for additional functionalities (using parameters) and is compatible with related functions, like `readFile()`. See CSV File Formats for more information.

- JSON. Supports object and array-based formats. See JSON File Formats for more information.

#### CSV File Formats

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

csv

    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:

logscale

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

the last matching row in `test.csv` is used.

item | value
--- | ---
field1 | c
field2 | e
column3 | f

item | value
--- | ---
field1 | c
column2 | e
column3 | f
field1 | c
column2 | d
column3 | a

item | value
--- | ---
field1 | c
column2 | e
column3 | f
field1 | c
column2 | d
column3 | a
field1 | c
column2 | b
column3 | a

method | description | url
--- | --- | ---
POST | Send Data | /humio/api/v1/ingest/elastic-bulk
POST | Transfer Data in | /humio/api/v1/ingest/elastic-bulk
POST | Transfer Data in | /humio/api/v1/ingest/elastic-bulk
POST | Send Data | /humio/api/v1/ingest/elastic-bulk
POST | Transfer Data in | /humio/api/v1/ingest/elastic-bulk
POST | Send Data | /humio/api/v1/ingest/elastic-bulk

#### JSON File Formats

For JSON files, two formats are supported:

- Object-based, where the lookup field does not have an explicit name

- Array-based, where the information is an array of objects

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.

json

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

### Important

Nested JSON objects are not supported. Uploading a file with nested objects will not fail, but the information cannot be matched.

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:

logscale

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

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

_count | name
--- | ---
2 | krab

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()`.

json

    [
      { "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()`:

logscale

    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:

logscale Syntax

    ...
    | 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

### Important

The `match()` function does not report an error if the file format cannot be parsed.

### `match()` Examples

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

#### Filter For Items Not Part of Data Set Using `!match()`

Find the set difference using the `match()` function with negation

##### Query

logscale

    src_ip=*
    | !match("known_ips.csv", field=src_ip)

##### Introduction

In this example, the `match()` function is used with a negation to search and find IP addresses, that are not part of a known list `known_ips.csv`.

Example incoming data might look like this:

timestamp | src_ip | dst_ip | src_port | dst_port | protocol | bytes_sent | bytes_received
--- | --- | --- | --- | --- | --- | --- | ---
2025-04-01T07:00:00Z | 192.168.1.101 | 10.0.0.50 | 52431 | 443 | TCP | 1024 | 2048
2025-04-01T07:00:01Z | 172.16.0.24 | 8.8.8.8 | 33221 | 53 | UDP | 64 | 512
2025-04-01T07:00:02Z | 192.168.1.150 | 172.16.0.100 | 49223 | 80 | TCP | 2048 | 4096
2025-04-01T07:00:03Z | 10.0.0.75 | 192.168.1.1 | 55678 | 22 | TCP | 512 | 1024
2025-04-01T07:00:04Z | 192.168.1.200 | 1.1.1.1 | 44556 | 53 | UDP | 64 | 512

##### Step-by-Step

1. Starting with the source repository events.

2. logscale

       src_ip=*

   Filters for all events that have a src_ip field.

3. logscale

       | !match("known_ips.csv", field=src_ip)

   Excludes (filters out) any events where the src_ip field matches entries in the file `known_ips.csv`, and returns a list of IP addresses that are not found in the specified file. The negation operator is used to return non-matching results.

4. Event Result set.

##### Summary and Results

The query is used to search for unknown or unexpected source IP addresses matched up againt a known list. This is useful for detecting potential security theats and monitoring for unauthorized network access.

Sample output from the incoming example data:

timestamp | src_ip | dst_ip | src_port | dst_port | protocol | bytes_sent | bytes_received
--- | --- | --- | --- | --- | --- | --- | ---
2025-04-01T07:00:00Z | 192.168.1.101 | 10.0.0.50 | 52431 | 443 | TCP | 1024 | 2048
2025-04-01T07:00:01Z | 172.16.0.24 | 8.8.8.8 | 33221 | 53 | UDP | 64 | 512

#### Match Event Fields Against Lookup Table Values

Compare event fields with column values in a lookup table using the `match()` function

##### Query

logscale

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

##### Introduction

In this example, the `match()` function is used to match the column userid of the `users.csv` file against the id field in the event.

##### Step-by-Step

1. Starting with the source repository events.

2. logscale

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

   Matches events for which the id field matches the value of the column userid in the `users.csv` file (the lookup table file). All events with non-matching IDs are filtered out.

   No additional columns are added.

3. Event Result set.

##### Summary and Results

The query is used to compare and match event fields and file values as strings, in this case using exact string matching (the default value of the `mode` parameter is `string`). The `match()` function is useful for comparing or combining data from multiple sources. In this example, only events with matching values are passed on, meaning that all events with non-matching IDs are removed. Matching events against an authorized users list is, for example, useful for filtering out unauthorized access attempts, for validation of user activities, or other monitoring.

#### Match Event Fields Against Lookup Table Values Adding Specific Columns

Compare event IP fields with CIDR ranges in lookup table using the `match()` function with `mode` parameter

##### Query

logscale

    match(file="cidr-file.csv", column="cidr-block", field=ip, mode=cidr, include=["info","type"])

##### Introduction

In this example, the `match()` function is used to match event IP addresses against the column cidr-block of the `cidr-file.csv` file, adding specific columns details to the events.

The query matches IP addresses against CIDR blocks (CIDR subnets) and adds specific network information from the columns info and type to the output rows.

Example incoming event data might look like this:

@timestamp | ip | action
--- | --- | ---
2024-01-15T09:00:00.000Z | 10.0.1.25 | login
2024-01-15T09:01:00.000Z | 192.168.1.100 | connect
2024-01-15T09:02:00.000Z | 172.16.5.12 | access

Example `cidr-file.csv` file data might look like this:

cidr-block | info | type | location | department
--- | --- | --- | --- | ---
10.0.1.0/24 | Internal Network | corporate | HQ | IT
192.168.1.0/24 | Development Network | test | Lab | Engineering
172.16.0.0/16 | Production Network | critical | DC | Operations

##### Step-by-Step

1. Starting with the source repository events.

2. logscale

       match(file="cidr-file.csv", column="cidr-block", field=ip, mode=cidr, include=["info","type"])

   Uses CIDR ranges matching to match the cidr-block column of the `cidr-file.csv` lookup table file against the IP addresses (ip field) in the events, and adds specific network information to the output rows.

   It will only add the specified columns of the matching row. The column names become new field names.

   Note that when the `mode` parameter is set to `cidr`, then the event is matched if the field contains an IP address within the CIDR subnet. If multiple subnets match, the most specific one is selected, or an arbitrary one, if there are multiple equally specific subnets.

3. Event Result set.

##### Summary and Results

The query is used to match IP addresses against CIDR blocks and add specific network information from the columns info and type to the output rows.

The query helps analyze network traffic and security events by mapping IP addresses to network segments.

Sample output from the incoming example data:

@timestamp | ip | action | info | type
--- | --- | --- | --- | ---
2024-01-15T09:00:00.000Z | 10.0.1.25 | login | Internal Network | corporate
2024-01-15T09:01:00.000Z | 192.168.1.100 | connect | Development Network | test
2024-01-15T09:02:00.000Z | 172.16.5.12 | access | Production Network | critical

Note how only the specified fields from the `cidr-file.csv` file appear in output.

#### Match Event Fields Against Lookup Table Values Allowing All Events to Pass

Compare event fields with column values in lookup table using the `match()` function with `strict` parameter to allow also non-matching events to pass

##### Query

logscale

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

##### Introduction

In this example, the `match()` function is used to match event IDs against the column userid of the `users.csv` file, adding the matching user details to the events. As the `strict` parameter is set to `true`, all events - including non-matching events - are passed through, but only events with matches will be enriched with all other columns of the matching row.

Example incoming event data might look like this:

@timestamp | id | action | source_ip
--- | --- | --- | ---
2024-01-15T09:00:00.000Z | ADMIN-123 | login | 10.0.0.1
2024-01-15T09:01:00.000Z | unknown-user | login_attempt | 10.0.0.2
2024-01-15T09:02:00.000Z | dev-user-456 | code_push | 10.0.0.3

Example `users.csv` file data might look like this:

userid | department | access_level | location
--- | --- | --- | ---
ADMIN-123 | IT | administrator | HQ
dev-user-456 | Engineering | developer | Remote

##### Step-by-Step

1. Starting with the source repository events.

2. logscale

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

   When an event ID matches the column userid in the `users.csv` lookup file, all columns from that first matching row are added to the event. The column names become new field names.

   As the `strict` parameter is set to `true`, all events - including non-matching events - are passed through, but only events with matches will be enriched with all other columns of the matching row.

3. Event Result set.

##### Summary and Results

The query is used to enrich matching events while allowing all events to pass through. Matching events against an authorized users list is, for example, useful for filtering out unauthorized access attempts, for validation of user activities, or other monitoring. Showing non-matching events in output as well can, for example, be useful for tracking unauthorized access attempts, identifying unknown users or systems or for monitoring suspicious activities.

Sample output from the incoming example data:

@timestamp | id | action | source_ip | department | access_level | location
--- | --- | --- | --- | --- | --- | ---
2024-01-15T09:00:00.000Z | ADMIN-123 | login | 10.0.0.1 | IT | administrator | HQ
2024-01-15T09:01:00.000Z | unknown-user | login_attempt | 10.0.0.2 | <no value> | <no value> | <no value>
2024-01-15T09:02:00.000Z | dev-user-456 | code_push | 10.0.0.3 | Engineering | developer | Remote

After matching, the output combines original event fields with matched user details. Note how also non-matching events (in this example `unknown-user`) appear in output.

#### Match Event Fields Against Patterns in Lookup Table Values

Compare event fields with column values containing patterns in a lookup table using the `match()` function with glob pattern matching

##### Query

logscale

    id =~ match(file="users.csv", column=userid, mode=glob, ignoreCase=true)

##### Introduction

In this example, the `match()` function is used with glob pattern matching (defined by the `mode` parameter) to match event IDs against the column userid of the `users.csv` file, adding the matching user details to the events.

Example incoming event data might look like this:

@timestamp | id | action | source_ip
--- | --- | --- | ---
2024-01-15T09:00:00.000Z | ADMIN-123 | login | 10.0.0.1
2024-01-15T09:01:00.000Z | dev-user-456 | code_push | 10.0.0.2
2024-01-15T09:02:00.000Z | TEST_789 | test_run | 10.0.0.3
2024-01-15T09:03:00.000Z | support-001 | ticket_update | 10.0.0.4
2024-01-15T09:04:00.000Z | unknown-user | login_attempt | 10.0.0.5

Example `users.csv` file data might look like this:

userid | department | access_level | location | title
--- | --- | --- | --- | ---
ADMIN-* | IT | administrator | HQ | System Administrator
dev-user-* | Engineering | developer | Remote | Software Engineer
TEST_* | QA | tester | Lab | QA Engineer
support-* | Support | agent | Office | Support Specialist

##### Step-by-Step

1. Starting with the source repository events.

2. logscale

       id =~ match(file="users.csv", column=userid, mode=glob, ignoreCase=true)

   Uses glob pattern matching to match the userid column of the `users.csv` lookup table file against the IDs in the events. When an event ID matches a pattern in `users.csv`, all (non-pattern) columns from that first matching row are added to the event. The column names become new field names.

   Pattern matching examples based on the input data and lookup file are:

   `ADMIN-123` matches `ADMIN-*`

   `dev-user-456` matches `dev-user-*`

   `TEST_789` matches `TEST_*`

   `support-001` matches `support-*`

3. Event Result set.

##### Summary and Results

The query is used to match event IDs against patterns in a user list, and then add the matching user details (other columns from the row in the `users.csv` file) to the events.

Pattern-based matching with field enrichment is, for example, useful in case you want to add user context to authentication logs.

Sample output from the incoming example data:

@timestamp | id | action | source_ip | department | access_level | location | title
--- | --- | --- | --- | --- | --- | --- | ---
2024-01-15T09:00:00.000Z | ADMIN-123 | login | 10.0.0.1 | IT | administrator | HQ | System Administrator
2024-01-15T09:01:00.000Z | dev-user-456 | code_push | 10.0.0.2 | Engineering | developer | Remote | Software Engineer
2024-01-15T09:02:00.000Z | TEST_789 | test_run | 10.0.0.3 | QA | tester | Lab | QA Engineer
2024-01-15T09:03:00.000Z | support-001 | ticket_update | 10.0.0.4 | Support | agent | Office | Support Specialist

After matching, the output combines original event fields with matched user details. Only events with matching patterns appear in output.

#### Match Multiple Pairs of Event Fields Against Multiple Columns in .CSV Lookup File

Compare multiple pairs of event fields against multiple columns in a .CSV lookup file using the `match()` function

##### Query

logscale

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

##### Introduction

In this example, the `match()` function is used to match multiple pairs of fields against multiple columns in a CSV file named `test.csv` simultaneously.

Example incoming event data might look like this:

Example `test.csv` file data might look like this:

column1 | column2 | column3
--- | --- | ---
a | b | d
c | d | a
c | e | f

##### Step-by-Step

1. Starting with the source repository events.

2. logscale

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

   For each event, checks if field1 matches column1 and field2 matches column2

3. Event Result set.

##### Summary and Results

The query is used to match multiple pairs of event fields against multiple columns in the .CSV file named `test.csv`. Multiple field matching helps validate and enrich complex event data.

Sample output from the incoming example data:

column3 | field1 | field2
--- | --- | ---
f | c | e

#### Enter search term