Configurazione degli indici datastore con index.yaml

Puoi utilizzare Firestore in modalità Datastore (Datastore) per archiviare i dati delle tue applicazioni eseguite nell'ambiente standard. Datastore utilizza gli indici per ogni query eseguita dall'applicazione. Questi indici vengono aggiornati ogni volta che un'entità cambia, quindi è possibile restituire rapidamente i risultati quando l'app effettua una query. Per farlo, Datastore deve sapere in anticipo quali query eseguirà l'applicazione. Specifica gli indici di cui la tua app ha bisogno in un file di configurazione index.yaml. Puoi utilizzare l'emulatore Datastore per generare automaticamente il file durante il test dell'app oppure scrivere personalmente il file. Il file index.yaml deve essere caricato quando esegui il deployment dell'app.

Informazioni su index.yaml

Ogni query Datastore creata da un'applicazione richiede un indice corrispondente. Gli indici per query semplici, come le query su una singola proprietà, vengono creati automaticamente. Gli indici per query complesse devono essere definiti in un file di configurazione denominato index.yaml. Questo file viene caricato con l'applicazione per creare gli indici in Datastore.

Nell'esempio seguente è riportato un file index.yaml:

indexes:

- kind: Cat
  ancestor: no
  properties:
  - name: name
  - name: age
    direction: desc

- kind: Cat
  properties:
  - name: name
    direction: asc
  - name: whiskers
    direction: desc

- kind: Store
  ancestor: yes
  properties:
  - name: business
    direction: asc
  - name: owner
    direction: asc

La sintassi di index.yaml è il formato YAML. Per ulteriori informazioni su questa sintassi, consulta il sito web YAML.

Definizioni degli indici

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

Ogni elemento di questo elenco ha i seguenti elementi:

name
Il nome del datastore della proprietà.
direction
La direzione di ordinamento, asc per l'ordine crescente o desc per la discesa. Questa operazione è obbligatoria solo per le proprietà utilizzate in ordinamenti della query e deve corrispondere alla direzione utilizzata dalla query. Il valore predefinito è asc.
ancestor

yes se la query contiene una clausola di predecessore (hasAncestor). Il valore predefinito è no.

Creazione di file indice

Puoi creare un file di indice manualmente, utilizzando un editor di testo e seguendo il layout del file descritto sopra. Un approccio più efficiente consiste nel generare automaticamente il file durante il test locale dell'app. Puoi combinare i due metodi.

Quando esegui il test nel tuo ambiente locale, puoi utilizzare il comando emulatore gcloud per avviare un servizio che emula Datastore prima di eseguire la tua app:

gcloud beta emulators datastore start --data-dir DATA-DIR

Utilizza il flag --data-dir per specificare la directory in cui verrà visualizzato il file index.yaml generato automaticamente.

Durante il test della tua app, ogni volta che generi una query di Datastore, l'emulatore aggiunge una definizione di indice generata a index.yaml. Tutte le definizioni di indice generate automaticamente verranno visualizzate nel file sotto la riga seguente:

# AUTOGENERATED

Tutte le definizioni di indice superiori a questa riga sono considerate controllate manualmente e non vengono aggiornate dal server web di sviluppo. Il server web apporta modifiche solo al di sotto della riga e solo se il file index.yaml completo non descrive un indice che tiene conto di una query eseguita dall'applicazione. Per assumere il controllo di una definizione automatica dell'indice, spostala sopra questa riga.

L'emulatore potrebbe aggiornare le definizioni esistenti sotto questa riga mentre l'applicazione effettua le query. Se l'app genera tutte le query che esegue durante il test, le voci generate in index.yaml saranno complete. Potrebbe essere necessario modificare manualmente il file per eliminare gli indici non utilizzati in produzione o definire gli indici che non sono stati creati durante il test.

Deployment del file di configurazione dell'indice

Per il deployment del file di configurazione index.yaml, esegui questo comando:

gcloud app deploy index.yaml

Eliminazione degli indici inutilizzati

Quando modifichi o rimuovi un indice dalla configurazione dell'indice, l'indice originale non viene eliminato automaticamente da App Engine. In questo modo hai la possibilità di lasciare in esecuzione una versione precedente dell'app mentre sono in corso la creazione di nuovi indici 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 non siano più necessari, puoi eliminarli da App Engine nel seguente modo:

gcloud datastore indexes cleanup index.yaml