|
| 1 | +--- |
| 2 | +title: array_extract |
| 3 | +description: 'This page explains how to use the array_extract function in APL.' |
| 4 | +--- |
| 5 | + |
| 6 | +Use the `array_extract` function to extract specific values from a dynamic array using a JSON path expression. You can use this function to transform structured array data, such as arrays of objects, into simpler arrays of scalars. This is useful when working with nested JSON-like structures where you need to extract only selected fields for analysis, visualization, or filtering. |
| 7 | + |
| 8 | +Use `array_extract` when: |
| 9 | + |
| 10 | +- You need to pull scalar values from arrays of objects. |
| 11 | +- You want to simplify a nested data structure before further analysis. |
| 12 | +- You are working with structured logs or metrics where key values are nested inside arrays. |
| 13 | + |
| 14 | +## For users of other query languages |
| 15 | + |
| 16 | +If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL. |
| 17 | + |
| 18 | +<AccordionGroup> |
| 19 | +<Accordion title="Splunk SPL users"> |
| 20 | + |
| 21 | +In Splunk SPL, you typically use `spath` with a wildcard or field extraction logic to navigate nested structures. APL’s `array_extract` uses JSON path syntax to extract array elements that match a given pattern. |
| 22 | + |
| 23 | +<CodeGroup> |
| 24 | +```sql Splunk example |
| 25 | +| eval arr=mvappend("{\"id\":1,\"value\":true}", "{\"id\":2,\"value\":false}") |
| 26 | +| spath input=arr path="{}.value" output=extracted_value |
| 27 | +```` |
| 28 | + |
| 29 | +```kusto APL equivalent |
| 30 | +['sample-http-logs'] |
| 31 | +| extend extracted_value = array_extract(dynamic([{'id': 1, 'value': true}, {'id': 2, 'value': false}]), @'$[*].value') |
| 32 | +| project _time, extracted_value |
| 33 | +``` |
| 34 | + |
| 35 | +</CodeGroup> |
| 36 | + |
| 37 | +</Accordion> |
| 38 | +<Accordion title="ANSI SQL users"> |
| 39 | + |
| 40 | +ANSI SQL doesn’t offer native support for JSON path queries on arrays in standard syntax. While some engines support functions like `JSON_VALUE` or `JSON_TABLE`, they operate on single objects. APL’s `array_extract` provides a concise and expressive way to query arrays using JSON path. |
| 41 | + |
| 42 | +<CodeGroup> |
| 43 | +```sql SQL example |
| 44 | +SELECT JSON_EXTRACT(data, '$[*].value') AS extracted_value |
| 45 | +FROM my_table; |
| 46 | +``` |
| 47 | + |
| 48 | +```kusto APL equivalent |
| 49 | +['sample-http-logs'] |
| 50 | +| extend extracted_value = array_extract(dynamic([{'id': 1, 'value': true}, {'id': 2, 'value': false}]), @'$[*].value') |
| 51 | +| project _time, extracted_value |
| 52 | +``` |
| 53 | + |
| 54 | +</CodeGroup> |
| 55 | + |
| 56 | +</Accordion> |
| 57 | +</AccordionGroup> |
| 58 | + |
| 59 | +## Usage |
| 60 | + |
| 61 | +### Syntax |
| 62 | + |
| 63 | +```kusto |
| 64 | +array_extract(sourceArray, jsonPath) |
| 65 | +``` |
| 66 | + |
| 67 | +### Parameters |
| 68 | + |
| 69 | +| Name | Type | Description | |
| 70 | +| ------------- | --------- | ------------------------------------------------------- | |
| 71 | +| `sourceArray` | `dynamic` | A JSON-like dynamic array to extract values from. | |
| 72 | +| `jsonPath` | `string` | A JSON path expression to select values from the array. | |
| 73 | + |
| 74 | +### Returns |
| 75 | + |
| 76 | +A dynamic array of values that match the JSON path expression. The function always returns an array, even when the path matches only one element or no elements. |
| 77 | + |
| 78 | +## Use case examples |
| 79 | + |
| 80 | +<Tabs> |
| 81 | +<Tab title="Log analysis"> |
| 82 | + |
| 83 | +Use `array_extract` to retrieve specific fields from structured arrays, such as arrays of request metadata. |
| 84 | + |
| 85 | +**Query** |
| 86 | + |
| 87 | +```kusto |
| 88 | +['sample-http-logs'] |
| 89 | +| extend extracted_value = array_extract(dynamic([{'id': 1, 'value': true}, {'id': 2, 'value': false}]), @'$[*].value') |
| 90 | +| project _time, extracted_value |
| 91 | +``` |
| 92 | + |
| 93 | +[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%20extracted_value%20%3D%20array_extract%28dynamic%28[%7B'id'%3A%201%2C%20'value'%3A%20true%7D%2C%20%7B'id'%3A%202%2C%20'value'%3A%20false%7D]%29%2C%20%40'%24%5B*%5D.value'%29%20%7C%20project%20_time%2C%20extracted_value%22%7D) |
| 94 | + |
| 95 | +**Output** |
| 96 | + |
| 97 | +| _time | extracted_value | |
| 98 | +| ---------------- | ------------------ | |
| 99 | +| Jun 24, 09:28:10 | ["true", "false"] | |
| 100 | +| Jun 24, 09:28:10 | ["true", "false"] | |
| 101 | +| Jun 24, 09:28:10 | ["true", "false"] | |
| 102 | + |
| 103 | +This query extracts the `value` field from an array of objects, returning a flat array of booleans in string form. |
| 104 | + |
| 105 | +</Tab> |
| 106 | +<Tab title="OpenTelemetry traces"> |
| 107 | + |
| 108 | +Use `array_extract` to extract service names from a nested structure—for example, collecting `service.name` from span records in a trace bundle. |
| 109 | + |
| 110 | +**Query** |
| 111 | + |
| 112 | +```kusto |
| 113 | +['otel-demo-traces'] |
| 114 | +| summarize traces=make_list(pack('trace_id', trace_id, 'service', ['service.name'])) by span_id |
| 115 | +| extend services=array_extract(traces, @'$[*].service') |
| 116 | +``` |
| 117 | + |
| 118 | +[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%20%7C%20summarize%20traces%3Dmake_list%28pack%28'trace_id'%2C%20trace_id%2C%20'service'%2C%20%5B'service.name'%5D%29%29%20by%20span_id%20%7C%20extend%20services%3Darray_extract%28traces%2C%20%40'%24%5B*%5D.service'%29%22%7D) |
| 119 | + |
| 120 | +**Output** |
| 121 | + |
| 122 | +| span_id | services | |
| 123 | +| ---------------- | -------------------------------------- | |
| 124 | +| 24157518330f7967 | [frontend-proxy] | |
| 125 | +| 209a0815d291d88a | [currency] | |
| 126 | +| aca763479149f1d0 | [frontend-web] | |
| 127 | + |
| 128 | +This query collects and extracts the `service.name` fields from a constructed nested structure of spans. |
| 129 | + |
| 130 | +</Tab> |
| 131 | +<Tab title="Security logs"> |
| 132 | + |
| 133 | +Use `array_extract` to extract HTTP status codes from structured log entries grouped into sessions. |
| 134 | + |
| 135 | +**Query** |
| 136 | + |
| 137 | +```kusto |
| 138 | +['sample-http-logs'] |
| 139 | +| summarize events=make_list(pack('uri', uri, 'status', status)) by id |
| 140 | +| extend status_codes=array_extract(events, @'$[*].status') |
| 141 | +``` |
| 142 | + |
| 143 | +[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20events%3Dmake_list%28pack%28'uri'%2C%20uri%2C%20'status'%2C%20status%29%29%20by%20id%20%7C%20extend%20status_codes%3Darray_extract%28events%2C%20%40'%24%5B*%5D.status'%29%22%7D) |
| 144 | + |
| 145 | +**Output** |
| 146 | + |
| 147 | +| id | status_codes | |
| 148 | +| ----- | ---------------------- | |
| 149 | +| user1 | [200] | |
| 150 | +| user2 | [201] | |
| 151 | +| user3 | [200] | |
| 152 | + |
| 153 | +This query extracts all HTTP status codes per user session, helping to identify patterns like repeated failures or suspicious behavior. |
| 154 | + |
| 155 | +</Tab> |
| 156 | +</Tabs> |
| 157 | + |
| 158 | +## List of related functions |
| 159 | + |
| 160 | +- [array_slice](/apl/scalar-functions/array-functions/array-slice): Returns a subarray like `array_extract`, but supports negative indexing. |
| 161 | +- [array_length](/apl/scalar-functions/array-functions/array-length): Returns the number of elements in an array. Useful before applying `array_extract`. |
| 162 | +- [array_concat](/apl/scalar-functions/array-functions/array-concat): Joins arrays end-to-end. Use before or after slicing arrays with `array_extract`. |
| 163 | +- [array_index_of](/apl/scalar-functions/array-functions/array-index-of): Finds the position of an element in an array, which can help set the `startIndex` for `array_extract`. |
0 commit comments