Use the pair function to create a dynamic object representing a key-value pair from separate key and value components. This function is useful for constructing structured pair objects that you can use with functions like find_pair to search arrays of pairs.
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.
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 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.
['sample-http-logs']
| extend tag = pair('host', 'server1')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.
['sample-http-logs']
| extend tag = pair('host', 'server1')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_pairOutput
| _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.
List of related functions
- parse_pair: Parses a pair string into a dynamic object with key and value properties. Use
pairto create pair objects directly from components. - find_pair: Searches an array of pairs for a matching key-value pattern. Use
pairto construct pair objects for comparison. - bag_pack: Creates a dynamic property bag from key-value pairs. Use
pairwhen you specifically need the pair object structure with separator.