Find Pair — axiomhq/docs

Use the find_pair function in APL to search an array of key-value pairs and find the first pair that matches specified key and value patterns. This function combines pattern matching with pair extraction, making it easy to locate specific pairs in collections of metadata or tags.

You use find_pair when working with arrays of pairs (such as tags, labels, or metadata) where you need to find a specific pair based on pattern matching. This is particularly useful in log analysis, OpenTelemetry traces with custom attributes, and any scenario where data is stored as key-value pair 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, you typically iterate through multi-value fields using mvfind or use spath for JSON data. APL's find_pair provides a specialized function for finding key-value pairs with pattern matching.

```sql Splunk example | eval found_tag=mvfind(tags, 'host=server.*') ```

['sample-http-logs']
| extend tags = dynamic(['host:server1', 'env:prod', 'region:us-west'])
| extend found = find_pair(tags, 'host', 'server*')

In ANSI SQL, you typically use JSON_EXTRACT or array functions with LIKE patterns to search arrays. APL's find_pair provides a more direct approach for pair-based searches.

```sql SQL example SELECT * FROM logs WHERE JSON_EXTRACT(tags, '$[*].key') LIKE 'host%' ```

['sample-http-logs']
| extend tags = dynamic(['host:server1', 'env:prod'])
| extend found = find_pair(tags, 'host*', '*')

Usage

Syntax

find_pair(array, key_pattern, value_pattern)
find_pair(array, key_pattern, value_pattern, separator)

Parameters

Name	Type	Description
`array`	`dynamic`	An array of strings representing key-value pairs to search.
`key_pattern`	`string`	A wildcard pattern to match against pair keys. Use `*` for wildcard matching.
`value_pattern`	`string`	A wildcard pattern to match against pair values. Use `*` for wildcard matching.
`separator`	`string`	(Optional) The separator between keys and values in the pairs. Defaults to `:`.

Returns

A dynamic object representing the first matched pair, with key, value and separator properties. Returns null if no matching pair is found.

Example

Use find_pair to extract specific metadata from HTTP logs stored as tag arrays.

Query

['sample-http-logs']
| extend tags = dynamic(['server:web01', 'env:production', 'region:us-west'])
| extend server_tag = find_pair(tags, 'server', '*')
| project _time, uri, tags, server_tag
| take 5

Run in Playground

Output

_time	uri	tags	server_tag
2025-05-26 08:15:30	/api/user	['server:web01', 'env:production', 'region:us-west']	{"separator": ":", "value": "web01", "key": "server"}
2025-05-26 08:16:45	/api/data	['server:web01', 'env:production', 'region:us-west']	{"separator": ":", "value": "web01", "key": "server"}

This query searches tag arrays for server information and extracts the matching pair, making it easy to filter or group by server tags.

parse_pair: Use parse_pair to parse a single pair string into key and value. Use find_pair to search an array of pairs.
pair: Use pair to create a pair string from a key and value. Use find_pair to locate existing pairs in arrays.
array_index_of: Use array_index_of for exact match searches in arrays. Use find_pair for pattern-based pair matching.
extract: Use extract for regex-based extraction from single strings. Use find_pair for structured pair searching in arrays.

#For users of other query languages

#Usage

#Syntax

#Parameters

#Returns

#Example

#List of related functions

Good morning