Query Datastore

Una query Datastore recupera le entità da Datastore che soddisfano un insieme specificato di condizioni.

Una query tipica include quanto segue:

  • Un tipo di entità a cui si applica la query
  • _Filtri_ facoltativi basati sui valori delle proprietà, sulle chiavi e sui predecessori delle entità
  • _Ordinamenti_ facoltativi per sequenziare i risultati

Quando viene eseguita, una query recupera tutte le entità del tipo specificato che soddisfano tutti i filtri indicati, ordinate nell'ordine specificato. Le query vengono eseguite in modalità di sola lettura.

Questa pagina descrive la struttura e i tipi di query utilizzati in App Engine per recuperare i dati da Datastore.

Filtri

I filtri di una query impostano vincoli sulle proprietà, sulle chiavi e sui predecessori delle entità da recuperare.

Filtri delle proprietà

Un filtro delle proprietà specifica

  • Un nome della proprietà
  • Un operatore di confronto
  • Un valore della proprietà
Ad esempio:

q := datastore.NewQuery("Person").Filter("Height <=", maxHeight)

Il valore della proprietà deve essere fornito dall'applicazione; non può fare riferimento ad altre proprietà o essere calcolato in base a queste. Un'entità soddisfa il filtro se ha una proprietà con il nome specificato il cui valore viene confrontato con il valore indicato nel filtro nel modo descritto dall'operatore di confronto.

L'operatore di confronto può essere uno dei seguenti:

Operatore Significato
= Uguale a
< Minore di
<= Minore o uguale a
> Maggiore di
>= Maggiore o uguale a

Filtri principali

Per filtrare in base al valore della chiave di un'entità, utilizza la proprietà speciale __key__:

q := datastore.NewQuery("Person").Filter("__key__ >", lastSeenKey)

Quando si confrontano le chiavi per la disuguaglianza, vengono ordinate in base ai seguenti criteri, in ordine:

  1. Percorso del predecessore
  2. Tipo di entità
  3. Identificatore (nome della chiave o ID numerico)

Gli elementi del percorso del predecessore vengono confrontati in modo simile: per tipo (stringa), quindi per nome della chiave o ID numerico. I tipi e i nomi delle chiavi sono stringhe e vengono ordinati in base al valore dei byte; gli ID numerici sono numeri interi e vengono ordinati numericamente. Se le entità con lo stesso elemento principale e tipo utilizzano una combinazione di stringhe di nomi di chiavi e ID numerici, quelle con ID numerici precedono quelle con nomi di chiavi.

Le query sulle chiavi utilizzano gli indici proprio come le query sulle proprietà e richiedono indici personalizzati negli stessi casi, con un paio di eccezioni: i filtri di disuguaglianza o un ordinamento crescente sulla chiave non richiedono un indice personalizzato, ma un ordinamento decrescente sulla chiave sì. Come per tutte le query, il server web di sviluppo crea le voci appropriate nel file di configurazione dell'indice quando viene testata una query che richiede un indice personalizzato.

Filtri dei predecessori

Puoi filtrare le query Datastore in base a un predecessore specificato in modo che i risultati restituiti includano solo le entità discendenti da quel predecessore:

q := datastore.NewQuery("Person").Ancestor(ancestorKey)

Tipi di query speciali

Alcuni tipi specifici di query meritano una menzione speciale:

Query senza tipo

Una query senza tipo e senza filtro del predecessore recupera tutte le entità di un'applicazione da Datastore. Sono incluse le entità create e gestite da altre funzionalità di App Engine, come le entità statistiche e entità di metadati Blobstore (se presenti). Queste query senza tipo non possono includere filtri o ordinamenti sui valori delle proprietà. Possono, tuttavia, filtrare le chiavi delle entità specificando __key__ come nome della proprietà:

q := datastore.NewQuery("").Filter("__key__ >", lastSeenKey)

Query dei predecessori

Una query con un filtro del predecessore limita i risultati all'entità specificata e ai relativi discendenti:

// Create two Photo entities in the datastore with a Person as their ancestor.
tomKey := datastore.NewKey(ctx, "Person", "Tom", 0, nil)

wPhoto := Photo{URL: "http://example.com/some/path/to/wedding_photo.jpg"}
wKey := datastore.NewKey(ctx, "Photo", "", 0, tomKey)
_, err := datastore.Put(ctx, wKey, wPhoto)
// check err

bPhoto := Photo{URL: "http://example.com/some/path/to/baby_photo.jpg"}
bKey := datastore.NewKey(ctx, "Photo", "", 0, tomKey)
_, err = datastore.Put(ctx, bKey, bPhoto)
// check err

// Now fetch all Photos that have tomKey as an ancestor.
// This will populate the photos slice with wPhoto and bPhoto.
q := datastore.NewQuery("Photo").Ancestor(tomKey)
var photos []Photo
_, err = q.GetAll(ctx, &photos)
// check err
// do something with photos

Query dei predecessori senza tipo

Una query senza tipo che include un filtro del predecessore recupererà il predecessore specificato e tutti i relativi discendenti, indipendentemente dal tipo. Questo tipo di query non richiede indici personalizzati. Come tutte le query senza tipo, non può includere filtri o ordinamenti sui valori delle proprietà, ma può filtrare la chiave dell'entità:

q := datastore.NewQuery("").Ancestor(ancestorKey).Filter("__key__ >", lastSeenKey)

L'esempio seguente illustra come recuperare tutte le entità discendenti da un determinato predecessore:

tomKey := datastore.NewKey(ctx, "Person", "Tom", 0, nil)

weddingPhoto := &Photo{URL: "http://example.com/some/path/to/wedding_photo.jpg"}
_, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Photo", tomKey), weddingPhoto)

weddingVideo := &Video{URL: "http://example.com/some/path/to/wedding_video.avi"}
_, err = datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Video", tomKey), weddingVideo)

// The following query returns both weddingPhoto and weddingVideo,
// even though they are of different entity kinds.
q := datastore.NewQuery("").Ancestor(tomKey)
t := q.Run(ctx)
for {
	var x interface{}
	_, err := t.Next(&x)
	if err == datastore.Done {
		break
	}
	if err != nil {
		log.Errorf(ctx, "fetching next Photo/Video: %v", err)
		break
	}
	// Do something (e.g. switch on types)
	doSomething(x)
}

Query basate solo su chiavi

Una query basata solo su chiavi restituisce solo le chiavi delle entità dei risultati anziché le entità stesse, con una latenza e un costo inferiori rispetto al recupero delle entità intere:

q := datastore.NewQuery("Person").KeysOnly()

Spesso è più economico eseguire prima una query basata solo su chiavi e poi recuperare un sottoinsieme di entità dai risultati, anziché eseguire una query generale che potrebbe recuperare più entità di quelle effettivamente necessarie.

Tieni presente che una query basata solo su chiavi può restituire più di 1000 risultati, ma GetAll può recuperare solo 1000 chiavi alla volta e genererà un errore se viene chiamata su un risultato più grande. Pertanto, ti consigliamo di aggiungere un limite di 1000 chiavi alla query.

Query di proiezione

A volte tutto ciò che ti serve dai risultati di una query sono i valori di alcune proprietà specifiche. In questi casi, puoi utilizzare una query di proiezione per recuperare solo le proprietà che ti interessano effettivamente, con una latenza e un costo inferiori rispetto al recupero dell'intera entità; per i dettagli, consulta la pagina Query di proiezione.

Ordinamenti

Un ordinamento di una query specifica

  • Un nome della proprietà
  • Una direzione di ordinamento (crescente o decrescente)

In Go, l'ordinamento decrescente è indicato da un trattino (-) che precede il nome della proprietà; se il trattino viene omesso, viene specificato l'ordinamento crescente per impostazione predefinita. Ad esempio:

// Order alphabetically by last name:
q := datastore.NewQuery("Person").Order("LastName")

// Order by height, tallest to shortest:
q = datastore.NewQuery("Person").Order("-Height")

Se una query include più ordinamenti, questi vengono applicati nella sequenza specificata. L'esempio seguente ordina prima in base al cognome in ordine crescente e poi in base all'altezza in ordine decrescente:

q := datastore.NewQuery("Person").Order("LastName").Order("-Height")

Se non vengono specificati ordinamenti, i risultati vengono restituiti nell'ordine in cui vengono recuperati da Datastore.

Nota: a causa del modo in cui Datastore esegue le query, se una query specifica filtri di disuguaglianza su una proprietà e ordinamenti su altre proprietà, la proprietà utilizzata nei filtri di disuguaglianza deve essere ordinata prima delle altre proprietà.

Indici

Ogni query Datastore calcola i risultati utilizzando uno o più indici, che contengono le chiavi delle entità in una sequenza specificata dalle proprietà dell'indice e, facoltativamente, dai predecessori dell'entità. Gli indici vengono aggiornati in modo incrementale per riflettere le modifiche apportate dall'applicazione alle relative entità, in modo che i risultati corretti di tutte le query siano disponibili senza ulteriori calcoli.

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 i 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.

Esempio di interfaccia di query

L'API Datastore Go fornisce un tipo Query per preparare ed eseguire le query.

type Person struct {
	FirstName string
	LastName  string
	City      string
	BirthYear int
	Height    int
}

func handle(w http.ResponseWriter, r *http.Request) {
	ctx := appengine.NewContext(r)

	// The Query type and its methods are used to construct a query.
	q := datastore.NewQuery("Person").
		Filter("LastName =", "Smith").
		Filter("Height <=", maxHeight).
		Order("-Height")

	// To retrieve the results,
	// you must execute the Query using its GetAll or Run methods.
	var people []Person
	if _, err := q.GetAll(ctx, &people); err != nil {
		// Handle error.
	}
	// ...
}

Passaggi successivi