Configurazione degli indici datastore con index.yaml

Puoi utilizzare Firestore in modalità Datastore (Datastore) per archiviare i dati delle tue applicazioni in esecuzione nell'ambiente standard. 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'app esegue una query. Per farlo, Datastore deve sapere in anticipo quali le query eseguite dall'applicazione. Puoi specificare gli indici richiesti dalla tua app in un di configurazione di index.yaml. Puoi utilizzare l'emulatore Datastore per generare automaticamente il file durante il test dell'app o scriverlo autonomamente. Il file index.yaml deve essere caricato quando esegui il deployment dell'app.

Informazioni su index.yaml

Ogni query Datastore effettuata da un'applicazione richiede un indice corrispondente. Indici per query semplici, ad esempio query su un singolo vengono create automaticamente. Gli indici per le query complesse devono essere definiti in un file di configurazione denominato index.yaml. Questo file viene caricato con per creare indici in Datastore.

Di seguito è riportato un esempio di 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, visita il sito web di YAML.

Definizioni degli indici

index.yaml ha un singolo elemento dell'elenco chiamato indexes. Ogni elemento dell'elenco rappresenta un indice 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, nell'ordine da includere ordinate: prima le proprietà utilizzate nei filtri di uguaglianza e poi quelle utilizzate nei filtri di disuguaglianza, poi all'ordinamento e alle relative direzioni.

Ogni elemento dell'elenco contiene i seguenti elementi:

name
Il nome 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 ha una clausola predecessore (Query.setAncestor). Il valore predefinito è no.

Creazione dei file di indice

Puoi creare un file di indice manualmente utilizzando un editor di testo e seguendo le layout di file descritto sopra. Un approccio più efficiente è quello di e generare il file mentre testi l'app localmente. Puoi combinare i due metodi.

Quando esegui i test nel tuo ambiente locale, puoi utilizzare comando gcloud emulator avviare un servizio che emula Datastore prima di eseguire dell'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 dell'app, ogni volta che generi una query Datastore, l'emulatore aggiunge una definizione di indice generata a index.yaml. Tutte le definizioni degli indici generate automaticamente verranno visualizzate nel file sotto la seguente riga:

# AUTOGENERATED

Tutte le definizioni dell'indice sopra questa riga sono considerate manuali e non vengono aggiornati dal server web di sviluppo. Il server web apporta modifiche solo sotto la riga e lo fa 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 di indice automatico, spostala sopra questa riga.

L'emulatore potrebbe aggiornare le definizioni esistenti sotto questa riga man mano che l'applicazione esegue query. Se l'app genera ogni query che eseguirà durante il test, le voci generate in index.yaml saranno complete. Potresti dover modificare manualmente il file per eliminare gli indici non utilizzati in produzione, oppure per per definire gli indici che non sono stati creati durante il test.

Eseguire il deployment del file di configurazione dell'indice

Il file index.yaml può trovarsi in qualsiasi posizione della directory del codice sorgente.

Per eseguire il deployment del file senza modificare la versione attualmente pubblicata, utilizza uno dei seguenti comandi nella directory contenente il file di indice, a seconda del tuo ambiente:

gcloud

gcloud app deploy index.yaml

Maven

mvn appengine:deployIndex index.yaml

Gradle

gradle appengineDeployIndex index.yaml

IDE

Se utilizzi IntelliJ o Eclipse, tu selezionare i singoli file di configurazione di cui eseguire il deployment modulo di deployment.

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 durante la creazione di nuovi indici 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 non sono più necessari, puoi eliminarli da App Engine nel seguente modo:

gcloud datastore indexes cleanup index.yaml