Функции для работы с массивами

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

Имя Описание
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

Синтаксис:

array(values: ANY...) -> ARRAY

Описание.

Создает массив из указанных элементов.

  • Если аргумент не существует, в результирующем массиве он заменяется на NULL.

Примеры

values array(values)
() []
(1, 2, 3) [1, 2, 3]
("a", 1, true) ["a", 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();
Swift
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();
Проложить маршрут
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayConcat(firestore.FieldOf("genre"), firestore.FieldOf("subGenre")).As("allGenres"),
	)).
	Execute(ctx)

ARRAY_CONTAINS

Синтаксис:

array_contains(array: ARRAY, value: ANY) -> BOOLEAN

Описание.

Возвращает TRUE, если value найдено в array, и FALSE в противном случае.

Примеры

Массив value array_contains(array, value)
[1, 2, 3] 2 true
[[1, 2], [3]] [1, 2] true
[1, null] null true
"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"))
);
Swift
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();
Проложить маршрут
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayContains(firestore.FieldOf("genre"), "mystery").As("isMystery"),
	)).
	Execute(ctx)

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] true
[1, 2, 3] [1, 4] false
[1, null] [ноль] true
[NaN] [NaN] true
[] [] true
[1, 2, 3] [] true
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")
  )
);
Swift
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();
Проложить маршрут
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayContainsAll(firestore.FieldOf("genre"), []string{"fantasy", "adventure"}).As("isFantasyAdventure"),
	)).
	Execute(ctx)

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] true
[1, 2, 3] [4, 5] false
[1, 2, null] [ноль] true
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")
  )
);
Swift
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();
Проложить маршрут
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayContainsAny(firestore.FieldOf("genre"), []string{"fantasy", "nonfiction"}).As("isMysteryOrFantasy"),
	)).
	Execute(ctx)

ARRAY_FILTER

Синтаксис:

array_filter(array: ARRAY, predicate: (ANY) -> BOOLEAN) -> ARRAY

Описание.

Фильтрует array с помощью выражения predicate, возвращая новый массив, содержащий только элементы, которые соответствуют предикату.

  • Для каждого элемента в array вычисляется predicate. Если возвращается значение true, элемент включается в результат, а если false или null – пропускается.
  • Если predicate возвращает не логическое значение и не null, функция возвращает ошибку.

Примеры

Массив предикат 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" ["a", "c"]
[] x -> true []

ARRAY_GET

Синтаксис:

array_get(array: ARRAY, index: INT64) -> ANY

Описание.

Возвращает элемент с индексом index (начиная с нуля) в массиве array.

  • Если значение 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 ошибка
null 0 null
Array "a" ошибка
Array 2.0 ошибка

ARRAY_LENGTH

Синтаксис:

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"))
);
Swift
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();
Проложить маршрут
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayLength(firestore.FieldOf("genre")).As("genreCount"),
	)).
	Execute(ctx)

ARRAY_REVERSE

Синтаксис:

array_reverse(array: ARRAY) -> ARRAY

Описание.

Возвращает противоположное значение array.

Примеры

Массив array_reverse(array)
[1, 2, 3] [3, 2, 1]
["a", "b"] ["b", "a"]
[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"))
);
Swift
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();
Проложить маршрут
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayReverse(firestore.FieldOf("genre")).As("reversedGenres"),
	)).
	Execute(ctx)

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 – отрицательное число, возвращается ошибка.

Примеры

Массив 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. Если значение value не найдено, возвращает -1.

Примеры

Массив value array_index_of(array, value)
[1, 2, 3, 2] 2 1
[1, 2, 3] 4 -1
[1, null, 3] null 1

ARRAY_INDEX_OF_ALL

Синтаксис:

array_index_of_all(array: ARRAY, value: ANY) -> ARRAY<INT64>

Описание.

Возвращает массив, содержащий индексы (начиная с 0) всех вхождений value в array. Если value не найдено, возвращает [].

Примеры

Массив value array_index_of_all(array, value)
[1, 2, 3, 2] 2 [1, 3]
[1, 2, 3] 4 []
[1, null, 3, null] 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 – отрицательное число, возвращается ошибка.

Примеры

Массив 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"] "c"
[null, null] null
[] null

MAXIMUM_N

Синтаксис:

maximum_n(array: ARRAY, n: INT64) -> ARRAY

Описание.

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

  • Значения NULL игнорируются.
  • Если n – отрицательное число, возвращается ошибка.

Примеры

Массив 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"] "a"
[null, null] null
[] null

MINIMUM_N

Синтаксис:

minimum_n(array: ARRAY, n: INT64) -> ARRAY

Описание.

Возвращает массив из n наименьших значений в array в порядке возрастания.

  • Значения NULL игнорируются.
  • Если n – отрицательное число, возвращается ошибка.

Примеры

Массив N minimum_n(array, n)
[1, 5, 2, 4, 3] 3 [1, 2, 3]
[5, null, 1] 3 [1, 5]

SUM

Синтаксис:

sum(array: ARRAY) -> INT64 | FLOAT64

Описание.

Возвращает сумму всех значений NUMERIC в ARRAY.

  • Нечисловые значения в массиве игнорируются.
  • Если какое-либо числовое значение в массиве равно NaN, функция возвращает NaN.
  • Тип возвращаемого значения определяется самым широким числовым типом в массиве: INT64 < FLOAT64.
  • Если до суммирования значений с плавающей запятой происходит переполнение 64-битного целого числа, возвращается ошибка. Если суммируются значения с плавающей запятой, переполнение приведет к +/- бесконечности.
  • Если в массиве нет числовых значений, функция возвращает NULL.

Примеры

Массив sum(array)
[1, 2, 3] 6L
[1L, 2L, 3L] 6L
[2000000000, 2000000000] 4000000000L
[10, 20.5] 30,5
[1, "a", 2] 3L
[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"] "," "a,c"
[b'a', b'b', b'c'] b',' b'a,b,c'
["a", b'c'] "," ошибка
["a", "c"] b',' ошибка
[b'a', b'c'] "," ошибка

Если указан параметр null_text:

Массив разделитель null_text join(array, delimiter, null_text)
["a", null, "c"] "," "MISSING" "a,MISSING,c"
[b'a', null, b'c'] b',' b'NULL' b'a,NULL,c'
[null, "b", null] "," "MISSING" "MISSING,b,MISSING"
[b'a', null, null] b',' b'NULL' b'a,NULL,NULL'
["a", null] "," b'N' ошибка
[b'a', null] b',' "N" ошибка