> 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/arraycreate.md).

# arraycreate

Use the `arraycreate()` function to return a new array based on the given parameters defined for its elements.

## Syntax

```sql
arraycreate ("<array_element1>", "<array_element2>",...)
```

## Parameters

| Name              | Type                            | Required | Description                                                                                                 |
| ----------------- | ------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `<array_element>` | string, integer, float, boolean | Yes      | The values to include as elements in the new array. Must be enclosed in quotes if they are string literals. |

## Returns

The `arraycreate()` function returns a single, new array containing the specified elements.

## Usage notes

* All elements within the array created by `arraycreate()` must be of the same data type.
* The function returns the data types exactly as entered and doesn't implicitly convert string representations of numeric or boolean values. For example, `"123"` remains a string `"123"` within the array, and isn't converted to a number.
* If all elements are `NULL`, the output is an empty array with no elements.

## Examples

### Example 1: Creating an array of string literals

**Goal**: Define a new array containing only direct string values.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter custom_tags = arraycreate("alert", "investigation_needed") 
| fields event_id, custom_tags 
| limit 3
```

**Explanation**: For each record in `sample_xql_raw`, a new field named `custom_tags` is created. This field contains an array with two string elements: `"alert"` and `"investigation_needed"`.

**Output**:

| EVENT\_ID | CUSTOM\_TAGS                        |
| --------- | ----------------------------------- |
| 101       | \["alert", "investigation\_needed"] |
| 102       | \["alert", "investigation\_needed"] |
| 103       | \["alert", "investigation\_needed"] |

### Example 2: Creating an array with literals representing different data types (as strings)

**Goal**: Handle different types of literal values, specifically strings, numbers, and booleans, by treating them as string parameters.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter mixed_info = arraycreate("version_1.0", "123", "true", "45.67") 
| fields event_id, mixed_info 
| limit 3
```

**Explanation**: A `mixed_info` array is generated for each record. The query demonstrates that `arraycreate()` can incorporate various literal values into a single array, with all elements being treated as strings, adhering to the rule that all elements must be of the same data type.

**Output**:

| EVENT\_ID | MIXED\_INFO                               |
| --------- | ----------------------------------------- |
| 101       | \["version\_1.0", "123", "true", "45.67"] |
| 102       | \["version\_1.0", "123", "true", "45.67"] |
| 103       | \["version\_1.0", "123", "true", "45.67"] |

### Example 3: Creating an array by combining literals with existing field values

**Goal**: Dynamically build an array by including both static literal values and values from existing fields in each record.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter event_summary = arraycreate(to_string(event_id), event_description, to_string(is_successful)) 
| fields event_id, event_description, is_successful, event_summary 
| limit 3
```

**Explanation**: The `to_string()` function is used to convert the `event_id` (numeric) and `is_successful` (boolean) fields into strings, allowing them to be combined with the `event_description` (string) into a new array called `event_summary`. Each row will have a unique `event_summary` array reflecting its own `event_id`, `event_description`, and `is_successful` status.

**Output**:

| EVENT\_ID | EVENT\_DESCRIPTION               | IS\_SUCCESSFUL | EVENT\_SUMMARY                                     |
| --------- | -------------------------------- | -------------- | -------------------------------------------------- |
| 101       | "User login successful"          | true           | \["101", "User login successful", "true"]          |
| 102       | "File access attempt"            | false          | \["102", "File access attempt", "false"]           |
| 103       | "Network connection established" | true           | \["103", "Network connection established", "true"] |

### Example 4: Creating an array with derived values from JSON extraction

**Goal**: Incorporate values that are the result of other XQL functions, specifically `json_extract_scalar()` for extracting data from JSON fields.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter status_code = json_extract_scalar(simple_json_data, "$.code") 
| alter user_name = json_extract_scalar(nested_json_data, "$.user.name") 
| alter extracted_details = arraycreate(status_code, user_name) 
| fields event_id, simple_json_data, nested_json_data, extracted_details 
| limit 3
```

**Explanation**: `status_code` is created by extracting the `code` field from `simple_json_data`. `user_name` is created by extracting the `user.name` field from `nested_json_data`. `extracted_details` then combines these two (potentially NULL) string values into a new array. If all the input elements are NULL, then the output is an empty array.

**Output**:

| EVENT\_ID | SIMPLE\_JSON\_DATA                                | NESTED\_JSON\_DATA                                  | EXTRACTED\_DETAILS |
| --------- | ------------------------------------------------- | --------------------------------------------------- | ------------------ |
| 101       | {"status": "ok", "code": 200}                     | {"user": {"id": "U1", "name": "Alice"}, ...}        | \["200", "Alice"]  |
| 102       | {"status": "fail", "error": "access\_denied"}     | {"process": {"name": "cmd.exe", "pid": 1234}, ...}  | \[]                |
| 103       | {"connection\_id": "CONN-001", "protocol": "TCP"} | {"source": {"ip": "172.16.0.1", "port": 5000}, ...} | \[]                |

## Related articles

* **Stages**: [`alter`](/xql-command-reference-guide/readme/stages/alter.md)
* **Functions**: [`arrayconcat`](/xql-command-reference-guide/readme/functions/arrayconcat.md), [`to_string`](/xql-command-reference-guide/readme/functions/to_string.md), [`json_extract_scalar`](/xql-command-reference-guide/readme/functions/json_extract_scalar.md)
* **Datasets**: [`xdr_data`](https://www.google.com/search?q=%5Bhttps://docs-cortex.paloaltonetworks.com/r/Cortex-XQL-Schema-Reference-Guide/Introduction%5D\(https://docs-cortex.paloaltonetworks.com/r/Cortex-XQL-Schema-Reference-Guide/Introduction\))


---

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