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 NameDescription
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_leftRotates values inside a dynamic array to the left.
array_rotate_rightRotates 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

NameTypeRequired or OptionalDescription
arr1…arrNdynamicRequiredInput 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 concatenate = array_concat(labels)

Run in Playground

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

array_iff()

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

Arguments

NameTypeRequired or OptionalDescription
condition_arraydynamicRequiredInput array of boolean or numeric values
when_trueRequiredInput array of values - the result value(s) when the corresponding value of ConditionArray is true.
when_falseRequiredInput 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

NameTypeRequired or OptionalDescription
arrayarrayRequiredInput array to search.
lookup_valuescalarRequiredThe value should be of type long, integer, double, datetime, timespan, or string.
start_indexnumberOptionalSearch start position. A negative value will offset the starting search value from the end of the array by abs(start_index) steps..
lengthnumberOptionalNumber of values to examine. A value of -1 means unlimited length.
occurrenceThe number of the occurrence. Default 1No

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

NameTypeRequired or OptionalDescription
arraydynamicRequiredA 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

NameTypeRequired or OptionalDescription
arraydynamicRequiredInput array to rotate, must be dynamic array.
rotate_countintegerRequiredNumber 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

NameTypeRequired or OptionalDescription
arraydynamicRequiredInput array to rotate, must be dynamic array.
rotate_countintegerRequiredNumber 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

NameTypeRequired or OptionalDescription
arraydynamicRequiredInput array of dictionaries, must be dynamic array.
keystringRequiredKey to use for selection in of the dictionaries.
valuescalarRequiredValue 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

NameTypeRequired or OptionalDescription
arraydynamicRequiredInput array to rotate, must be dynamic array.
shift_countintegerRequiredNumber 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_valuescalarRequiredValue 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

NameTypeRequired or OptionalDescription
arraydynamicRequiredInput array to rotate, must be dynamic array.
shift_countintegerRequiredNumber 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_valuescalarRequiredValue 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

NameTypeRequired or OptionalDescription
arraydynamicRequiredInput array to extract the slice.
shift_countnumberRequiredStart index of the slice (inclusive). Negative values are converted to array_length+start.
endnumberRequiredLast 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

NameTypeRequired or OptionalDescription
arraydynamicRequiredArray to split.
indicesintegerRequiredSplit 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

NameTypeRequired or OptionalDescription
arraydynamicRequiredArray 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"]
}