Cloud Firestore garantisce le prestazioni delle query richiedendo un indice per ogni query. Gli indici richiesti per le query più elementari vengono creati automaticamente per te. Mentre utilizzi e testi la tua app, Cloud Firestore genera messaggi di errore che ti aiutano a creare gli indici aggiuntivi richiesti dalla tua app. Questa pagina descrive come gestire gli indici a campo singolo e compositi .
Crea un indice mancante tramite un messaggio di errore
Se tenti di eseguire una query composta con una clausola di intervallo che non è mappata a un indice esistente, ricevi un errore. Il messaggio di errore include un collegamento diretto per creare l'indice mancante nella console Firebase.
Segui il collegamento generato alla console Firebase, esamina le informazioni popolate automaticamente e fai clic su Crea .
Ruoli e autorizzazioni
Prima di poter creare un indice in Cloud Firestore, assicurati che ti sia assegnato uno dei seguenti ruoli:
-
roles/datastore.owner -
roles/datastore.indexAdmin -
roles/editor -
roles/owner
Se hai definito ruoli personalizzati, assegna tutte le seguenti autorizzazioni per creare indici:
-
datastore.indexes.create -
datastore.indexes.delete -
datastore.indexes.get -
datastore.indexes.list -
datastore.indexes.update
Utilizza la console Firebase
Per creare manualmente un nuovo indice dalla console Firebase:
- Vai alla sezione Cloud Firestore della console Firebase .
- Vai alla scheda Indici e fai clic su Aggiungi indice .
- Inserisci il nome della raccolta e imposta i campi in base ai quali desideri ordinare l'indice.
- Fare 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 vedere i tuoi indici e il loro stato nella sezione Indici compositi. Se stanno ancora costruendo, la console Firebase include una barra di stato della costruzione.
Rimuovere gli indici
Per eliminare un indice:
- Vai alla sezione Cloud Firestore della console Firebase .
- Fare clic sulla scheda Indici .
- Passa il mouse sopra l'indice che desideri eliminare e seleziona Elimina dal menu contestuale.
- Conferma di volerlo eliminare facendo clic su Elimina dall'avviso.
Utilizza la CLI di Firebase
Puoi anche distribuire gli indici con la CLI Firebase . Per iniziare, esegui firebase init firestore nella directory del tuo progetto. Durante la configurazione, la CLI Firebase genera un file JSON con gli indici predefiniti nel formato corretto. Modifica il file per aggiungere più indici e distribuiscilo con il comando firebase deploy .
Per distribuire solo indici e regole Cloud Firestore, aggiungi il flag --only firestore .
Se apporti modifiche agli indici utilizzando la console Firebase, assicurati di aggiornare anche il file degli indici locali. Fare riferimento al riferimento alla definizione dell'indice JSON .
Tempo di creazione dell'indice
Per creare un indice, Cloud Firestore deve configurare l'indice e quindi riempirlo con i dati esistenti. Il tempo di creazione dell'indice è la somma del tempo di installazione e del tempo di recupero:
L'impostazione di un indice richiede alcuni minuti. Il tempo minimo di creazione di un indice è di pochi minuti, anche per un database vuoto.
Il tempo di recupero dipende dalla quantità di dati esistenti appartenenti al nuovo indice. Maggiore è il numero di valori di campo che corrispondono alla definizione dell'indice, maggiore è il tempo necessario per riempire l'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 hanno il prefisso projects/[PROJECT_ID]/databases/(default)/operations/ , ad esempio:
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
Tuttavia, puoi tralasciare 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, utilizzare il comando gcloud firestore Operations List . Questo comando elenca le operazioni in corso e completate di recente. Le operazioni sono elencate per alcuni giorni dopo il completamento:
gcloud firestore operations list
Controllare lo stato operativo
Invece di 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, visualizza il valore del campo state per lo stato complessivo dell'operazione.
Una richiesta per lo stato di un'operazione di lunga durata restituisce anche le metriche workEstimated e workCompleted . Queste metriche vengono restituite per il numero di documenti. workEstimated mostra il numero totale stimato di documenti che un'operazione elaborerà. workCompleted mostra il numero di documenti elaborati finora. Al termine dell'operazione, workCompleted riflette il numero totale di documenti effettivamente elaborati, che potrebbe essere diverso dal valore di workEstimated .
Dividere workCompleted per workEstimated per una stima approssimativa dello stato di avanzamento. La stima potrebbe essere imprecisa poiché dipende da un ritardo nella raccolta delle statistiche.
Ad esempio, ecco lo stato di avanzamento della creazione di un 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 descrizione dell'operazione conterrà "done": true . Vedere il valore del campo state per il risultato dell'operazione. Se il campo done non è impostato nella risposta, il suo valore è false . Non dipendere dall'esistenza del valore done per le operazioni in corso.
Errori nella creazione dell'indice
Potresti riscontrare errori di creazione dell'indice durante la gestione degli indici compositi e delle esenzioni per gli indici a campo singolo. Un'operazione di indicizzazione può non riuscire se Cloud Firestore riscontra un problema con i dati che sta indicizzando. Nella maggior parte dei casi, ciò significa che hai raggiunto un limite di indice . Ad esempio, l'operazione potrebbe aver raggiunto il numero massimo di voci di indice per documento.
Se la creazione dell'indice non riesce, viene visualizzato il messaggio di errore nella console. Dopo aver verificato di non aver raggiunto i limiti dell'indice , riprova l'operazione sull'indice.