> 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/array_length.md). # array\_length Use the `array_length()` function to return the number of elements in an array. ## Syntax ```sql array_length () ``` ## Parameters | Name | Type | Required | Description | | ------- | ----- | -------- | ------------------------------------- | | `array` | array | Yes | The array field you want to evaluate. | ## Returns The `array_length()` function returns an integer representing the count of elements in the specified array. ## Usage notes * If the input array is empty, the function returns `0`. * The function provides a direct count of how many items are present within an array field. * This function is typically used within the `alter` stage to create new fields or modify existing ones by calculating array sizes. * The function can also be used in `filter` stages to narrow down results based on string length. ## Examples ### Example 1: Calculating the length of a string array **Goal**: Determine the number of string elements in an array field. **XQL code**: ```sql config timeframe = 1d | dataset = sample_xql_raw | alter num_string_tags = array_length(string_tags) | fields event_id, string_tags, num_string_tags | limit 4 ``` **Explanation**: For `event_id` 101, 102, and 103, `string_tags` contains two elements, so `num_string_tags` is 2. For `event_id` 104, `string_tags` contains one element, so `num_string_tags` is 1. **Output**: | EVENT\_ID | STRING\_TAGS | NUM\_STRING\_TAGS | | --------- | --------------------------- | ----------------- | | 101 | \["security", "login"] | 2 | | 102 | \["filesystem", "critical"] | 2 | | 103 | \["network", "cloud"] | 2 | | 104 | \["monitoring"] | 1 | ### Example 2: Calculating the length of a numeric array **Goal**: Determine the number of numeric elements in an array field. **XQL code**: ```sql config timeframe = 1d | dataset = sample_xql_raw | alter num_numeric_codes = array_length(numeric_codes) | fields event_id, numeric_codes, num_numeric_codes | limit 6 ``` **Explanation**: For `event_id` 101, 102, and 105, `numeric_codes` contains five elements. For `event_id` 103 and 106, `numeric_codes` contains six elements. For `event_id` 104, `numeric_codes` is an empty array, so `num_numeric_codes` is 0. **Output**: | EVENT\_ID | NUMERIC\_CODES | NUM\_NUMERIC\_CODES | | --------- | --------------------------- | ------------------- | | 101 | \[13, -47, 29, 82, -15] | 5 | | 102 | \[-21, 56, 13, -88, 42] | 5 | | 103 | \[90, -33, 7, 51, -62, 18] | 6 | | 104 | \[] | 0 | | 105 | \[77, -9, 35, -47, 61] | 5 | | 106 | \[-12, 24, 68, -59, 37, 80] | 6 | ### Example 3: Calculating the length of an array of JSON objects **Goal**: Determine the number of JSON objects contained within an array field. **XQL code**: ```sql config timeframe = 1d | dataset = sample_xql_raw | alter num_json_objects = array_length(array_of_json_objects) | fields event_id, array_of_json_objects, num_json_objects | limit 4 ``` **Explanation**: For `event_id` 101 and 103, `array_of_json_objects` contains two elements. For `event_id` 102, `array_of_json_objects` contains one element. For `event_id` 104, `array_of_json_objects` is an empty array, so `num_json_objects` is 0. **Output**: | EVENT\_ID | ARRAY\_OF\_JSON\_OBJECTS | NUM\_JSON\_OBJECTS | | --------- | ------------------------------------------------------------------------------------- | ------------------ | | 101 | \[{"action": "read", "file": "doc1.txt"}, {"action": "write", "file": "report.log"}] | 2 | | 102 | \[{"event": "file\_open", "path": "/etc/passwd"}] | 1 | | 103 | \[{"conn\_type": "outbound", "bytes": 1024}, {"conn\_type": "inbound", "bytes": 512}] | 2 | | 104 | \[] | 0 | ### Example 4: Using array\_length() in a filter to check for non-empty arrays **Goal**: Filter events to include only those where a specific array field is not empty. **XQL code**: ```sql config timeframe = 1d | dataset = sample_xql_raw | alter tags_count = array_length(string_tags) | filter tags_count > 0 | fields event_id, string_tags, tags_count | limit 5 ``` **Explanation**: This query returns all events where the `string_tags` array has at least one element. No events with an empty `string_tags` array are present in this filtered result set. **Output**: | EVENT\_ID | STRING\_TAGS | TAGS\_COUNT | | --------- | --------------------------- | ----------- | | 101 | \["security", "login"] | 2 | | 102 | \["filesystem", "critical"] | 2 | | 103 | \["network", "cloud"] | 2 | | 104 | \["monitoring"] | 1 | | 105 | \["data\_ops"] | 1 | ### Example 5: Using array\_length() in a filter to check for a specific array size **Goal**: Filter events to include only those where an array field contains a precise number of elements. **XQL code**: ```sql config timeframe = 1d | dataset = sample_xql_raw | alter codes_count = array_length(numeric_codes) | filter codes_count = 5 | fields event_id, numeric_codes, codes_count | limit 5 ``` **Explanation**: Only events with exactly five elements in their `numeric_codes` array are returned, such as `event_id` 101, 102, and 105. Events like 103 (length 6) or 104 (length 0) are excluded by the filter. **Output**: | EVENT\_ID | NUMERIC\_CODES | CODES\_COUNT | | --------- | ----------------------- | ------------ | | 101 | \[13, -47, 29, 82, -15] | 5 | | 102 | \[-21, 56, 13, -88, 42] | 5 | | 105 | \[77, -9, 35, -47, 61] | 5 | ## Related articles * **Stages**: [`alter`](/xql-command-reference-guide/readme/stages/alter.md), [`filter`](/xql-command-reference-guide/readme/stages/filter.md), [`fields`](/xql-command-reference-guide/readme/stages/fields.md) * **Functions**: [`array_all`](/xql-command-reference-guide/readme/functions/array_all.md), [`array_any`](/xql-command-reference-guide/readme/functions/array_any.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/array_length.md?ask=&goal= ``` `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.