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.
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.
let index = array_index_of(array, 'value')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.
let index = array_index_of(array, 'value')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
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')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')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')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.