Query di proiezione

La maggior parte delle query Datastore restituisce entità intere come risultati, ma spesso un'applicazione è interessata solo ad alcune delle proprietà dell'entità. Le query di proiezione consentono di eseguire query su Datastore solo per le proprietà specifiche di un'entità di cui hai effettivamente bisogno, con una latenza e un costo inferiori rispetto al recupero dell'intera entità.

Le query di proiezione sono simili alle query SQL del modulo:

SELECT name, email, phone FROM CUSTOMER

Puoi utilizzare tutte le funzionalità di filtro e ordinamento disponibili per le query di entità standard, soggette alle limitazioni descritte di seguito. La query restituisce risultati abbreviati con solo le proprietà specificate (nell'esempio name, email e phone) compilate con i valori; tutte le altre proprietà non contengono dati.

Utilizzo delle query di proiezione

Quando prepari una Query, specifica una proiezione utilizzando il Project metodo:

q := datastore.NewQuery("People").Project("FirstName", "LastName")

Gestisci i risultati di queste query come faresti per una query di entità standard, ad esempio scorrendo i risultati.

Il seguente esempio esegue una query sulle proprietà Title, ReadPath e DateWritten di tutte le voci EventLog, ordinate in ordine crescente per DateWritten, e scrive il valore di ogni proprietà nel log dell'applicazione:

q := datastore.NewQuery("EventLog").
	Project("Title", "ReadPath", "DateWritten").
	Order("DateWritten")
t := q.Run(ctx)
for {
	var l EventLog
	_, err := t.Next(&l)
	if err == datastore.Done {
		break
	}
	if err != nil {
		log.Errorf(ctx, "Running query: %v", err)
		break
	}
	log.Infof(ctx, "Log record: %v, %v, %v", l.Title, l.ReadPath, l.DateWritten)
}

Raggruppamento(sperimentale)

Le query di proiezione possono utilizzare il Distinct metodo per garantire che in un insieme di risultati vengano restituiti solo risultati completamente univoci. Verrà restituito solo il primo risultato per le entità che hanno gli stessi valori per le proprietà di cui viene eseguita la proiezione.

q := datastore.NewQuery("Person").
	Project("LastName", "Height").Distinct().
	Filter("Height >", 20).
	Order("-Height").Order("LastName")

Limitazioni delle proiezioni

Le query di proiezione sono soggette alle seguenti limitazioni:

  • È possibile proiettare solo le proprietà indicizzate.

    La proiezione non è supportata per le proprietà non indicizzate, né esplicitamente né implicitamente. Le stringhe più lunghe di 1500 byte e gli array di byte con più di 1500 elementi non sono indicizzati.

  • Non è possibile proiettare la stessa proprietà più di una volta.

  • Non è possibile proiettare le proprietà a cui viene fatto riferimento in un filtro di uguaglianza (=) .

    Ad esempio,

    SELECT A FROM kind WHERE B = 1
    

    è valido (la proprietà proiettata non viene utilizzata nel filtro di uguaglianza), così come

    SELECT A FROM kind WHERE A > 1
    

    (non è un filtro di uguaglianza), ma

    SELECT A FROM kind WHERE A = 1
    

    (la proprietà proiettata viene utilizzata nel filtro di uguaglianza) non è valida.

  • I risultati restituiti da una query di proiezione non devono

    Poiché la query restituisce risultati compilati solo parzialmente, non dovresti non scriverli di nuovo in Datastore.

Proiezioni e proprietà con più valori

La proiezione di una proprietà con più valori non compila tutti i valori per quella proprietà. Viene invece restituita un'entità separata per ogni combinazione univoca di valori proiettati che corrisponde alla query. Supponiamo, ad esempio, di avere un'entità di tipo Foo con due proprietà con più valori, A e B:

entity := Foo{A: []int{1, 1, 2, 3}, B: []string{"x", "y", "x"}}

La query di proiezione

q := datastore.NewQuery("Foo").Project("A", "B").Filter("A <", 3)

restituirà quattro entità con le seguenti combinazioni di valori:

A = 1, B = 'x'
A = 1, B = 'y'
A = 2, B = 'x'
A = 2, B = 'y'

Tieni presente che se un'entità ha una proprietà con più valori senza valori, non verranno incluse voci nell'indice e non verranno restituiti risultati per l'entità da una query di proiezione che include la proprietà.

Indici per le proiezioni

Le query di proiezione richiedono che tutte le proprietà specificate nella proiezione siano incluse in un indice Datastore index. Il server di sviluppo di App Engine genera automaticamente gli indici necessari nel file di configurazione degli indici, index.yaml, che viene caricato con l'applicazione.

Un modo per ridurre al minimo il numero di indici richiesti è proiettare le stesse proprietà in modo coerente, anche quando non sono sempre tutte necessarie. Ad esempio, queste query richiedono due indici separati:

SELECT A, B FROM Kind
SELECT A, B, C FROM Kind

Tuttavia, se proietti sempre le proprietà A, B e C, anche quando C non è obbligatoria, sarà necessario un solo indice.

La conversione di una query esistente in una query di proiezione potrebbe richiedere la creazione di un nuovo indice se le proprietà nella proiezione non sono già incluse in un'altra parte della query. Supponiamo, ad esempio, di avere una query esistente come

SELECT * FROM Kind WHERE A > 1 ORDER BY A, B

che richiede l'indice

Index(Kind, A, B)

La conversione in una delle query di proiezione

SELECT C FROM Kind WHERE A > 1 ORDER BY A, B
SELECT A, B, C FROM Kind WHERE A > 1 ORDER BY A, B

introduce una nuova proprietà (C) e quindi richiederà la creazione di un nuovo indice Index(Kind, A, B, C). Tieni presente che la query di proiezione

SELECT A, B FROM Kind WHERE A > 1 ORDER BY A, B

non modificherebbe l'indice richiesto, poiché le proprietà proiettate A e B erano già incluse nella query esistente.