Функции массивов
| Имя | Описание |
ARRAY | Возвращает ARRAY содержащий один элемент для каждого входного аргумента. |
ARRAY_CONCAT | Объединяет несколько массивов в один ARRAY |
ARRAY_CONTAINS | Возвращает TRUE если заданный ARRAY содержит определенное значение. |
ARRAY_CONTAINS_ALL | Возвращает TRUE если все значения присутствуют в ARRAY |
ARRAY_CONTAINS_ANY | Возвращает TRUE если хотя бы одно из значений присутствует в ARRAY |
ARRAY_FILTER | Отфильтровывает из ARRAY элементы, не удовлетворяющие предикату. |
ARRAY_FIRST | Возвращает первый элемент ARRAY |
ARRAY_FIRST_N | Возвращает первые n элементов ARRAY . |
ARRAY_GET | Возвращает элемент по заданному индексу в ARRAY |
ARRAY_INDEX_OF | Возвращает индекс первого вхождения значения в ARRAY |
ARRAY_INDEX_OF_ALL | Возвращает все индексы значения в ARRAY |
ARRAY_LENGTH | Возвращает количество элементов в ARRAY |
ARRAY_LAST | Возвращает последний элемент ARRAY . |
ARRAY_LAST_N | Возвращает последние n элементов ARRAY . |
ARRAY_REVERSE | Изменяет порядок элементов в ARRAY |
ARRAY_SLICE | Возвращает срез ARRAY |
ARRAY_TRANSFORM | Преобразует элементы ARRAY , применяя выражение к каждому элементу. |
MAXIMUM | Возвращает максимальное значение в ARRAY |
MAXIMUM_N | Возвращает n наибольших значений в ARRAY |
MINIMUM | Возвращает минимальное значение в ARRAY |
MINIMUM_N | Возвращает n наименьших значений в ARRAY |
SUM | Возвращает сумму всех NUMERIC значений в ARRAY . |
JOIN | Создает конкатенацию элементов ARRAY в виде STRING значения. |
МНОЖЕСТВО
Синтаксис:
array(values: ANY...) -> ARRAY
Описание:
Создает массив из заданных элементов.
- Если аргумент отсутствует, он заменяется значением
NULLв результирующем массиве.
Примеры:
| ценности | array(values) |
|---|---|
| () | [] |
| (1, 2, 3) | [1, 2, 3] |
| ("а", 1, true) | ["а", 1, true] |
| (1, null) | [1, null] |
| (1, [2, 3]) | [1, [2, 3]] |
ARRAY_CONCAT
Синтаксис:
array_concat(arrays: ARRAY...) -> ARRAY
Описание:
Объединяет два или более массивов в один ARRAY .
Примеры:
| массивы | array_concat(arrays) |
|---|---|
| ([1, 2], [3, 4]) | [1, 2, 3, 4] |
| (["a", "b", ["c"]) | ["a", "b", "c"] |
| ([1], [2], [3]) | [1, 2, 3] |
| ([], [1, 2]) | [1, 2] |
Node.js
const result = await db.pipeline() .collection("books") .select(field("genre").arrayConcat([field("subGenre")]).as("allGenres")) .execute();
Быстрый
let result = try await db.pipeline() .collection("books") .select([Field("genre").arrayConcat([Field("subGenre")]).as("allGenres")]) .execute()
Kotlin
val result = db.pipeline() .collection("books") .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres")) .execute()
Java
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres")) .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field result = ( client.pipeline() .collection("books") .select(Field.of("genre").array_concat(Field.of("subGenre")).as_("allGenres")) .execute() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("books") .select(arrayConcat(field("genre"), field("subGenre")).as("allGenres")) .execute() .get();
ARRAY_CONTAINS
Синтаксис:
array_contains(array: ARRAY, value: ANY) -> BOOLEAN
Описание:
Возвращает TRUE если value найдено в array , и FALSE в противном случае.
Примеры:
| множество | ценить | array_contains(array, value) |
|---|---|---|
| [1, 2, 3] | 2 | истинный |
| [[1, 2], [3]] | [1, 2] | истинный |
| [1, null] | нулевой | истинный |
| "abc" | ЛЮБОЙ | ошибка |
Node.js
const result = await db.pipeline() .collection("books") .select(field("genre").arrayContains(constant("mystery")).as("isMystery")) .execute();
Web
const result = await execute(db.pipeline() .collection("books") .select(field("genre").arrayContains(constant("mystery")).as("isMystery")) );
Быстрый
let result = try await db.pipeline() .collection("books") .select([Field("genre").arrayContains(Constant("mystery")).as("isMystery")]) .execute()
Kotlin
val result = db.pipeline() .collection("books") .select(field("genre").arrayContains("mystery").alias("isMystery")) .execute()
Java
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select(field("genre").arrayContains("mystery").alias("isMystery")) .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field result = ( client.pipeline() .collection("books") .select(Field.of("genre").array_contains("mystery").as_("isMystery")) .execute() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("books") .select(arrayContains(field("genre"), "mystery").as("isMystery")) .execute() .get();
ARRAY_CONTAINS_ALL
Синтаксис:
array_contains_all(array: ARRAY, search_values: ARRAY) -> BOOLEAN
Описание:
Возвращает TRUE если все search_values найдены в array , и FALSE в противном случае.
Примеры:
| множество | search_values | array_contains_all(array, search_values) |
|---|---|---|
| [1, 2, 3] | [1, 2] | истинный |
| [1, 2, 3] | [1, 4] | ЛОЖЬ |
| [1, null] | [нулевой] | истинный |
| [NaN] | [NaN] | истинный |
| [] | [] | истинный |
| [1, 2, 3] | [] | истинный |
Node.js
const result = await db.pipeline() .collection("books") .select( field("genre") .arrayContainsAll([constant("fantasy"), constant("adventure")]) .as("isFantasyAdventure") ) .execute();
Web
const result = await execute(db.pipeline() .collection("books") .select( field("genre") .arrayContainsAll([constant("fantasy"), constant("adventure")]) .as("isFantasyAdventure") ) );
Быстрый
let result = try await db.pipeline() .collection("books") .select([ Field("genre") .arrayContainsAll([Constant("fantasy"), Constant("adventure")]) .as("isFantasyAdventure") ]) .execute()
Kotlin
val result = db.pipeline() .collection("books") .select( field("genre") .arrayContainsAll(listOf("fantasy", "adventure")) .alias("isFantasyAdventure") ) .execute()
Java
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select( field("genre") .arrayContainsAll(Arrays.asList("fantasy", "adventure")) .alias("isFantasyAdventure") ) .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field result = ( client.pipeline() .collection("books") .select( Field.of("genre") .array_contains_all(["fantasy", "adventure"]) .as_("isFantasyAdventure") ) .execute() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("books") .select( arrayContainsAll(field("genre"), Arrays.asList("fantasy", "adventure")) .as("isFantasyAdventure")) .execute() .get();
ARRAY_CONTAINS_ANY
Синтаксис:
array_contains_any(array: ARRAY, search_values: ARRAY) -> BOOLEAN
Описание:
Возвращает TRUE если в array найдено хотя бы одно из значений search_values , и FALSE в противном случае.
Примеры:
| множество | search_values | array_contains_any(array, search_values) |
|---|---|---|
| [1, 2, 3] | [4, 1] | истинный |
| [1, 2, 3] | [4, 5] | ЛОЖЬ |
| [1, 2, null] | [нулевой] | истинный |
Node.js
const result = await db.pipeline() .collection("books") .select( field("genre") .arrayContainsAny([constant("fantasy"), constant("nonfiction")]) .as("isMysteryOrFantasy") ) .execute();
Web
const result = await execute(db.pipeline() .collection("books") .select( field("genre") .arrayContainsAny([constant("fantasy"), constant("nonfiction")]) .as("isMysteryOrFantasy") ) );
Быстрый
let result = try await db.pipeline() .collection("books") .select([ Field("genre") .arrayContainsAny([Constant("fantasy"), Constant("nonfiction")]) .as("isMysteryOrFantasy") ]) .execute()
Kotlin
val result = db.pipeline() .collection("books") .select( field("genre") .arrayContainsAny(listOf("fantasy", "nonfiction")) .alias("isMysteryOrFantasy") ) .execute()
Java
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select( field("genre") .arrayContainsAny(Arrays.asList("fantasy", "nonfiction")) .alias("isMysteryOrFantasy") ) .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field result = ( client.pipeline() .collection("books") .select( Field.of("genre") .array_contains_any(["fantasy", "nonfiction"]) .as_("isMysteryOrFantasy") ) .execute() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("books") .select( arrayContainsAny(field("genre"), Arrays.asList("fantasy", "nonfiction")) .as("isMysteryOrFantasy")) .execute() .get();
ARRAY_FILTER
Синтаксис:
array_filter(array: ARRAY, predicate: (ANY) -> BOOLEAN) -> ARRAY
Описание:
Фильтрует array используя predicate выражение, и возвращает новый массив, содержащий только элементы, удовлетворяющие предикату.
- Для каждого элемента
arrayвыполняется оценкаpredicate. Если он возвращаетtrue, элемент включается в результат; в противном случае (если он возвращаетfalseилиnull) он опускается. - Если результат вычисления
predicateне равен логическому значению или значению, функция возвращает ошибку.
Примеры:
| множество | предикат | array_filter(array, predicate) |
|---|---|---|
| [1, 2, 3] | x -> x > 1 | [2, 3] |
| [1, null, 3] | x -> x > 1 | [3] |
| ["a", "b", "c"] | x -> x != "b" | ["а", "с"] |
| [] | x -> true | [] |
ARRAY_GET
Синтаксис:
array_get(array: ARRAY, index: INT64) -> ANY
Описание:
Возвращает элемент array , index которого начинается с 0.
- Если
indexотрицательный, доступ к элементам осуществляется с конца массива, где-1— последний элемент. - Если
arrayне является типомARRAYи неnull, возвращается ошибка. - Если
indexвыходит за пределы допустимого диапазона, функция возвращает отсутствующее значение. - Если
indexне имеет типаINT64, функция возвращает ошибку.
Примеры:
| множество | индекс | array_get(array, index) |
|---|---|---|
| [1, 2, 3] | 0 | 1 |
| [1, 2, 3] | -1 | 3 |
| [1, 2, 3] | 3 | отсутствующий |
| [1, 2, 3] | -4 | отсутствующий |
| "abc" | 0 | ошибка |
| нулевой | 0 | нулевой |
Array | "а" | ошибка |
Array | 2.0 | ошибка |
ДЛИНА МАССИВА
Синтаксис:
array_length(array: ARRAY) -> INT64
Описание:
Возвращает количество элементов в array .
Примеры:
| множество | array_length(array) |
|---|---|
| [1, 2, 3] | 3 |
| [] | 0 |
| [1, 1, 1] | 3 |
| [1, null] | 2 |
Node.js
const result = await db.pipeline() .collection("books") .select(field("genre").arrayLength().as("genreCount")) .execute();
Web
const result = await execute(db.pipeline() .collection("books") .select(field("genre").arrayLength().as("genreCount")) );
Быстрый
let result = try await db.pipeline() .collection("books") .select([Field("genre").arrayLength().as("genreCount")]) .execute()
Kotlin
val result = db.pipeline() .collection("books") .select(field("genre").arrayLength().alias("genreCount")) .execute()
Java
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select(field("genre").arrayLength().alias("genreCount")) .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field result = ( client.pipeline() .collection("books") .select(Field.of("genre").array_length().as_("genreCount")) .execute() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("books") .select(arrayLength(field("genre")).as("genreCount")) .execute() .get();
ARRAY_REVERSE
Синтаксис:
array_reverse(array: ARRAY) -> ARRAY
Описание:
Переворачивает заданный array .
Примеры:
| множество | array_reverse(array) |
|---|---|
| [1, 2, 3] | [3, 2, 1] |
| ["а", "б"] | ["б", "а"] |
| [1, 2, 2, 3] | [3, 2, 2, 1] |
Node.js
const result = await db.pipeline() .collection("books") .select(arrayReverse(field("genre")).as("reversedGenres")) .execute();
Web
const result = await execute(db.pipeline() .collection("books") .select(field("genre").arrayReverse().as("reversedGenres")) );
Быстрый
let result = try await db.pipeline() .collection("books") .select([Field("genre").arrayReverse().as("reversedGenres")]) .execute()
Kotlin
val result = db.pipeline() .collection("books") .select(field("genre").arrayReverse().alias("reversedGenres")) .execute()
Java
Task<Pipeline.Snapshot> result = db.pipeline() .collection("books") .select(field("genre").arrayReverse().alias("reversedGenres")) .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field result = ( client.pipeline() .collection("books") .select(Field.of("genre").array_reverse().as_("reversedGenres")) .execute() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("books") .select(arrayReverse(field("genre")).as("reversedGenres")) .execute() .get();
ARRAY_FIRST
Синтаксис:
array_first(array: ARRAY) -> ANY
Описание:
Возвращает первый элемент array . Это эквивалентно функции array_get(array, 0) .
- Если
arrayпуст, возвращает отсутствующее значение.
Примеры:
| множество | array_first(array) |
|---|---|
| [1, 2, 3] | 1 |
| [] | отсутствующий |
ARRAY_FIRST_N
Синтаксис:
array_first_n(array: ARRAY, n: INT64) -> ARRAY
Описание:
Возвращает первые n элементов array . Это эквивалентно функции array_slice(array, 0, n) .
- Если
nотрицательное, возвращается ошибка.
Примеры:
| множество | н | array_first_n(array, n) |
|---|---|---|
| [1, 2, 3, 4, 5] | 3 | [1, 2, 3] |
| [1, 2] | 3 | [1, 2] |
| [1, 2, 3] | 0 | [] |
ARRAY_INDEX_OF
Синтаксис:
array_index_of(array: ARRAY, value: ANY) -> INT64
Описание:
Возвращает индекс первого вхождения value в array , начинающийся с 0. Возвращает -1, если value не найдено.
Примеры:
| множество | ценить | array_index_of(array, value) |
|---|---|---|
| [1, 2, 3, 2] | 2 | 1 |
| [1, 2, 3] | 4 | -1 |
| [1, null, 3] | нулевой | 1 |
ARRAY_INDEX_OF_ALL
Синтаксис:
array_index_of_all(array: ARRAY, value: ANY) -> ARRAY<INT64>
Описание:
Возвращает массив, содержащий индексы всех вхождений value в array , начиная с 0. Возвращает [] , если value не найдено.
Примеры:
| множество | ценить | array_index_of_all(array, value) |
|---|---|---|
| [1, 2, 3, 2] | 2 | [1, 3] |
| [1, 2, 3] | 4 | [] |
| [1, null, 3, null] | нулевой | [1, 3] |
ARRAY_LAST
Синтаксис:
array_last(array: ARRAY) -> ANY
Описание:
Возвращает последний элемент array . Это эквивалентно функции array_get(array, -1) .
- Если
arrayпуст, возвращает отсутствующее значение.
Примеры:
| множество | array_last(array) |
|---|---|
| [1, 2, 3] | 3 |
| [] | отсутствующий |
ARRAY_LAST_N
Синтаксис:
array_last_n(array: ARRAY, n: INT64) -> ARRAY
Описание:
Возвращает последние n элементов array .
- Если
nотрицательное, возвращается ошибка.
Примеры:
| множество | н | array_last_n(array, n) |
|---|---|---|
| [1, 2, 3, 4, 5] | 3 | [3, 4, 5] |
| [1, 2] | 3 | [1, 2] |
| [1, 2, 3] | 0 | [] |
ARRAY_SLICE
Синтаксис:
array_slice(array: ARRAY, offset: INT64, length: INT64) -> ARRAY
Описание:
Возвращает подмножество array , начиная с нулевого offset и включая элементы length .
- Если
offsetотрицательное, оно указывает начальную позицию от конца массива, при этом-1соответствует последнему элементу. - Если
lengthпревышает количество элементов, оставшихся в массиве послеoffset, результат распространяется до конца массива. -
lengthдолжна быть неотрицательной, в противном случае возвращается ошибка.
Примеры:
| множество | компенсировать | длина | array_slice(array, offset, length) |
|---|---|---|---|
| [1, 2, 3, 4, 5] | 1 | 3 | [2, 3, 4] |
| [1, 2, 3, 4, 5] | -2 | 2 | [4, 5] |
| [1, 2, 3] | 1 | 5 | [2, 3] |
| [1, 2, 3] | 3 | 2 | [] |
ARRAY_TRANSFORM
Синтаксис:
array_transform(array: ARRAY, expression: (ANY) -> ANY) -> ARRAY
array_transform(array: ARRAY, expression: (ANY, INT64) -> ANY) -> ARRAY
Описание:
Преобразует array , применяя expression к каждому элементу, и возвращает новый массив с преобразованными элементами. Выходной массив всегда будет иметь тот же размер, что и входной массив.
-
expressionможет быть унарной функциейelement -> resultили бинарной функцией(element, index) -> result. - Если
expressionявляется унарным, оно вызывается для каждого элементаarray. - Если
expressionявляется бинарным, оно вызывается для каждого элементаarrayи соответствующего ему индекса, начинающегося с 0.
Примеры:
| множество | выражение | array_transform(array, expression) |
|---|---|---|
| [1, 2, 3] | x -> x * 2 | [2, 4, 6] |
| [1, 2, 3] | x -> x + 1 | [2, 3, 4] |
| [10, 20] | (x, i) -> x + i | [10, 21] |
| [] | x -> 1 | [] |
МАКСИМУМ
Синтаксис:
maximum(array: ARRAY) -> ANY
Описание:
Возвращает максимальное значение в array .
- Значения
NULLигнорируются при сравнении. - Если
arrayпуст или содержит только значенияNULL, возвращаетNULL.
Примеры:
| множество | maximum(array) |
|---|---|
| [1, 5, 2] | 5 |
| [1, null, 5] | 5 |
| ["a", "c", "b"] | "с" |
| [null, null] | нулевой |
| [] | нулевой |
МАКСИМУМ_Н
Синтаксис:
maximum_n(array: ARRAY, n: INT64) -> ARRAY
Описание:
Возвращает массив из n наибольших значений в array в порядке убывания.
- Значения
NULLигнорируются. - Если
nотрицательное, возвращается ошибка.
Примеры:
| множество | н | maximum_n(array, n) |
|---|---|---|
| [1, 5, 2, 4, 3] | 3 | [5, 4, 3] |
| [1, null, 5] | 3 | [5, 1] |
МИНИМУМ
Синтаксис:
minimum(array: ARRAY) -> ANY
Описание:
Возвращает минимальное значение в array .
- Значения
NULLигнорируются при сравнении. - Если
arrayпуст или содержит только значенияNULL, возвращаетNULL.
Примеры:
| множество | minimum(array) |
|---|---|
| [1, 5, 2] | 1 |
| [5, null, 1] | 1 |
| ["a", "c", "b"] | "а" |
| [null, null] | нулевой |
| [] | нулевой |
МИНИМУМ_Н
Синтаксис:
minimum_n(array: ARRAY, n: INT64) -> ARRAY
Описание:
Возвращает массив из n наименьших значений в array в порядке возрастания.
- Значения
NULLигнорируются. - Если
nотрицательное, возвращается ошибка.
Примеры:
| множество | н | minimum_n(array, n) |
|---|---|---|
| [1, 5, 2, 4, 3] | 3 | [1, 2, 3] |
| [5, null, 1] | 3 | [1, 5] |
СУММА
Синтаксис:
sum(array: ARRAY) -> INT64 | FLOAT64
Описание:
Возвращает сумму всех NUMERIC значений в ARRAY .
- Нечисловые значения в массиве игнорируются.
- Если какое-либо числовое значение в массиве равно
NaN, функция возвращаетNaN. - Тип возвращаемого значения определяется самым широким числовым типом в массиве:
INT64<FLOAT64. - Если переполнение 64-битного целого числа происходит до суммирования каких-либо значений с плавающей запятой, возвращается ошибка. Если значения с плавающей запятой суммируются, переполнение приведет к значению +/- бесконечность.
- Если массив не содержит числовых значений, функция возвращает
NULL.
Примеры:
| множество | sum(array) |
|---|---|
| [1, 2, 3] | 6 л |
| [1 л, 2 л, 3 л] | 6 л |
| [2000000000, 2000000000] | 4000000000 л |
| [10, 20.5] | 30.5 |
| [1, "а", 2] | 3 л |
| [INT64.MAX_VALUE, 1] | ошибка |
| [INT64.MAX_VALUE, 1, -1.0] | ошибка |
| [INT64.MAX_VALUE, 1.0] | 9.223372036854776e+18 |
ПРИСОЕДИНИТЬСЯ
Синтаксис:
join[T <: STRING | BYTES](array: ARRAY<T>, delimiter: T) -> STRING
join[T <: STRING | BYTES](array: ARRAY<T>, delimiter: T, null_text: T) -> STRING
Описание:
Возвращает конкатенацию элементов array в виде STRING . array может иметь тип данных STRING или BYTES .
- Все элементы в
array,delimiterиnull_textдолжны быть одного типа; все они должны бытьSTRINGилиBYTES. - Если указан
null_text, все значенияNULLвarrayзаменяются наnull_text. - Если
null_textне указан, значенияNULLвarrayисключаются из результата.
Примеры:
Если null_text не указан:
| множество | разделитель | join(array, delimiter) |
|---|---|---|
| ["a", "b", "c"] | "," | "a,b,c" |
| ["a", null, "c"] | "," | "а,с" |
| [b'a', b'b', b'c'] | б',' | б'а,б,с' |
| ["а", б'с'] | "," | ошибка |
| ["а", "с"] | б',' | ошибка |
| [b'a', b'c'] | "," | ошибка |
Если предоставлен null_text :
| множество | разделитель | нулевой текст | join(array, delimiter, null_text) |
|---|---|---|---|
| ["a", null, "c"] | "," | "ОТСУТСТВУЮЩИЙ" | "a,MISSING,c" |
| [b'a', null, b'c'] | б',' | b'NULL' | b'a,NULL,c' |
| [null, "b", null] | "," | "ОТСУТСТВУЮЩИЙ" | "ПРОПАВШИЙ,b,ПРОПАВШИЙ" |
| [b'a', null, null] | б',' | b'NULL' | b'a,NULL,NULL' |
| ["a", null] | "," | б'Н' | ошибка |
| [b'a', null] | б',' | "Н" | ошибка |