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_GET Devuelve el elemento en un índice determinado en un ARRAY.
ARRAY_LENGTH Devuelve la cantidad de elementos en un ARRAY.
ARRAY_REVERSE Invierte el orden de los elementos 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]

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayConcat([field("subGenre")]).as("allGenres"))
);
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

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

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

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

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

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

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

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, la función devuelve un valor ausente.
  • 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 ausente
nulo 0 ausente
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

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

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]

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

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