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.

All regex functions of APL use the RE2 regex syntax.

For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.

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)

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;

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 start value is negative.
• The occurrence value is less than 1.
• The length is set to a value below -1.

Use case examples

Log analysis

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_pos

Run in Playground

Output

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