Gestisci gli indici in Cloud Firestore

Cloud Firestore garantisce il rendimento delle query richiedendo un indice per ogni query. Gli indici richiesti per le query più semplici vengono creati automaticamente. Quando utilizzi e testi l'app, Cloud Firestore genera messaggi di errore che ti aiutano a creare gli indici aggiuntivi richiesti dall'app. In questa pagina viene descritto come gestire gli indici automatici, manuali e vettoriali.

Creare un indice mancante tramite un messaggio di errore

Se tenti di eseguire una query composta con una clausola di intervallo che non esegue il mapping a un indice esistente, riceverai 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, esamina le informazioni compilate automaticamente e fai clic su Crea.

Se è necessario un indice vettoriale, il messaggio di errore includerà un Google Cloud CLI comando per creare l'indice vettoriale mancante. Esegui il comando per creare l'indice mancante.

Ruoli e autorizzazioni

Prima di poter creare un indice in Cloud Firestore, assicurati di avere 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 gli indici:

  • datastore.indexes.create
  • datastore.indexes.delete
  • datastore.indexes.get
  • datastore.indexes.list
  • datastore.indexes.update

Utilizzare la console Firebase

Per creare manualmente un nuovo indice dalla console Firebase:

Immagine dell'interfaccia di indicizzazione di Firestore nella console 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 vuoi ordinare l'indice.
  4. Fai clic su Crea.

I campi dell'indice devono rispettare i vincoli dei 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 loro stato nella sezione Indici composti. Se sono ancora in fase di creazione, la console Firebase include una barra di stato di creazione.

Rimuovere gli indici

Per eliminare un indice:

  1. Vai alla sezione Cloud Firestore della console Firebase.
  2. Fai clic sulla scheda Indici.
  3. Passa il mouse sopra l'indice che vuoi eliminare e seleziona Elimina dal menu contestuale.
  4. Fai clic su Elimina nell'avviso per confermare l'eliminazione.

Utilizzare 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, l'interfaccia a riga di comando di Firebase genera un file JSON con gli indici predefiniti nel formato corretto. Modifica il file per aggiungere altri indici ed eseguirne il deployment con il comando firebase deploy.

Per eseguire il deployment solo degli indici e delle regole Cloud Firestore, aggiungi il --only firestore flag.

Se modifichi gli indici utilizzando la console Firebase, assicurati di aggiornare anche il file degli indici locali. Consulta il riferimento alla definizione dell'indice JSON .

Utilizzare Terraform

Creare indici nel database

I database Cloud Firestore possono includere indici a campo singolo (automatici) e composti (manuali). Puoi modificare il file di configurazione di Terraform per creare un indice per il tuo database. Gli indici automatici e manuali utilizzano tipi di risorse Terraform distinti (google_firestore_index e google_firestore_field).

Indice a campo singolo (automatico)

Il seguente file di configurazione di Terraform di esempio crea un indice a campo singolo sul 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 database.

Indice composto (manuale)

Il seguente file di configurazione di Terraform di esempio 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 database.

Indice vettoriale

Il seguente file di configurazione di Terraform di esempio crea un indice vettoriale sul campo embedding nella raccolta chatrooms:

firestore.tf

resource "google_firestore_index" "vector-index" {
  project = "project-id"
  database = "database-id"
  collection = "chatrooms"

  fields {
    field_path = "__name__"
    order = "ASCENDING"
  }

  fields {
    field_path = "embedding"
    vector_config {
      dimension = 128
      flat {}
    }
  }
}
  • Sostituisci project-id con l'ID progetto. Gli ID progetto devono essere univoci.
  • Sostituisci database-id con l'ID database.

Tempo di creazione dell'indice

Per creare un indice, Cloud Firestore deve configurare l'indice e poi eseguire il backfill dell'indice con i dati esistenti. Il tempo di creazione dell'indice è la somma del tempo di configurazione e del tempo di backfill:

  • La configurazione di un indice richiede alcuni minuti. Il tempo di creazione minimo per un indice è di alcuni minuti, anche per un database vuoto.

  • Il tempo di backfill dipende dalla quantità di dati esistenti che appartengono al nuovo indice. Più valori di campo corrispondono alla definizione dell'indice, più tempo è necessario per eseguire il backfill dell'indice.

Le creazioni di 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 omettere il prefisso quando specifichi un nome di operazione per il describe comando.

Elencare 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 quelle completate di recente. Le operazioni vengono elencate per alcuni giorni dopo il completamento:

gcloud firestore operations list

Controllare 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

Stimare il tempo di completamento

Durante l'esecuzione dell'operazione, consulta il valore del state campo per lo stato generale 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 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.

Dividi workCompleted per workEstimated per una stima approssimativa dell'avanzamento. La stima potrebbe essere imprecisa perché dipende dalla raccolta ritardata 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. Consulta il valore del campo state per il risultato dell'operazione. Se il campo done non è impostato nella risposta, il suo valore è false. Non fare affidamento sull'esistenza del valore done per le operazioni in corso.

Errori di creazione dell'indice

Potresti riscontrare errori di creazione dell'indice durante la gestione degli indici manuali e delle esenzioni degli indici automatici. Un'operazione di indicizzazione può non riuscire se Cloud Firestore rileva un problema con i dati che sta indicizzando. Nella maggior parte dei casi, questo significa che hai raggiunto un limite dell'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 alcun limite dell'indice, riprova a eseguire l'operazione dell'indice.