Gestisci indici

Gestisci indici

Firestore garantisce le prestazioni delle query richiedendo un indice per ogni query. Gli indici necessari per le query di base vengono creati automaticamente per te. Mentre utilizzi e test la tua app, Cloud Firestore genera messaggi di errore che ti consentono di creare indici aggiuntivi richiesti dalla tua app. In questa pagina viene descritto come gestire gli indici a campo singolo e compositi.

Crea un indice mancante tramite un messaggio di errore

Se provi a 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 link diretto per creare l'indice mancante nella Console Firebase.

Nota: puoi gestire Firestore tramite la console Firebase o la console di Google Cloud Platform, ma questi link verranno sempre aperti nella console Firebase.

Segui il link generato alla console Firebase, esamina le informazioni compilate automaticamente e fai clic su Crea.

Nota: per i campi non array e non mappa, devi selezionare l'ordinamento crescente o decrescente, anche se non è necessario il campo per l'ordinamento. La tua scelta non influisce sul comportamento delle uguaglianze nella query.

Ruoli e autorizzazioni

Prima di poter creare un indice in Firestore, assicurati di averti assegnato uno dei seguenti ruoli:

Nota: i ruoli seguenti sono gestiti tramite Identity and Access Management (IAM). Per saperne di più sui ruoli e sulle autorizzazioni associate, consulta Ruoli predefiniti.

• roles/datastore.owner
• roles/datastore.indexAdmin
• roles/editor
• roles/owner

Se hai definito ruoli personalizzati, assegna tutte le autorizzazioni seguenti per creare gli indici:

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

Utilizzare la console di Google Cloud Platform

Dalla console di Google Cloud Platform, puoi gestire esenzioni dell'indicizzazione a campo singolo e indici composti.

Crea un indice composto

Per creare manualmente un nuovo indice composto dalla console di Google Cloud:

1. Nella console Google Cloud, vai alla pagina Database.

   Vai a Database

2. Seleziona il database richiesto dall'elenco dei database.

3. Nel menu di navigazione, fai clic su Indici e poi sulla scheda Composito.

4. Fai clic su Crea indice.

5. Inserisci un ID raccolta. Aggiungi i nomi dei campi da indicizzare e una modalità di indicizzazione per ogni campo. Fai clic su Salva indice.

Il nuovo indice verrà visualizzato nell'elenco degli indici composti e Firestore inizierà a crearlo. Al termine della creazione dell'indice, vedrai un segno di spunta verde accanto all'indice.

Elimina un indice composto

Per eliminare un indice composto:

1. Nella console Google Cloud, vai alla pagina Database.

   Vai a Database

2. Seleziona il database richiesto dall'elenco dei database.

3. Nel menu di navigazione, fai clic su Indici e poi sulla scheda Composito.

4. Nell'elenco degli indici composti, fai clic sul pulsante Altro in corrispondenza dell'indice da eliminare. Fai clic su Elimina.

5. Conferma di voler eliminare questo indice facendo clic su Elimina indice nell'avviso.

Aggiungi un'esenzione per l'indice a campo singolo

Le esenzioni dell'indice a campo singolo consentono di sostituire le impostazioni dell'indice automatiche per i campi specifici di una raccolta. Puoi aggiungere esenzioni a campo singolo dalla console:

1. Nella console Google Cloud, vai alla pagina Database.

   Vai a Database

2. Seleziona il database richiesto dall'elenco dei database.

3. Nel menu di navigazione, fai clic su Indici e poi sulla scheda Campo singolo.

4. Fai clic su Aggiungi esenzione.

5. Inserisci un ID raccolta e un Percorso campo.

6. Seleziona le nuove impostazioni di indicizzazione per questo campo. Abilita o disabilita gli indici a campo singolo aggiornati automaticamente, in ordine decrescente e array-contiene per questo campo.

7. Fai clic su Salva esenzione.

Aggiungi un'esenzione a livello di raccolta

Per definire un'esenzione per l'indice a campo singolo che si applica a tutti i campi di un ID raccolta:

1. Fai clic su Aggiungi esenzione.

2. Inserisci un ID raccolta per il gruppo di raccolte e imposta Percorso campo su *.

   

3. Seleziona le esenzioni di indicizzazione da applicare a tutti i campi nel gruppo di raccolte.

4. Fai clic su Salva esenzione.

Elimina un'esenzione dell'indice a campo singolo

Per eliminare un'esenzione per l'indice a campo singolo, segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina Database.

   Vai a Database

2. Seleziona il database richiesto dall'elenco dei database.

3. Nel menu di navigazione, fai clic su Indici e poi sulla scheda Campo singolo.

4. Nell'elenco delle esenzioni dell'indice a campo singolo, fai clic sul pulsante Altro per l'esenzione che vuoi eliminare. Fai clic su Elimina.

5. Conferma di voler eliminare l'esenzione facendo clic su Elimina nell'avviso.

Quando elimini un'esenzione a campo singolo, il campo o il sottocampo specificato utilizzerà le impostazioni di indicizzazione ereditate. I campi del documento vengono ripristinati alle impostazioni indice automatiche del database. I campi secondari di una mappa ereditano eventuali esenzioni dai campi principali prima di ereditare le impostazioni di indicizzazione automatiche.

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, 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 eseguine il deployment con il comando firebase deploy.

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

Se apporti modifiche agli indici utilizzando la console Firebase, assicurati di aggiornare anche il file indici locali. Consulta il riferimento per la definizione degli indici JSON.

Utilizza Terraform

Creazione di indici nel database

Il database Firestore può includere un indice a campo singolo o un indice composto. 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 l'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 composto per una combinazione dei campi name e 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.

Tempo di creazione indice

Per creare un indice, Firestore deve configurarlo 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 compilazione minimo per un indice è di pochi minuti, anche per un database vuoto.

• Il tempo di backfill dipende dalla quantità di dati esistenti appartenenti al nuovo indice. Maggiore è il numero di valori del campo che corrispondono alla definizione dell'indice, più tempo sarà necessario per il backfill dell'indice.

Le build dell'indice sono operazioni a lunga esecuzione.

Termine chiave: Firestore supporta diverse operazioni amministrative il cui completamento può richiedere molto tempo. Queste operazioni sono chiamate operazioni a lunga esecuzione. Firestore include funzionalità per l'esecuzione e la gestione di operazioni a lunga esecuzione. Le operazioni a lunga esecuzione supportate includono build di indice e operazioni di esportazione.

Dopo aver avviato la build di un indice, Firestore assegna all'operazione un nome univoco. I nomi delle operazioni sono preceduti dal prefisso projects/[PROJECT_ID]/databases/(default)/operations/, ad esempio:

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Tuttavia, puoi escludere il prefisso quando specifichi un nome 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 quelle completate di recente. Le operazioni sono 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 generale dell'operazione.

Una richiesta sullo 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 effettivamente elaborati, che potrebbe essere diverso dal valore di workEstimated.

Dividi workCompleted per workEstimated per ottenere una stima approssimativa dell'avanzamento. La stima potrebbe non essere precisa perché dipende da un ritardo nella raccolta delle statistiche.

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. Visualizza il valore del campo state relativo al 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 di creazione dell'indice

Potresti riscontrare errori di creazione degli indici durante la gestione di indici composti ed esenzioni degli indici a campo singolo. Un'operazione di indicizzazione può non riuscire se Firestore riscontra un problema con i dati che sta indicizzando. Più di solito, questo significa che hai raggiunto un limite indice. Ad esempio, l'operazione potrebbe aver raggiunto il numero massimo di voci di indice per documento.

Se la creazione dell'indice non riesce, verrà visualizzato un messaggio di errore nella console. Dopo aver verificato che non stai raggiungendo alcun limite dell'indice, riprova a eseguire l'operazione.