Configurazione dell'indice composto

Firestore in modalità Datastore utilizza gli indici per ogni query effettuata dall'applicazione. Questi indici vengono aggiornati ogni volta che un'entità cambia, quindi i risultati possono essere velocemente quando l'applicazione esegue una query. La modalità Datastore fornisce automaticamente gli indici integrati, ma deve sapere in anticipo quali indici composti richiederà l'applicazione. In un file di configurazione specifichi gli indici compositi di cui ha bisogno la tua applicazione. L'emulatore Datastore può generare automaticamente la configurazione dell'indice composito in modalità Datastore durante il test dell' applicazione. Lo strumento a riga di comando gcloud fornisce i comandi per aggiornare disponibili per il database di produzione in modalità Datastore.

Requisiti di sistema

Per utilizzare l'interfaccia a riga di comando gcloud, devi aver installato Google Cloud CLI.

Informazioni su index.yaml

Ogni query in modalità Datastore effettuata da un'applicazione richiede un indice corrispondente. Vengono creati indici per query semplici, ad esempio query su una singola proprietà automaticamente. Gli indici composti per le query complesse devono essere definiti in una configurazione file denominato index.yaml. Questo file viene caricato con l'applicazione per creare indici compositi in un database in modalità Datastore.

L'emulatore Datastore aggiunge automaticamente elementi a questo file quando un'applicazione cerca di eseguire una query che richiede un indice composto che non abbia la voce appropriata nel file di configurazione. Puoi modificare gli indici composti o creare nuove manualmente modificando il file. index.yaml si trova nella <project-directory>/WEB-INF/. Per impostazione predefinita, la directory dei dati contiene WEB-INF/appengine-generated/index.yaml è ~/.config/gcloud/emulators/datastore/. Consulta: Directory del progetto dell'emulatore di datastore per maggiori dettagli.

Di seguito è riportato un esempio di file index.yaml:

indexes:

- kind: Task
  ancestor: no
  properties:
  - name: done
  - name: priority
    direction: desc

- kind: Task
  properties:
  - name: collaborators
    direction: asc
  - name: created
    direction: desc

- kind: TaskList
  ancestor: yes
  properties:
  - name: percent_complete
    direction: asc
  - name: type
    direction: asc

La sintassi di index.yaml è il formato YAML. Per ulteriori informazioni su questa sintassi, visita il sito web di YAML.

Definizioni degli indici composti

index.yaml ha un singolo elemento dell'elenco chiamato indexes. Ogni elemento dell'elenco rappresenta un indice composito per l'applicazione.

Un elemento di indice può avere i seguenti elementi:

kind
Il tipo di entità per la query. Questo elemento è obbligatorio.
properties

Un elenco di proprietà da includere come colonne dell'indice composto, nell'ordine in cui devono essere ordinate: prima le proprietà utilizzate nei filtri di uguaglianza, seguite dalla proprietà utilizzata nei filtri di disuguaglianza, poi gli ordini di ordinamento e le relative direzioni.

Ogni elemento dell'elenco contiene i seguenti elementi:

name
Il nome della modalità Datastore della proprietà.
direction
La direzione in cui eseguire l'ordinamento, asc per crescente o desc per in ordine decrescente. Questo è obbligatorio solo per le proprietà utilizzate negli ordini di ordinamento della query e deve corrispondere alla direzione utilizzata dalla query. L'impostazione predefinita è asc.
ancestor

yes se la query ha una clausola predecessore. Il valore predefinito è no.

Indici composti automatici e manuali

Quando l'emulatore Datastore aggiunge una definizione di indice composto generata a index.yaml, lo fa sotto la riga seguente, inserendolo se necessario:

# AUTOGENERATED

L'emulatore considera automatiche tutte le definizioni degli indici compositi sotto questa riga e può aggiornare le definizioni esistenti sotto questa riga man mano che l'applicazione esegue query.

Tutte le definizioni di indici compositi sopra questa riga sono considerate sotto controllo manuale e non vengono aggiornate dall'emulatore. L'emulatore apporterà modifiche solo sotto la riga e lo farà solo se il file index.yaml completo non descrive un indice composito che tiene conto di una query eseguita dall'applicazione. Per assumere il controllo di una definizione automatica di indice composto, spostalo sopra su questa riga.

Aggiornamento degli indici composti

Il comando datastore indexes create esamina il tuo indice composto Datastore locale (il file index.yaml) e se la configurazione dell'indice composto definisce indice composto che non esiste ancora nel database in modalità Datastore di produzione, il database crea il nuovo indice composto. Consulta il flusso di lavoro di sviluppo con l'interfaccia a riga di comando gcloud per un esempio di utilizzo di indexes create.

Per creare un indice composto, il database deve configurarlo e poi eseguire il suo completamento con i dati esistenti. La data/ora di creazione dell'indice composto è la somma del tempo di configurazione e del tempo di backfill:

  • La configurazione di un indice composito richiede alcuni minuti. Il numero minimo di creazioni per un indice composto è di pochi minuti, anche per un database vuoto.

  • Il tempo di backfill dipende dalla quantità di dati esistenti che appartengono al nuovo indice composto. Maggiore è il numero di valori delle proprietà che appartengono all'indice composto, maggiore è il tempo necessario per eseguire il backfill dell'indice composto.

Se l'applicazione esegue una query che richiede un indice composto che non è stato completato creando ancora, la query genera un'eccezione. Per evitare questo problema, devi eseguire con attenzione il deployment di una nuova versione dell'applicazione che richiede un indice composito prima del completamento della creazione del nuovo indice composito.

Puoi controllare lo stato degli indici compositi dalla pagina Indici nella console Google Cloud.

Eliminazione degli indici composti inutilizzati

Quando modifichi o rimuovi un indice composito dalla configurazione dell'indice composito, l'indice composito originale non viene eliminato automaticamente dal database in modalità Datastore. In questo modo hai la possibilità di lasciare in esecuzione una versione precedente dell'applicazione durante la creazione di nuovi indici compositi o di ripristinare immediatamente la versione precedente se viene rilevato un problema con una versione più recente.

Quando hai la certezza che i vecchi indici compositi non sono più necessari, puoi eliminarli utilizzando il comando datastore indexes cleanup. Questo comando elimina tutti gli indici composti per l'istanza di produzione in modalità Datastore che non sono menzionati nella versione locale di index.yaml. Consulta il flusso di lavoro di sviluppo con l'interfaccia a riga di comando gcloud per un esempio di come utilizzare indexes cleanup.

Argomenti della riga di comando

Per informazioni dettagliate sugli argomenti della riga di comando per la creazione e la pulizia degli indici compositi, consulta datastore indexes create e datastore indexes cleanup, rispettivamente. Per informazioni dettagliate sugli argomenti a riga di comando per l'interfaccia a riga di comando gcloud, consulta la documentazione di riferimento dell'interfaccia a riga di comando gcloud.

Gestione di operazioni a lunga esecuzione

Le build di indici composti sono operazioni che richiedono molto tempo e possono richiedere molto tempo per essere completate.

Dopo aver avviato una compilazione dell'indice composito, la modalità Datastore assegna all'operazione un nome univoco. I nomi delle operazioni sono preceduti da projects/[PROJECT_ID]/databases/(default)/operations/, ad esempio:

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

Tuttavia, puoi omettere il prefisso quando specifichi un nome dell'operazione per il comando describe.

Elenco di tutte le operazioni a lunga esecuzione

Per elencare le operazioni a lunga esecuzione, utilizza il comando gcloud datastore operations list. Questo comando elenca le operazioni in corso e completate di recente. Le operazioni vengono elencate per alcuni giorni dopo il completamento:

gcloud

gcloud datastore operations list

rest

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • project-id: il tuo ID progetto

Metodo HTTP e URL: 

GET https://datastore.googleapis.com/v1/projects/project-id/operations

Per inviare la richiesta, espandi una di queste opzioni:

Leggi le informazioni sulla risposta di seguito.

Ad esempio, una build di indice composto completata di recente mostra le seguenti informazioni:

{
  "operations": [
  {
    "name": "projects/project-id/operations/S01vcFVpSmdBQ0lDDCoDIGRiNTdiZDQNmE4YS0yMTVmNWUzZSQadGx1YWZlZAcSMXRzYWVzdS1yZXhlZG5pLW5pbWRhFQpWEg",
    "done": true,
    "metadata": {
      "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
      "common": {
        "endTime": "2020-06-23T16:55:29.923562Z",
        "operationType": "CREATE_INDEX",
        "startTime": "2020-06-23T16:55:10Z",
        "state": "SUCCESSFUL"
      },
      "indexId": "CICAJiUpoMK",
      "progressEntities": {
        "workCompleted": "2193027",
        "workEstimated": "2198182"
      }
    },
    "response": {
      "@type": "type.googleapis.com/google.datastore.admin.v1.Index",
      "ancestor": "NONE",
      "indexId": "CICAJiUpoMK",
      "kind": "Task",
      "projectId": "project-id",
           "properties": [
        {
          "direction": "ASCENDING",
          "name": "priority"
        },
        {
          "direction": "ASCENDING",
          "name": "done"
        },
        {
          "direction": "DESCENDING",
          "name": "created"
        }
      ],
      "state": "READY"
    }
  },
  ]
}

Descrizione di una singola operazione

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

gcloud

Utilizza il comando operations describe per visualizzare lo stato di una compilazione dell'indice composto.

gcloud datastore operations describe operation-name

rest

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • project-id: il tuo ID progetto

Metodo HTTP e URL: 

GET https://datastore.googleapis.com/v1/projects/project-id/operations

Per inviare la richiesta, espandi una di queste opzioni:

Leggi le informazioni sulla risposta di seguito.

Stima del tempo di completamento

Durante l'esecuzione dell'operazione, controlla il valore del campo state per lo stato complessivo dell'operazione.

Una richiesta relativa allo stato di un'operazione a lunga esecuzione restituisce anche le metriche workEstimated e workCompleted. Queste metriche vengono restituite per il numero di entità. workEstimated mostra il numero totale stimato di entità che verrà elaborato da un'operazione in base alle statistiche del database. workCompleted mostra il numero di entità elaborate finora. Al termine dell'operazione,workCompleted riflette il numero totale di entità effettivamente elaborate, che potrebbe essere diverso dal valore di workEstimated.

Dividi workCompleted per workEstimated per una stima approssimativa dei progressi. L' stima potrebbe non essere precisa perché dipende dalla raccolta delle statistiche con ritardo.

Ad esempio, ecco lo stato di avanzamento di una build di un indice composto:

{
  "operations": [
    {
      "name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
        "common": {
          "operationType": "CREATE_INDEX",
          "startTime": "2020-06-23T16:52:25.697539Z",
          "state": "PROCESSING"
        },
        "progressEntities": {
          "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 dipendono dall'esistenza del valore done per le operazioni in corso.