Configurazione dell'indice composto

Firestore in modalità Datastore utilizza gli indici per ogni query eseguita dalla tua applicazione. Questi indici vengono aggiornati ogni volta che un'entità cambia, in modo che i risultati possano essere restituiti rapidamente 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 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 eseguita da un'applicazione richiede un indice corrispondente. Gli indici per query semplici, ad esempio query su una singola proprietà, vengono creati automaticamente. Gli indici composti per le 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 ha una voce appropriata nel file di configurazione. Puoi modificare gli indici compositi o crearne di nuovi manualmente modificando il file. index.yaml si trova nella <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.

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 di questo elenco contiene i seguenti elementi:

name
Il nome della modalità Datastore della proprietà.
direction
La direzione di ordinamento, asc per crescente o desc per decrescente. Questo è obbligatorio 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 contiene una clausola antenato. Il valore predefinito è no.

Indici composti automatici e manuali

Quando l'emulatore Datastore aggiunge una definizione di indice composto generato a index.yaml, lo fa sotto la riga seguente, inserendola 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 di indice composito automatico, spostala sopra questa riga.

Aggiornamento degli indici composti

Il comando datastore indexes create esamina la configurazione dell'indice composito di Datastore locale (file index.yaml) e, se la configurazione dell'indice composito definisce un indice composito che non esiste ancora nel database di produzione in modalità Datastore, il database crea il nuovo indice composito. 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. Il tempo 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 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 composito. 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 di cui non è stata ancora completata la compilazione, la query genera un'eccezione. Per evitare ciò, 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 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 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 gcloud CLI, consulta la documentazione della gcloud CLI 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 di lunga durata, 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, apporta 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:

Consulta le informazioni sulla risposta di seguito.

Ad esempio, una compilazione dell'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 di 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, apporta 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:

Consulta 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, di seguito è riportato lo stato di avanzamento della creazione 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 fare affidamento sull'esistenza del valore done per le operazioni in corso.