array_length ↗

Use the array_length() function to return the number of elements in an array.

Syntax

array_length (<array>)

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:

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:

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:

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:

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:

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