> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/arraymerge.md).

# arraymerge

Use the `arraymerge()` function to flatten an input array containing JSON strings representing arrays into a single, merged XQL array.

## Syntax

```sql
arraymerge (<field>)
```

## Parameters

| Name    | Type  | Required | Description                                                                                                                             |
| ------- | ----- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `field` | array | Yes      | A single array field whose elements are JSON strings, where each JSON string represents an array (for example, `["value1", "value2"]`). |

## Returns

The `arraymerge()` function returns a new, flattened XQL-native array containing all elements from the inner JSON-string-represented arrays.

## Usage notes

* The function strictly requires an array where each element is a valid JSON string that represents an array.
* The function flattens the structure, taking an array of arrays (represented as JSON strings) and reducing it to a single-dimensional array.
* This function is commonly used in conjunction with `arraymap()` when the internal function of `arraymap()` produces JSON strings of arrays.

## Examples

### Example 1: Merging artificially constructed arrays (literal JSON strings)

**Goal**: Demonstrate the core functionality by creating an array where each element is a JSON string representing an array, and then flattening them into a single array.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter json_array_str_part1 = to_json_string(arraycreate("tag1", "tag2")) // Creates JSON string '["tag1", "tag2"]' 
| alter json_array_str_part2 = to_json_string(arraycreate("valueA", "valueB")) // Creates JSON string '["valueA", "valueB"]' 
| alter input_array_for_merge = arraycreate(json_array_str_part1, json_array_str_part2) // Creates an array of these JSON strings: ['["tag1", "tag2"]', '["valueA", "valueB"]'] 
| alter merged_result = arraymerge(input_array_for_merge) 
| fields event_id, merged_result 
| limit 2 
```

**Explanation**: The query first creates two string representations of arrays (`json_array_str_part1` and `json_array_str_part2`) using `arraycreate()` and `to_json_string()`. The query then combines these into `input_array_for_merge`. Finally, `arraymerge()` extracts the elements from within each JSON string in the input array and combines them into a single, flattened `merged_result` array.

**Output**:

| EVENT\_ID | MERGED\_RESULT                        |
| --------- | ------------------------------------- |
| 101       | \["tag1", "tag2", "valueA", "valueB"] |
| 102       | \["tag1", "tag2", "valueA", "valueB"] |

### Example 2: Merging scalar values extracted and wrapped into arrays via arraymap()

**Goal**: Demonstrate how to process an array of JSON objects, extract specific scalar values, wrap them into new conceptual arrays, convert them to JSON strings, and finally flatten the result using `arraymerge()`.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter mapped_json_arrays_as_strings = arraymap( 
    array_of_json_objects, 
    to_json_string( // Converts the dynamically created array into a JSON string 
        arraycreate( // Creates a new temporary array from extracted scalars 
            to_string(coalesce(json_extract_scalar(to_json_string("@element"), "$.action"), json_extract_scalar(to_json_string("@element"), "$.event"))), // Extracts 'action' or 'event' 
            to_string(coalesce(json_extract_scalar(to_json_string("@element"), "$.file"), json_extract_scalar(to_json_string("@element"), "$.path"), json_extract_scalar(to_json_string("@element"), "$.conn_type"))) // Extracts 'file', 'path', or 'conn_type' 
        ) 
    ) 
) 
| alter flattened_array = arraymerge(mapped_json_arrays_as_strings) 
| fields event_id, array_of_json_objects, flattened_array 
| limit 4 
```

**Explanation**: `arraymap()` iterates over each JSON object in `array_of_json_objects`. For each element, it extracts specific scalar values (like action, event, file, path) using `json_extract_scalar()` and wraps them into a temporary array using `arraycreate()`. `to_json_string()` converts this temporary array into a JSON string. The result of `arraymap()` is an array of these JSON strings. Finally, `arraymerge()` flattens all the inner elements from these strings into a single `flattened_array`.

**Output**:

| EVENT\_ID | ARRAY\_OF\_JSON\_OBJECTS                                                              | FLATTENED\_ARRAY                             |
| --------- | ------------------------------------------------------------------------------------- | -------------------------------------------- |
| 101       | \[{"action": "read", "file": "doc1.txt"}, {"action": "write", "file": "report.log"}]  | \["read", "doc1.txt", "write", "report.log"] |
| 102       | \[{"event": "file\_open", "path": "/etc/passwd"}]                                     | \["file\_open", "/etc/passwd"]               |
| 103       | \[{"conn\_type": "outbound", "bytes": 1024}, {"conn\_type": "inbound", "bytes": 512}] | \["outbound", "inbound"]                     |
| 104       | \[]                                                                                   | \[]                                          |

### Example 2: Merge IP addresses extracted from a nested map

**Goal**: Create a single consolidated array containing all IPv4 addresses found within the `agent_interface_map` field. This query extracts the "ipv4" element from each object in the map and merges them into a flattened array.

**XQL Code**:

```sql
dataset = sample_xql_raw
| alter a = arraymerge(arraymap(agent_interface_map, to_json_string(json_extract_array(to_json_string("@element"), "$.ipv4"))))
```

**Explanation**:

1. The query processes the agent\_interface\_map, which is an array of objects.
2. arraymap() iterates through each element (@element) in the array.
3. to\_json\_string() converts the element to a JSON string so it can be parsed.
4. json\_extract\_array(..., "$.ipv4") locates and extracts the IPv4 addresses associated with the "ipv4" key in each object.
5. arraymerge() takes the resulting nested arrays and flattens them into a single, comprehensive array assigned to the field 'a'.

**Output**:

| agent\_interface\_map                                                            | a                             |
| -------------------------------------------------------------------------------- | ----------------------------- |
| \[{"ipv4":\["10.0.0.1"],"name":"eth0"},{"ipv4":\["192.168.1.1"],"name":"wlan0"}] | \["10.0.0.1", "192.168.1.1"]  |
| \[{"ipv4":\["172.16.0.5", "172.16.0.6"],"name":"eth1"}]                          | \["172.16.0.5", "172.16.0.6"] |

## Related articles

* **Stages**: [`alter`](/xql-command-reference-guide/readme/stages/alter.md), [`config`](/xql-command-reference-guide/readme/stages/config.md), [`fields`](/xql-command-reference-guide/readme/stages/fields.md), [`limit`](/xql-command-reference-guide/readme/stages/limit.md)
* **Functions**: [`arraycreate`](/xql-command-reference-guide/readme/functions/arraycreate.md), [`to_json_string`](/xql-command-reference-guide/readme/functions/to_json_string.md), [`arraymap`](/xql-command-reference-guide/readme/functions/arraymap.md), [`json_extract_scalar`](/xql-command-reference-guide/readme/functions/json_extract_scalar.md), [`to_string`](/xql-command-reference-guide/readme/functions/to_string.md), [`coalesce`](/xql-command-reference-guide/readme/functions/coalesce.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/arraymerge.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.