Riferimento per le funzioni di array

Riferimento per le funzioni di array

Anteprima — Firestore in modalità Native (con operazioni della pipeline) per Enterprise Edition

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Puoi trattare i dati personali per questa funzionalità come indicato nell'Addendum per il trattamento dei dati Cloud, fatti salvi gli obblighi e le restrizioni all'interno dell'accordo che regola l'accesso a Google Cloud. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Funzioni di array

Nome	Descrizione
ARRAY	Restituisce un ARRAY contenente un elemento per ogni argomento di input
ARRAY_CONCAT	Concatena più array in un unico ARRAY
ARRAY_CONTAINS	Restituisce TRUE se un determinato ARRAY contiene un valore specifico
ARRAY_CONTAINS_ALL	Restituisce TRUE se tutti i valori sono presenti in ARRAY
ARRAY_CONTAINS_ANY	Restituisce TRUE se uno dei valori è presente in ARRAY
ARRAY_FILTER	Filtra gli elementi di un ARRAY che non soddisfano un predicato
ARRAY_FIRST	Restituisce il primo elemento di un ARRAY
ARRAY_FIRST_N	Restituisce i primi n elementi di un ARRAY
ARRAY_GET	Restituisce l'elemento in un determinato indice di un ARRAY
ARRAY_INDEX_OF	Restituisce l'indice della prima occorrenza di un valore in un ARRAY
ARRAY_INDEX_OF_ALL	Restituisce tutti gli indici di un valore in un ARRAY
ARRAY_LENGTH	Restituisce il numero di elementi in un ARRAY
ARRAY_LAST	Restituisce l'ultimo elemento di un ARRAY
ARRAY_LAST_N	Restituisce gli ultimi n elementi di un ARRAY
ARRAY_REVERSE	Inverte l'ordine degli elementi in un ARRAY
ARRAY_SLICE	Restituisce una sezione di un ARRAY
ARRAY_TRANSFORM	Trasforma gli elementi in un ARRAY applicando l'espressione a ogni elemento
MAXIMUM	Restituisce il valore massimo in un ARRAY
MAXIMUM_N	Restituisce i n valori più grandi in un ARRAY
MINIMUM	Restituisce il valore minimo in un ARRAY
MINIMUM_N	Restituisce i n valori più piccoli in un ARRAY
SUM	Restituisce la somma di tutti i valori NUMERIC in un ARRAY.
JOIN	Produce una concatenazione degli elementi in un ARRAY come valore STRING.

ARRAY

Sintassi:

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

Descrizione:

Costruisce un array dagli elementi specificati.

• Se un argomento non esiste, viene sostituito con NULL nell'array risultante.

Esempi:

valori	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

Sintassi:

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

Descrizione:

Concatena due o più array in un unico ARRAY.

Esempi:

array	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

Sintassi:

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

Descrizione:

Restituisce TRUE se value viene trovato in array, altrimenti restituisce FALSE.

Esempi:

matrice	valore	array_contains(array, value)
[1, 2, 3]	2	true
[[1, 2], [3]]	[1, 2]	true
[1, null]	null	true
"abc"	QUALSIASI	errore

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

Sintassi:

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

Descrizione:

Restituisce TRUE se tutti i search_values si trovano in array, altrimenti restituisce FALSE.

Esempi:

matrice	search_values	array_contains_all(array, search_values)
[1, 2, 3]	[1, 2]	true
[1, 2, 3]	[1, 4]	falso
[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();
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

Sintassi:

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

Descrizione:

Restituisce TRUE se uno qualsiasi dei search_values viene trovato in array, altrimenti restituisce FALSE.

Esempi:

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

Sintassi:

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

Descrizione:

Filtra array utilizzando un'espressione predicate, restituendo un nuovo array con solo gli elementi che soddisfano il predicato.

• Per ogni elemento in array, viene valutato predicate. Se restituisce true, l'elemento è incluso nel risultato; altrimenti (se restituisce false o null), viene omesso.
• Se predicate restituisce un valore non booleano o non nullo, la funzione restituisce un errore.

Esempi:

matrice	predicato	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

Sintassi:

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

Descrizione:

Restituisce l'elemento in corrispondenza dell'indice index basato su 0 in array.

• Se index è negativo, gli elementi vengono accessibili dalla fine dell'array, dove -1 è l'ultimo elemento.
• Se array non è di tipo ARRAY e non è null, restituisce un errore.
• Se index non rientra nei limiti, la funzione restituisce un valore assente.
• Se index non è di tipo INT64, la funzione restituisce un errore.

Esempi:

matrice	indice	array_get(array, index)
[1, 2, 3]	0	1
[1, 2, 3]	-1	3
[1, 2, 3]	3	assente
[1, 2, 3]	-4	assente
"abc"	0	errore
null	0	null
Array	"a"	errore
Array	2.0	errore

ARRAY_LENGTH

Sintassi:

array_length(array: ARRAY) -> INT64

Descrizione:

Restituisce il numero di elementi in array.

Esempi:

matrice	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

Sintassi:

array_reverse(array: ARRAY) -> ARRAY

Descrizione:

Inverte il array specificato.

Esempi:

matrice	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

Sintassi:

array_first(array: ARRAY) -> ANY

Descrizione:

Restituisce il primo elemento di array. Equivale a array_get(array, 0).

• Se array è vuoto, restituisce un valore assente.

Esempi:

matrice	array_first(array)
[1, 2, 3]	1
[]	assente

ARRAY_FIRST_N

Sintassi:

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

Descrizione:

Restituisce i primi n elementi di array. Equivale a array_slice(array, 0, n).

• Se n è negativo, restituisce un errore.

Esempi:

matrice	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

Sintassi:

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

Descrizione:

Restituisce l'indice a base 0 della prima occorrenza di value in array. Restituisce -1 se value non viene trovato.

Esempi:

matrice	valore	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

Sintassi:

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

Descrizione:

Restituisce un array contenente gli indici in base zero di tutte le occorrenze di value in array. Restituisce [] se value non viene trovato.

Esempi:

matrice	valore	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

Sintassi:

array_last(array: ARRAY) -> ANY

Descrizione:

Restituisce l'ultimo elemento di array. Equivale a array_get(array, -1).

• Se array è vuoto, restituisce un valore assente.

Esempi:

matrice	array_last(array)
[1, 2, 3]	3
[]	assente

ARRAY_LAST_N

Sintassi:

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

Descrizione:

Restituisce gli ultimi n elementi di array.

• Se n è negativo, restituisce un errore.

Esempi:

matrice	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

Sintassi:

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

Descrizione:

Restituisce un sottoinsieme di array a partire dall'indice in base zero offset e includendo length elementi.

• Se offset è negativo, indica la posizione iniziale dalla fine dell'array, con -1 che è l'ultimo elemento.
• Se length è maggiore del numero di elementi rimanenti nell'array dopo offset, il risultato si estende fino alla fine dell'array.
• length non deve essere un valore negativo, altrimenti viene restituito un errore.

Esempi:

matrice	offset	lunghezza	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

Sintassi:

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

Descrizione:

Trasforma array applicando expression a ogni elemento, restituendo un nuovo array con gli elementi trasformati. L'array di output avrà sempre le stesse dimensioni dell'array di input.

• expression può essere una funzione unaria element -> result o una funzione binaria (element, index) -> result.
• Se expression è unario, viene chiamato con ogni elemento di array.
• Se expression è binaria, viene chiamata con ogni elemento di array e il relativo indice in base 0.

Esempi:

matrice	espressione	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	[]

MASSIMO

Sintassi:

maximum(array: ARRAY) -> ANY

Descrizione:

Restituisce il valore massimo in array.

• I valori NULL vengono ignorati durante il confronto.
• Se array è vuoto o contiene solo valori NULL, restituisce NULL.

Esempi:

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

MAXIMUM_N

Sintassi:

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

Descrizione:

Restituisce un array dei n valori più grandi in array in ordine decrescente.

• I valori NULL vengono ignorati.
• Se n è negativo, restituisce un errore.

Esempi:

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

MINIMO

Sintassi:

minimum(array: ARRAY) -> ANY

Descrizione:

Restituisce il valore minimo in array.

• I valori NULL vengono ignorati durante il confronto.
• Se array è vuoto o contiene solo valori NULL, restituisce NULL.

Esempi:

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

MINIMUM_N

Sintassi:

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

Descrizione:

Restituisce un array dei n valori più piccoli in array in ordine crescente.

• I valori NULL vengono ignorati.
• Se n è negativo, restituisce un errore.

Esempi:

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

SUM

Sintassi:

sum(array: ARRAY) -> INT64 | FLOAT64

Descrizione:

Restituisce la somma di tutti i valori NUMERIC in un ARRAY.

• I valori non numerici nell'array vengono ignorati.
• Se un valore numerico nell'array è NaN, la funzione restituisce NaN.
• Il tipo restituito è determinato dal tipo numerico più ampio nell'array: INT64 < FLOAT64.
• Se si verifica un overflow di numeri interi a 64 bit prima che venga sommato un valore in virgola mobile, viene restituito un errore. Se vengono sommati valori in virgola mobile, l'overflow genererà +/- infinito.
• Se l'array non contiene valori numerici, la funzione restituisce NULL.

Esempi:

matrice	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]	errore
[INT64.MAX_VALUE, 1, -1.0]	errore
[INT64.MAX_VALUE, 1.0]	9,223372036854776e+18

JOIN

Sintassi:

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

Descrizione:

Restituisce una concatenazione degli elementi in array come STRING. array può essere di tipo STRING o BYTES.

• Tutti gli elementi in array, delimiter e null_text devono essere dello stesso tipo: devono essere tutti STRING o tutti BYTES.
• Se viene fornito null_text, tutti i valori NULL in array vengono sostituiti con null_text.
• Se null_text non viene fornito, i valori NULL in array vengono omessi dal risultato.

Esempi:

Quando null_text non viene fornito:

matrice	delimitatore	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']	","	errore
["a", "c"]	b','	errore
[b'a', b'c']	","	errore

Quando viene fornito null_text:

matrice	delimitatore	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'	errore
[b'a', null]	b','	"N"	errore

Passaggi successivi

• Consulta la panoramica delle query della pipeline