Nota: Python 2.7 ha raggiunto la fine del supporto il 31 gennaio 2024. Le applicazioni Python 2.7 esistenti continueranno a essere eseguite e a ricevere traffico. Tuttavia, App Engine potrebbe bloccare il ri deployment di applicazioni che utilizzano runtime dopo la data di fine del supporto. Ti consigliamo di eseguire la migrazione all'ultima versione supportata di Python.

Query di proiezione

Nota: gli sviluppatori che creano nuove applicazioni sono vivamente incoraggiati a utilizzare la libreria client NDB, che offre diversi vantaggi rispetto a questa libreria client, come la memorizzazione nella cache automatica delle entità tramite l'API Memcache. Se attualmente utilizzi la libreria client DB precedente, leggi la Guida alla migrazione dal database a NDB

La maggior parte delle query Datastore restituisce entità intere come risultati, ma spesso un'applicazione è effettivamente interessata solo ad alcune delle proprietà dell'entità. Le query di proiezione ti consentono di eseguire query su Datastore solo per quelle specifiche proprietà 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 nel formato:

SELECT name, email, phone FROM CUSTOMER

Puoi utilizzare tutte le funzionalità di filtro e ordinamento disponibili per le query di entità standard, fatte salve le limitazioni descritte di seguito. La query restituisce risultati ridotti in cui solo le proprietà specificate (name, email e phone nell'esempio) sono completate con i valori; tutte le altre proprietà non contengono dati.

Utilizzo delle query di proiezione in Python 2

Puoi specificare una proiezione in questo modo: Le query di proiezione sono supportate dagli oggetti Query e GqlQuery. Entrambi i corsi richiedono questa importazione:

from google.appengine.ext import db

Puoi specificare una proiezione nel seguente modo:

proj = db.Query(entity_name, projection=('property_1', 'property_2','property_n'))

proj = db.GqlQuery("SELECT property_1, property_2, property_n FROM entity_name")

Puoi gestire i risultati di queste query come faresti per una query di entità standard, ad esempio eseguendo l'iterazione dei risultati.

L'esempio seguente esegue una query per le proprietà title, read_path e date_written di tutte le voci EventLog, ordinate in ordine crescente in base al valore date_written, e scrive il valore di ogni proprietà nel log dell'applicazione:

for proj in db.GqlQuery("SELECT title, read_path, date_written" +
                        "FROM EventLog" +
                        "ORDER BY date_written ASC"):
  logging.info(proj.title)
  logging.info(proj.read_path)
  logging.info(proj.date_written)

Raggruppamento^{(sperimentale)}

Le query di proiezione possono utilizzare la parola chiave distinct per garantire che in un insieme di risultati vengano restituiti solo risultati completamente unici. Verrà restituito solo il primo risultato per le entità che hanno gli stessi valori per le proprietà di cui si esegue la proiezione.

query = db.Query(projection=['A', 'B'], distinct=True).filter('B >', 1).order('-B, A')

Limitazioni sulle proiezioni

Le query di proiezione sono soggette alle seguenti limitazioni:

È possibile prevedere soltanto le proprietà indicizzate.

La proiezione non è supportata per le proprietà che non vengono indicizzate, in modo esplicito o implicito. Le stringhe di testo lunghe (Text) e le stringhe di byte lunghi (Blob) non vengono indicizzate.
La stessa proprietà non può essere proiettata più di una volta.
Non è possibile prevedere le proprietà a cui viene fatto riferimento in un filtro di uguaglianza (=) o appartenenza (IN).

Ad esempio:
```
SELECT A FROM kind WHERE B = 1
```
(la proprietà prevista non viene utilizzata nel filtro di uguaglianza), così com'è
```
SELECT A FROM kind WHERE A > 1
```
(non un filtro di uguaglianza), ma
```
SELECT A FROM kind WHERE A = 1
```
(proprietà prevista utilizzata nel filtro di uguaglianza) non lo è.
I risultati restituiti da una query di proiezione non possono essere salvati in Datastore.

Poiché la query restituisce risultati che sono stati completati solo parzialmente, non è possibile scriverli in Datastore.

Proiezioni e proprietà a più valori

La proiezione di una proprietà con più valori non completerà tutti i valori per quella proprietà. Verrà invece restituita un'entità separata per ogni combinazione univoca di valori previsti che corrispondono alla query. Ad esempio, supponi di avere un'entità di tipo Foo con due proprietà a più valori, A e B:

entity = Foo(A=[1, 1, 2, 3], B=['x', 'y', 'x'])

Quindi la query di proiezione

SELECT A, B FROM Foo WHERE 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à a più valori senza valori, non verrà inclusa alcuna voce nell'indice e non verrà restituito nessun risultato per l'entità in questione da una query di proiezione che include quella proprietà.

Indici per le proiezioni

Le query di proiezione richiedono che tutte le proprietà specificate nella proiezione siano incluse in un indice Datastore. Il server di sviluppo App Engine genera automaticamente gli indici necessari nel file di configurazione dell'indice, index.yaml, che viene caricato insieme all'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 distinti:

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

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

La conversione di una query esistente in una query di proiezione può richiedere la creazione di un nuovo indice se le proprietà della proiezione non sono già incluse in un'altra parte della query. Ad esempio, supponiamo che tu abbia una query

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

che richiede l'indicizzazione

Index(Kind, A, B)

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 richiede quindi la creazione di un nuovo indice Index(Kind, A, B, C). Nota 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à previste A e B erano già incluse nella query esistente.