Fonctions de tableau

Fonctions de tableau

Nom Description
ARRAY Renvoie un ARRAY contenant un élément pour chaque argument d'entrée.
ARRAY_CONCAT Concatène plusieurs tableaux en un seul ARRAY
ARRAY_CONTAINS Renvoie TRUE si un ARRAY donné contient une valeur spécifique.
ARRAY_CONTAINS_ALL Renvoie TRUE si toutes les valeurs sont présentes dans ARRAY.
ARRAY_CONTAINS_ANY Renvoie TRUE si l'une des valeurs est présente dans ARRAY.
ARRAY_FILTER Filtre les éléments d'un ARRAY qui ne respectent pas un prédicat
ARRAY_FIRST Renvoie le premier élément d'un ARRAY.
ARRAY_FIRST_N Renvoie les n premiers éléments d'un ARRAY.
ARRAY_GET Renvoie l'élément à un index donné dans un ARRAY.
ARRAY_INDEX_OF Renvoie l'index de la première occurrence d'une valeur dans un ARRAY.
ARRAY_INDEX_OF_ALL Renvoie tous les index d'une valeur dans un ARRAY.
ARRAY_LENGTH Renvoie le nombre d'éléments dans un ARRAY.
ARRAY_LAST Renvoie le dernier élément d'un ARRAY.
ARRAY_LAST_N Renvoie les n derniers éléments d'un ARRAY.
ARRAY_REVERSE Inverse l'ordre des éléments d'un ARRAY
ARRAY_SLICE Renvoie une tranche d'un ARRAY
ARRAY_TRANSFORM Transforme les éléments d'un ARRAY en appliquant une expression à chaque élément.
MAXIMUM Renvoie la valeur maximale dans un ARRAY.
MAXIMUM_N Renvoie les n valeurs les plus élevées dans un ARRAY.
MINIMUM Renvoie la valeur minimale dans un ARRAY.
MINIMUM_N Renvoie les n valeurs les plus petites dans un ARRAY.
SUM Renvoie la somme de toutes les valeurs NUMERIC dans un ARRAY.
JOIN Génère une concaténation des éléments d'un ARRAY sous forme de valeur STRING.

ARRAY

Syntaxe :

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

Description :

Construit un tableau à partir des éléments fournis.

  • Si un argument n'existe pas, il est remplacé par NULL dans le tableau résultant.

Exemples :

valeurs 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

Syntaxe :

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

Description :

Concatène deux tableaux ou plus en un seul ARRAY.

Exemples :

arrays 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();
Accéder
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayConcat(firestore.FieldOf("genre"), firestore.FieldOf("subGenre")).As("allGenres"),
	)).
	Execute(ctx)

ARRAY_CONTAINS

Syntaxe :

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

Description :

Renvoie TRUE si value est trouvé dans array, et FALSE dans le cas contraire.

Exemples :

tableau valeur array_contains(array, value)
[1, 2, 3] 2 true
[[1, 2], [3]] [1, 2] true
[1, null] null true
"abc" TOUTES erreur
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();
Accéder
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayContains(firestore.FieldOf("genre"), "mystery").As("isMystery"),
	)).
	Execute(ctx)

ARRAY_CONTAINS_ALL

Syntaxe :

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

Description :

Renvoie TRUE si tous les search_values sont trouvés dans array, et FALSE dans le cas contraire.

Exemples :

tableau search_values array_contains_all(array, search_values)
[1, 2, 3] [1, 2] true
[1, 2, 3] [1, 4] faux
[1, null] [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();
Accéder
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayContainsAll(firestore.FieldOf("genre"), []string{"fantasy", "adventure"}).As("isFantasyAdventure"),
	)).
	Execute(ctx)

ARRAY_CONTAINS_ANY

Syntaxe :

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

Description :

Renvoie TRUE si l'un des search_values est trouvé dans array, ou FALSE dans le cas contraire.

Exemples :

tableau search_values array_contains_any(array, search_values)
[1, 2, 3] [4, 1] true
[1, 2, 3] [4, 5] faux
[1, 2, null] [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();
Accéder
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayContainsAny(firestore.FieldOf("genre"), []string{"fantasy", "nonfiction"}).As("isMysteryOrFantasy"),
	)).
	Execute(ctx)

ARRAY_FILTER

Syntaxe :

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

Description :

Filtre array à l'aide d'une expression predicate et renvoie un nouveau tableau contenant uniquement les éléments qui satisfont le prédicat.

  • Pour chaque élément de array, predicate est évalué. Si elle renvoie true, l'élément est inclus dans le résultat. Sinon (si elle renvoie false ou null), il est omis.
  • Si predicate renvoie une valeur non booléenne ou non nulle, la fonction renvoie une erreur.

Exemples :

tableau prédicat 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

Syntaxe :

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

Description :

Renvoie l'élément à l'index index (base 0) dans array.

  • Si index est négatif, les éléments sont accessibles à partir de la fin du tableau, où -1 est le dernier élément.
  • Si array n'est pas de type ARRAY et n'est pas null, une erreur est renvoyée.
  • Si index est hors limites, la fonction renvoie une valeur absente.
  • Si index n'est pas de type INT64, la fonction renvoie une erreur.

Exemples :

tableau index array_get(array, index)
[1, 2, 3] 0 1
[1, 2, 3] -1 3
[1, 2, 3] 3 absent
[1, 2, 3] -4 absent
"abc" 0 erreur
null 0 null
Array "a" erreur
Array 2.0 erreur

ARRAY_LENGTH

Syntaxe :

array_length(array: ARRAY) -> INT64

Description :

Renvoie le nombre d'éléments dans array.

Exemples :

tableau 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();
Accéder
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayLength(firestore.FieldOf("genre")).As("genreCount"),
	)).
	Execute(ctx)

ARRAY_REVERSE

Syntaxe :

array_reverse(array: ARRAY) -> ARRAY

Description :

Inverse le array donné.

Exemples :

tableau 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();
Accéder
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayReverse(firestore.FieldOf("genre")).As("reversedGenres"),
	)).
	Execute(ctx)

ARRAY_FIRST

Syntaxe :

array_first(array: ARRAY) -> ANY

Description :

Renvoie le premier élément de array. Cela équivaut à array_get(array, 0).

  • Si array est vide, renvoie une valeur absente.

Exemples :

tableau array_first(array)
[1, 2, 3] 1
[] absent

ARRAY_FIRST_N

Syntaxe :

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

Description :

Renvoie les n premiers éléments de array. Cela équivaut à array_slice(array, 0, n).

  • Si n est négatif, une erreur est renvoyée.

Exemples :

tableau 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

Syntaxe :

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

Description :

Renvoie l'index en base 0 de la première occurrence de value dans array. Renvoie -1 si value est introuvable.

Exemples :

tableau valeur 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

Syntaxe :

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

Description :

Renvoie un tableau contenant les index (basés sur 0) de toutes les occurrences de value dans array. Renvoie [] si value est introuvable.

Exemples :

tableau valeur 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

Syntaxe :

array_last(array: ARRAY) -> ANY

Description :

Renvoie le dernier élément de array. Cela équivaut à array_get(array, -1).

  • Si array est vide, renvoie une valeur absente.

Exemples :

tableau array_last(array)
[1, 2, 3] 3
[] absent

ARRAY_LAST_N

Syntaxe :

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

Description :

Renvoie les n derniers éléments de array.

  • Si n est négatif, une erreur est renvoyée.

Exemples :

tableau 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

Syntaxe :

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

Description :

Renvoie un sous-ensemble de array commençant à l'index de base 0 offset et incluant length éléments.

  • Si offset est négatif, il indique la position de départ à partir de la fin du tableau, -1 étant le dernier élément.
  • Si length est supérieur au nombre d'éléments restants dans le tableau après offset, le résultat s'étend jusqu'à la fin du tableau.
  • length ne doit pas être négatif, sinon une erreur est renvoyée.

Exemples :

tableau offset longueur 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

Syntaxe :

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

Description :

Transforme array en appliquant expression à chaque élément et renvoie un nouveau tableau avec les éléments transformés. Le tableau de sortie aura toujours la même taille que le tableau d'entrée.

  • expression peut être une fonction unaire element -> result ou une fonction binaire (element, index) -> result.
  • Si expression est unaire, il est appelé avec chaque élément de array.
  • Si expression est binaire, il est appelé avec chaque élément de array et son index de base 0 correspondant.

Exemples :

tableau expression 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

Syntaxe :

maximum(array: ARRAY) -> ANY

Description :

Renvoie la valeur maximale dans array.

  • Les valeurs NULL sont ignorées lors de la comparaison.
  • Si array est vide ou ne contient que des valeurs NULL, renvoie NULL.

Exemples :

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

MAXIMUM_N

Syntaxe :

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

Description :

Renvoie un tableau des n valeurs les plus élevées de array, dans l'ordre décroissant.

  • Les valeurs NULL sont ignorées.
  • Si n est négatif, une erreur est renvoyée.

Exemples :

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

MINIMUM

Syntaxe :

minimum(array: ARRAY) -> ANY

Description :

Renvoie la valeur minimale dans array.

  • Les valeurs NULL sont ignorées lors de la comparaison.
  • Si array est vide ou ne contient que des valeurs NULL, renvoie NULL.

Exemples :

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

MINIMUM_N

Syntaxe :

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

Description :

Renvoie un tableau des n plus petites valeurs de array par ordre croissant.

  • Les valeurs NULL sont ignorées.
  • Si n est négatif, une erreur est renvoyée.

Exemples :

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

SUM

Syntaxe :

sum(array: ARRAY) -> INT64 | FLOAT64

Description :

Renvoie la somme de toutes les valeurs NUMERIC dans un ARRAY.

  • Les valeurs non numériques du tableau sont ignorées.
  • Si une valeur numérique du tableau est NaN, la fonction renvoie NaN.
  • Le type renvoyé est déterminé par le type numérique le plus large du tableau : INT64 < FLOAT64.
  • Si un dépassement de capacité d'entier 64 bits se produit avant l'addition d'une valeur à virgule flottante, une erreur est renvoyée. Si des valeurs à virgule flottante sont additionnées, le dépassement de capacité entraînera une valeur infinie positive ou négative.
  • Si le tableau ne contient aucune valeur numérique, la fonction renvoie NULL.

Exemples :

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

JOIN

Syntaxe :

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

Description :

Renvoie une concaténation des éléments de array sous forme de STRING. array peut être de type STRING ou BYTES.

  • Tous les éléments de array, delimiter et null_text doivent être du même type : ils doivent tous être des STRING ou des BYTES.
  • Si null_text est fourni, toutes les valeurs NULL de array sont remplacées par null_text.
  • Si null_text n'est pas fourni, les valeurs NULL dans array sont omises du résultat.

Exemples :

Lorsque null_text n'est pas fourni :

tableau delimiter 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'] "," erreur
["a", "c"] b',' erreur
[b'a', b'c'] "," erreur

Lorsque null_text est fourni :

tableau delimiter null_text join(array, delimiter, null_text)
["a", null, "c"] "," "MISSING" (MANQUANT) "a,MISSING,c"
[b'a', null, b'c'] b',' b'NULL' b'a,NULL,c'
[null, "b", null] "," "MISSING" (MANQUANT) "MISSING,b,MISSING"
[b'a', null, null] b',' b'NULL' b'a,NULL,NULL'
["a", null] "," b'N' erreur
[b'a', null] b',' "N" erreur