Tipi di indici in Cloud Firestore

Gli indici sono un fattore importante per le prestazioni di un database. Proprio come l'indice di un libro che mappa gli argomenti di un libro ai numeri di pagina, un indice di database mappa gli elementi in un database alle loro posizioni nel database. Quando si invia una query a un database, il database può utilizzare un indice per cercare rapidamente le posizioni degli elementi richiesti.

Questa pagina descrive i due tipi di indici utilizzati da Cloud Firestore, indici a campo singolo e indici compositi .

Un indice dietro ogni query

Se non esiste alcun indice per una query, la maggior parte dei database esegue la scansione del contenuto elemento per elemento, un processo lento che rallenta ulteriormente man mano che il database cresce. Cloud Firestore garantisce prestazioni di query elevate utilizzando gli indici per tutte le query. Di conseguenza, le prestazioni della query dipendono dalla dimensione del set di risultati e non dal numero di elementi nel database.

Meno gestione dell'indice, più sviluppo di app

Cloud Firestore include funzionalità che riducono il tempo necessario per la gestione degli indici. Gli indici richiesti per le query di base vengono creati automaticamente per te. Durante l'utilizzo e il test della tua app, Cloud Firestore ti aiuta a identificare e creare gli indici aggiuntivi richiesti dalla tua app.

Tipi di indice

Cloud Firestore utilizza due tipi di indici: campo singolo e composito . Oltre al numero di campi indicizzati, gli indici a campo singolo e compositi differiscono nel modo in cui vengono gestiti.

Indici a campo singolo

Un indice a campo singolo memorizza una mappatura ordinata di tutti i documenti in una raccolta che contengono un campo specifico. Ogni voce in un indice a campo singolo registra il valore di un documento per un campo specifico e la posizione del documento nel database. Cloud Firestore utilizza questi indici per eseguire molte query di base. Puoi gestire gli indici a campo singolo configurando le impostazioni di indicizzazione automatica del database e le esenzioni degli indici.

Indicizzazione automatica

Per impostazione predefinita, Cloud Firestore mantiene automaticamente gli indici a campo singolo per ogni campo in un documento e ogni sottocampo in una mappa. Cloud Firestore utilizza le seguenti impostazioni predefinite per gli indici a campo singolo:

• Per ogni campo non array e non mappa, Cloud Firestore definisce due indici a campo singolo nell'ambito della raccolta , uno in modalità ascendente e uno in modalità discendente.

• Per ogni campo della mappa, Cloud Firestore crea quanto segue:

  • Un indice ascendente dell'ambito di raccolta per ogni sottocampo non di matrice e non di mappa.
  • Un indice decrescente nell'ambito della raccolta per ogni sottocampo non di matrice e non di mappa.
  • Un indice contenente un array nell'ambito della raccolta per ogni sottocampo dell'array.
  • Cloud Firestore indicizza in modo ricorsivo ogni sottocampo della mappa.

• Per ogni campo matrice in un documento, Cloud Firestore crea e gestisce un indice contenente matrice nell'ambito della raccolta.

• Gli indici a campo singolo con ambito del gruppo di raccolta non vengono gestiti per impostazione predefinita.

Esenzioni per indice a campo singolo

Puoi esentare un campo dalle impostazioni di indicizzazione automatica creando un'esenzione dall'indice a campo singolo. Un'esenzione dall'indicizzazione sostituisce le impostazioni dell'indice automatico a livello di database. Un'esenzione può abilitare un indice a campo singolo che le impostazioni di indicizzazione automatica altrimenti disabiliterebbero o disabiliterebbe un indice a campo singolo che l'indicizzazione automatica abiliterebbe altrimenti. Per i casi in cui le esenzioni possono essere utili, consulta le best practice per l'indicizzazione .

Se crei un'esenzione dall'indice a campo singolo per un campo della mappa, i sottocampi della mappa ereditano tali impostazioni. È tuttavia possibile definire esenzioni indice a campo singolo per sottocampi specifici. Se elimini un'esenzione per un sottocampo, il sottocampo erediterà le impostazioni di esenzione del relativo padre, se esistono, o le impostazioni a livello di database se non esistono esenzioni principali.

Per creare e gestire le esenzioni degli indici a campo singolo, consulta Gestione degli indici in Cloud Firestore .

Indici compositi

Un indice composito memorizza una mappatura ordinata di tutti i documenti in una raccolta, basata su un elenco ordinato di campi da indicizzare.

Cloud Firestore utilizza indici compositi per supportare query non già supportate da indici a campo singolo.

Cloud Firestore non crea automaticamente indici compositi come fa per gli indici a campo singolo a causa dell'elevato numero di possibili combinazioni di campi. Al contrario, Cloud Firestore ti aiuta a identificare e creare gli indici compositi richiesti mentre crei la tua app.

Se tenti di eseguire la query sopra senza prima creare l'indice richiesto, Cloud Firestore restituisce un messaggio di errore contenente un link che puoi seguire per creare l'indice mancante. Ciò accade ogni volta che si tenta una query non supportata da un indice. Puoi anche definire e gestire gli indici compositi manualmente utilizzando la console o l' interfaccia a riga di comando di Firebase . Per ulteriori informazioni sulla creazione e la gestione degli indici compositi, vedere Gestione degli indici .

Modalità di indicizzazione e ambiti di query

Gli indici a campo singolo e compositi vengono configurati in modo diverso, ma entrambi richiedono la configurazione delle modalità di indice e degli ambiti di query per gli indici.

Modalità indice

Quando si definisce un indice, si seleziona una modalità di indice per ogni campo indicizzato. La modalità indice di ogni campo supporta clausole di query specifiche su quel campo. È possibile selezionare tra le seguenti modalità di indice:

Ambiti di query

Ogni indice ha come ambito una raccolta o un gruppo di raccolte. Questo è noto come ambito di query dell'indice:

Ambito di raccolta

Cloud Firestore crea indici con ambito di raccolta per impostazione predefinita. Questi indici supportano query che restituiscono risultati da una singola raccolta.

Ambito del gruppo di raccolta

Un gruppo di raccolte include tutte le raccolte con lo stesso ID raccolta. Per eseguire una query del gruppo di raccolta che restituisce risultati filtrati o ordinati da un gruppo di raccolta, è necessario creare un indice corrispondente con ambito del gruppo di raccolta.

Ordinamento predefinito e campo __name__

Oltre a ordinare i documenti in base alle modalità di indice specificate per ciascun campo (ascendente o discendente), gli indici applicano un ordinamento finale in base al campo __name__ di ciascun documento. Il valore del campo __name__ è impostato sul percorso completo del documento. Ciò significa che i documenti nel set di risultati con gli stessi valori di campo vengono ordinati in base al percorso del documento.

Per impostazione predefinita, il campo __name__ è ordinato nella stessa direzione dell'ultimo campo ordinato nella definizione dell'indice. Per esempio:

Per ordinare i risultati in base alla direzione __name__ non predefinita, è necessario creare quell'indice.

Esempio di indicizzazione

Creando automaticamente indici a campo singolo per te, Cloud Firestore consente alla tua applicazione di supportare rapidamente le query di database più basilari. Gli indici a campo singolo consentono di eseguire query semplici basate sui valori dei campi e sui comparatori < , <= , == , >= , > e in . Per i campi dell'array, consentono di eseguire query array-contains e array-contains-any .

Per illustrare, esaminare i seguenti esempi dal punto di vista della creazione dell'indice. Il seguente frammento di codice crea alcuni documenti city in una raccolta cities e imposta i campi name , state , country , capital , population e tags per ciascun documento:

var citiesRef = db.collection("cities");

citiesRef.doc("SF").set({
    name: "San Francisco", state: "CA", country: "USA",
    capital: false, population: 860000,
    regions: ["west_coast", "norcal"] });
citiesRef.doc("LA").set({
    name: "Los Angeles", state: "CA", country: "USA",
    capital: false, population: 3900000,
    regions: ["west_coast", "socal"] });
citiesRef.doc("DC").set({
    name: "Washington, D.C.", state: null, country: "USA",
    capital: true, population: 680000,
    regions: ["east_coast"] });
citiesRef.doc("TOK").set({
    name: "Tokyo", state: null, country: "Japan",
    capital: true, population: 9000000,
    regions: ["kanto", "honshu"] });
citiesRef.doc("BJ").set({
    name: "Beijing", state: null, country: "China",
    capital: true, population: 21500000,
    regions: ["jingjinji", "hebei"] });
test.firestore.js

Assumendo le impostazioni di indicizzazione automatica predefinite, Cloud Firestore aggiorna un indice di campo singolo ascendente per campo non di matrice, un indice di campo singolo discendente per campo non di matrice e un indice di campo singolo contenente matrice per il campo di matrice. Ogni riga nella tabella seguente rappresenta una voce in un indice a campo singolo:

Query supportate da indici a campo singolo

Utilizzando questi indici a campo singolo creati automaticamente, puoi eseguire query semplici come le seguenti:

const stateQuery = citiesRef.where("state", "==", "CA");
const populationQuery = citiesRef.where("population", "<", 100000);
const nameQuery = citiesRef.where("name", ">=", "San Francisco");
test.firestore.js

Puoi anche creare query in e di uguaglianza composta ( == ):

citiesRef.where('country', 'in', ["USA", "Japan", "China"])

// Compound equality queries
citiesRef.where("state", "==", "CO").where("name", "==", "Denver")
citiesRef.where("country", "==", "USA")
         .where("capital", "==", false)
         .where("state", "==", "CA")
         .where("population", "==", 860000)

Se è necessario eseguire una query composta che utilizza un confronto tra intervalli ( < , <= , > o >= ) o se è necessario ordinare in base a un campo diverso, è necessario creare un indice composito per tale query.

L'indice array-contains consente di interrogare il campo dell'array regions :

citiesRef.where("regions", "array-contains", "west_coast")
// array-contains-any and array-contains use the same indexes
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])

Query supportate da indici compositi

Cloud Firestore utilizza indici compositi per supportare query composte non già supportate da indici a campo singolo. Ad esempio, avresti bisogno di un indice composito per le seguenti query:

citiesRef.where("country", "==", "USA").orderBy("population", "asc")
citiesRef.where("country", "==", "USA").where("population", "<", 3800000)
citiesRef.where("country", "==", "USA").where("population", ">", 690000)
// in and == clauses use the same index
citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)

Queste query richiedono l'indice composito riportato di seguito. Poiché la query utilizza un'uguaglianza ( == o in ) per il campo country , è possibile utilizzare una modalità di indice ascendente o discendente per questo campo. Per impostazione predefinita, le clausole di disuguaglianza applicano un ordinamento crescente in base al campo nella clausola di disuguaglianza.

Per eseguire le stesse query ma con un ordinamento decrescente, è necessario un indice composito aggiuntivo in direzione decrescente per la population :

citiesRef.where("country", "==", "USA").orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", "<", 3800000)
         .orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", ">", 690000)
         .orderBy("population", "desc")

citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)
         .orderBy("population", "desc")

È inoltre necessario creare un indice composito per combinare una query array-contains o array-contains-any con clausole aggiuntive.

citiesRef.where("regions", "array-contains", "east_coast")
         .where("capital", "==", true)

// array-contains-any and array-contains use the same index
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])
         .where("capital", "==", true)

Query supportate dagli indici dei gruppi di raccolta

Per dimostrare un indice con ambito di gruppo di raccolta, immagina di aggiungere una sotto-raccolta landmarks ad alcuni dei documenti city :

var citiesRef = db.collection("cities");

citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Bridge",
    category : "bridge" });
citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Park",
    category : "park" });

citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Gallery of Art",
    category : "museum" });
citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Mall",
    category : "park" });

Utilizzando il seguente indice a campo singolo con ambito di raccolta, puoi eseguire query sulla raccolta di landmarks di una singola città in base al campo category :

citiesRef.doc("SF").collection("landmarks").where("category", "==", "park")
citiesRef.doc("SF").collection("landmarks").where("category", "in", ["park", "museum"])

Ora, immagina di essere interessato a interrogare i punti di riferimento in tutte le città. Per eseguire questa query sul gruppo di raccolta costituito da tutte le raccolte landmarks , è necessario abilitare un indice a campo singolo landmarks con ambito del gruppo di raccolta:

Con questo indice abilitato, puoi interrogare il gruppo di raccolta landmarks :

var landmarksGroupRef = db.collectionGroup("landmarks");

landmarksGroupRef.where("category", "==", "park")
landmarksGroupRef.where("category", "in", ["park", "museum"])

Per eseguire una query del gruppo di raccolta che restituisce risultati filtrati o ordinati, è necessario abilitare un indice composto o a campo singolo corrispondente con ambito del gruppo di raccolta. Le query del gruppo di raccolte che non filtrano o ordinano i risultati, tuttavia, non richiedono ulteriori definizioni di indice.

Ad esempio, puoi eseguire la seguente query del gruppo di raccolta senza abilitare un indice aggiuntivo:

db.collectionGroup("landmarks").get()

Voci di indice

Gli indici configurati del tuo progetto e la struttura di un documento determinano il numero di voci di indice per un documento. Le voci dell'indice vengono conteggiate ai fini del limite di conteggio delle voci dell'indice .

L'esempio seguente mostra le voci di indice di un documento.

Documento

/cities/SF

city_name : "San Francisco"
temperatures : {summer: 67, winter: 55}
neighborhoods : ["Mission", "Downtown", "Marina"]

Indici a campo singolo

• nome_città ASC
• nome_città DESC
• temperature.estate ASC
• temperature.estate DESC
• temperature.inverno ASC
• temperature.inverno DESC
• quartieri Array Contiene (ASC e DESC)

Indici compositi

• nome_città ASC, quartieri ARRAY
• nome_città DESC, quartieri ARRAY

Voci di indice

Questa configurazione di indicizzazione comporta le seguenti 18 voci di indice per il documento:

Indici e prezzi

Gli indici contribuiscono ai costi di archiviazione dell'applicazione. Per ulteriori informazioni su come viene calcolata la dimensione di archiviazione per gli indici, vedere Dimensione voce indice .

Sfruttare l'unione degli indici

Sebbene Cloud Firestore utilizzi un indice per ogni query, non richiede necessariamente un indice per query. Per le query con più clausole di uguaglianza ( == ) e, facoltativamente, una clausola orderBy , Cloud Firestore può riutilizzare gli indici esistenti. Cloud Firestore può unire gli indici per semplici filtri di uguaglianza per creare gli indici compositi necessari per query di uguaglianza più grandi.

È possibile ridurre i costi di indicizzazione identificando le situazioni in cui è possibile trarre vantaggio dall'unione degli indici. Ad esempio, immagina una raccolta restaurants per un'app di valutazione dei ristoranti:

• collections_bookmark ristoranti

  • hamburger class

    name : "Burger Thyme"
category : "burgers"
city : "San Francisco"
editors_pick : true
star_rating : 4
    

Ora, immagina che questa app utilizzi query come quelle qui sotto. Si noti che l'app utilizza combinazioni di clausole di uguaglianza per category , city e editors_pick ordinando sempre per star_rating crescente :

db.collection("restaurants").where("category", "==", "burgers")
                            .orderBy("star_rating")

db.collection("restaurants").where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==" "San Francisco")
                            .where("editors_pick", "==", true )
                            .orderBy("star_rating")

Potresti creare un indice per ogni query:

Come soluzione migliore, puoi ridurre il numero di indici sfruttando la capacità di Cloud Firestore di unire gli indici per le clausole di uguaglianza:

Non solo questo insieme di indici è più piccolo, ma supporta anche una query aggiuntiva:

db.collection("restaurants").where("editors_pick", "==", true)
                            .orderBy("star_rating")

Limiti di indicizzazione

I seguenti limiti si applicano agli indici. Per tutte le quote e i limiti, vedere Quote e limiti .

Best practice per l'indicizzazione

Per la maggior parte delle app, puoi fare affidamento sull'indicizzazione automatica e sui collegamenti ai messaggi di errore per gestire i tuoi indici. Tuttavia, potresti voler aggiungere esenzioni a campo singolo nei seguenti casi:

Per ulteriori informazioni su come risolvere i problemi di indicizzazione (fanout dell'indice, errori INVALID_ARGUMENT ), consulta la pagina di risoluzione dei problemi .