Riferimento index.yaml

Puoi utilizzare Firestore in modalità Datastore (Datastore) per archiviare i dati delle tue applicazioni in esecuzione nell'ambiente standard. Utilizzi di Datastore indici per ogni query effettuata dalla tua applicazione. Questi indici vengono aggiornati ogni volta che cambia l'entità, in modo che i risultati possano essere restituiti rapidamente quando l'app query. Per farlo, Datastore deve sapere in anticipo quali le query eseguite dall'applicazione. Devi specificare gli indici di cui ha bisogno la tua app in un file di configurazione 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 eseguita da un'applicazione richiede un indice corrispondente. Gli indici per query semplici, ad esempio query su una singola proprietà, vengono creati automaticamente. È necessario definire gli indici per le query complesse 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 ulteriori informazioni al riguardo, consulta il sito web di YAML per maggiori informazioni.

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 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, 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. Questa operazione è obbligatoria 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 contiene una clausola ANCESTOR (Query.ancestor() o una clausola GQL ANCESTOR IS). Il valore predefinito è no.

Creazione dei file di indice

Puoi creare un file di indicizzazione 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 dell'app a livello locale. Puoi combinare i due metodi.

Quando esegui 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 viene generato automaticamente Verrà visualizzato index.yaml file.

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 degli indici 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 lo farà solo se l'intero Il file index.yaml non descrive un indice che spiega una query eseguita dall'applicazione. Per assumere il controllo di una definizione di indice automatica, spostala al di sopra di questa riga.

L'emulatore potrebbe aggiornare le definizioni esistenti sotto questa riga quando esegue query. Se l'app genera ogni query che effettuerà 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 o per definire gli indici non creati durante il test.

Eseguire il deployment del file di configurazione dell'indice

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, non venga 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 siano più necessari, puoi eliminarli da App Engine nel seguente modo:

gcloud datastore indexes cleanup index.yaml