array_index_of

This page explains how to use the array_index_of function in APL.

The array_index_of function in APL returns the zero-based index of the first occurrence of a specified value within an array. If the value isn’t found, the function returns -1. Use this function when you need to identify the position of a specific item within an array, such as finding the location of an error code in a sequence of logs or pinpointing a particular value within telemetry data arrays.

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

In Splunk SPL, the mvfind function retrieves the position of an element within an array, similar to how array_index_of operates in APL. However, note that APL uses a zero-based index for results, while SPL is one-based.

Splunk example

| eval index=mvfind(array, "value")

ANSI SQL users

ANSI SQL doesn’t have a direct equivalent for finding the index of an element within an array. Typically, you would use a combination of array and search functions if supported by your SQL variant.

SQL example

SELECT POSITION('value' IN ARRAY[...])

Usage

Syntax

array_index_of(array, lookup_value, [start], [length], [occurrence])

Parameters

Name	Type	Required	Description
array	array	Yes	Input array to search.
lookup_value	scalar	Yes	Scalar value to search for in the array. Accepted data types: long, integer, double, datetime, timespan, or string.
start_index	number	No	The index where to start the search. A negative value offsets the starting search value from the end of the array by abs(start_index) steps.
length	number	No	Number of values to examine. A value of -1 means unlimited length.
occurrence	number	No	The number of the occurrence. By default 1.

Returns

array_index_of returns the zero-based index of the first occurrence of the specified lookup_value in array. If lookup_value doesn’t exist in the array, it returns -1.

Use case examples

Log analysis

You can use array_index_of to find the position of a specific HTTP status code within an array of codes in your log analysis.

Query

['sample-http-logs']
| take 50
| summarize status_array = make_list(status)
| extend index_500 = array_index_of(status_array, '500')

Run in Playground

Output

status_array	index_500
[“200”, “404”, “500”]	2

This query creates an array of status codes and identifies the position of the first occurrence of the 500 status.

You can use array_index_of to find the position of a specific HTTP status code within an array of codes in your log analysis.

Query

['sample-http-logs']
| take 50
| summarize status_array = make_list(status)
| extend index_500 = array_index_of(status_array, '500')

Run in Playground

Output

status_array	index_500
[“200”, “404”, “500”]	2

This query creates an array of status codes and identifies the position of the first occurrence of the 500 status.

In OpenTelemetry traces, you can find the position of a specific service.name within an array of service names to detect when a particular service appears.

Query

['otel-demo-traces']
| take 50
| summarize service_array = make_list(['service.name'])
| extend frontend_index = array_index_of(service_array, 'frontend')

Run in Playground

Output

service_array	frontend_index
[“frontend”, “cartservice”]	0

This query collects the array of services and determines where the frontend service first appears.

When working with security logs, array_index_of can help identify the index of a particular error or status code, such as 500, within an array of status codes.

Query

['sample-http-logs']
| take 50
| summarize status_array = make_list(status)
| extend index_500 = array_index_of(status_array, '500')

Run in Playground

Output

status_array	index_500
[“200”, “404”, “500”]	2

This query helps identify at what index the 500 status code appears.

List of related functions

• array_concat: Combines multiple arrays.
• array_rotate_right: Rotates array elements to the right by a specified number of positions.
• array_rotate_left: Rotates elements of an array to the left.