> ## Documentation Index
> Fetch the complete documentation index at: https://axiom.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://axiom.co/docs/feedback

```json
{
  "path": "/apl/scalar-functions/pair-functions/find-pair",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# 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.

## 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.

<AccordionGroup>
  <Accordion title="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.

    <CodeGroup>
      ```sql Splunk example theme={null}
      | eval found_tag=mvfind(tags, 'host=server.*')
      ```

      ```kusto APL equivalent theme={null}
      ['sample-http-logs']
      | extend tags = dynamic(['host:server1', 'env:prod', 'region:us-west'])
      | extend found = find_pair(tags, 'host', 'server*')
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="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.

    <CodeGroup>
      ```sql SQL example theme={null}
      SELECT *
      FROM logs
      WHERE JSON_EXTRACT(tags, '$[*].key') LIKE 'host%'
      ```

      ```kusto APL equivalent theme={null}
      ['sample-http-logs']
      | extend tags = dynamic(['host:server1', 'env:prod'])
      | extend found = find_pair(tags, 'host*', '*')
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Usage

### Syntax

```kusto theme={null}
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**

```kusto theme={null}
['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](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20extend%20tags%20%3D%20dynamic\(%5B'server%3Aweb01'%2C%20'env%3Aproduction'%2C%20'region%3Aus-west'%5D\)%20%7C%20extend%20server_tag%20%3D%20find_pair\(tags%2C%20'server'%2C%20'*'\)%20%7C%20project%20_time%2C%20uri%2C%20tags%2C%20server_tag%20%7C%20take%205%22%7D)

**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.

## List of related functions

* [parse\_pair](/apl/scalar-functions/pair-functions#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](/apl/scalar-functions/pair-functions#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](/apl/scalar-functions/array-functions/array-index-of): Use `array_index_of` for exact match searches in arrays. Use `find_pair` for pattern-based pair matching.
* [extract](/apl/scalar-functions/string-functions#extract): Use `extract` for regex-based extraction from single strings. Use `find_pair` for structured pair searching in arrays.