Tipi di indice in Cloud Firestore

Gli indici sono un fattore importante per le prestazioni di un database. Proprio come l'indice di un libro mappa gli argomenti di un libro ai numeri di pagina, un indice di database mappa gli elementi di un database alle loro posizioni nel database. Quando esegui una query su un database, quest'ultimo può utilizzare un indice per identificare rapidamente le posizioni degli elementi richiesti.

In questa pagina vengono descritti i due tipi di indici utilizzati da Cloud Firestore: indici automatici e indici manuali.

Definizione e struttura dell'indice

Un indice viene definito su un elenco di campi di un determinato documento, con una modalità di indicizzazione corrispondente per ogni campo.

Un indice contiene una voce per ogni campo denominato nella definizione dell'indice. L'indice include tutti i documenti che sono i potenziali risultati per le query basate sull'indice. Un documento viene incluso nell'indice solo se ha un valore indicizzato impostato per ogni campo utilizzato nell'indice. Se la definizione dell'indice fa riferimento a un campo per il quale il documento non ha un valore impostato, il documento non verrà visualizzato nell'indice. In questo caso, il documento non verrà mai restituito come risultato per nessuna query basata sull'indice.

L'indice è ordinato in base ai valori dei campi, nell'ordine specificato nella definizione dell'indice.

Un indice per ogni query

Se non esiste un indice per una query, la maggior parte dei database esegue la scansione dei contenuti elemento per elemento, un processo lento che rallenta ancora di più man mano che il database cresce. Cloud Firestore contribuisce a fornire prestazioni di query elevate utilizzando gli indici per tutte le query. Di conseguenza, le prestazioni delle query dipendono dalle dimensioni del set di risultati e non dal numero di elementi nel database.

Meno gestione degli indici, più sviluppo di app

Cloud Firestore include funzionalità che riducono il tempo che devi dedicare alla gestione degli indici. Gli indici necessari per le query più semplici vengono creati automaticamente. Mentre utilizzi e testi la tua app, Cloud Firestore ti aiuta a identificare e creare indici aggiuntivi richiesti dalla tua app.

Tipi di indice

Cloud Firestore utilizza due tipi di indici: automatici e manuali. Gli indici manuali e automatici differiscono per il modo in cui li gestisci.

Indici automatici

Per impostazione predefinita, Cloud Firestore crea automaticamente gli indici per ogni campo presente nei documenti di una raccolta. Questi indici a campo singolo ti consentono di eseguire molte query di base. Puoi gestire gli indici automatici configurando le impostazioni di indicizzazione automatica e le esenzioni degli indici del database.

Impostazioni predefinite degli indici automatici

Cloud Firestore utilizza le seguenti impostazioni predefinite per gli indici automatici:

• Per ogni campo non array e non mappa, Cloud Firestore definisce due indici con ambito raccolta, uno in modalità crescente e uno in modalità decrescente.

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

  • Un indice ascendente con ambito raccolta per ogni sottocampo non array e non mappa.
  • Un indice decrescente con ambito raccolta per ogni sottocampo non array e non mappa.
  • Un indice ascendente con ambito raccolta per l'intero valore della mappa
  • Un indice decrescente con ambito raccolta per l'intero valore della mappa
  • Un indice array-contains con ambito raccolta per ogni sottocampo dell'array.
  • Cloud Firestore indicizza in modo ricorsivo ogni sottocampo della mappa.

• Per ogni campo di array in un documento, Cloud Firestore crea quanto segue:

  • Un indice ascendente con ambito raccolta per l'intero valore dell'array
  • Un indice decrescente con ambito raccolta per l'intero valore dell'array
  • Un indice array-contains con ambito della raccolta.

• Gli indici automatici con ambito del gruppo di raccolte non vengono gestiti per impostazione predefinita.

Esenzioni degli indici automatici

Puoi esentare un campo dalle impostazioni di indicizzazione automatica creando un'esenzione dall'indicizzazione. Un'esenzione dell'indicizzazione esegue l'override delle impostazioni dell'indice automatico a livello di database. Un'esenzione può abilitare un indice che altrimenti verrebbe disabilitato dalle impostazioni dell'indicizzazione automatica oppure può disabilitare un indice che altrimenti verrebbe abilitato dall'indicizzazione automatica. Per i casi in cui le esenzioni possono essere utili, consulta le best practice per l'indicizzazione.

Utilizza il valore del percorso del campo * per aggiungere esenzioni dagli indici a livello di raccolta su tutti i campi di un gruppo di raccolte. Ad esempio, per il gruppo di raccolte comments, imposta il percorso del campo su * in modo che corrisponda a tutti i campi del gruppo di raccolte comments e disattiva l'indicizzazione di tutti i campi del gruppo di raccolte. Puoi quindi aggiungere eccezioni per indicizzare solo i campi richiesti per le tue query. La riduzione del numero di campi indicizzati riduce i costi di archiviazione e può migliorare le prestazioni di scrittura.

Se crei un'esenzione dall'indice per un campo mappa, i campi secondari della mappa ereditano queste impostazioni. Tuttavia, puoi definire esenzioni dall'indice per sottocampi specifici. Se elimini un'esenzione per un sottocampo, quest'ultimo erediterà le impostazioni di esenzione del campo principale, se presenti, o le impostazioni a livello di database se non esistono esenzioni principali.

Per creare e gestire le esenzioni degli indici automatici, consulta Gestisci gli indici.

Indici manuali

Un indice manuale archivia un mapping ordinato di tutti i documenti di una raccolta, in base a un elenco ordinato di campi da indicizzare.

Cloud Firestore utilizza indici manuali per supportare query non ancora supportate dagli indici automatici.

Per impostazione predefinita, Cloud Firestore crea automaticamente indici a campo singolo per ogni campo presente all'interno di una raccolta. Cloud Firestore non crea automaticamente indici per le combinazioni di campi a causa dell'elevato numero di combinazioni di campi possibili. Invece, Cloud Firestore ti aiuta a identificare e creare gli indici richiesti durante la creazione dell'app.

Ogni volta che tenti una query non supportata da un indice esistente, Cloud Firestore restituisce un messaggio di errore con un link che puoi seguire per creare l'indice mancante.

Puoi anche definire e gestire gli indici manualmente utilizzando la console o l'interfaccia a riga di comando di Firebase. Per saperne di più sulla creazione e sulla gestione degli indici manuali, consulta Gestisci gli indici.

Modalità di indicizzazione e ambiti di query

Gli indici automatici e manuali vengono configurati in modo diverso, ma entrambi richiedono la configurazione delle modalità di indicizzazione e degli ambiti di query per gli indici.

Modalità indice

Quando definisci un indice, selezioni una modalità di indicizzazione per ogni campo indicizzato. La modalità di indicizzazione di ogni campo supporta clausole di query specifiche su quel campo. Puoi selezionare una delle seguenti modalità di indicizzazione:

Ambiti di query

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

Ambito della raccolta

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

Ambito del gruppo di raccolte

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

Ordine predefinito e campo __name__

Oltre a ordinare i documenti in base alle modalità di indicizzazione specificate per ogni campo (crescente o decrescente) , gli indici applicano un ordinamento finale in base al campo __name__ di ogni 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__ viene ordinato nella stessa direzione dell'ultimo campo ordinato nella definizione dell'indice. Ad esempio:

Per ordinare i risultati in base alla direzione __name__ non predefinita, devi creare l'indice.

Proprietà dell'indice

Un indice che consente di eseguire la query nel modo più efficiente è definito dalle seguenti proprietà:

• Campi utilizzati nei filtri di uguaglianza
• Campi utilizzati negli ordinamenti
• Campi utilizzati nei filtri di intervallo e disuguaglianza (non già inclusi negli ordinamenti)
• Campi utilizzati nelle aggregazioni (che non sono già inclusi negli ordinamenti e nei filtri di intervallo e disuguaglianza)

Cloud Firestore calcola i risultati delle query nel seguente modo:

1. Identifica l'indice corrispondente alla raccolta, alle proprietà di filtro, agli operatori di filtro e agli ordinamenti della query.
2. Identifica la posizione dell'indice da cui inizia la scansione. La posizione iniziale è preceduta dai filtri di uguaglianza della query e termina con i filtri di intervallo e disuguaglianza sul primo campo orderBy.
3. Inizia la scansione dell'indice, restituendo ogni documento che soddisfa tutti i filtri, finché il processo di scansione non esegue una delle seguenti operazioni:
   • Incontra un documento che non soddisfa le condizioni di filtro e conferma che nessun documento successivo soddisferà mai completamente le condizioni di filtro.
   • Raggiunge la fine dell'indice.
   • Raccoglie il numero massimo di risultati richiesti dalla query.

Esempio di indicizzazione

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

Per illustrare questo concetto, esamina i seguenti esempi dal punto di vista della creazione degli indici. Il seguente snippet crea alcuni documenti city in una raccolta cities e imposta i campi name, state, country, capital, population e regions per ogni 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

Supponendo che siano attive le impostazioni di indicizzazione automatica predefinite, Cloud Firestore aggiorna un indice a campo singolo crescente per campo, un indice a campo singolo decrescente per campo e un indice a campo singolo array-contains per il campo dell'array. Ogni riga della tabella seguente rappresenta una voce in un indice a campo singolo:

Query supportate dagli 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 devi eseguire una query composta che utilizza un confronto di intervalli (<, <=, > o >=) o se devi ordinare in base a un campo diverso, devi creare un indice manuale per la query.

L'indice array-contains ti consente di eseguire query sul campo 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 dagli indici manuali

Crea indici manuali per supportare le query composte non ancora supportate dagli indici automatici a campo singolo. Ad esempio, avresti bisogno di un indice manuale 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 il seguente indice. Poiché la query utilizza un'uguaglianza (== o in) per il campo country, puoi utilizzare una modalità di indicizzazione crescente o decrescente 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, devi avere un indice aggiuntivo in direzione decrescente per 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")

Per evitare la perdita di prestazioni causata dall'unione degli indici, ti consigliamo di creare un indice 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 raccolte

Per mostrare un indice con ambito del gruppo di raccolte, aggiungi una sottoraccolta 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 della raccolta, puoi eseguire query sulla raccolta 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"])

Se vuoi eseguire una query sui punti di riferimento in tutte le città, ad esempio, esegui questa query sul gruppo di raccolte composto da tutte le raccolte landmarks. Devi anche abilitare un indice a campo singolo landmarks con ambito del gruppo di raccolte:

Con questo indice abilitato, puoi eseguire query sul gruppo di raccolte landmarks:

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

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

Per eseguire una query su un gruppo di raccolte che restituisce risultati filtrati o ordinati, devi attivare un indice corrispondente con ambito del gruppo di raccolte. Tuttavia, le query sui gruppi di raccolte che non filtrano o ordinano i risultati non richiedono definizioni di indici aggiuntive.

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

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

Voci di indice

Gli indici configurati del 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 del numero di voci dell'indice.

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

Documento

/cities/SF

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

Indici automatici

• city_name ASC
• city_name DESC
• neighborhoods ASC
• neighborhoods DESC
• temperatures ASC
• temperatures DESC
• temperatures.summer ASC
• temperatures.summer DESC
• temperatures.winter ASC
• temperatures.winter DESC
• neighborhoods Array Contains

Indici manuali

• city_name ASC, neighborhoods ARRAY
• city_name DESC, neighborhoods ARRAY

Voci di indice

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

Indici e prezzi

Gli indici contribuiscono ai costi di archiviazione della tua applicazione. Per saperne di più su come calcolare le dimensioni di archiviazione per gli indici, consulta Dimensioni delle voci di indice.

Utilizza 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 filtri di uguaglianza semplici per creare gli indici necessari per query di uguaglianza più grandi.

Puoi ridurre i costi di indicizzazione identificando le situazioni in cui puoi utilizzare l'unione degli indici. Ad esempio, in una raccolta restaurants per un'app di valutazione dei ristoranti:

• collections_bookmark ristoranti

  • class burgerthyme

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

Questa app utilizza query come le seguenti. L'app utilizza combinazioni di clausole di uguaglianza per category, city e editors_pick, ordinando sempre in base a star_rating in ordine 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")

Puoi creare un indice per ogni query:

Una soluzione migliore consiste nel ridurre il numero di indici sfruttando la capacità di Cloud Firestore di unire gli indici per le clausole di uguaglianza:

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

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

Limiti di indicizzazione

Agli indici si applicano i seguenti limiti. Per saperne di più su quote e limiti, consulta Quote e limiti.

Best practice per l'indicizzazione

Per la maggior parte delle app, puoi fare affidamento sull'indicizzazione automatica e sui link dei messaggi di errore per gestire gli indici. Tuttavia, potresti voler aggiungere esenzioni per l'indicizzazione automatica nei seguenti casi:

Se utilizzi query con operatori di intervallo e disuguaglianza su più campi, consulta le considerazioni sull'indicizzazione da tenere presenti per ottimizzare le prestazioni e il costo delle query Cloud Firestore.

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