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

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

Имя Описание
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] б',' "Н" ошибка