Indici Datastore

Go Java PHP Python

App Engine predefinisce un indice semplice su ogni proprietà di un'entità. Un'applicazione App Engine può definire ulteriori indici personalizzati in un file di configurazione dell'indice denominato index.yaml. Il server di sviluppo aggiunge automaticamente suggerimenti a questo file quando rileva query che non possono essere eseguite con gli indici esistenti. Puoi ottimizzare gli indici manualmente modificando il file prima di caricare l'applicazione.

Nota: il meccanismo di query basato su indici supporta un'ampia gamma di query ed è adatto alla maggior parte delle applicazioni. Tuttavia, non supporta alcuni tipi di query comuni in altre tecnologie di database: in particolare, le query di join e aggregate non sono supportate nel motore di query di Datastore. Consulta la pagina Query di Datastore per le limitazioni delle query di Datastore.

Definizione e struttura dell'indice

Un indice è definito su un elenco di proprietà di un determinato tipo di entità, con un ordine corrispondente (crescente o decrescente) per ogni proprietà. Per l'utilizzo con le query dei predecessori, l'indice può anche includere facoltativamente i predecessori di un'entità.

Una tabella di indici contiene una colonna per ogni proprietà denominata nella definizione dell'indice. Ogni riga della tabella rappresenta un'entità in Datastore che è un potenziale risultato per le query basate sull'indice. Un'entità è inclusa nell'indice solo se ha un valore indicizzato impostato per ogni proprietà utilizzata nell'indice; se la definizione dell'indice fa riferimento a una proprietà per la quale l'entità non ha un valore, l'entità non verrà visualizzata nell'indice e quindi non verrà mai restituita come risultato per qualsiasi query basata sull'indice.

Le righe di una tabella di indici vengono ordinate prima per predecessore e poi per valori delle proprietà, nell'ordine specificato nella definizione dell'indice. L'indice perfetto per una query, che consente di eseguire la query in modo più efficiente, è definito sulle seguenti proprietà, in ordine:

1. Proprietà utilizzate nei filtri di uguaglianza
2. Proprietà utilizzata in un filtro di disuguaglianza (di cui non può essercene più di una)
3. Proprietà utilizzate negli ordinamenti

In questo modo, tutti i risultati per ogni possibile esecuzione della query vengono visualizzati in righe consecutive della tabella. Datastore esegue una query utilizzando un indice perfetto seguendo questi passaggi:

1. Identifica l'indice corrispondente al tipo, alle proprietà del filtro, agli operatori di filtro e agli ordinamenti della query.
2. Esegue la scansione dall'inizio dell'indice alla prima entità che soddisfa tutte le condizioni di filtro della query.
3. Continua a eseguire la scansione dell'indice, restituendo ogni entità a turno, finché
   • non rileva un'entità che non soddisfa le condizioni di filtro oppure
   • non raggiunge la fine dell'indice oppure
   • non ha raccolto il numero massimo di risultati richiesti dalla query.

Ad esempio, considera la seguente query:

SELECT * FROM Person WHERE LastName = "Smith"
                       AND Height < 72
                  ORDER BY Height DESC

L'indice perfetto per questa query è una tabella di chiavi per le entità di tipo Person, con colonne per i valori delle proprietà LastName e Height . L'indice viene ordinato prima in ordine crescente per LastName e poi in ordine decrescente per Height.

Per generare questi indici, configurali come segue:

indexes:
- kind: Person
  properties:
  - name: LastName
    direction: asc
  - name: Height
    direction: desc

Due query della stessa forma ma con valori di filtro diversi utilizzano lo stesso indice. Ad esempio, la seguente query utilizza lo stesso indice di quella sopra:

SELECT * FROM Person WHERE LastName = "Jones"
                       AND Height < 63
                     ORDER BY Height DESC

Anche le due query seguenti utilizzano lo stesso indice, nonostante le forme diverse:

SELECT * FROM Person WHERE LastName = "Friedkin"
                       AND FirstName = "Damian"
                     ORDER BY Height ASC

e

SELECT * FROM Person WHERE LastName = "Blair"
                  ORDER BY FirstName, Height ASC

Attenzione: l'utilizzo di un indice perfetto può aumentare notevolmente il costo della scrittura delle entità, soprattutto nel caso di indici esplosivi.

Configurazione degli indici

Per impostazione predefinita, Datastore predefinisce automaticamente un indice per ogni proprietà di ogni tipo di entità. Questi indici predefiniti sono sufficienti per eseguire molte query semplici, come le query solo di uguaglianza e le query di disuguaglianza semplici. Per tutte le altre query, l'applicazione deve definire gli indici di cui ha bisogno in un file di configurazione dell'indice denominato index.yaml. Se l'applicazione tenta di eseguire una query che non può essere eseguita con gli indici disponibili (predefiniti o specificati nel file di configurazione dell'indice), la query non andrà a buon fine.

Datastore crea indici automatici per le query dei seguenti moduli:

• Query senza tipo che utilizzano solo filtri di predecessore e chiave
• Query che utilizzano solo filtri di predecessore e uguaglianza
• Query che utilizzano solo filtri di disuguaglianza (che sono limitati a una singola proprietà)
• Query che utilizzano solo filtri di predecessore, filtri di uguaglianza sulle proprietà e filtri di disuguaglianza sulle chiavi
• Query senza filtri e con un solo ordinamento su una proprietà, crescente o decrescente

Altre forme di query richiedono che gli indici siano specificati nel file di configurazione dell'indice, tra cui:

• Query con filtri di predecessore e disuguaglianza
• Query con uno o più filtri di disuguaglianza su una proprietà e uno o più filtri di uguaglianza su altre proprietà
• Query con un ordinamento sulle chiavi in ordine decrescente
• Query con più ordinamenti

Nota: Datastore suggerisce automaticamente gli indici che sono appropriati per la maggior parte delle applicazioni. A seconda dell'utilizzo da parte dell'applicazione Datastore, dimensioni e forma dei dati, regolazioni manuali ai tuoi indici possono essere garantiti. Ad esempio, scrivere entità con più dei valori delle proprietà può causare un indice esplosivo con valori e scrivere i costi.

Nota: il server web di sviluppo può semplificare la gestione dell'indice di configurazione del deployment. Invece di non riuscire a eseguire una query che richiede un indice e non ne ha uno, il server web di sviluppo può generare un indice che consentirebbe il completamento della query. Se il test locale di un l'applicazione esegue ogni possibile query inviata dall'applicazione, utilizzando ogni combinazione di filtro e ordinamento, le voci generate rappresenteranno un insieme completo di indici. Se il test non si esercita ogni possibile modulo di query, puoi rivedere e modificare il file di configurazione dell'indice prima caricare l'applicazione.

Indici e proprietà

Di seguito sono riportate alcune considerazioni speciali da tenere presente sugli indici e sul loro rapporto con le proprietà delle entità in Datastore:

Proprietà con tipi di valori misti

Quando due entità hanno proprietà con lo stesso nome ma tipi di valori diversi, un indice della proprietà ordina le entità prima per tipo di valore e poi per un ordinamento secondario appropriato per ogni tipo. Ad esempio, se due entità hanno ciascuna una proprietà denominata age, una con un valore intero e una con un valore stringa, l'entità con il valore intero precede sempre quella con il valore stringa quando viene ordinata in base alla proprietà age, indipendentemente dai valori delle proprietà stesse.

Questo è particolarmente importante nel caso di numeri interi e numeri in rappresentazione in virgola mobile, che vengono trattati come tipi separati da Datastore. Poiché tutti i numeri interi vengono ordinati prima di tutti i numeri in virgola mobile, una proprietà con il valore intero 38 viene ordinata prima di una con il valore in virgola mobile 37.5.

Proprietà non indicizzate

Se sai che non dovrai mai filtrare o ordinare in base a una determinata proprietà, puoi indicare a Datastore di non gestire le voci di indice per quella proprietà dichiarandola non indicizzata. In questo modo, il costo di esecuzione dell'applicazione viene ridotto diminuendo il numero di scritture di Datastore che deve eseguire. Un'entità con una proprietà non indicizzata si comporta come se la proprietà non fosse impostata: le query con un filtro o un ordinamento sulla proprietà non indicizzata non corrisponderanno mai a questa entità.

Nota: se una proprietà viene visualizzata in un indice composto da più proprietà e impostandola su Non indicizzato, non verrà indicizzata nell'indice composto.

Ad esempio, supponiamo che un'entità abbia le proprietà a e b e che tu voglia creare un indice in grado di soddisfare query come WHERE a ="bike" and b="red". Supponiamo inoltre che le query WHERE a="bike" e WHERE b="red" non ti interessino. Se imposti a su Non indicizzato e crei un indice per a e b, il datastore non creerà voci di indice per gli indici a e b e, di conseguenza, la query WHERE a="bike" and b="red" non funzionerà. Affinché Datastore crei voci per gli indici a e b, sia a che b devono essere indicizzati.

Nota: oltre a qualsiasi proprietà non indicizzata dichiarata esplicitamente, quelle digitate come []byte sono trattate automaticamente come non indicizzate.

Per dichiarare una proprietà non indicizzata, imposta noindex nel tag del campo struct:

type Person struct {
	Name string
	Age  int `datastore:",noindex"`
}

Tieni presente, tuttavia, che la modifica di una proprietà da non indicizzata a indicizzata non influisce sulle entità esistenti che potrebbero essere state create prima della modifica. Le query che filtrano la proprietà non restituiranno queste entità esistenti, perché le entità non sono state scritte nell'indice della query al momento della creazione. Per rendere le entità accessibili dalle query future, devi riscriverle in Datastore in modo che vengano inserite negli indici appropriati. Ovvero, devi eseguire le seguenti operazioni per ogni entità esistente:

1. Recupera (ottieni) l'entità da Datastore.
2. Scrivi (inserisci) l'entità di nuovo in Datastore.

Allo stesso modo, la modifica di una proprietà da indicizzata a non indicizzata influisce solo sulle entità scritte successivamente in Datastore. Le voci di indice per le entità esistenti con quella proprietà continueranno a esistere finché le entità non vengono aggiornate o eliminate. Per evitare risultati indesiderati, devi eliminare dal codice tutte le query che filtrano o ordinano in base alla proprietà (ora non indicizzata).

Limiti degli indici

Datastore impone limiti al numero e alle dimensioni complessive delle voci di indice che possono essere associate a una singola entità. Questi limiti sono elevati e la maggior parte delle applicazioni non ne risente. Tuttavia, in alcune circostanze potresti riscontrare i limiti.

Come descritto sopra, Datastore crea una voce in un indice predefinito per ogni proprietà di ogni entità, tranne per []byte e quelle che hai dichiarato esplicitamente come non indicizzate. La proprietà può anche essere inclusa in altri indici personalizzati dichiarati nel file di configurazione di index.yaml. Se un'entità non ha proprietà elenco, avrà al massimo una voce in ciascun indice personalizzato (per gli indici non predecessori) o una per ciascuno dei predecessori dell'entità (per gli indici dei predecessori). Ognuna di queste voci di indice va aggiornata ogni volta che cambia il valore della proprietà.

Per una proprietà che ha un singolo valore per ogni entità, ogni valore possibile deve essere archiviato una sola volta per entità nell'indice predefinito della proprietà. Anche in questo caso, è possibile che un'entità con un numero elevato di proprietà a valore singolo superi il limite di voci o dimensioni dell'indice. Allo stesso modo, un'entità che può avere più valori per la stessa proprietà richiede una voce di indice separata per ogni valore; anche in questo caso, se il numero di valori possibili è elevato, un'entità di questo tipo può superare il limite di voci.

La situazione peggiora nel caso di entità con più proprietà, ognuna delle quali può assumere più valori. Per ospitare un'entità di questo tipo, l'indice deve includere una voce per ogni possibile combinazione di valori delle proprietà. Gli indici personalizzati che fanno riferimento a più proprietà, ognuna con più valori, possono "esplodere" in modo combinatorio, richiedendo un numero elevato di voci per un'entità con un numero relativamente piccolo di valori di proprietà possibili. Questi indici esplosivi possono aumentare notevolmente il costo della scrittura di un'entità in Datastore, a causa del numero elevato di voci di indice che devono essere aggiornate, e possono anche facilmente far sì che l'entità superi il limite di voci o dimensioni dell'indice.

Considera la query

SELECT * FROM Widget WHERE X=1 AND Y=2 ORDER BY Date

che fa sì che l'SDK suggerisca il seguente indice:

indexes:
- kind: Widget
  properties:
  - name: X
  - name: Y
  - name: Date

Questo indice richiede un totale di |X| * |Y| * |Date| voci per ogni entità (dove |X| indica il numero di valori associati all'entità per la proprietà X). Ad esempio, il codice seguente

type Widget struct {
	X    []int
	Y    []string
	Date time.Time
}

func f(ctx context.Context) {
	e2 := &Widget{
		X:    []int{1, 2, 3, 4},
		Y:    []string{"red", "green", "blue"},
		Date: time.Now(),
	}

	k := datastore.NewIncompleteKey(ctx, "Widget", nil)
	if _, err := datastore.Put(ctx, k, e2); err != nil {
		// Handle error.
	}
}

crea un'entità con quattro valori per la proprietà x, tre valori per la proprietà y e date impostata sulla data corrente. Sono necessarie 12 voci di indice, una per ogni combinazione possibile di valori delle proprietà:

(1, "red", <now>) (1, "green", <now>) (1, "blue", <now>)

(2, "red", <now>) (2, "green", <now>) (2, "blue", <now>)

(3, "red", <now>) (3, "green", <now>) (3, "blue", <now>)

(4, "red", <now>) (4, "green", <now>) (4, "blue", <now>)

Quando la stessa proprietà viene ripetuta più volte, Datastore può rilevare gli indici esplosivi e suggerire un indice alternativo. Tuttavia, in tutte le altre circostanze (ad esempio la query definita in questo esempio), Datastore genererà un indice enorme. In questo caso, puoi aggirare l'indice enorme configurando manualmente un indice nel file di configurazione dell'indice:

indexes:
- kind: Widget
  properties:
  - name: X
  - name: Date
- kind: Widget
  properties:
  - name: Y
  - name: Date

In questo modo, il numero di voci necessarie viene ridotto a (|X| * |Date| + |Y| * |Date|), ovvero 7 voci anziché 12:

(1, <now>) (2, <now>) (3, <now>) (4, <now>)

("red", <now>) ("green", <now>) ("blue", <now>)

un errore. Il testo dell' errore descrive quale limite è stato superato ("Too many indexed properties" o "Index entries too large") e quale indice personalizzato ne è la causa. Se crei un nuovo indice che supererebbe i limiti per qualsiasi entità al momento della creazione, le query sull'indice non andranno a buon fine e l'indice verrà visualizzato nello stato Error nella Google Cloud console. Per risolvere gli indici nello stato Error:

1. Rimuovi l'indice nello stato Error dal file index.yaml.

2. Esegui il comando seguente dalla directory in cui si trova index.yaml per rimuovere l'indice da Datastore:

   gcloud datastore indexes cleanup index.yaml
   

3. Risolvi la causa dell'errore. Ad esempio:

   • Riformula la definizione dell'indice e le query corrispondenti.
   • Rimuovi le entità che causano l'esplosione dell'indice.

4. Aggiungi di nuovo l'indice al file index.yaml.

5. Esegui il comando seguente dalla directory in cui si trova index.yaml per creare l'indice in Datastore:

   gcloud datastore indexes create index.yaml
   

Puoi evitare gli indici esplosivi evitando le query che richiedono un indice personalizzato che utilizza una proprietà elenco. Come descritto sopra, sono incluse le query con più ordinamenti o le query con una combinazione di filtri di uguaglianza e disuguaglianza.