indexof_regex
The function returns the zero-based index of the first match. If no match is found, it returns -1. Use indexof_regex when you need more flexibility than simple substring search (indexof), especially when working with dynamic or non-fixed patterns.
All regex functions of APL use the RE2 regex syntax.
Usage#
Syntax#
indexof_regex(string, match [, start [, occurrence [, length]]])Parameters#
| Name | Type | Required | Description |
|---|---|---|---|
| string | string | Yes | The input text to inspect. |
| match | string | Yes | The regular expression pattern to search for. |
| start | int | The index in the string where to begin the search. If negative, the function starts that many characters from the end. | |
| occurrence | int | Which instance of the pattern to match. Defaults to 1 if not specified. |
|
| length | int | The number of characters to search through. Use -1 to search to the end of the string. |
Returns#
The function returns the position (starting at zero) where the pattern first matches within the string. If the pattern isn’t found, the result is -1.
The function returns null in the following cases:
- The
startvalue is negative. - The
occurrencevalue is less than 1. - The
lengthis set to a value below-1.
Use case examples#
Use indexof_regex to detect whether the URI in a log entry contains an encoded user ID by checking for patterns like user-[0-9]+.
Query
['sample-http-logs']
| extend user_id_pos = indexof_regex(uri, 'user-[0-9]+')
| where user_id_pos != -1
| project _time, id, uri, user_id_posOutput
| _time | id | uri | user_id_pos |
|---|---|---|---|
| 2025-06-10T12:34:56Z | user42 | /api/user-12345/settings | 5 |
| 2025-06-10T12:35:07Z | user91 | /v2/user-6789/dashboard | 4 |
The query finds log entries where the URI contains a user ID pattern and shows the position of the match in the URI string.
Use indexof_regex to detect trace IDs that include a specific structure, such as four groups of hex digits.
Query
['otel-demo-traces']
| extend match_index = indexof_regex(trace_id, '^[0-9a-f]{8}-[0-9a-f]{4}')
| where match_index == 0
| project _time, trace_id, match_indexOutput
| _time | trace_id | match_index |
|---|---|---|
| 2025-06-10T08:23:12Z | ab12cd34-1234-5678-9abc-def123456789 | 0 |
| 2025-06-10T08:24:55Z | fe98ba76-4321-abcd-8765-fedcba987654 | 0 |
This query finds spans where the trace ID begins with a specific regex pattern, helping validate span ID formatting.
Use indexof_regex to locate suspicious request patterns such as attempts to access system files (/etc/passwd).
Query
['sample-http-logs']
| extend passwd_index = indexof_regex(uri, '/etc/passwd')
| where passwd_index != -1
| project _time, id, uri, passwd_indexOutput
| _time | id | uri | passwd_index |
|---|---|---|---|
| 2025-06-10T10:15:45Z | user88 | /cgi-bin/view?path=/etc/passwd | 20 |
This query detects HTTP requests attempting to access sensitive file paths, a common indicator of intrusion attempts.
Other query languages#
Splunk SPL users
Use match() in Splunk SPL to perform regular expression matching. However, match() returns a Boolean, not the match position. APL’s indexof_regex is similar to combining match() with additional logic to extract position, which isn’t natively supported in SPL.
Splunk example
... | eval match_index=if(match(field, "pattern"), 0, -1)APL equivalent
['dataset']
| extend match_index = indexof_regex(field, 'pattern')ANSI SQL users
ANSI SQL doesn’t have a built-in function to return the index of a regex match. You typically use REGEXP_LIKE for Boolean evaluation. indexof_regex provides a more direct and powerful way to find the exact match position in APL.
SQL example
SELECT CASE WHEN REGEXP_LIKE(field, 'pattern') THEN 0 ELSE -1 END FROM table;APL equivalent
['dataset']
| extend match_index = indexof_regex(field, 'pattern')