arraymap ↗

Use the arraymap() function to apply a specified callable function to every element of an input array, returning a new array containing the transformed elements.

Syntax

arraymap (<array>, <function()>)

Parameters

Name Type Required Description
array array Yes The array whose elements you want to transform.
function() function Yes The function to apply to each element of the array. Use the special keyword "@element" as a placeholder for the current array element being processed.

Returns

The arraymap() function returns a new array, where each element is the result of applying the specified function to the corresponding element of the original array.

Usage notes

  • The function iterates through each element, applies the defined transformation, and collects the results into a new array.
  • When the function applied within arraymap() needs to reference the current array element being processed, it uses "@element" as a placeholder for that element.
  • arraymap() is typically used within the alter or filter stages for data transformations.

Examples

Example 1: Applying a simple mathematical transformation to a numeric array

Goal: Multiply each element in a numeric array by a specific constant.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter multiplied_codes = arraymap(numeric_codes, multiply("@element", 10))
| fields event_id, numeric_codes, multiplied_codes
| limit 4

Explanation: For each record, arraymap() iterates over the numeric_codes array. The multiply() function takes each "@element" (for example, 13) and multiplies it by 10. The results form the new multiplied_codes array. An empty input array (event_id 104) results in an empty output array.

Output:

EVENT_ID NUMERIC_CODES MULTIPLIED_CODES
101 [13, -47, 29, 82, -15] [130, -470, 290, 820, -150]
102 [-21, 56, 13, -88, 42] [-210, 560, 130, -880, 420]
103 [90, -33, 7, 51, -62, 18] [900, -330, 70, 510, -620, 180]
104 [] []

Example 2: Applying a string transformation (uppercase) to a string array

Goal: Convert all string elements within an array to uppercase.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter uppercase_tags = arraymap(string_tags, uppercase("@element"))
| fields event_id, string_tags, uppercase_tags
| limit 4

Explanation: The arraymap() function processes each element in string_tags (for example, "security"). The uppercase() function converts "@element" to its uppercase equivalent. The transformed elements form the uppercase_tags array.

Output:

EVENT_ID STRING_TAGS UPPERCASE_TAGS
101 ["security", "login"] ["SECURITY", "LOGIN"]
102 ["filesystem", "critical"] ["FILESYSTEM", "CRITICAL"]
103 ["network", "cloud"] ["NETWORK", "CLOUD"]
104 ["monitoring"] ["MONITORING"]

Example 3: Applying a conditional transformation (replacing negative values) to a numeric array

Goal: Replace any negative numbers in an array with 0, while keeping positive numbers unchanged.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter positive_codes = arraymap(numeric_codes, if("@element" < 0, 0, "@element"))
| fields event_id, numeric_codes, positive_codes
| limit 4

Explanation: For each number in numeric_codes, the if() function checks if "@element" is less than 0. If true, it is replaced with 0; otherwise, the original "@element" value is retained.

Output:

EVENT_ID NUMERIC_CODES POSITIVE_CODES
101 [13, -47, 29, 82, -15] [13, 0, 29, 82, 0]
102 [-21, 56, 13, -88, 42] [0, 56, 13, 0, 42]
103 [90, -33, 7, 51, -62, 18] [90, 0, 7, 51, 0, 18]
104 [] []

Example 4: Extracting scalar values from JSON Objects within an array

Goal: Iterate through an array of JSON objects and extract a specific scalar value (for example, action or event) from each object into a new array.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter extracted_actions = arraymap(array_of_json_objects, coalesce(
        json_extract_scalar(to_json_string("@element"), "$.action"),
        json_extract_scalar(to_json_string("@element"), "$.event")
    ))
| fields event_id, array_of_json_objects, extracted_actions
| limit 4

Explanation: arraymap() iterates over each JSON object within array_of_json_objects. For each @element (a JSON object), to_json_string() converts it to a string. json_extract_scalar() then attempts to extract the action field. If not found, it tries to extract the event field. coalesce() returns the first non-null result.

Output:

EVENT_ID ARRAY_OF_JSON_OBJECTS EXTRACTED_ACTIONS
101 [{"action": "read", "file": "doc1.txt"}, {"action": "write", "file": "report.log"}] ["read", "write"]
102 [{"event": "file_open", "path": "/etc/passwd"}] ["file_open"]
103 [{"conn_type": "outbound", "bytes": 1024}, {"conn_type": "inbound", "bytes": 512}] []
104 [] []