Configurazione degli indici datastore con index.yaml

Puoi utilizzare Firestore in modalità Datastore (Datastore) per archiviare i dati per le tue applicazioni in esecuzione nell'ambiente standard. Datastore utilizza gli indici per ogni query eseguita dall'applicazione. Questi indici vengono aggiornati ogni volta che un'entità cambia, quindi i risultati possono essere restituiti rapidamente quando l'app esegue una query. A questo scopo, Datastore deve sapere in anticipo quali query eseguirà l'applicazione. Puoi specificare gli indici necessari per l'app in un file di configurazione index.yaml. Puoi utilizzare l'emulatore Datastore per generare il file automaticamente mentre testi l'app oppure puoi scrivere il file manualmente. Il file index.yaml deve essere caricato quando esegui il deployment dell'app.

Informazioni su `index.yaml`

Ogni query 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 delle query complesse devono essere definiti in un file di configurazione denominato index.yaml. Questo file viene caricato con l'applicazione 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 saperne di più 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. In genere, si tratta del nome della classe Model che definisce il modello per le entità. Questo elemento è obbligatorio.

properties

Un elenco di proprietà da includere come colonne dell'indice, 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 del datastore della proprietà.
direction: La direzione da ordinare, asc in senso crescente o desc in senso discendente. Questa operazione è obbligatoria solo per le proprietà utilizzate nell'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.ancestor() o una clausola GQL ANCESTOR IS). Il valore predefinito è no.

Creazione di file di indice in corso...

Puoi creare un file di indice manualmente, utilizzando un editor di testo e seguendo il layout del file descritto sopra. Un approccio più efficiente è generare automaticamente il file quando testi la tua app a livello locale. Puoi combinare i due metodi.

Quando esegui dei test nel tuo ambiente locale, puoi utilizzare il comando gcloud emulator per avviare un servizio che emula Datastore prima di eseguire l'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.

Quando testi l'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 riga seguente:

# AUTOGENERATED

Tutte le definizioni di indice sopra questa riga sono considerate sotto controllo manuale e non vengono aggiornate dal server web di sviluppo. Il server web apporta modifiche solo sotto la 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 dell'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 esegue mentre la testi, le voci generate in index.yaml saranno complete. Potrebbe essere necessario modificare il file manualmente per eliminare gli indici non utilizzati in produzione o per definire gli indici che non sono stati creati durante il test.

Deployment del file di configurazione degli indici

Per eseguire 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. Ciò ti offre la possibilità di lasciare una versione precedente dell'app in esecuzione 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 siano più necessari, puoi eliminarli da App Engine nel seguente modo:

gcloud datastore indexes cleanup index.yaml