Referência de funções de matriz

Funções de matriz

Nome Descrição
ARRAY Retorna um ARRAY que contém um elemento para cada argumento de entrada.
ARRAY_CONCAT Concatena várias matrizes em um único ARRAY
ARRAY_CONTAINS Retorna TRUE se um determinado ARRAY contém um valor específico.
ARRAY_CONTAINS_ALL Retorna TRUE se todos os valores estiverem presentes no ARRAY.
ARRAY_CONTAINS_ANY Retorna TRUE se algum dos valores estiver presente no ARRAY
ARRAY_FILTER Filtra elementos de um ARRAY que não satisfazem um predicado.
ARRAY_FIRST Retorna o primeiro elemento em um ARRAY
ARRAY_FIRST_N Retorna os primeiros elementos n em um ARRAY
ARRAY_GET Retorna o elemento em um determinado índice em um ARRAY
ARRAY_INDEX_OF Retorna o índice da primeira ocorrência de um valor em um ARRAY.
ARRAY_INDEX_OF_ALL Retorna todos os índices de um valor em um ARRAY
ARRAY_LENGTH Retorna o número de elementos em um ARRAY
ARRAY_LAST Retorna o último elemento em um ARRAY
ARRAY_LAST_N Retorna os últimos elementos n em um ARRAY
ARRAY_REVERSE Inverte a ordem dos elementos em um ARRAY.
ARRAY_SLICE Retorna uma fração de um ARRAY
ARRAY_TRANSFORM Transforma elementos em um ARRAY aplicando uma expressão a cada elemento
MAXIMUM Retorna o valor máximo em um ARRAY
MAXIMUM_N Retorna os n maiores valores em um ARRAY
MINIMUM Retorna o valor mínimo em um ARRAY
MINIMUM_N Retorna os n menores valores em um ARRAY.
SUM Retorna a soma de todos os valores NUMERIC em um ARRAY.
JOIN Produz uma concatenação dos elementos em um ARRAY como um valor STRING.

ARRAY

Sintaxe:

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

Descrição:

Cria uma matriz com base nos elementos fornecidos.

  • Se um argumento não existir, ele será substituído por NULL na matriz resultante.

Exemplos:

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

Sintaxe:

array_concat(arrays: ARRAY...) -> ARRAY

Descrição:

Concatena duas ou mais matrizes em um único ARRAY.

Exemplos:

matrizes 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();
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayConcat([Field("subGenre")]).as("allGenres")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres"))
    .execute();
DocSnippets.java
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()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayConcat(field("genre"), field("subGenre")).as("allGenres"))
        .execute()
        .get();
PipelineSnippets.java

ARRAY_CONTAINS

Sintaxe:

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

Descrição:

Retorna TRUE se value for encontrado no array. Caso contrário, retorna FALSE.

Exemplos:

matriz valor array_contains(array, value)
[1, 2, 3] 2 verdadeiro
[[1, 2], [3]] [1, 2] verdadeiro
[1, null] null verdadeiro
"abc" ANY erro
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("genre").arrayContains(constant("mystery")).as("isMystery"))
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayContains(constant("mystery")).as("isMystery"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayContains(Constant("mystery")).as("isMystery")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayContains("mystery").alias("isMystery"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayContains("mystery").alias("isMystery"))
    .execute();
DocSnippets.java
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()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayContains(field("genre"), "mystery").as("isMystery"))
        .execute()
        .get();
PipelineSnippets.java

ARRAY_CONTAINS_ALL

Sintaxe:

array_contains_all(array: ARRAY, search_values: ARRAY) -> BOOLEAN

Descrição:

Retorna TRUE se todos os search_values forem encontrados no array. Caso contrário, retorna FALSE.

Exemplos:

matriz search_values array_contains_all(array, search_values)
[1, 2, 3] [1, 2] verdadeiro
[1, 2, 3] [1, 4] falso
[1, null] [null] verdadeiro
[NaN] [NaN] verdadeiro
[] [] verdadeiro
[1, 2, 3] [] verdadeiro
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAll([constant("fantasy"), constant("adventure")])
      .as("isFantasyAdventure")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAll([constant("fantasy"), constant("adventure")])
      .as("isFantasyAdventure")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre")
      .arrayContainsAll([Constant("fantasy"), Constant("adventure")])
      .as("isFantasyAdventure")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAll(listOf("fantasy", "adventure"))
            .alias("isFantasyAdventure")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAll(Arrays.asList("fantasy", "adventure"))
            .alias("isFantasyAdventure")
    )
    .execute();
DocSnippets.java
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()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            arrayContainsAll(field("genre"), Arrays.asList("fantasy", "adventure"))
                .as("isFantasyAdventure"))
        .execute()
        .get();
PipelineSnippets.java

ARRAY_CONTAINS_ANY

Sintaxe:

array_contains_any(array: ARRAY, search_values: ARRAY) -> BOOLEAN

Descrição:

Retorna TRUE se um dos search_values for encontrado no array. Caso contrário, retorna FALSE.

Exemplos:

matriz search_values array_contains_any(array, search_values)
[1, 2, 3] [4, 1] verdadeiro
[1, 2, 3] [4, 5] falso
[1, 2, null] [null] verdadeiro
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAny([constant("fantasy"), constant("nonfiction")])
      .as("isMysteryOrFantasy")
  )
  .execute();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAny([constant("fantasy"), constant("nonfiction")])
      .as("isMysteryOrFantasy")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre")
      .arrayContainsAny([Constant("fantasy"), Constant("nonfiction")])
      .as("isMysteryOrFantasy")
  ])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAny(listOf("fantasy", "nonfiction"))
            .alias("isMysteryOrFantasy")
    )
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAny(Arrays.asList("fantasy", "nonfiction"))
            .alias("isMysteryOrFantasy")
    )
    .execute();
DocSnippets.java
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()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            arrayContainsAny(field("genre"), Arrays.asList("fantasy", "nonfiction"))
                .as("isMysteryOrFantasy"))
        .execute()
        .get();
PipelineSnippets.java

ARRAY_FILTER

Sintaxe:

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

Descrição:

Filtra array usando uma expressão predicate, retornando uma nova matriz com apenas elementos que satisfazem o predicado.

  • Para cada elemento em array, predicate é avaliado. Se ele retornar true, o elemento será incluído no resultado. Caso contrário (se retornar false ou null), ele será omitido.
  • Se predicate for avaliado como um valor não booleano ou não nulo, a função vai retornar um erro.

Exemplos:

matriz predicado 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

Sintaxe:

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

Descrição:

Retorna o elemento no index baseado em zero em array.

  • Se index for negativo, os elementos serão acessados do final da matriz, em que -1 é o último elemento.
  • Se array não for do tipo ARRAY nem null, vai retornar um erro.
  • Se index estiver fora dos limites, a função vai retornar um valor ausente.
  • Se index não for do tipo INT64, a função vai retornar um erro.

Exemplos:

matriz índice array_get(array, index)
[1, 2, 3] 0 1
[1, 2, 3] -1 3
[1, 2, 3] 3 ausente
[1, 2, 3] -4 ausente
"abc" 0 erro
null 0 null
Array "a" erro
Array 2,0 erro

ARRAY_LENGTH

Sintaxe:

array_length(array: ARRAY) -> INT64

Descrição:

Retorna o número de elementos em um array.

Exemplos:

matriz 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();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayLength().as("genreCount"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayLength().as("genreCount")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayLength().alias("genreCount"))
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayLength().alias("genreCount"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_length().as_("genreCount"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayLength(field("genre")).as("genreCount"))
        .execute()
        .get();
PipelineSnippets.java

ARRAY_REVERSE

Sintaxe:

array_reverse(array: ARRAY) -> ARRAY

Descrição:

Inverte o array especificado.

Exemplos:

matriz 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();
test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayReverse().as("reversedGenres"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayReverse().as("reversedGenres")])
  .execute()
PipelineSnippets.swift
Kotlin
Android
val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayReverse().alias("reversedGenres"))
    .execute()
DocSnippets.kt
 
    
Java
Android

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayReverse().alias("reversedGenres"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_reverse().as_("reversedGenres"))
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayReverse(field("genre")).as("reversedGenres"))
        .execute()
        .get();
PipelineSnippets.java

ARRAY_FIRST

Sintaxe:

array_first(array: ARRAY) -> ANY

Descrição:

Retorna o primeiro elemento em array. É equivalente a array_get(array, 0).

  • Se array estiver vazio, vai retornar um valor ausente.

Exemplos:

matriz array_first(array)
[1, 2, 3] 1
[] ausente

ARRAY_FIRST_N

Sintaxe:

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

Descrição:

Retorna os primeiros elementos n de array. É equivalente a array_slice(array, 0, n).

  • Se n for negativo, vai retornar um erro.

Exemplos:

matriz 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

Sintaxe:

array_index_of(array: ARRAY, value: ANY) -> INT64

Descrição:

Retorna o índice baseado em zero da primeira ocorrência de value em array. Retorna -1 se value não for encontrado.

Exemplos:

matriz valor 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

Sintaxe:

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

Descrição:

Retorna uma matriz que contém os índices baseados em zero de todas as ocorrências de value em array. Retorna [] se value não for encontrado.

Exemplos:

matriz valor 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

Sintaxe:

array_last(array: ARRAY) -> ANY

Descrição:

Retorna o último elemento em array. É equivalente a array_get(array, -1).

  • Se array estiver vazio, vai retornar um valor ausente.

Exemplos:

matriz array_last(array)
[1, 2, 3] 3
[] ausente

ARRAY_LAST_N

Sintaxe:

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

Descrição:

Retorna os últimos elementos n de array.

  • Se n for negativo, vai retornar um erro.

Exemplos:

matriz 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

Sintaxe:

array_slice(array: ARRAY, offset: INT64, length: INT64) -> ARRAY

Descrição:

Retorna um subconjunto de array começando pelo índice baseado em zero offset e incluindo length elementos.

  • Se offset for negativo, ele vai indicar a posição inicial do final da matriz, em que -1 é o último elemento.
  • Se length for maior que o número de elementos restantes na matriz após offset, o resultado será estendido até o final da matriz.
  • length não pode ser negativo. Caso contrário, um erro será retornado.

Exemplos:

matriz offset comprimento 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

Sintaxe:

array_transform(array: ARRAY, expression: (ANY) -> ANY) -> ARRAY
array_transform(array: ARRAY, expression: (ANY, INT64) -> ANY) -> ARRAY

Descrição:

Transforma array aplicando expression a cada elemento e retorna uma nova matriz com elementos transformados. A matriz de saída sempre terá o mesmo tamanho da matriz de entrada.

  • expression pode ser uma função unária element -> result ou uma função binária (element, index) -> result.
  • Se expression for unário, ele será chamado com cada elemento de array.
  • Se expression for binário, ele será chamado com cada elemento de array e o índice correspondente baseado em zero.

Exemplos:

matriz expressão 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

Sintaxe:

maximum(array: ARRAY) -> ANY

Descrição:

Retorna o valor máximo em array.

  • Os valores NULL são ignorados durante a comparação.
  • Se array estiver vazio ou contiver apenas valores NULL, vai retornar NULL.

Exemplos:

matriz maximum(array)
[1, 5, 2] 5
[1, null, 5] 5
["a", "c", "b"] "c"
[null, null] null
[] null

MAXIMUM_N

Sintaxe:

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

Descrição:

Retorna uma matriz dos n maiores valores em array em ordem decrescente.

  • Os valores NULL são ignorados.
  • Se n for negativo, vai retornar um erro.

Exemplos:

matriz n maximum_n(array, n)
[1, 5, 2, 4, 3] 3 [5, 4, 3]
[1, null, 5] 3 [5, 1]

MINIMUM

Sintaxe:

minimum(array: ARRAY) -> ANY

Descrição:

Retorna o valor mínimo em array.

  • Os valores NULL são ignorados durante a comparação.
  • Se array estiver vazio ou contiver apenas valores NULL, vai retornar NULL.

Exemplos:

matriz minimum(array)
[1, 5, 2] 1
[5, null, 1] 1
["a", "c", "b"] "a"
[null, null] null
[] null

MINIMUM_N

Sintaxe:

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

Descrição:

Retorna uma matriz dos n menores valores em array em ordem crescente.

  • Os valores NULL são ignorados.
  • Se n for negativo, vai retornar um erro.

Exemplos:

matriz n minimum_n(array, n)
[1, 5, 2, 4, 3] 3 [1, 2, 3]
[5, null, 1] 3 [1, 5]

SUM

Sintaxe:

sum(array: ARRAY) -> INT64 | FLOAT64

Descrição:

Retorna a soma de todos os valores NUMERIC em um ARRAY.

  • Valores não numéricos na matriz são ignorados.
  • Se algum valor numérico na matriz for NaN, a função retornará NaN.
  • O tipo de retorno é determinado pelo tipo numérico mais amplo na matriz: INT64 < FLOAT64.
  • Se um número inteiro flutuante de 64 bits ocorrer antes que qualquer valor de ponto flutuante seja somado, um erro será retornado. Se valores de ponto flutuante forem somados, o valor flutuante vai resultar em +/- infinito.
  • Se a matriz não tiver valores numéricos, a função vai retornar NULL.

Exemplos:

matriz 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] erro
[INT64.MAX_VALUE, 1, -1.0] erro
[INT64.MAX_VALUE, 1.0] 9.223372036854776e+18

PARTICIPAR

Sintaxe:

join[T <: STRING | BYTES](array: ARRAY<T>, delimiter: T) -> STRING
join[T <: STRING | BYTES](array: ARRAY<T>, delimiter: T, null_text: T) -> STRING

Descrição:

Retorna uma concatenação dos elementos em array como um STRING. O array pode ser dos tipos de dados STRING ou BYTES.

  • Todos os elementos em array, delimiter e null_text precisam ser do mesmo tipo: todos precisam ser STRING ou BYTES.
  • Se null_text for fornecido, todos os valores NULL em array serão substituídos por null_text.
  • Se null_text não for fornecido, os valores NULL em array serão omitidos do resultado.

Exemplos:

Quando null_text não é fornecido:

matriz delimitador 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'] "," erro
["a", "c"] b',' erro
[b'a', b'c'] "," erro

Quando null_text é fornecido:

matriz delimitador 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' erro
[b'a', null] b',' "N" erro

A seguir