Configurazione indice composito

Firestore in modalità Datastore utilizza gli indici per ogni query eseguita dall'applicazione. Questi indici vengono aggiornati ogni volta che un'entità viene modificata, in modo che i risultati possano essere restituiti rapidamente quando l'applicazione esegue una query. La modalità Datastore fornisce indici integrati, ma deve sapere in anticipo quali indici composti saranno richiesti dall'applicazione. Devi specificare gli indici composti necessari per l'applicazione in un file di configurazione. L'emulatore datastore può generare automaticamente la configurazione dell'indice composito in modalità Datastore mentre testi l'applicazione. Lo strumento a riga di comando gcloud fornisce comandi per aggiornare gli indici disponibili nel database di produzione in modalità Datastore.

Requisiti di sistema

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

Informazioni su index.yaml

A ogni query in modalità Datastore eseguita da un'applicazione è necessario un indice corrispondente. Gli indici per query semplici, ad esempio query 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 composto che non dispone di una voce appropriata nel file di configurazione. Puoi modificare 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 Directory dei progetti dell'emulatore di datastore.

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 maggiori informazioni su questa sintassi, consulta il sito web YAML.

Definizioni degli indici composti

index.yaml ha un singolo elemento dell'elenco chiamato indexes. Ogni elemento dell'elenco rappresenta un indice composto 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, in ordine di ordinamento: le proprietà utilizzate prima nei filtri di uguaglianza, seguite dalla proprietà utilizzata nei filtri di disuguaglianza, poi gli ordinamenti e le relative indicazioni.

Ogni elemento dell'elenco contiene i seguenti elementi:

name
Il nome in modalità Datastore della proprietà.
direction
La direzione da ordinare: asc per crescente o desc per ordine decrescente. Questa operazione è obbligatoria solo per le proprietà utilizzate negli ordini di ordinamento della query e deve corrispondere alla direzione utilizzata dalla query. Il valore predefinito è 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 composti sottostanti questa riga e potrebbe aggiornare le definizioni esistenti al di sotto di questa riga man mano che l'applicazione esegue query.

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

Aggiornamento degli indici composti

Il comando datastore indexes create controlla la configurazione dell'indice composto Datastore locale (il file index.yaml) e, se la configurazione dell'indice composto definisce un 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 per lo sviluppo con gcloud CLI per un esempio di come utilizzare indexes create.

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

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

  • Il tempo di backfill dipende dalla quantità di dati esistenti appartenenti al nuovo indice composto. Maggiore è il numero di valori delle proprietà appartenenti all'indice composto, più tempo sarà necessario per il backfill dell'indice composto.

Se l'applicazione esegue una query che richiede un indice composto la cui creazione non è ancora terminata, la query genera un'eccezione. Per evitare che ciò accada, devi prestare attenzione al deployment di una nuova versione dell'applicazione che richiede un indice composto prima che la creazione del nuovo indice composto finisca.

Puoi controllare lo stato degli indici composti dalla pagina Indici della console Google Cloud.

Eliminazione degli indici composti non utilizzati

Quando modifichi o rimuovi un indice composto dalla configurazione dell'indice composto, l'indice composito originale non viene eliminato automaticamente dal database in modalità Datastore. Ciò 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 non menzionati nella versione locale di index.yaml. Consulta il flusso di lavoro per lo sviluppo con gcloud CLI per un esempio di come utilizzare indexes cleanup.

Argomenti della riga di comando

Per dettagli sugli argomenti della 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 di gcloud CLI.

Gestione di operazioni a lunga esecuzione

Le build di indici composti sono operazioni a lunga esecuzione e il loro completamento può richiedere molto tempo.

Dopo aver avviato la build di un indice composto, la modalità Datastore 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 datastore 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

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 un 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"
    }
  },
  ]
}

Descrivere 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 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 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 entità. workEstimated mostra il numero totale stimato di entità che verrà elaborata da un'operazione, in base a 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 ottenere una stima approssimativa dell'avanzamento. La stima potrebbe non essere precisa perché dipende da un ritardo nella raccolta delle statistiche.

Ad esempio, questo è lo stato di avanzamento di una build di 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 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.