Cloud Firestore garantisce le prestazioni delle query richiedendo un indice per ogni query. Gli indici richiesti per le query più semplici vengono creati automaticamente per te. Mentre utilizzi e testi l'app, Cloud Firestore genera messaggi di errore che ti aiutano a creare ulteriori indici richiesti dall'app. Questa pagina descrive come gestire gli indici a campo singolo e composti.
Crea un indice mancante tramite un messaggio di errore
Se tenti di eseguire una query composta con una clausola Range che non è mappata a un indice esistente, ricevi un errore. Il messaggio di errore include un link diretto per creare l'indice mancante nella console Firebase.
Segui il link generato alla console Firebase, controlla le informazioni compilate automaticamente e fai clic su Crea.
Ruoli e autorizzazioni
Prima di poter creare un indice in Cloud Firestore, assicurati che ti siano stati assegnati uno dei seguenti ruoli:
roles/datastore.ownerroles/datastore.indexAdminroles/editorroles/owner
Se hai definito ruoli personalizzati, assegna tutte le seguenti autorizzazioni per creare gli indici:
datastore.indexes.createdatastore.indexes.deletedatastore.indexes.getdatastore.indexes.listdatastore.indexes.update
Utilizzare la console Firebase
Per creare manualmente un nuovo indice dalla console Firebase:
- Vai alla sezione Cloud Firestore della console di Firebase.
- Vai alla scheda Indici e fai clic su Aggiungi indice.
- Inserisci il nome della raccolta e imposta i campi in base ai quali vuoi ordinare l'indice.
- Fai clic su Crea.
I campi indice devono essere conformi ai vincoli sui percorsi dei campi.
La creazione degli indici può richiedere alcuni minuti, a seconda delle dimensioni della query. Dopo averli creati, puoi visualizzare gli indici e il relativo stato nella sezione Indici composti. Se sono ancora in fase di compilazione, la console Firebase include una barra di stato della compilazione.
Rimuovere gli indici
Per eliminare un indice:
- Vai alla sezione Cloud Firestore della console di Firebase.
- Fai clic sulla scheda Indici.
- Passa il mouse sopra l'indice che vuoi eliminare e seleziona Elimina dal menu contestuale.
- Conferma di volerlo eliminare facendo clic su Elimina nell'avviso.
Utilizza l'interfaccia a riga di comando di Firebase
Puoi anche eseguire il deployment degli indici con l'interfaccia a riga di comando di Firebase.
Per iniziare, esegui firebase init firestore nella directory del progetto.
Durante la configurazione, Firebase CLI genera un file JSON con gli indici predefiniti nel formato corretto. Modifica il file per aggiungere altri indici e esegui il deployment con il comando firebase deploy.
Per eseguire il deployment solo di indici e regole Cloud Firestore, aggiungi il
--only firestore flag.
Se apporti modifiche agli indici utilizzando la console Firebase, assicurati di aggiornare anche il file degli indici locali. Fai riferimento al riferimento alla definizione dell'indice JSON.
Utilizza Terraform
crea gli indici nel database
I database Cloud Firestore possono includere indici a campo singolo e composti. Puoi modificare il file di configurazione Terraform per creare un indice per il tuo database. Gli indici a campo singolo e composti utilizzano tipi di risorse Terraform distinti.
Indice a campo singolo
Il seguente file di configurazione Terraform di esempio crea un indice a campo singolo nel campo name nella raccolta chatrooms:
firestore.tf
resource "random_id" "variable"{
byte_length = 8
}
resource "google_firestore_field" "single-index" {
project = "project-id"
database = "database-id"
collection = "chatrooms_${random_id.variable.hex}"
field = "name"
index_config {
indexes {
order = "ASCENDING"
query_scope = "COLLECTION_GROUP"
}
indexes {
array_config = "CONTAINS"
}
}
ttl_config {}
}
- Sostituisci project-id con l'ID progetto. Gli ID progetto devono essere univoci.
- Sostituisci database-id con l'ID del tuo database.
Indice composto
Il seguente esempio di file di configurazione Terraform crea un indice composto per una combinazione del campo name e del campo description nella raccolta chatrooms:
firestore.tf
resource "google_firestore_index" "composite-index" {
project = "project-id"
database = "database-id"
collection = "chatrooms"
fields {
field_path = "name"
order = "ASCENDING"
}
fields {
field_path = "description"
order = "DESCENDING"
}
}
- Sostituisci project-id con l'ID progetto. Gli ID progetto devono essere univoci.
- Sostituisci database-id con l'ID del tuo database.
Ora di creazione indice
Per creare un indice, Cloud Firestore deve configurare l'indice e quindi eseguire il backfill dell'indice con i dati esistenti. Il tempo di creazione dell'indice è la somma del tempo di configurazione e di quello di backfill:
La configurazione di un indice richiede alcuni minuti. Il tempo di compilazione minimo per un indice è di alcuni minuti, anche per un database vuoto.
Il tempo necessario per il backfill dipende dalla quantità di dati esistenti appartenenti al nuovo indice. Maggiore è il numero di valori dei campi che corrispondono alla definizione dell'indice, maggiore è il tempo necessario per il backfill dell'indice.
Le build degli indici sono operazioni a lunga esecuzione.
Dopo aver avviato la creazione di un indice, Cloud Firestore assegna all'operazione un nome univoco. I nomi delle operazioni sono preceduti da projects/[PROJECT_ID]/databases/(default)/operations/,
ad esempio:
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
Tuttavia, puoi omettere il prefisso quando specifichi il nome di un'operazione per il comando describe.
Elenco di tutte le operazioni a lunga esecuzione
Per elencare le operazioni a lunga esecuzione, utilizza il comando gcloud firestore operations list. Questo comando elenca le operazioni in corso e completate di recente. Le operazioni vengono elencate per alcuni giorni dopo il completamento:
gcloud firestore operations list
Controlla lo stato dell'operazione
Anziché elencare tutte le operazioni a lunga esecuzione, puoi elencare i dettagli di una singola operazione:
gcloud firestore operations describe operation-name
Stima del tempo di completamento
Durante l'esecuzione dell'operazione, controlla il valore del campo state per lo stato complessivo dell'operazione.
Una richiesta per lo stato di un'operazione a lunga esecuzione restituisce anche le metriche workEstimated e workCompleted. Queste metriche vengono restituite
per il numero di documenti. workEstimated mostra il numero totale stimato di documenti elaborati da un'operazione. workCompleted
mostra il numero di documenti elaborati finora. Al termine dell'operazione, workCompleted riflette il numero totale di documenti che sono stati effettivamente elaborati, che potrebbe essere diverso dal valore di workEstimated.
Dividi workCompleted per workEstimated per ottenere una stima approssimativa. L' stima potrebbe non essere precisa perché dipende dalla raccolta delle statistiche con ritardo.
Ad esempio, ecco lo stato di avanzamento di una build dell'indice:
{
"operations": [
{
"name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI",
"metadata": {
"@type": "type.googleapis.com/google.firestore.admin.v1.IndexOperationMetadata",
"common": {
"operationType": "CREATE_INDEX",
"startTime": "2020-06-23T16:52:25.697539Z",
"state": "PROCESSING"
},
"progressDocuments": {
"workCompleted": "219327",
"workEstimated": "2198182"
}
},
},
...
Al termine di un'operazione, la relativa descrizione conterrà "done":
true. Vedi il valore del campo state per
il risultato dell'operazione. Se il campo done non è impostato nella risposta, il suo valore è false. Non dipendono dall'esistenza del valore done
per le operazioni in corso.
Errori di creazione degli indici
Potresti riscontrare errori di creazione dell'indice durante la gestione degli indici compositi e delle esenzioni per gli indici a un campo. Un'operazione di indicizzazione può non riuscire se Cloud Firestore riscontra un problema con i dati che sta indicizzando. In genere, significa che hai raggiunto un limite di indicizzazione. Ad esempio, l'operazione potrebbe aver raggiunto il numero massimo di voci dell'indice per documento.
Se la creazione dell'indice non riesce, nella console viene visualizzato il messaggio di errore. Dopo aver verificato che non stai raggiungendo i limiti dell'indice, riprova a eseguire l'operazione di indicizzazione.