find_pair

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

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.

Usage

Syntax

APL

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

APLRun in Playground

['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

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.