Array Functions

Functions for creating, accessing, transforming, and combining arrays in SDBQL.

Array Operations

[*] Array Spread Operator

The array spread operator [*] extracts a specific field from all elements in an array, returning a new array with just those values. This is similar to a map operation.

-- Extract user_key from all attendees
FOR event IN events
  RETURN event.attendees[*].user_key
-- Result: [["u1", "u2"], ["u3"]]

-- Nested field extraction
FOR doc IN data
  RETURN doc.items[*].user.name
-- Result: [["Alice", "Bob"]]

Basic Usage

-- Given: {items: [{name: "A"}, {name: "B"}]}
doc.items[*].name  -- ["A", "B"]

Chained Spread

-- Given: {items: [{tags: ["a","b"]}, {tags: ["c"]}]}
doc.items[*].tags[*]  -- ["a", "b", "c"]

Missing Fields

-- Given: {items: [{name: "A"}, {other: "B"}]}
doc.items[*].name  -- ["A", null]

Bare Spread

-- Given: {values: [1, 2, 3]}
doc.values[*]  -- [1, 2, 3]

Note: If the base value is not an array, an empty array is returned. When a field is missing from an array element, null is included in the result.

Access Functions

FIRST(arr)

Returns the first element.

RETURN FIRST([5, 1, 9]) --5

LAST(arr)

Returns the last element.

RETURN LAST([5, 1, 9]) --9

NTH(arr, n)

Returns element at index n (0-based).

RETURN NTH([5, 1, 9], 1) --1

SLICE(arr, start, len?)

Extracts a portion of the array.

RETURN SLICE([1, 2, 3, 4, 5], 1, 3) --[2, 3, 4]

COLLECTION_COUNT(coll)

Returns the number of documents in a collection.

RETURN COLLECTION_COUNT("users") --100

INDEX_OF(arr, value)

Returns index of value, or -1 if not found.

RETURN INDEX_OF([1,2,3], 2) --1

TAKE(arr, n)

Returns first n elements.

RETURN TAKE([1,2,3,4], 2) --[1,2]

DROP(arr, n)

Returns array without first n elements. Alias: SKIP.

RETURN DROP([1,2,3,4], 2) --[3,4]

CHUNK(arr, size)

Splits array into chunks of specified size.

RETURN CHUNK([1,2,3,4,5], 2) --[[1,2],[3,4],[5]]

Transformation Functions

UNIQUE(arr)

Removes duplicate values.

RETURN UNIQUE([1, 2, 2, 3]) --[1, 2, 3]

SORTED(arr)

Sorts the array in ascending order.

RETURN SORTED([3, 1, 2]) --[1, 2, 3]

SORTED_UNIQUE(arr)

Sorts and removes duplicates.

RETURN SORTED_UNIQUE([3, 1, 2, 2]) --[1, 2, 3]

REVERSE(arr)

Reverses the array order.

RETURN REVERSE([1, 2, 3]) --[3, 2, 1]

FLATTEN(arr, depth?)

Flattens nested arrays. Depth defaults to 1.

RETURN FLATTEN([[1, 2], [3]], 1) --[1, 2, 3]

RANGE(start, end, step?)

Generates an array of numbers.

RETURN RANGE(1, 5) --[1, 2, 3, 4, 5]
RETURN RANGE(1, 5, 2) --[1, 3, 5]

Combination Functions

PUSH(arr, elem)

Appends an element to the array.

RETURN PUSH([1, 2], 3) --[1, 2, 3]

APPEND(arr1, arr2)

Concatenates two arrays.

RETURN APPEND([1], [2, 3]) --[1, 2, 3]

UNION(arr1, arr2)

Union of arrays (produces unique values).

RETURN UNION([1, 2], [2, 3]) --[1, 2, 3]

INTERSECTION(arr1, arr2...)

Returns common elements between arrays.

RETURN INTERSECTION([1, 2], [2, 3]) --[2]

MINUS(arr1, arr2)

Returns elements in arr1 not in arr2.

RETURN MINUS([1, 2, 3], [2]) --[1, 3]

ZIP(arr1, arr2)

Zips two arrays into an array of pairs.

RETURN ZIP([1, 2], ["a", "b"]) --[[1, "a"], [2, "b"]]

REMOVE_VALUE(arr, val, limit?)

Removes all occurrences of value from array. Optional limit.

RETURN REMOVE_VALUE([1, 2, 1, 3], 1) --[2, 3]

Search Functions

POSITION(arr, elem, start?)

Returns 0-based index if element exists, -1 otherwise. Optional start index.

RETURN POSITION([10, 20], 20) --1
RETURN POSITION([10, 20], 30) ---1

CONTAINS_ARRAY(arr, elem)

Returns true if array contains element, false otherwise.

RETURN CONTAINS_ARRAY([1, 2], 3) --false
RETURN CONTAINS_ARRAY([1, 2], 1) --true

Practical Examples

-- Combine and deduplicate tags
LET tags1 = ["rust", "database"]
LET tags2 = ["database", "nosql"]
RETURN UNION(tags1, tags2)  -- ["rust", "database", "nosql"]

-- Get top 3 values from sorted array
LET values = [5, 2, 8, 1, 9, 3]
RETURN SLICE(SORTED(values), 3, 3)  -- [5, 8, 9] (last 3)

-- Flatten nested arrays
LET nested = [[1, 2], [3, [4, 5]]]
RETURN FLATTEN(nested, 2)  -- [1, 2, 3, 4, 5]

-- Find users with specific skills
FOR user IN users
  FILTER LENGTH(INTERSECTION(user.skills, ["rust", "go"])) > 0
  RETURN user.name

-- Extract all unique tags from documents
LET allTags = (FOR doc IN documents RETURN doc.tags)
RETURN SORTED_UNIQUE(FLATTEN(allTags))

Date Functions Numeric Functions