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 automatica nella cache delle entità tramite l'API Memcache. Se attualmente utilizzi la libreria client di DB precedente, leggi la guida alla migrazione da DB a NDB
La classe GqlQuery
rappresenta una query per recuperare entità
dall'App Engine Datastore utilizzando il linguaggio di query GQL, simile a SQL. Per una discussione completa sulla sintassi e sulle funzionalità di GQL, consulta la documentazione di GQL; vedi anche la classe correlata Query
, che utilizza oggetti e metodi, anziché GQL, per preparare le query.
GqlQuery
è definito nel modulo google.appengine.ext.db
.
Nota: il meccanismo di query basato su indice 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, join e query aggregate non sono supportati all'interno del motore di query di Datastore. Consulta la pagina Query Datastore per conoscere i limiti delle query Datastore.
Introduzione
Un'applicazione crea un oggetto query GQL chiamando direttamente il
costruttore GqlQuery
o il metodo della classe
gql()
della classe di modello di un tipo di entità. Il costruttore GqlQuery
prende come
argomento una stringa di query,ovvero un'istruzione GQL completa che inizia con
SELECT
...
FROM
model-name
. I valori nelle clausole WHERE
possono essere valori letterali numerici o di stringa oppure possono utilizzare l'associazione di parametri per i valori. I parametri possono essere associati utilizzando argomenti posizionali o di parole chiave:
q = GqlQuery("SELECT * FROM Song WHERE composer = 'Lennon, John'") q = GqlQuery("SELECT __key__ FROM Song WHERE composer = :1", "Lennon, John") q = GqlQuery("SELECT * FROM Song WHERE composer = :composer", composer="Lennon, John")
Per praticità, le classi Model
e Expando
hanno un metodo della classe gql()
che restituisce un'istanza GqlQuery
. Questo metodo accetta una stringa di query GQL senza il prefisso SELECT
...
FROM
model-name
, che è implicito:
q = Song.gql("WHERE composer = 'Lennon, John'")
L'applicazione può quindi eseguire la query e accedere ai risultati in uno dei seguenti modi:
-
Tratta l'oggetto query come iterabile, per elaborare le entità corrispondenti una alla volta:
for song in q: print song.title
Questa operazione chiama in modo implicito il metodo
run()
della query per generare le entità corrispondenti. Equivale quindi afor song in q.run(): print song.title
Puoi impostare un limite per il numero di risultati da elaborare con l'argomento parola chiave
limit
:for song in q.run(limit=5): print song.title
L'interfaccia Iterator non memorizza i risultati nella cache, quindi se crei un nuovo iteratore dall'oggetto query, la stessa query viene ripetuta dall'inizio.
-
Chiama il metodo
get()
della query per ottenere la prima singola entità corrispondente trovata in Datastore:song = q.get() print song.title
-
Chiama il metodo
fetch()
della query per ottenere un elenco di tutte le entità corrispondenti fino a un numero specificato di risultati:results = q.fetch(limit=5) for song in results: print song.title
Come nel caso di
run()
, l'oggetto query non memorizza i risultati nella cache, quindi chiamandofetch()
una seconda volta viene ripetuta la stessa query.Nota: raramente dovresti usare questo metodo; è quasi sempre meglio usare
run()
.
Costruttore
Il costruttore per la classe GqlQuery
è definito come segue:
- class GqlQuery (query_string, *args, **kwds)
-
Crea un'istanza di classe
GqlQuery
per recuperare entità da App Engine Datastore utilizzando il linguaggio di query GQL.Argomenti
- query_string
- Stringa contenente un'istruzione GQL completa.
- args
- Valori dei parametri posizionali.
- kwds
- Valori dei parametri parola chiave.
Metodi di istanza
Le istanze della classe GqlQuery
hanno i seguenti metodi:
- bind (*args, **kwds)
-
Riassocia i valori parametro della query. La query modificata verrà eseguita al primo accesso ai risultati dopo il rimbalzo dei relativi parametri.
Riassociare i parametri a un oggetto
GqlQuery
esistente è più veloce rispetto alla creazione di un nuovo oggettoGqlQuery
, perché non è necessario analizzare nuovamente la stringa di query.Argomenti
- args
- Nuovi valori dei parametri posizionali.
- kwds
- Nuovi valori dei parametri delle parole chiave.
- proiezione ()
-
Restituisce la tupla delle proprietà nella proiezione o
None
. - is_keys_only ()
-
Restituisce un valore booleano che indica se la query è composta da sole chiavi.
- run (read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policySTRONG_CONSISTENCYSTRONG_CONSISTENCYread_policy
-
Restituisce un comando iterabile per il loop dei risultati della query. Ciò consente di specificare l'operazione della query con le impostazioni dei parametri e di accedere ai risultati in modo iterativo:
- Recupera e ignora il numero di risultati specificato dall'argomento
offset
. - Recupera e restituisce il numero massimo di risultati specificato dall'argomento
limit
.
Il rendimento del loop viene quindi scalato in modo lineare con la somma di
offset
+limit
. Se sai quanti risultati vuoi recuperare, devi sempre impostare un valorelimit
esplicito.Questo metodo utilizza il precaricamento asincrono per migliorare le prestazioni. Per impostazione predefinita, recupera i risultati da Datastore in piccoli batch, consentendo all'applicazione di arrestare l'iterazione ed evitare di recuperare più risultati di quelli necessari.
Suggerimento: per recuperare tutti i risultati disponibili quando il loro numero è sconosciuto, imposta
batch_size
su un valore grande, ad esempio1000
.Suggerimento: se non devi modificare i valori dell'argomento predefiniti, puoi semplicemente utilizzare l'oggetto query direttamente come iterazione per controllare il loop. Questa operazione chiama implicitamente
run()
con argomenti predefiniti.Argomenti
- read_policy
- Leggi il criterio che specifica il livello desiderato di coerenza dei dati:
- STRONG_CONSISTENCY
- Garantisce i risultati più recenti, ma limitati a un singolo gruppo di entità.
- EVENTUAL_CONSISTENCY
- Può comprendere più gruppi di entità, ma a volte restituisce risultati inattivi. In generale, le query a coerenza finale vengono eseguite più velocemente rispetto a quelle a elevata coerenza, ma non c'è alcuna garanzia.
Nota: le query globali (non predecessori) ignorano questo argomento.
- scadenza
- Tempo massimo, in secondi, di attesa che Datastore restituisca un risultato prima di interrompere con un errore. Accetta un valore intero o in virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere modificato verso il basso per garantire che una determinata operazione non vada a buon fine rapidamente (ad esempio per restituire una risposta più rapida all'utente, riprovare a eseguire l'operazione, provare un'operazione diversa o aggiungerla a una coda di attività).
- offset
- Numero di risultati da saltare prima di restituire il primo.
- limite
- Numero massimo di risultati da restituire.
Se questo parametro viene omesso, verrà usato il valore specificato nella clausola
LIMIT
della stringa di query GQL. Se viene impostato esplicitamente suNone
, verranno recuperati tutti i risultati disponibili. - batch_size
- Numero di risultati da tentare di recuperare per batch. Se il criterio
limit
viene configurato, il valore predefinito corrisponde al limite specificato, altrimenti il valore predefinito è20
. - keys_only
- Se
true
, restituisce solo le chiavi anziché le entità complete. Le query solo chiavi sono più veloci ed economiche di quelle che restituiscono entità complete. - proiezione
- Elenco o tupla di nomi delle proprietà da restituire. Verranno restituite solo le entità che possiedono le proprietà specificate. Se non viene specificato, per impostazione predefinita vengono restituite intere entità.
Le query di proiezione sono più veloci ed economiche di quelle che restituiscono entità complete.
Nota: se specifichi questo parametro, i requisiti di indice della query potrebbero cambiare.
- start_cursor
- Posizione del cursore da cui iniziare la query.
- end_cursor
- Posizione del cursore alla quale terminare la query.
- Recupera e ignora il numero di risultati specificato dall'argomento
- get (read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY)
-
Esegue la query e restituisce il primo risultato oppure
None
se non viene trovato alcun risultato. Al massimo un risultato viene recuperato da Datastore; la clausolaLIMIT
della stringa di query GQL, se presente, viene ignorata.Argomenti
- read_policy
- Leggi il criterio che specifica il livello desiderato di coerenza dei dati:
- STRONG_CONSISTENCY
- Garantisce i risultati più recenti, ma limitati a un singolo gruppo di entità.
- EVENTUAL_CONSISTENCY
- Può comprendere più gruppi di entità, ma a volte restituisce risultati inattivi. In generale, le query a coerenza finale vengono eseguite più velocemente rispetto a quelle a elevata coerenza, ma non c'è alcuna garanzia.
Nota: le query globali (non predecessori) ignorano questo argomento.
- scadenza
- Tempo massimo, in secondi, di attesa che Datastore restituisca un risultato prima di interrompere con un errore. Accetta un valore intero o in virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere modificato verso il basso per garantire che una determinata operazione non vada a buon fine rapidamente (ad esempio per restituire una risposta più rapida all'utente, riprovare a eseguire l'operazione, provare un'operazione diversa o aggiungerla a una coda di attività).
- offset
- Numero di risultati da saltare prima di restituire il primo.
- keys_only
- Se
true
, restituisce solo le chiavi anziché le entità complete. Le query solo chiavi sono più veloci ed economiche di quelle che restituiscono entità complete. - proiezione
- Elenco o tupla di nomi delle proprietà da restituire. Verranno restituite solo le entità che possiedono le proprietà specificate. Se non viene specificato, per impostazione predefinita vengono restituite intere entità.
Le query di proiezione sono più veloci ed economiche di quelle che restituiscono entità complete.
Nota: se specifichi questo parametro, i requisiti di indice della query potrebbero cambiare.
- start_cursor
- Posizione del cursore da cui iniziare la query.
- end_cursor
- Posizione del cursore alla quale terminare la query.
- fetch (limit, read_policy=STRONG_CONSISTENCY, deadline=STRONG_CONSISTENCY, offset=STRONG_CONSISTENCY, keys_only=STRONG_CONSISTENCY, projection=STRONG_CONSISTENCY, start_cursor=STRONG_CONSISTENCY, end_cursor=STRONG_CONSISTENCY)
-
Esegue la query e restituisce un elenco di risultati (possibilmente vuoto):
- Recupera e ignora il numero di risultati specificato dall'argomento
offset
. - Recupera e restituisce il numero massimo di risultati specificato dall'argomento
limit
.
Il rendimento del metodo scala quindi in modo lineare con la somma di
offset
+limit
.Nota: questo metodo non è altro che un sottile wrapper per il metodo
run()
ed è meno efficiente e richiede più memoria rispetto all'utilizzo diretto dirun()
. Raramente dovrai usarefetch()
; viene fornito principalmente per praticità nei casi in cui devi recuperare un elenco completo in memoria dei risultati delle query.Suggerimento: il metodo
fetch()
è progettato per recuperare solo il numero di risultati specificato dall'argomentolimit
. Per recuperare tutti i risultati disponibili di una query quando il loro numero è sconosciuto, utilizzarun()
con una dimensione del batch elevata, ad esempiorun(batch_size=1000)
, anzichéfetch()
.Argomenti
- limite
- Numero massimo di risultati da restituire.
Se impostato su
None
, verranno recuperati tutti i risultati disponibili. - read_policy
- Leggi il criterio che specifica il livello desiderato di coerenza dei dati:
- STRONG_CONSISTENCY
- Garantisce i risultati più recenti, ma limitati a un singolo gruppo di entità.
- EVENTUAL_CONSISTENCY
- Può comprendere più gruppi di entità, ma a volte restituisce risultati inattivi. In generale, le query a coerenza finale vengono eseguite più velocemente rispetto a quelle a elevata coerenza, ma non c'è alcuna garanzia.
Nota: le query globali (non predecessori) ignorano questo argomento.
- scadenza
- Tempo massimo, in secondi, di attesa che Datastore restituisca un risultato prima di interrompere con un errore. Accetta un valore intero o in virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere modificato verso il basso per garantire che una determinata operazione non vada a buon fine rapidamente (ad esempio per restituire una risposta più rapida all'utente, riprovare a eseguire l'operazione, provare un'operazione diversa o aggiungerla a una coda di attività).
- offset
- Numero di risultati da saltare prima di restituire il primo.
- keys_only
- Se
true
, restituisce solo le chiavi anziché le entità complete. Le query solo chiavi sono più veloci ed economiche di quelle che restituiscono entità complete. - proiezione
- Elenco o tupla di nomi delle proprietà da restituire. Verranno restituite solo le entità che possiedono le proprietà specificate. Se non viene specificato, per impostazione predefinita vengono restituite intere entità.
Le query di proiezione sono più veloci ed economiche di quelle che restituiscono entità complete.
Nota: se specifichi questo parametro, i requisiti di indice della query potrebbero cambiare.
- start_cursor
- Posizione del cursore da cui iniziare la query.
- end_cursor
- Posizione del cursore alla quale terminare la query.
- Recupera e ignora il numero di risultati specificato dall'argomento
- count (read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY)
-
Restituisce il numero di risultati corrispondenti alla query. Questo è più veloce di un fattore costante rispetto al recupero effettivo di tutti i risultati, ma il tempo di esecuzione viene comunque scalato in modo lineare con la somma di
offset
+limit
. A meno che non si preveda un conteggio dei risultati ridotto, è meglio specificare un argomentolimit
; in caso contrario, il metodo continuerà fino al termine del conteggio o al timeout.Argomenti
- read_policy
- Leggi il criterio che specifica il livello desiderato di coerenza dei dati:
- STRONG_CONSISTENCY
- Garantisce i risultati più recenti, ma limitati a un singolo gruppo di entità.
- EVENTUAL_CONSISTENCY
- Può comprendere più gruppi di entità, ma a volte restituisce risultati inattivi. In generale, le query a coerenza finale vengono eseguite più velocemente rispetto a quelle a elevata coerenza, ma non c'è alcuna garanzia.
Nota: le query globali (non predecessori) ignorano questo argomento.
- scadenza
- Tempo massimo, in secondi, di attesa che Datastore restituisca un risultato prima di interrompere con un errore. Accetta un valore intero o in virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere modificato verso il basso per garantire che una determinata operazione non vada a buon fine rapidamente (ad esempio per restituire una risposta più rapida all'utente, riprovare a eseguire l'operazione, provare un'operazione diversa o aggiungerla a una coda di attività).
- offset
- Numero di risultati da saltare prima di conteggiare il primo.
- limite
- Numero massimo di risultati da conteggiare.
Nota: se specificato esplicitamente, questo parametro sostituisce qualsiasi valore impostato nella clausola
LIMIT
della stringa di query GQL. Tuttavia, se il parametro viene omesso, il valore predefinito di1000
non sostituisce la clausolaLIMIT
della query GQL e si applica solo se non è stata specificata nessuna clausolaLIMIT
. - start_cursor
- Posizione del cursore da cui iniziare la query.
- end_cursor
- Posizione del cursore alla quale terminare la query.
- index_list ()
-
Restituisce un elenco di indici utilizzati da una query eseguita, inclusi indici primari, composti, di tipo e a proprietà singola.
Attenzione: richiamando questo metodo su una query non ancora eseguita, si verifica un'eccezione
AssertionError
.Nota:questa funzionalità non è completamente supportata sul server di sviluppo. Se utilizzato con il server di sviluppo, il risultato è un elenco vuoto o un elenco contenente esattamente un indice composto.
Ad esempio, il seguente codice stampa varie informazioni sugli indici utilizzati da una query:
# other imports ... import webapp2 from google.appengine.api import users from google.appengine.ext import db class Greeting(db.Model): author = db.StringProperty() content = db.StringProperty(multiline=True) date = db.DateTimeProperty(auto_now_add=True) class MainPage(webapp2.RequestHandler): def get(self): user = users.get_current_user() q = db.GqlQuery(Greeting) q.filter("author =", user.user_id()) q.order("-date") q.fetch(100) index_list = q.index_list() for ix in index_list: self.response.out.write("Kind: %s" % ix.kind()) self.response.out.write("<br />") self.response.out.write("Has ancestor? %s" % ix.has_ancestor()) self.response.out.write("<br />") for name, direction in ix.properties(): self.response.out.write("Property name: "+name) self.response.out.write("<br />") if direction == db.Index.DESCENDING: self.response.out.write("Sort direction: DESCENDING") else: self.response.out.write("Sort direction: ASCENDING") self.response.out.write("<br />")
Questo produce un output come il seguente per ogni indice:
Kind: Greeting Has ancestor? False Property name: author Sort direction: ASCENDING Property name: date Sort direction: DESCENDING
- cursore ()
-
Restituisce una stringa cursore codificata in base64 che indica la posizione nel set di risultati della query dopo l'ultimo risultato recuperato. La stringa del cursore può essere utilizzata in sicurezza nei parametri HTTP
GET
ePOST
e può anche essere archiviata in Datastore o Memcache. Una chiamata futura della stessa query può fornire questa stringa tramite il parametrostart_cursor
o il metodowith_cursor()
per riprendere il recupero dei risultati da questa posizione.Attenzione: richiamando questo metodo su una query non ancora eseguita, si verifica un'eccezione
AssertionError
.Nota: non tutte le query sono compatibili con i cursori. Per ulteriori informazioni, consulta la pagina Query Datastore.
- with_cursor (start_cursor, start_cursor=Nessuno)
-
Specifica le posizioni iniziali e (facoltativamente) finali all'interno del set di risultati di una query da cui recuperare i risultati. Le stringhe del cursore che indicano le posizioni iniziale e finale possono essere ottenute richiamando
cursor()
dopo una precedente chiamata alla query. La query corrente deve essere identica a quella precedente, inclusi tipo di entità, filtri proprietà, filtri predecessori e ordinamento.Argomenti
- start_cursor
- Stringa del cursore con codifica Base64 che specifica da dove iniziare la query.
- end_cursor
- Stringa del cursore con codifica Base64 che specifica dove deve terminare la query.