Array functions

Learn how to use and combine different mathematical functions in APL

Array Functions

• Most of the array functions are used with the dynamic array function. Dynamic arrays lets you insert an element if there is no more space left for the new element. It allows you to add or remove elements, allocates memory at run time, and can be modified with any array function.

• In APL, a dynamic array expands as you add more objects. So you don’t need to determine the size ahead of time, and also lets you write functions that are reusable.

Function Name	Description
array_concat()	Concatenates a number of dynamic arrays to a single array.
array_iff()	Returns a new array containing elements from the input array that satisfy the condition.
array_index_of()	Searches the array for the specified item, and returns its position.
array_length()	Calculates the number of elements in a dynamic array.
array_reverse()	Reverses the order of the elements in a dynamic array.
array_rotate_left	Rotates values inside a dynamic array to the left.
array_rotate_right	Rotates values inside a dynamic array to the right.
array_select_dict()	Selects a dictionary from an array of dictionaries.
array_shift_left()	Shifts the values inside a dynamic array to the left.
array_shift_right()	shifts values inside an array to the right.
array_slice()	Extracts a slice of a dynamic array.
array_split()	Splits an array to multiple arrays according to the split indices and packs the generated array in a dynamic array.
array_sum()	Calculates the sum of elements in a dynamic array.
isarray()	Checks whether a value is an array.
pack_array()	Packs all input values into a dynamic array.

Each argument has a required section which is denoted with required or optional

• If it’s denoted by required it means the argument must be passed into that function before it’ll work.
• if it’s denoted by optional it means the function can work without passing the argument value.

array_concat()

Concatenates a number of dynamic arrays to a single array.

Arguments

Name	Type	Required or Optional	Description
arr1…arrN	dynamic	Required	Input arrays to be concatenated into a dynamic array. All arguments must be dynamic arrays

Returns

Dynamic array of arrays with arr1, arr2, … , arrN.

Examples

array_concat(array ...)

['github-issues-event']
| extend array1 = dynamic([{"name": "status", "color": "ededed", "description": ""}])
| extend array2 = dynamic([{"name": "puffer-ai-hpc-portal", "color": "ededed", "description": ""}])
| extend concatenate = array_concat(array1, array2)
| project concatenate

Run in Playground

• Result

{
  "concatenate": [
    {
      "name": "status",
      "description": "",
      "color": "ededed"
    },
    {
      "name": "puffer-ai-hpc-portal",
      "description": "",
      "color": "ededed"
    }
  ]
}

['github-issues-event']
| extend array1 = dynamic([{"app": "App1", "status": "running", "method": "GET"}])
| extend array2 = dynamic([{"app": "App2", "status": "stopped", "method": "POST"}])
| extend concatenatedLogs = array_concat(array1, array2)
| project concatenatedLogs

Run in Playground

• Result

{
  "concatenatedLogs": [
    {
      "app": "App1",
      "status": "running",
      "method": "GET"
    },
    {
      "app": "App2",
      "status": "stopped",
      "method": "POST"
    }
  ]
}

array_iff()

Returns a new array containing elements from the input array that satisfy the condition.

Arguments

Name	Type	Required or Optional	Description
condition_array	dynamic	Required	Input array of boolean or numeric values
when_true		Required	Input array of values - the result value(s) when the corresponding value of ConditionArray is true.
when_false		Required	Input array of values - the result value(s) when the corresponding value of ConditionArray is false.

Returns

Dynamic array of the values taken either from the when_true or when_false [array] values, according to the corresponding value of the Condition array.

Examples

array_iff(Condition_array, when_true, when_false)

['github-issues-event']
| extend return_array = array_iff(dynamic([true,false,true]), dynamic([4,2,1]), dynamic([7,8,4]))

Run in Playground

• Result

{
  "return_array": [4, 8, 1]
}

array_index_of()

Searches the array for the specified item, and returns its position.

Arguments

Name	Type	Required or Optional	Description
array	array	Required	Input array to search.
lookup_value	scalar	Required	The value should be of type long, integer, double, datetime, timespan, or string.
start_index	number	Optional	Search start position. A negative value will offset the starting search value from the end of the array by abs(start_index) steps..
length	number	Optional	Number of values to examine. A value of -1 means unlimited length.
occurrence	The number of the occurrence. Default 1	No

Returns

Zero-based index position of lookup. Returns -1 if the value isn’t found in the array.

For irrelevant inputs (occurrence < 0 or length < -1) - returns null.

Examples

array_index_of(array, value, [start], [length], [occurrence])

['github-issues-event']
| extend index_of_array = array_index_of(dynamic(["this", "is", "an", "example", "an", "example"]), "pn")

Run in Playground

• Result

{
  "index_of_array": -1
}

array_length()

Calculates the number of elements in a dynamic array.

Arguments

Name	Type	Required or Optional	Description
array	dynamic	Required	A dynamic value

Returns

The number of elements in array, or null if array is not an array.

Examples

array_length(array)

['github-issues-event']
| project return_length = array_length(labels)

Run in Playground

• Result

{
  "return_length": 2
}

array_reverse()

Reverses the order of the elements in a dynamic array.

Arguments

• array: Input array to reverse.

Returns

An array that contains exactly the same elements as the input array, but in reverse order.

Examples

array_reverse(array)

['github-issues-event']
| project reversed_array = array_reverse(labels)

Run in Playground

• Result

{
  "reversed_array": [
    {
      "name": "axiom",
      "color": "d73a4a",
      "description": "Axiom observability data"
    }
  ]
}

array_rotate_left()

Rotates values inside a dynamic array to the left.

Arguments

Name	Type	Required or Optional	Description
array	dynamic	Required	Input array to rotate, must be dynamic array.
rotate_count	integer	Required	Number of positions that array elements will be rotated to the left. If the value is negative, the elements will be rotated to the right.

Returns

Dynamic array containing the same amount of the elements as in original array, where each element was rotated according to rotate_count.

Examples

array_rotate_left(array, rotate_count)

['github-issues-event']
| project rotate_array_left = array_rotate_left(dynamic([1,2,3,4,5]), 1)

Run in Playground

• Result

{
  "rotate_array_left": [2, 3, 4, 5, 1]
}

array_rotate_right()

Rotates values inside a dynamic array to the right.

Arguments

Name	Type	Required or Optional	Description
array	dynamic	Required	Input array to rotate, must be dynamic array.
rotate_count	integer	Required	Number of positions that array elements will be rotated to the right. If the value is negative, the elements will be rotated to the Left.

Returns

Dynamic array containing the same amount of the elements as in the original array, where each element was rotated according to rotate_count.

Examples

array_rotate_right(array, rotate_count)

['github-issues-event']
| project rotate_array_right = array_rotate_right(dynamic([1,2,3,4,5]), 1)

Run in Playground

• Result

{
  "rotate_array_right": [5, 1, 2, 3, 4]
}

array_select_dict()

Selects a dictionary from an array of dictionaries.

Arguments

Name	Type	Required or Optional	Description
array	dynamic	Required	Input array of dictionaries, must be dynamic array.
key	string	Required	Key to use for selection in of the dictionaries.
value	scalar	Required	Value of the selected key to create a match.

Returns

The first dictionary in the array that has a key and value match to the parameters or null if none. If a value in the array is not a dictionary, it will be ignored.

Examples

array_select_dict(array, "search key", "matching value")

datatable(a: dynamic)[dynamic([{"key": 5, "extra": "data", ""}, {"key": 6, "extra": "other_data", ""}])]
| project selected = array_select_dict(a, "key", 5)

• Result

{
  "selected": dynamic({"key": 5, "extra": "data"})
}

array_shift_left()

Shifts the values inside a dynamic array to the left.

Arguments

Name	Type	Required or Optional	Description
array	dynamic	Required	Input array to rotate, must be dynamic array.
shift_count	integer	Required	Number of positions that array elements will be shifted to the left. If the value is negative, the elements will be shifted to the right.
default_value	scalar	Required	Value used for inserting elements instead of the ones that were shifted and removed. The default is null or an empty string depending on the array type.

Returns

Dynamic array containing the same number of elements as in the original array. Each element has been shifted according to shift_count

Examples

array_shift_left(array, shift_count [, default_value ])

['github-issues-event']
| project shift_array_left = array_shift_left(dynamic([1,2,3,4,5]), 1)

Run in Playground

• Result

{
  "shift_array_left": [2, 3, 4, 5, null]
}

array_shift_right()

shifts values inside an array to the right.

Arguments

Name	Type	Required or Optional	Description
array	dynamic	Required	Input array to rotate, must be dynamic array.
shift_count	integer	Required	Number of positions that array elements will be shifted to the right. If the value is negative, the elements will be shifted to the left.
default_value	scalar	Required	Value used for inserting elements instead of the ones that were shifted and removed. The default is null or an empty string depending on the array type.

Returns

Dynamic array containing the same amount of the elements as in the original array. Each element has been shifted according to shift_count. New elements that are added instead of the removed elements will have a value of default_value.

Examples

array_shift_right(array, shift_count [, default_value ])

['github-issues-event']
| project shift_array_right = array_shift_right(dynamic([1,2,3,4,5]), 1)

Run in Playground

• Result

{
  "shift_array_right": [null, 1, 2, 3, 4]
}

array_slice()

Extracts a slice of a dynamic array.

Arguments

Name	Type	Required or Optional	Description
array	dynamic	Required	Input array to extract the slice.
shift_count	number	Required	Start index of the slice (inclusive). Negative values are converted to array_length+start.
end	number	Required	Last index of the slice. (inclusive). Negative values are converted to array_length+end.

Returns

Dynamic array of the values in the range [start..end] from array.

Example

array_slice(array, start, end)

['github-issues-event']
| project slice_array = array_slice(dynamic([1,2,3]), 1, 2)

Run in Playground

• Result

{
  "slice_array": [2]
}

array_split()

Splits an array to multiple arrays according to the split indices and packs the generated array in a dynamic array.

Arguments

Name	Type	Required or Optional	Description
array	dynamic	Required	Array to split.
indices	integer	Required	Split indices (zero based). This can be a single integer or a dynamic array of integers. Negative values are converted to array_length + value.

Returns

Dynamic array containing N+1 arrays with the values in the range [0..1,2),from array, where N is the number of input indices.

Examples

array_split(array, indices)

['github-issues-event']
| project split_array = array_split(dynamic([1,2,3,4,5]), 4)

Run in Playground

• Result

{
  "split_array": [[1, 2, 3, 4], [5]]
}

array_sum()

Calculates the sum of elements in a dynamic array.

Arguments

Name	Type	Required or Optional	Description
array	dynamic	Required	Array that will be used in the input

Returns

Double type value with the sum of the elements of the array.

Examples

array_sum(array)

['github-issues-event']
| project sum_array = array_sum(dynamic([2,5,6]))

Run in Playground

isarray()

Returns a Boolean value indicating whether a variable is an array. It determines whether the passed value is an Array.

Arguments

• Expression: input value passed to the function.

Returns

Returns True if the expression is an array; otherwise, it returns False.

Examples

isarray(expression)

['github-issues-event']
| project is_array = isarray( ['milestone.creator'] )

Run in Playground

• Result

{
  "is_array": false
}

pack_array()

Packs all input values into a dynamic array.

Arguments

• Expression: Input expression value to be packed into a dynamic array.

Returns

Dynamic array which includes the values of Expr1, Expr2, … , ExprN.

Examples

pack_array(value, ...)

['github-issues-event']
| project packed_array = pack_array( creator, ['milestone.creator'] )

Run in Playground

• Result

{
  "packed_array": ["axiomhq", "next-axiom"]
}