indexof_regex
This page explains how to use the indexof_regex function in APL.
Use the indexof_regex function to find the position of the first match of a regular expression in a string. The function is helpful when you want to locate a pattern within a larger text field and take action based on its position. For example, you can use indexof_regex to extract fields from semi-structured logs, validate string formats, or trigger alerts when specific patterns appear in log data.
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.
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.