Documentation de référence sur les 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 particulière.
|
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 premiers éléments n 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 dans un ARRAY.
|
ARRAY_SLICE
|
Renvoie une tranche d'un ARRAY.
|
ARRAY_TRANSFORM
|
Transforme les éléments d'un ARRAY en appliquant une expression à chacun d'eux.
|
MAXIMUM
|
Renvoie la valeur maximale dans un ARRAY.
|
MAXIMUM_N
|
Renvoie les n valeurs les plus élevées d'un ARRAY.
|
MINIMUM
|
Renvoie la valeur minimale dans un ARRAY.
|
MINIMUM_N
|
Renvoie les n valeurs les plus petites d'une ARRAY.
|
SUM
|
Renvoie la somme de toutes les valeurs NUMERIC dans un ARRAY.
|
JOIN
|
Produit 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
NULLdans 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
Android
val result = db.pipeline() .collection("books") .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres")) .execute()
Java
Android
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
Syntaxe :
array_contains(array: ARRAY, value: ANY) -> BOOLEAN
Description :
Renvoie TRUE si value est trouvé dans array, ou FALSE si ce n'est pas le cas.
Exemples :
| tableau | valeur | array_contains(array, value) |
|---|---|---|
| [1, 2, 3] | 2 | vrai |
| [[1, 2], [3]] | [1, 2] | vrai |
| [1, null] | null | vrai |
| "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
Android
val result = db.pipeline() .collection("books") .select(field("genre").arrayContains("mystery").alias("isMystery")) .execute()
Java
Android
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
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] | vrai |
| [1, 2, 3] | [1, 4] | faux |
| [1, null] | [null] | vrai |
| [NaN] | [NaN] | vrai |
| [] | [] | vrai |
| [1, 2, 3] | [] | vrai |
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
Android
val result = db.pipeline() .collection("books") .select( field("genre") .arrayContainsAll(listOf("fantasy", "adventure")) .alias("isFantasyAdventure") ) .execute()
Java
Android
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
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 si ce n'est pas le cas.
Exemples :
| tableau | search_values | array_contains_any(array, search_values) |
|---|---|---|
| [1, 2, 3] | [4, 1] | vrai |
| [1, 2, 3] | [4, 5] | faux |
| [1, 2, null] | [null] | vrai |
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
Android
val result = db.pipeline() .collection("books") .select( field("genre") .arrayContainsAny(listOf("fantasy", "nonfiction")) .alias("isMysteryOrFantasy") ) .execute()
Java
Android
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
Syntaxe :
array_filter(array: ARRAY, predicate: (ANY) -> BOOLEAN) -> ARRAY
Description :
Filtre array à l'aide d'une expression predicate, en renvoyant un nouveau tableau avec uniquement les éléments qui satisfont le prédicat.
predicateest évalué pour chaque élément dearray. S'il renvoietrue, l'élément est inclus dans le résultat. Sinon (s'il renvoiefalseounull), il est omis.- Si
predicaterenvoie 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 de base 0 index dans array.
- Si
indexest négatif, les éléments sont accessibles à partir de la fin du tableau, où-1est le dernier élément. - Si
arrayn'est pas de typeARRAYet n'est pasnull, une erreur est renvoyée. - Si
indexest hors limites, la fonction renvoie une valeur absente. - Si
indexn'est pas de typeINT64, 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
Android
val result = db.pipeline() .collection("books") .select(field("genre").arrayLength().alias("genreCount")) .execute()
Java
Android
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
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
Android
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();
Android
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
Syntaxe :
array_first(array: ARRAY) -> ANY
Description :
Renvoie le premier élément de array. Cela équivaut à array_get(array, 0).
- Si
arrayest 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
nest 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 de 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 de base 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
arrayest 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
nest 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
offsetest négatif, il indique la position de départ à partir de la fin du tableau,-1étant le dernier élément. - Si
lengthest supérieur au nombre d'éléments restants dans le tableau aprèsoffset, le résultat s'étend jusqu'à la fin du tableau. lengthne doit pas être négatif, sinon une erreur est renvoyée.
Exemples :
| tableau | 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
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, puis renvoie un tableau avec les éléments transformés. Le tableau de sortie aura toujours la même taille que le tableau d'entrée.
expressionpeut être une fonction unaireelement -> resultou une fonction binaire(element, index) -> result.- Si
expressionest unaire, il est appelé avec chaque élément dearray. - Si
expressionest binaire, elle est appelée avec chaque élément dearrayet 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
NULLsont ignorées lors de la comparaison. - Si
arrayest vide ou ne contient que des valeursNULL, renvoieNULL.
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, par ordre décroissant.
- Les valeurs
NULLsont ignorées. - Si
nest 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
NULLsont ignorées lors de la comparaison. - Si
arrayest vide ou ne contient que des valeursNULL, renvoieNULL.
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
NULLsont ignorées. - Si
nest 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 renvoieNaN. - 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 qu'une valeur à virgule flottante ne soit additionnée, une erreur est renvoyée. Si des valeurs à virgule flottante sont additionnées, un 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,delimiteretnull_textdoivent être du même type : ils doivent tous être desSTRINGou desBYTES. - Si
null_textest fourni, toutes les valeursNULLdearraysont remplacées parnull_text. - Si
null_textn'est pas fourni, les valeursNULLdansarraysont 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 |
Étapes suivantes
- Consultez la présentation des requêtes de pipeline.