find_pair

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.

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.

Other query languages#

Splunk SPL users

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.

Splunk example

| eval found_tag=mvfind(tags, 'host=server.*')

APL equivalent

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

ANSI SQL users

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 example

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