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 classe Query
rappresenta una query per recuperare entità da App Engine Datastore. (Vedi anche la classe correlata GqlQuery
, che definisce le query utilizzando GQL, un linguaggio di query simile a SQL.)
Query
è 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, i join e le query aggregate non sono supportati all'interno del motore di query Datastore. Consulta la pagina Query Datastore per le limitazioni sulle query Datastore.
Introduzione
Un'applicazione crea un oggetto query per un determinato tipo di entità chiamando direttamente il costruttore Query
class Song(db.Model): title = db.StringProperty() composer = db.StringProperty() date = db.DateTimeProperty() q = db.Query(Song)
o il metodo della classe
all()
della classe del modello del tipo:
q = Song.all()
Senza ulteriori modifiche, l'istanza della classe
Query
risultante recupererà tutte le entità esistenti del tipo specificato.
Le chiamate al metodo sull'oggetto possono quindi essere utilizzate per personalizzare la query con criteri di filtro aggiuntivi, condizioni predecessori e ordini di ordinamento:
q.filter('title =', 'Imagine') q.ancestor(ancestor_key) q.order('-date')
Per praticità, tutti questi metodi restituiscono l'oggetto di query stesso in modo che possano essere inseriti a cascata in una singola istruzione:
q.filter('title =', 'Imagine').ancestor(key).order('-date')
L'applicazione può quindi eseguire la query e accedere ai risultati in uno dei seguenti modi:
-
Tratta l'oggetto della query come iterabile, per elaborare le entità corrispondenti una alla volta:
for song in q: print song.title
Questo richiama implicitamente il metodo
run()
della query per generare le entità corrispondenti. Equivale afor song in q.run(): print song.title
Puoi impostare un limite per il numero di risultati da elaborare con l'argomento della parola chiave
limit
:for song in q.run(limit=5): print song.title
L'interfaccia iteratore non memorizza nella cache i risultati, quindi la creazione di un nuovo iteratore dall'oggetto query consente di ripetere la stessa query dall'inizio.
-
Chiama il metodo
get()
della query per ottenere la prima 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 con
run()
, l'oggetto query non memorizza nella cache i risultati, quindi se chiamifetch()
una seconda volta, la stessa query viene riemessa.Nota: questo metodo sarà raro; è quasi sempre preferibile usare
run()
.
Costruttore
Il costruttore della classe Query
viene definito come segue:
- class Query (model_class=None, keys_only=False, cursor=None, namespace=None, projection=None, distinct=False)
-
Crea un'istanza di classe
Query
per recuperare entità da App Engine Datastore.Senza ulteriori modifiche, l'oggetto query risultante recupererà tutte le entità esistenti del tipo specificato da
model_class
. I metodi di istanzafilter()
,ancestor(),
eorder()
possono quindi essere utilizzati per personalizzare la query con criteri di filtro, condizioni predecessori e ordini di ordinamento aggiuntivi.Argomenti
- model_class
- Classe del modello (o expando) che rappresenta il tipo di entità a cui si applica la query.
- keys_only
- Se
true
, restituisci solo chiavi anziché entità complete. Le query solo con chiave sono più veloci e più economiche di quelle che restituiscono entità complete. - cursore
- Posizione del cursore da cui riprendere la query.
- spazio dei nomi
- Spazio dei nomi da utilizzare per la query.
- proiezione
- Elenco o tupla di nomi di proprietà da restituire. Verranno restituite solo le entità che possiedono le proprietà specificate. Se non specificato, per impostazione predefinita vengono restituite intere entità.
Le query di proiezione
sono più veloci e più economiche di quelle che restituiscono entità complete.
Nota: se specifichi questo parametro, i requisiti di indice della query potrebbero subire modifiche.
- distinto
- Nel caso di Query di proiezione, distinct=True specifica che in un insieme di risultati verranno restituiti solo risultati completamente univoci. Verrà restituito solo il primo risultato per le entità che hanno gli stessi valori per le proprietà di cui si esegue la previsione.
- Vero
- Restituisci solo il primo risultato per ogni insieme distinto di valori per le proprietà nella proiezione.
- Falso
- Vengono restituiti tutti i risultati.
Metodi di istanza
Le istanze della classe Query
hanno i seguenti metodi:
- filter (property_operator, value)
-
Aggiunge un filtro delle proprietà alla query. La query restituirà solo entità le cui proprietà soddisfano tutti i filtri.
Argomenti
- property_operator
- Stringa composta da un nome di proprietà e da un operatore di confronto facoltativo (
=
,!=
,<
,<=
,>
,>=
,IN
), separati da uno spazio, ad esempio'age
>'
. Se viene specificato solo il nome di una proprietà senza un operatore di confronto, il filtro confronta per impostazione predefinita l'uguaglianza (=
). - valore
- Valore da confrontare con il valore della proprietà. Ad esempio:
q.filter('height >', 42).filter('city =', 'Seattle') q.filter('user =', users.get_current_user())
Il valore di confronto specificato deve essere dello stesso tipo di valore della proprietà da confrontare.
- ancestor (ancestor)
-
Aggiunge un filtro dei predecessori alla query. La query restituirà solo entità con il predecessore specificato.
Argomento
- ancestor
- Entità o chiave predecessore.
- order (proprietà)
-
Aggiunge un ordinamento alla query. Se vengono aggiunti più ordinamenti, verranno applicati nell'ordine specificato.
Argomento
- proprietà
- Stringa che indica il nome della proprietà in cui ordinare, facoltativamente preceduta da un trattino (
-
) per specificare l'ordine decrescente. L'omissione del trattino specifica l'ordine crescente per impostazione predefinita. Ad esempio:# Order alphabetically by last name: q.order('last_name') # Order by height, tallest to shortest: q.order('-height')
- proiezione ()
-
Restituisce la tupla delle proprietà nella proiezione o
None
. - is_keys_only ()
-
Restituisce un valore booleano che indica se la query è una query basata solo su chiavi.
- run (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=Nessuno, batch_size=20, keys_only=False, projection=Nessuno, start_cursor=Nessuno, start_cursor=Nessuno,
-
Restituisce un iterabile per il loop dei risultati della query. In questo modo puoi specificare l'operazione della query con le impostazioni dei parametri e accedere ai risultati in modo iterativo:
- Recupera ed elimina il numero di risultati specificato dall'argomento
offset
. - Recupera e restituisce fino al 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 conosci il numero di risultati che 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 interrompere l'iterazione ed evitare di recuperare più risultati del necessario.
Suggerimento:per recuperare tutti i risultati disponibili quando il numero è sconosciuto, imposta
batch_size
su un valore grande, ad esempio1000
.Suggerimento: se non devi modificare i valori dell'argomento predefinito, puoi utilizzare direttamente l'oggetto della query come iterabile per il controllo del 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ò includere più gruppi di entità, ma a volte può restituire risultati obsoleti. In generale, le query a coerenza finale vengono eseguite più velocemente delle query a coerenza elevata, ma non vi è alcuna garanzia.
Nota:le query globali (non predecessori) ignorano questo argomento.
- scadenza
- Tempo massimo, in secondi, di attesa affinché Datastore restituisca un risultato prima di interrompere con un errore. Accetta un numero intero o un valore con virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere regolato 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, ritentare l'operazione, provare un'operazione diversa o aggiungere l'operazione a una coda di attività).
- offset
- Numero di risultati da ignorare prima di restituire il primo.
- limite
- Numero massimo di risultati da restituire.
Se omesso o impostato su
None
, tutti i risultati disponibili verranno recuperati per impostazione predefinita. - batch_size
- Numero di risultati da tentare di recuperare per gruppo. Se viene configurato
limit
, il valore predefinito corrisponde al limite specificato; in caso contrario, il valore predefinito è20
. - keys_only
- Se
true
, restituisci solo chiavi anziché entità complete. Le query solo con chiave sono più veloci e più economiche di quelle che restituiscono entità complete. - proiezione
- Elenco o tupla di nomi di proprietà da restituire. Verranno restituite solo le entità che possiedono le proprietà specificate. Se non specificato, per impostazione predefinita vengono restituite intere entità.
Le query di proiezione
sono più veloci e più economiche di quelle che restituiscono entità complete.
Nota: se specifichi questo parametro, i requisiti di indice della query potrebbero subire modifiche.
- start_cursor
- Posizione del cursore da cui iniziare la query.
- end_cursor
- Posizione del cursore in cui terminare la query.
- Recupera ed elimina il numero di risultati specificato dall'argomento
- get (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=Nessuno, start_cursor=Nessuno, end_cursor=Nessuno)
-
Esegue la query e restituisce il primo risultato oppure
None
se non viene trovato alcun risultato.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ò includere più gruppi di entità, ma a volte può restituire risultati obsoleti. In generale, le query a coerenza finale vengono eseguite più velocemente delle query a coerenza elevata, ma non vi è alcuna garanzia.
Nota:le query globali (non predecessori) ignorano questo argomento.
- scadenza
- Tempo massimo, in secondi, di attesa affinché Datastore restituisca un risultato prima di interrompere con un errore. Accetta un numero intero o un valore con virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere regolato 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, ritentare l'operazione, provare un'operazione diversa o aggiungere l'operazione a una coda di attività).
- offset
- Numero di risultati da ignorare prima di restituire il primo.
- keys_only
- Se
true
, restituisci solo chiavi anziché entità complete. Le query solo con chiave sono più veloci e più economiche di quelle che restituiscono entità complete. - proiezione
- Elenco o tupla di nomi di proprietà da restituire. Verranno restituite solo le entità che possiedono le proprietà specificate. Se non specificato, per impostazione predefinita vengono restituite intere entità.
Le query di proiezione
sono più veloci e più economiche di quelle che restituiscono entità complete.
Nota: se specifichi questo parametro, i requisiti di indice della query potrebbero subire modifiche.
- start_cursor
- Posizione del cursore da cui iniziare la query.
- end_cursor
- Posizione del cursore in cui terminare la query.
- fetch (limit, read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=Nessuno, start_cursor=Nessuno, end_cursor=Nessuno)
-
Esegue la query e restituisce un elenco di risultati (possibilmente vuoto):
- Recupera ed elimina il numero di risultati specificato dall'argomento
offset
. - Recupera e restituisce fino al numero massimo di risultati specificato dall'argomento
limit
.
Di conseguenza, il rendimento del metodo viene adeguato in modo lineare con la somma di
offset
+limit
.Nota: questo metodo è semplicemente un wrapper sottile per il metodo
run()
ed è meno efficiente e richiede più memoria rispetto all'utilizzo diretto dirun()
. Raramente dovresti utilizzarefetch()
; è fornito principalmente per comodità nei casi in cui sia necessario 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 un batch di grandi dimensioni, 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ò includere più gruppi di entità, ma a volte può restituire risultati obsoleti. In generale, le query a coerenza finale vengono eseguite più velocemente delle query a coerenza elevata, ma non vi è alcuna garanzia.
Nota:le query globali (non predecessori) ignorano questo argomento.
- scadenza
- Tempo massimo, in secondi, di attesa affinché Datastore restituisca un risultato prima di interrompere con un errore. Accetta un numero intero o un valore con virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere regolato 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, ritentare l'operazione, provare un'operazione diversa o aggiungere l'operazione a una coda di attività).
- offset
- Numero di risultati da ignorare prima di restituire il primo.
- keys_only
- Se
true
, restituisci solo chiavi anziché entità complete. Le query solo con chiave sono più veloci e più economiche di quelle che restituiscono entità complete. - proiezione
- Elenco o tupla di nomi di proprietà da restituire. Verranno restituite solo le entità che possiedono le proprietà specificate. Se non specificato, per impostazione predefinita vengono restituite intere entità.
Le query di proiezione
sono più veloci e più economiche di quelle che restituiscono entità complete.
Nota: se specifichi questo parametro, i requisiti di indice della query potrebbero subire modifiche.
- start_cursor
- Posizione del cursore da cui iniziare la query.
- end_cursor
- Posizione del cursore in cui terminare la query.
- Recupera ed elimina il numero di risultati specificato dall'argomento
- count (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=1000, start_cursor=Nessuno, end_cursor=Nessuno)
-
Restituisce il numero di risultati corrispondenti alla query. Questo è un fattore più veloce rispetto al recupero effettivo di tutti i risultati, ma il tempo di esecuzione continua a essere scalato in modo lineare con la somma di
offset
+limit
. A meno che non si preveda che il conteggio dei risultati sia ridotto, è meglio specificare un argomentolimit
; in caso contrario, il metodo continuerà fino al termine del conteggio o fino 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ò includere più gruppi di entità, ma a volte può restituire risultati obsoleti. In generale, le query a coerenza finale vengono eseguite più velocemente delle query a coerenza elevata, ma non vi è alcuna garanzia.
Nota:le query globali (non predecessori) ignorano questo argomento.
- scadenza
- Tempo massimo, in secondi, di attesa affinché Datastore restituisca un risultato prima di interrompere con un errore. Accetta un numero intero o un valore con virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere regolato 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, ritentare l'operazione, provare un'operazione diversa o aggiungere l'operazione a una coda di attività).
- offset
- Numero di risultati da saltare prima di conteggiare il primo.
- limite
- Numero massimo di risultati da conteggiare.
- start_cursor
- Posizione del cursore da cui iniziare la query.
- end_cursor
- Posizione del cursore in cui terminare la query.
- index_list ()
-
Restituisce un elenco di indici utilizzati da una query eseguita, inclusi indici primari, composti, kind e a proprietà singola.
Attenzione: la chiamata di questo metodo su una query non ancora eseguita genererà 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.Query(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 simile al 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 di cursore con codifica base64 che indica la posizione nel set di risultati della query dopo l'ultimo risultato recuperato. La stringa del cursore è sicura da utilizzare nei parametri HTTP
GET
ePOST
e può essere archiviata anche 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: la chiamata di questo metodo su una query non ancora eseguita genererà un'eccezione
AssertionError
.Nota: non tutte le query sono compatibili con i cursori. Per ulteriori informazioni, consulta la pagina Query del 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 di cursore che indicano la posizione iniziale e finale possono essere ottenute chiamando
cursor()
dopo una chiamata precedente della query. La query corrente deve essere identica alla chiamata precedente, inclusi il tipo di entità, i filtri delle proprietà, i filtri dei predecessori e gli ordini di ordinamento.Argomenti
- start_cursor
- Stringa cursore con codifica Base64 che specifica da dove iniziare la query.
- end_cursor
- Stringa cursore con codifica Base64 che specifica dove terminare la query.