Configurazione dell'indice composito

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

Requisiti di sistema

Per utilizzare gcloud CLI, devi aver installato Google Cloud CLI.

Informazioni su index.yaml

Ogni query in modalità Datastore effettuata da un'applicazione richiede un indice corrispondente. Gli indici per le query semplici, come quelle su una singola proprietà, vengono creati automaticamente. Gli indici composti per query complesse devono essere definiti in un file di configurazione 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 l'applicazione tenta di eseguire una query che richiede un indice composito che non ha una voce appropriata nel file di configurazione. Puoi regolare gli indici composti o crearne di nuovi manualmente modificando il file. index.yaml si trova nella cartella <project-directory>/WEB-INF/. Per impostazione predefinita, la directory dei dati che contiene WEB-INF/appengine-generated/index.yaml è ~/.config/gcloud/emulators/datastore/. Per ulteriori dettagli, consulta le directory dei progetti dell'emulatore Datastore.

Ecco 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 sintesi, consulta il sito web YAML.

Definizioni di Composite Index

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

Un elemento 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, in ordine di ordinamento: le proprietà utilizzate prima nei filtri di uguaglianza, seguite dalla proprietà utilizzata nei filtri di disuguaglianza, poi l'ordinamento e le relative direzioni.

Ogni elemento di questo elenco contiene i seguenti elementi:

name
Il nome della modalità Datastore della proprietà.
direction
La direzione di ordinamento, asc in ordine crescente o desc in ordine discendente. Questo campo è obbligatorio solo per le proprietà utilizzate negli ordini della query e deve corrispondere alla direzione utilizzata dalla query. Il valore predefinito è asc.
ancestor

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

Indici compositi automatici e manuali

Quando l'emulatore di Datastore aggiunge una definizione di indice composito generato a index.yaml, lo esegue al di sotto della riga seguente, inserendolo se necessario:

# AUTOGENERATED

L'emulatore considera tutte le definizioni di indice composito sotto questa riga come automatiche e potrebbe aggiornare le definizioni esistenti al di sotto di questa riga mentre l'applicazione esegue le query.

Tutte le definizioni dell'indice composito sopra questa riga sono considerate sotto controllo manuale e non sono 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 dell'indice composito, spostala sopra questa riga.

Aggiornamento degli indici composti

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

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

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

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

Se l'applicazione esegue una query che richiede un indice composito che non ha ancora completato la creazione, la query genera un'eccezione. Per evitare questo problema, devi prestare attenzione quando esegui il deployment di una nuova versione della tua applicazione che richiede un indice composito prima che la creazione del nuovo indice composito finisca.

Puoi controllare lo stato degli indici composti 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 della modalità Datastore. Questo ti offre l'opportunità di lasciare in esecuzione una versione precedente dell'applicazione durante la creazione di nuovi indici composti 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 composti non siano più necessari, puoi eliminarli utilizzando il comando datastore indexes cleanup. Questo comando elimina tutti gli indici composti per l'istanza in modalità Datastore di produzione 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 maggiori dettagli sugli argomenti a riga di comando per la creazione e la pulizia degli indici composti, consulta rispettivamente datastore indexes create e datastore indexes cleanup. Per maggiori dettagli sugli argomenti della riga di comando per gcloud CLI, consulta il riferimento per gcloud CLI'interfaccia a riga di comando gcloud.

Gestione di operazioni a lunga esecuzione

Le build di indice composito sono operazioni a lunga esecuzione e possono richiedere molto tempo.

Dopo aver avviato una build 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 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 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: l'ID del tuo progetto

Metodo e URL HTTP: 

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

Per inviare la richiesta, espandi una delle seguenti opzioni:

Consulta le informazioni sulla risposta di seguito.

Ad esempio, una build di indice composito 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 di una singola operazione:

gcloud

Utilizza il comando operations describe per mostrare lo stato di una build di indice composito.

gcloud datastore operations describe operation-name

rest

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

  • project-id: l'ID del tuo progetto

Metodo e URL HTTP: 

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

Per inviare la richiesta, espandi una delle seguenti opzioni:

Consulta le informazioni sulla risposta di seguito.

Stima del tempo di completamento

Durante l'esecuzione dell'operazione, visualizza il valore del campo state 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 entità. workEstimated mostra il numero totale stimato di entità elaborate 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à che sono state effettivamente elaborate, che potrebbe essere diverso dal valore di workEstimated.

Dividi workCompleted per workEstimated per una stima approssimativa dell'avanzamento. La stima potrebbe non essere precisa perché dipende dalla raccolta delle statistiche in ritardo.

Ad esempio, di seguito è riportato lo stato di avanzamento di una build dell'indice composito:

{
  "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"
        }
       },
    },
    ...

Quando un'operazione è completata, la descrizione dell'operazione conterrà "done": true. Visualizza il valore del campo state per il risultato dell'operazione. Se il campo done non è impostato nella risposta, il valore è false. Non dipendere dall'esistenza del valore done per le operazioni in corso.