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