pair

Use pair when you need to programmatically build key-value pair objects for filtering or matching against pair arrays in your logs. The function returns a dynamic object with key, value, and separator properties.

Usage#

Syntax#

pair(key, value, [separator])

Parameters#

Name	Type	Required	Description
`key`	`string`	Required	The key component of the pair.
`value`	`string`	Required	The value component of the pair.
`separator`	`string`	Optional	The separator to store in the pair object. Defaults to `:`.

Returns#

A dynamic object with the following properties:

key: The key component of the pair.
value: The value component of the pair.
separator: The separator used in the pair.

Example#

Create pair objects to represent request metadata.

Query

['sample-http-logs']
| extend method_pair = pair('method', method)
| project _time, uri, method_pair

Run in Playground

Output

_time	uri	method_pair
2025-01-29 10:48:08	/api/v1/textdata/change	`{"key": "method", "separator": ":", "value": "GET"}`
2025-01-29 10:48:07	/api/v1/sell/bucket	`{"key": "method", "separator": ":", "value": "PUT"}`
2025-01-29 10:48:06	/api/v1/user/notify	`{"key": "method", "separator": ":", "value": "POST"}`

This query creates pair objects from request fields, storing both the key name and value in a structured format.

parse_pair: Parses a pair string into a dynamic object with key and value properties. Use pair to create pair objects directly from components.
find_pair: Searches an array of pairs for a matching key-value pattern. Use pair to construct pair objects for comparison.
bag_pack: Creates a dynamic property bag from key-value pairs. Use pair when you specifically need the pair object structure with separator.

Other query languages#

Splunk SPL users

In Splunk SPL, you typically work with key-value pairs as strings. APL's pair function creates a structured object instead, which you can use for pattern matching with find_pair.

Splunk example

| eval tag = host . ":" . value

APL equivalent

['sample-http-logs']
| extend tag = pair('host', 'server1')

ANSI SQL users

In ANSI SQL, you use CONCAT to build key-value strings or JSON functions to create objects. APL's pair function creates a structured dynamic object directly.

SQL example

SELECT JSON_OBJECT('key', key_col, 'value', value_col) AS tag FROM logs