Функции массива¶

AQL предоставляет функции для манипулирования массивами на более высоком уровне. Также смотрите numeric functions для функций, работающих с массивами чисел. Если вы хотите объединить элементы массива, эквивалентно join() в JavaScript, смотрите CONCAT() и CONCAT_SEPARATOR() в главе о строковых функциях.

Помимо этого, AQL также предлагает несколько языковых конструкций:

• простой доступ к массивам отдельных элементов,
• операторы массива для расширения и сжатия массива, опционально с встроенным фильтром, ограничением и проекцией,
• операторы сравнения массивов для сравнения каждого элемента массива со значением или элементами другого массива,
• операции над массивами с помощью циклов FOR, SORT, LIMIT, а также COLLECT для группировки, который также предлагает эффективную агрегацию.

APPEND()¶

APPEND(anyArray, values, unique) → newArray

Добавляет все элементы массива в другой массив. Все значения добавляются в конец массива (правая часть).

Также может использоваться для добавления одного элемента в массив. Нет необходимости оборачивать его в массив (если только он сам не является массивом). Вместо него можно также использовать PUSH().

• anyArray (массив): массив с элементами произвольного типа
• values (array|any): массив, элементы которого должны быть добавлены к anyArray.
• unique (bool, опционально): если установлено значение true, будут добавлены только те значения, которые еще не содержатся в anyArray. По умолчанию используется значение false.
• возвращает newArray (массив): измененный массив.

CONTAINS_ARRAY()¶

Это псевдоним для POSITION().

COUNT()¶

Это псевдоним для LENGTH().

COUNT_DISTINCT()¶

COUNT_DISTINCT(anyArray) → number.

Получает количество отдельных элементов в массиве.

• anyArray (массив): массив с элементами произвольного типа
• возвращает number: количество отдельных элементов в anyArray.

COUNT_UNIQUE()¶

Это псевдоним для COUNT_DISTINCT().

FIRST()¶

FIRST(anyArray) → firstElement

Получает первый элемент массива. Это то же самое, что и anyArray[0].

• anyArray (массив): массив с элементами произвольного типа
• возвращает firstElement (any|null): первый элемент anyArray, или null, если массив пуст.

FLATTEN()¶

FLATTEN(anyArray, depth) → flatArray

Превращает массив массивов в плоский массив. Все элементы массива array будут расширены в результирующем массиве. Элементы, не входящие в массив, добавляются по мере их наличия. Функция выполняет перебор в подмассивы до указанной глубины. Дубликаты не удаляются.

Также смотрите сокращение массива.

• array (массив): массив с элементами произвольного типа, включая вложенные массивы.
• depth (число, опционально): сплющивание до этого количества уровней, по умолчанию 1.
• возвращает flatArray (массив): сплющенный массив

INTERLEAVE()¶

Введено в: v3.7.1

INTERLEAVE(array1, array2, ... arrayN) → newArray

Принимает произвольное количество массивов и создает новый массив с чередованием элементов. Он перебирает входные массивы по кругу, выбирает по одному элементу из каждого массива за итерацию и объединяет их в такой последовательности в результирующий массив. Входные массивы могут содержать разное количество элементов.

• arrays (массив, повторяемый): произвольное количество массивов в качестве нескольких аргументов (не менее 2)
• возвращает newArray (array): чередующийся массив

INTERSECTION()¶

INTERSECTION(array1, array2, ... arrayN) → newArray

Возвращает пересечение всех указанных массивов. Результатом является массив значений, которые встречаются во всех аргументах.

Другие операции над множествами: UNION(), MINUS() и OUTERSECTION().

• arrays (array, repeatable): произвольное количество массивов в качестве нескольких аргументов (не менее 2).
• возвращает newArray (массив): единый массив, содержащий только те элементы, которые есть во всех предоставленных массивах. Порядок элементов случайный. Дубликаты удаляются.

JACCARD()¶

Введено в: v3.7.0

JACCARD(array1, array2) → jaccardIndex

Вычисляет индекс Жаккара двух массивов.

Эта мера сходства также известна как Intersection over Union и может быть вычислена (менее эффективно и более многословно) следующим образом:

1
2
3

COUNT(a) == 0 && COUNT(b) == 0
? 1 // two empty sets have a similarity of 1 by definition
: COUNT(INTERSECTION(array1, array2)) / COUNT(UNION_DISTINCT(array1, array2))

• array1 (массив): массив с элементами произвольного типа
• array2 (массив): массив с элементами произвольного типа
• возвращает jaccardIndex (число): вычисленный индекс Жаккарда входных массивов array1 и array2.

LAST()¶

LAST(anyArray) → lastElement

Получает последний элемент массива. Это то же самое, что и anyArray[-1].

• anyArray (массив): массив с элементами произвольного типа
• возвращает lastElement (any|null): последний элемент anyArray или null, если массив пуст.

LENGTH()¶

LENGTH(anyArray) → length

Определите количество элементов в массиве.

• anyArray (массив): массив с элементами произвольного типа
• возвращает length (число): количество элементов массива anyArray.

LENGTH() также может определить количество ключей атрибутов объекта / документа, количество документов в коллекции и длину символов строки.

MINUS()¶

MINUS(array1, array2, ... arrayN) → newArray

Возвращает разность всех указанных массивов.

Другие операции над множествами: UNION(), INTERSECTION() и OUTERSECTION().

• arrays (array, repeatable): произвольное количество массивов в качестве нескольких аргументов (не менее 2).
• возвращает newArray (массив): массив значений, которые встречаются в первом массиве, но не встречаются ни в одном из последующих массивов. Порядок в результирующем массиве не определен, и на него не следует полагаться. Дубликаты будут удалены.

NTH()¶

NTH(anyArray, position) → nthElement

Получение элемента массива в заданной позиции. Это то же самое, что и anyArray[position] для положительных позиций, но не поддерживает отрицательные позиции.

• anyArray (массив): массив с элементами произвольного типа
• position (число): позиция нужного элемента в массиве, позиции начинаются с 0.
• возвращает nthElement (any|null): элемент массива в заданной позиции. Если позиция отрицательна или выходит за верхнюю границу массива, то будет возвращен null.

OUTERSECTION()¶

OUTERSECTION(array1, array2, ... arrayN) → newArray

Возвращает значения, которые встречаются только один раз во всех указанных массивах.

Другие операции над множествами: UNION(), MINUS() и INTERSECTION().

• arrays (array, repeatable): произвольное количество массивов в качестве нескольких аргументов (не менее 2).
• возвращает newArray (массив): единый массив, содержащий только те элементы, которые существуют только один раз во всех предоставленных массивах. Порядок элементов является случайным.

POP()¶

POP(anyArray) → newArray

Удалить последний элемент из массива.

Чтобы добавить элемент (правая сторона), смотрите PUSH().

Чтобы удалить первый элемент, смотрите SHIFT().

Чтобы удалить элемент в произвольной позиции, смотрите REMOVE_NTH().

• anyArray (массив): массив с элементами произвольного типа
• возвращает newArray (массив): любойМассив без последнего элемента. Если он уже пуст или в нем остался только один элемент, возвращается пустой массив.

POSITION()¶

POSITION(anyArray, search, returnIndex) → position

Возвращает, содержится ли search в array. Опционально возвращает позицию.

• anyArray (массив): стог сена, массив с элементами произвольного типа.
• search (any): иголка, элемент произвольного типа.
• returnIndex (bool, опционально): если установлено значение true, вместо булевого числа возвращается позиция совпадения. По умолчанию false.
• возвращает позицию (bool|number): true, если search содержится в anyArray, false в противном случае. Если включен returnIndex, возвращается позиция совпадения (позиции начинаются с 0), или -1, если оно не найдено.

Чтобы определить, встречается ли строка в другой строке и в какой позиции, смотрите функцию CONTAINS() string.

PUSH()¶

PUSH(anyArray, value, unique) → newArray

Добавляет значение к любому массиву (правая часть).

Чтобы удалить последний элемент, смотрите POP().

Чтобы добавить значение (левая часть), смотрите UNSHIFT().

Чтобы добавить несколько элементов, смотрите APPEND().

• anyArray (массив): массив с элементами произвольного типа.
• значение (any): элемент произвольного типа
• unique (bool): если установлено значение true, то значение не добавляется, если уже присутствует в массиве. По умолчанию false.
• возвращает newArray (массив): любой массив с значением, добавленным в конец (правая часть).

Примечание: Флаг unique контролирует только добавление значения, если оно уже присутствует в anyArray. Дублирующие элементы, которые уже существуют в любом массиве, не будут удалены. Чтобы сделать массив уникальным, используйте функцию UNIQUE().

REMOVE_NTH()¶

REMOVE_NTH(anyArray, position) → newArray

Удаляет элемент в позиции из anyArray.

Чтобы удалить первый элемент, смотрите SHIFT().

Чтобы удалить последний элемент, смотрите POP().

• anyArray (массив): массив с элементами произвольного типа.
• position (число): позиция элемента, который нужно удалить. Позиции начинаются с 0. Поддерживаются отрицательные позиции, при этом -1 является последним элементом массива. Если position выходит за границы, массив возвращается без изменений.
• возвращает newArray (массив): любой массив без элемента в позиции.

REPLACE_NTH()¶

Введено в: v3.7.0

REPLACE_NTH(anyArray, position, replaceValue, defaultPaddingValue) → newArray

Заменяет элемент в позиции в anyArray на replaceValue.

• anyArray (массив): массив с элементами произвольного типа
• position (число): позиция заменяемого элемента. Позиции начинаются с 0. Поддерживаются отрицательные позиции, при этом -1 является последним элементом массива. Если отрицательная позиция выходит за границы, то она устанавливается на первый элемент (0).
• replaceValue значение, которое будет вставлено в позицию.
• defaultPaddingValue для вставки, если position находится на два или более элемента дальше последнего элемента в любом массиве.
• возвращает newArray (массив): anyArray с элементом в позиции, замененным replaceValue, или добавленным к anyArray и, возможно, заполненным defaultPaddingValue.

Допускается указывать позицию за верхней границей массива:

• replaceValue добавляется, если position равно длине массива
• если больше, то defaultPaddingValue добавляется к anyArray столько раз, сколько необходимо для размещения replaceValue в позиции
• если в вышеприведенном случае не указано defaultPaddingValue, то выдается ошибка запроса

REMOVE_VALUE()¶

REMOVE_VALUE(anyArray, value, limit) → newArray

Удаляет все вхождения value в anyArray. Опционально с ограничением на количество удалений.

• anyArray (массив): массив с элементами произвольного типа
• значение (любое): элемент произвольного типа
• limit (число, опционально): ограничение числа удалений этим значением.
• возвращает newArray (массив): любой массив с удаленным значением.

REMOVE_VALUES()¶

REMOVE_VALUES(anyArray, values) → newArray

Удаляет все вхождения любого из значений из любого массива.

• anyArray (массив): массив с элементами произвольного типа
• values (массив): массив с элементами произвольного типа, которые должны быть удалены из anyArray.
• возвращает newArray (массив): любойМассив с удаленными отдельными значениями.

REVERSE()¶

REVERSE(anyArray) → reversedArray

Возвращает массив с перевернутыми элементами.

• anyArray (массив): массив с элементами произвольного типа
• возвращает reversedArray (массив): новый массив со всеми элементами anyArray в обратном порядке.

SHIFT()¶

SHIFT(anyArray) → newArray

Удаляет первый элемент из anyArray.

Чтобы добавить элемент (с левой стороны), смотрите UNSHIFT().

Чтобы удалить последний элемент, смотрите POP().

Чтобы удалить элемент в произвольной позиции, смотрите REMOVE_NTH().

• anyArray (массив): массив с элементами произвольного типа
• возвращает newArray (массив): anyArray без крайнего левого элемента. Если anyArray уже пуст или в нем остался только один элемент, возвращается пустой массив.

SLICE()¶

SLICE(anyArray, start, length) → newArray

Извлечение фрагмента из любого массива.

• anyArray (массив): массив с элементами произвольного типа
• start (число): начать извлечение с данного элемента. Позиции начинаются с 0. Отрицательные значения указывают на позиции с конца массива.
• length (число, опционально): извлечение до length элементов, или всех элементов от start до length, если отрицательно (исключающее).
• возвращает newArray (массив): указанный фрагмент любого массива. Если length не указано, будут возвращены все элементы массива, начиная с start.

SORTED()¶

SORTED(anyArray) → newArray

Сортирует все элементы в любом массиве. Функция будет использовать порядок сравнения по умолчанию для типов значений AQL.

• anyArray (массив): массив с элементами произвольного типа
• возвращает newArray (массив): anyArray, с отсортированными элементами.

SORTED_UNIQUE()¶

SORTED_UNIQUE(anyArray) → newArray

Сортирует все элементы в любом массиве. Функция будет использовать порядок сравнения по умолчанию для типов значений AQL. Кроме того, значения в результирующем массиве будут уникальными.

• anyArray (массив): массив с элементами произвольного типа
• возвращает newArray (массив): любой массив, элементы которого отсортированы и удалены дубликаты.

UNION()¶

UNION(array1, array2, ... arrayN) → newArray

Возвращает объединение всех указанных массивов.

Другие операции с массивами: MINUS(), INTERSECTION() и OUTERSECTION().

• arrays (массив, повторяемый): произвольное количество массивов в качестве нескольких аргументов (не менее 2).
• возвращает newArray (массив): все элементы массива, объединенные в один массив, в любом порядке

UNION_DISTINCT()¶

UNION_DISTINCT(array1, array2, ... arrayN) → newArray.

Возвращает объединение отличительных значений всех указанных массивов.

• arrays (array, repeatable): произвольное количество массивов в качестве нескольких аргументов (не менее 2).
• возвращает newArray (массив): элементы всех заданных массивов в одном массиве, без дубликатов, в любом порядке.

UNIQUE()¶

UNIQUE(anyArray) → newArray

Возвращает все уникальные элементы в anyArray. Для определения уникальности функция будет использовать порядок сравнения.

• anyArray (массив): массив с элементами произвольного типа
• возвращает newArray (массив): любой массив без дубликатов, в любом порядке.

UNSHIFT()¶

UNSHIFT(anyArray, value, unique) → newArray

Добавьте значение к любому массиву (левая часть).

Чтобы удалить первый элемент, смотрите SHIFT().

Чтобы добавить значение (правая часть), смотрите PUSH().

• anyArray (массив): массив с элементами произвольного типа.
• значение (any): элемент произвольного типа
• unique (bool): если установлено значение true, то значение не добавляется, если уже присутствует в массиве. По умолчанию false.
• возвращает newArray (массив): любой массив с значением, добавленным в начало (левая часть).

Примечание: Флаг unique контролирует только добавление значения, если оно уже присутствует в anyArray. Дублирующие элементы, которые уже существуют в любом массиве, не будут удалены. Чтобы сделать массив уникальным, используйте функцию UNIQUE().

Комментарии