Configurazione dell'indice composto

Firestore in modalità Datastore utilizza 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 indici integrati automaticamente, ma deve sapere in anticipo quali indici compositi richiederà l'applicazione. Specifichi gli indici compositi di cui ha bisogno la tua applicazione in un file di configurazione. L'emulatore 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 tuo 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 le query semplici, ad esempio le 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. 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 di progetto 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 saperne di più su questa sintassi, visita il sito web di YAML.

Definizioni degli indici compositi

index.yaml ha un singolo elemento di elenco chiamato indexes. Ogni elemento dell'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, 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 ha i seguenti elementi:

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

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

Indici compositi automatici e manuali

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

# AUTOGENERATED

L'emulatore considera automatiche tutte le definizioni di indice composito sotto questa riga e potrebbe aggiornare le definizioni esistenti sotto questa riga man mano che l'applicazione esegue query.

Tutte le definizioni di indice composto sopra questa riga sono considerate sotto controllo manuale e non vengono aggiornate dall'emulatore. L'emulatore apporterà modifiche solo al di sotto della riga e 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 composto Datastore locale (il file index.yaml) e, se la configurazione dell'indice composto definisce un indice composto che non esiste ancora nel database Datastore in modalità produzione, il database crea il nuovo indice composto. Consulta il flusso di lavoro di sviluppo utilizzando gcloud CLI per un esempio di come utilizzare indexes create.

Per creare un indice composto, il database deve configurarlo e poi riempirlo 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 alcuni minuti, anche per un database vuoto.

  • Il tempo necessario per il backfill dipende dalla quantità di dati esistenti che appartengono al nuovo indice composito. Più valori di proprietà appartengono all'indice composto, più tempo ci vuole per eseguire il backfill dell'indice composto.

Se l'applicazione esegue una query che richiede un indice composito la cui creazione non è ancora terminata, la query genera un'eccezione. Per evitare questo problema, devi fare attenzione a eseguire il deployment di una nuova versione dell'applicazione che richiede un indice composto prima che la creazione del nuovo indice composto sia completata.

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

Eliminazione degli indici composti non utilizzati

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 l'opportunità di lasciare in esecuzione una versione precedente dell'applicazione mentre vengono creati nuovi indici compositi oppure 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 compositi per l'istanza della modalità Datastore di produzione che non sono menzionati nella versione locale di index.yaml. Consulta il flusso di lavoro di sviluppo utilizzando gcloud CLI 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, vedi datastore indexes create e datastore indexes cleanup, rispettivamente. Per informazioni dettagliate sugli argomenti della riga di comando per gcloud CLI, consulta il riferimento gcloud CLI.

Gestione di operazioni a lunga esecuzione

Le build di indici compositi sono operazioni di lunga durata e possono richiedere molto tempo per essere completate.

Dopo aver avviato la creazione di un 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 di 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 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 creazione 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"
    }
  },
  ]
}

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 composito.

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

Man mano che l'operazione viene eseguita, visualizza il valore del campo state per lo stato complessivo dell'operazione.

Una richiesta dello 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 un'operazione elaborerà, 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. La stima potrebbe essere imprecisa perché dipende dalla raccolta ritardata delle statistiche.

Ad esempio, ecco 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. Visualizza 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.