Gestisci indici

Gestisci indici

Firestore garantisce le prestazioni delle query richiedendo un indice per ogni query. Gli indici necessari per le query più basilari vengono automaticamente creati per te. Mentre usi e testi la tua app, Cloud Storage Firestore genera messaggi di errore che consentono di creare altri indici per il tuo richiede l'uso dell'app. In questa pagina viene descritto come gestire Indici a campo singolo e composito.

Crea un indice mancante tramite un messaggio di errore

Se tenti di eseguire una query composta da una clausola Range che non esegue la mappatura a un indice esistente. ricevi un messaggio di errore. Il messaggio di errore include un link diretto per creare indice mancante nella console Firebase.

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

Segui il collegamento generato alla console Firebase, rivedi l'impostazione compilate e fai clic su Crea.

Nota: per i campi non array e non mappa, devi selezionare crescente o ordine decrescente, anche se non hai bisogno del campo per ordinazione. La tua scelta non influisce sul comportamento delle uguaglianze nella query.

Ruoli e autorizzazioni

Prima di poter creare un indice in Firestore, assicurati che ti sia stato 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, vedi Ruoli predefiniti.

• 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 di Google Cloud Platform

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

Crea un indice composto

Per creare manualmente un nuovo indice composto dalla console 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 che vuoi indicizzare e una modalità di indice per ogni campo. Fai clic su Salva indice.

Il nuovo indice verrà visualizzato nell'elenco degli indici composti e Firestore inizierà a creare il tuo indice. Al termine dell'indicizzazione verrà visualizzato un segno di spunta verde accanto all'indice.

Eliminare 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 relativo all'indice da eliminare. Fai clic su Elimina.

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

Aggiungi un'esenzione dell'indice a campo singolo

Le esenzioni degli indici a campo singolo consentono di ignorare l'indicizzazione automatica impostazioni per campi specifici di una raccolta. Puoi aggiungi un'esenzione 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 del campo.

6. Seleziona nuove impostazioni di indicizzazione per questo campo. Attivazione o disattivazione automatica aggiornato in ordine crescente, decrescente e array-contiene indici a campo singolo per questo campo.

7. Fai clic su Salva esenzione.

Aggiungi un'esenzione a livello di raccolta

Per definire un'esenzione dell'indice a campo singolo che si applica a tutti i campi in 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 che vuoi 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 dell'indice a campo singolo:

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 degli indici a campo singolo, fai clic sul pulsante Altro per l'esenzione da eliminare. Fai clic su Elimina.

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

Quando elimini un'esenzione a campo singolo, il campo o il sottocampo specificato usano le impostazioni di indicizzazione ereditate. I campi del documento vengono ripristinati impostazioni indice automatiche. I campi secondari di una mappa ereditano eventuali esenzioni dall'elemento padre prima di ereditare le impostazioni di indice 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 il valore predefinito gli indici nel formato corretto. Modifica il file per aggiungere altri indici ed eseguirne il deployment con il comando firebase deploy.

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

Se apporti modifiche agli indici utilizzando la console Firebase, apporta aggiorna anche il file degli indici locali. Consulta Riferimento alla definizione dell'indice 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 di 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 composto

Il seguente file di configurazione 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 del tuo database.

Ora di creazione indice

Per creare un indice, Firestore deve configurarlo e quindi eseguire il backfill dell'indice con i dati esistenti. La metrica Tempo di creazione indice è la somma dei tempi di configurazione e tempo di backfill:

• La configurazione di un indice richiede alcuni minuti. La build minima per un indice è di pochi minuti, anche per un database vuoto.

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

Le build degli indici sono operazioni a lunga esecuzione.

Termine chiave: Firestore supporta diverse operazioni amministrative che può richiedere molto tempo. Queste operazioni sono chiamate a lunga esecuzione operazioni. Firestore include funzionalità per l'esecuzione e la gestione le operazioni in 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 un nome univoco per l'operazione. 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 omettere il prefisso quando specifichi il nome di un'operazione il comando describe.

Elenco di tutte le operazioni a lunga esecuzione

Per elencare le operazioni a lunga esecuzione, utilizza Elenco delle operazioni di gcloud firestore . 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

Controlla lo stato dell'operazione

Anziché elencare tutte le operazioni a lunga esecuzione, puoi elencare i dettagli in una singola operazione:

gcloud firestore operations describe operation-name

Stima del tempo di completamento

Durante l'esecuzione dell'operazione, osserva il valore del campo state per conoscere lo stato generale dell'operazione.

Anche una richiesta per lo stato di un'operazione a lunga esecuzione restituisce le metriche workEstimated e workCompleted. Queste metriche vengono restituite per il numero di documenti. workEstimated mostra il numero totale stimato di documenti verrà elaborata. 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. La stima potrebbe non essere precisa perché dipende da statistiche ritardate .

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 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 degli indici quando gestisci indici composti esenzioni degli indici a campo singolo. Un'operazione di indicizzazione può non riuscire se Firestore riscontra un problema con i dati che indicizza. Più alta di solito, questo significa che limite di indice. Per 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 il giorno verifichi di non aver raggiunto limiti di indice, riprova a eseguire l'operazione.