Gestisci gli indici in Cloud Firestore

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:

immagine dell'interfaccia di indicizzazione di Firestore nella console di Firebase

  1. Vai alla sezione Cloud Firestore della console Firebase .
  2. Vai alla scheda Indici e fai clic su Aggiungi indice .
  3. Inserisci il nome della raccolta e imposta i campi in base ai quali desideri ordinare l'indice.
  4. 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:

  1. Vai alla sezione Cloud Firestore della console Firebase .
  2. Fare clic sulla scheda Indici .
  3. Passa il mouse sopra l'indice che desideri eliminare e seleziona Elimina dal menu contestuale.
  4. 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 .

Usa Terraform

Creazione di indici nel database

Il database Cloud Firestore può includere un indice a campo singolo o un indice composito. Puoi modificare il file di configurazione Terraform per creare un indice per il tuo database.

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 il tuo ID progetto. Gli ID progetto devono essere univoci.
  • Sostituisci database-id con l'ID del tuo database.

Indice composito

Il seguente file di configurazione Terraform di esempio crea un indice composito per una combinazione del campo name e del campo della 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 il tuo ID progetto. Gli ID progetto devono essere univoci.
  • Sostituisci database-id con l'ID del tuo database.

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.