Funciones de arreglo

Funciones de matríz

Nombre Descripción
ARRAY Devuelve un ARRAY que contiene un elemento para cada argumento de entrada.
ARRAY_CONCAT Concatena varios arrays en un solo ARRAY.
ARRAY_CONTAINS Devuelve TRUE si un ARRAY determinado contiene un valor específico.
ARRAY_CONTAINS_ALL Devuelve TRUE si todos los valores están presentes en ARRAY.
ARRAY_CONTAINS_ANY Devuelve TRUE si alguno de los valores está presente en ARRAY.
ARRAY_FIRST Devuelve el primer elemento en un ARRAY.
ARRAY_FIRST_N Devuelve los primeros elementos n en un ARRAY.
ARRAY_GET Devuelve el elemento en un índice determinado en un ARRAY.
ARRAY_INDEX_OF Devuelve el índice de la primera ocurrencia de un valor en un ARRAY.
ARRAY_INDEX_OF_ALL Devuelve todos los índices de un valor en un ARRAY.
ARRAY_LENGTH Devuelve la cantidad de elementos en un ARRAY.
ARRAY_LAST Devuelve el último elemento de un ARRAY.
ARRAY_LAST_N Devuelve los últimos elementos de n en un ARRAY.
ARRAY_REVERSE Invierte el orden de los elementos en un ARRAY.
ARRAY_SLICE Devuelve un segmento de un ARRAY
MAXIMUM Devuelve el valor máximo en un ARRAY.
MAXIMUM_N Devuelve los valores más grandes de n en un ARRAY.
MINIMUM Devuelve el valor mínimo en un ARRAY.
MINIMUM_N Devuelve los valores más pequeños de n en un ARRAY.
SUM Devuelve la suma de todos los valores de NUMERIC en un ARRAY.
JOIN Produce una concatenación de los elementos en un ARRAY como un valor de STRING.

ARRAY

Sintaxis:

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

Descripción:

Construye un array a partir de los elementos proporcionados.

  • Si no existe un argumento, se reemplaza por NULL en el array resultante.

Ejemplos:

valores 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

Sintaxis:

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

Descripción:

Concatena dos o más arrays en un solo ARRAY.

Ejemplos:

arreglos 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

val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres"))
    .execute()
DocSnippets.kt

Java

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

Sintaxis:

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

Descripción:

Devuelve TRUE si se encuentra value en array y FALSE en caso contrario.

Ejemplos:

array valor array_contains(array, value)
[1, 2, 3] 2 verdadero
[[1, 2], [3]] [1, 2] verdadero
[1, null] nulo verdadero
"abc" CUALQUIERA error
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

val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayContains("mystery").alias("isMystery"))
    .execute()
DocSnippets.kt

Java

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

Sintaxis:

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

Descripción:

Devuelve TRUE si todos los search_values se encuentran en el array, y FALSE en caso contrario.

Ejemplos:

array search_values array_contains_all(array, search_values)
[1, 2, 3] [1, 2] verdadero
[1, 2, 3] [1, 4] falso
[1, null] [null] verdadero
[NaN] [NaN] verdadero
[] [] verdadero
[1, 2, 3] [] verdadero
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

val result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAll(listOf("fantasy", "adventure"))
            .alias("isFantasyAdventure")
    )
    .execute()
DocSnippets.kt

Java

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

Sintaxis:

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

Descripción:

Devuelve TRUE si se encuentra alguno de los search_values en el array, y FALSE en caso contrario.

Ejemplos:

array search_values array_contains_any(array, search_values)
[1, 2, 3] [4, 1] verdadero
[1, 2, 3] [4, 5] falso
[1, 2, null] [null] verdadero
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

val result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAny(listOf("fantasy", "nonfiction"))
            .alias("isMysteryOrFantasy")
    )
    .execute()
DocSnippets.kt

Java

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_GET

Sintaxis:

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

Descripción:

Devuelve el elemento en el índice index basado en 0 en array.

  • Si index es negativo, se accede a los elementos desde el final del array, donde -1 es el último elemento.
  • Si array no es del tipo ARRAY ni null, se devuelve un error.
  • Si index está fuera de los límites, la función devuelve un valor ausente.
  • Si index no es del tipo INT64, la función muestra un error.

Ejemplos:

array í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 error
nulo 0 nulo
Array "a" error
Array 2.0 error

ARRAY_LENGTH

Sintaxis:

array_length(array: ARRAY) -> INT64

Descripción:

Devuelve la cantidad de elementos en un array.

Ejemplos:

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();
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

val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayLength().alias("genreCount"))
    .execute()
DocSnippets.kt

Java

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

Sintaxis:

array_reverse(array: ARRAY) -> ARRAY

Descripción:

Invierte el array determinado.

Ejemplos:

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();
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

val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayReverse().alias("reversedGenres"))
    .execute()
DocSnippets.kt
 
    
Java

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

Sintaxis:

array_first(array: ARRAY) -> ANY

Descripción:

Devuelve el primer elemento de array. Esto equivale a array_get(array, 0).

  • Si array está vacío, devuelve un valor ausente.

Ejemplos:

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

ARRAY_FIRST_N

Sintaxis:

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

Descripción:

Devuelve los primeros elementos n de array. Esto equivale a array_slice(array, 0, n).

  • Si n es negativo, se muestra un error.

Ejemplos:

array 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

Sintaxis:

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

Descripción:

Devuelve el índice basado en 0 del primer caso de value en array. Devuelve value si no se encuentra.

Ejemplos:

array valor array_index_of(array, value)
[1, 2, 3, 2] 2 1
[1, 2, 3] 4 -1
[1, nulo, 3] nulo 1

ARRAY_INDEX_OF_ALL

Sintaxis:

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

Descripción:

Devuelve un array que contiene los índices basados en 0 de todos los casos de value en array. Muestra [] si no se encuentra value.

Ejemplos:

array valor array_index_of_all(array, value)
[1, 2, 3, 2] 2 [1, 3]
[1, 2, 3] 4 []
[1, nulo, 3, nulo] nulo [1, 3]

ARRAY_LAST

Sintaxis:

array_last(array: ARRAY) -> ANY

Descripción:

Devuelve el último elemento de array. Esto equivale a array_get(array, -1).

  • Si array está vacío, devuelve un valor ausente.

Ejemplos:

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

ARRAY_LAST_N

Sintaxis:

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

Descripción:

Devuelve los últimos elementos de n de array.

  • Si n es negativo, se muestra un error.

Ejemplos:

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

Sintaxis:

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

Descripción:

Devuelve un subconjunto de array que comienza en el índice offset basado en 0 y que incluye elementos length.

  • Si offset es negativo, indica la posición de inicio desde el final del array, en el que -1 es el último elemento.
  • Si length es mayor que la cantidad de elementos restantes en el array después de offset, el resultado se extiende hasta el final del array.
  • length debe ser no negativo; de lo contrario, se devolverá un error.

Ejemplos:

array offset longitud 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 []

MAXIMUM

Sintaxis:

maximum(array: ARRAY) -> ANY

Descripción:

Devuelve el valor máximo en array.

  • Los valores de NULL se ignoran durante la comparación.
  • Si array está vacío o solo contiene valores NULL, se devuelve NULL.

Ejemplos:

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

MAXIMUM_N

Sintaxis:

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

Descripción:

Devuelve un array con los valores más grandes de n en array en orden descendente.

  • Los valores NULL se ignoran.
  • Si n es negativo, se muestra un error.

Ejemplos:

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

MINIMUM

Sintaxis:

minimum(array: ARRAY) -> ANY

Descripción:

Devuelve el valor mínimo en array.

  • Los valores de NULL se ignoran durante la comparación.
  • Si array está vacío o solo contiene valores NULL, se devuelve NULL.

Ejemplos:

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

MINIMUM_N

Sintaxis:

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

Descripción:

Devuelve un array con los valores más pequeños de n en array en orden ascendente.

  • Los valores NULL se ignoran.
  • Si n es negativo, se muestra un error.

Ejemplos:

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

SUM

Sintaxis:

sum(array: ARRAY) -> INT64 | FLOAT64

Descripción:

Devuelve la suma de todos los valores de NUMERIC en un ARRAY.

  • Se ignoran los valores no numéricos del array.
  • Si algún valor numérico del array es NaN, la función devuelve NaN.
  • El tipo de datos que se devuelve se determina según el tipo numérico más amplio del array: INT64 < FLOAT64.
  • Si se produce un desbordamiento de números enteros de 64 bits antes de que se sume cualquier valor de punto flotante, se devuelve un error. Si se suman valores de punto flotante, el desbordamiento generará +/- infinito.
  • Si el array no contiene valores numéricos, la función devuelve NULL.

Ejemplos:

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

UNIRSE

Sintaxis:

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

Descripción:

Muestra una concatenación de los elementos en la array como una STRING. El array puede ser de tipos de datos STRING o BYTES.

  • Todos los elementos de array, delimiter y null_text deben ser del mismo tipo: todos deben ser STRING o todos deben ser BYTES.
  • Si se proporciona null_text, cualquier valor NULL en array se reemplaza por null_text.
  • Si no se proporciona null_text, los valores de NULL en array se omiten del resultado.

Ejemplos:

Cuando no se proporciona null_text:

array 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'] "," error
["a", "c"] b',' error
[b'a', b'c'] "," error

Cuando se proporciona null_text, ocurre lo siguiente:

array 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' error
[b'a', null] b',' "N" error