Nota: gli sviluppatori che creano nuove applicazioni sono vivamente consigliati di utilizzare la libreria client NDB, che presenta numerosi vantaggi rispetto a questa libreria client, come la memorizzazione automatica nella cache delle entità tramite l'API Memcache. Se al momento utilizzi la vecchia libreria client DB, leggi la guida alla migrazione da DB a NDB
La classe Query
rappresenta una query per recuperare le entità dal
repository di App Engine. Vedi anche la classe correlata GqlQuery
, che definisce le query utilizzando GQL, un linguaggio di query di tipo SQL.
Query
è definito nel modulo google.appengine.ext.db
.
Nota: il meccanismo delle query basato su indice supporta un'ampia gamma di query ed è adatto per la 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 Datastore. Per informazioni sui limiti delle query Datastore, consulta la pagina Query di 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)
oppure il metodo class
all()
della classe del modello di tipo:
q = Song.all()
Senza ulteriori modifiche, l'istanza risultante della classe Query
recupererà tutte le entità esistenti del tipo specificato.
Le chiamate metodo sull'oggetto possono quindi essere utilizzate per personalizzare la query con criteri di filtro aggiuntivi, condizioni predecessori e ordini:
q.filter('title =', 'Imagine') q.ancestor(ancestor_key) q.order('-date')
Per praticità, tutti questi metodi restituiscono direttamente l'oggetto query in modo che possano essere ereditati con 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:
-
Gestisci l'oggetto query come iterabile, per elaborare le entità corrispondenti una alla volta:
for song in q: print song.title
In questo modo viene chiamato implicitamente il metodo
run()
della query per generare le entità corrispondenti. È quindi equivalente 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 per l'iteratore non memorizza nella cache i risultati, quindi la creazione di un nuovo iteratore dall'oggetto di query ripete la stessa query dall'inizio.
-
Chiama il metodo
get()
della query per ottenere la prima singola entità corrispondente trovata nel datastore:song = q.get() print song.title
-
Chiama il metodo della query
fetch()
per ottenere un elenco di tutte le entità corrispondenti fino a un numero specifico di risultati:results = q.fetch(limit=5) for song in results: print song.title
Come per
run()
, l'oggetto query non memorizza i risultati nella cache, quindi chiamarefetch()
una seconda volta riemette la stessa query.Nota: di solito devi usare questo metodo; è quasi sempre preferibile utilizzare
run()
.
Costruttore
Il costruttore per la classe Query
è definito come segue:
- class Query (model_class=Nessuna, keys_only=False, trigger=None, namespace=None, projection=None, distinct=False)
-
Crea un'istanza di classe
Query
per recuperare entità dal datastore App Engine.Senza ulteriori modifiche, l'oggetto query risultante recupererà tutte le entità esistenti del tipo specificato da
model_class
. I metodi dell'istanzafilter()
,ancestor(),
eorder()
possono quindi essere utilizzati per personalizzare la query con criteri di filtro aggiuntivi, condizioni predecessori e ordini.Argomenti
- classe_modello
- La classe del modello (o Espandi) che rappresenta il tipo di entità a cui si applica la query.
- solo chiavi
- Se
true
, restituisci solo chiavi anziché entità complete. Le query basate su chiavi sono più veloci ed economiche rispetto a quelle che restituiscono entità complete. - asterisco
- Posizione del cursore in cui riprendere la query.
- spazio dei nomi
- Spazio dei nomi da utilizzare per la query.
- previsione
- 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 ed economiche rispetto a quelle che restituiscono entità complete.
Nota: la specifica di questo parametro può modificare i requisiti di indice della query.
- distinto
- Nel caso delle Query di proiezione, distinto=Vero specifica che verranno restituiti solo risultati completamente unici in un set di risultati. Verrà restituito solo il primo risultato per le entità che hanno gli stessi valori per le proprietà che vengono previste.
- Vero
- Restituisci solo il primo risultato per ogni set di valori distinto 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 proprietà alla query. La query restituisce solo le entità le cui proprietà soddisfano tutti i relativi filtri.
Argomenti
- gestore_proprietà
- Stringa composta da un nome 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 l'uguaglianza (=
) per impostazione predefinita. - value [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 di quello della proprietà da confrontare.
- antenato (antenato)
-
Aggiunge un filtro predecessore alla query. La query restituirà solo entità con il predecessore specificato.
Argomento
- antenato
- Entità o chiave predecessore.
- order (proprietà)
-
Aggiunge un ordinamento alla query. Se viene aggiunto più di un ordinamento, verranno applicati nell'ordine specificato.
Argomento
- proprietà
- Stringa che fornisce il nome della proprietà in base alla quale 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')
- visione ()
-
Restituisce la tupla delle proprietà nella proiezione o
None
. - is_keys_only ()
-
Restituisce un valore booleano che indica se la query è solo una chiave.
- run (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=None, batch_size=20, keys_only=False, projection=None, start_cursor=None, end_cursor=None)
-
Restituisce un'iterabile per ripetere il loop dei risultati della query. Ciò ti consente di specificare l'operazione della query con le impostazioni dei parametri e di accedere in modo iterativo ai risultati:
- Recupera e ignora il numero di risultati specificati dall'argomento
offset
. - Recupera e restituisce il numero massimo di risultati specificati dall'argomento
limit
.
Le prestazioni del loop vengono così scalate 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 dal 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 loro numero è sconosciuto, imposta
batch_size
su un valore grande, ad esempio1000
.Suggerimento: se non devi modificare i valori predefiniti dell'argomento, puoi semplicemente utilizzare l'oggetto di query come iterabile per controllare il loop. In questo modo viene chiamato implicitamente
run()
con argomenti predefiniti.Argomenti
- Leggi_policy
- Leggi il criterio che specifica il livello di coerenza dei dati desiderato:
- FORTE_CONSISTENCY
- Garantisce i risultati più recenti, ma limitati a un singolo gruppo di entità.
- EVENTUAL_CONSISTENCY
- Possono includere più gruppi di entità, ma occasionalmente possono restituire risultati obsoleti. In generale, alla fine le query coerenti vengono eseguite più velocemente rispetto alle query con coerenza elevata, ma non vi è alcuna garanzia.
Nota: le query globali (non predecessori) ignorano questo argomento.
- data limite
- Tempo massimo, in secondi, per attendere che Datastore restituisca un risultato prima di verificarsi un errore. Accetta un valore intero o con virgola mobile. Non può essere impostata su un valore superiore al valore predefinito (60 secondi), ma può essere modificata verso il basso per assicurare che un'operazione specifica non riesca rapidamente (ad esempio, per restituire una risposta più rapida all'utente, riprovare a eseguire l'operazione o provarne un'altra o aggiungere l'operazione a una coda di attività).
- offset
- Numero di risultati da saltare prima di restituire il primo.
- limite
- Il numero massimo di risultati da restituire.
Se omesso o impostato su
None
, tutti i risultati disponibili verranno recuperati per impostazione predefinita. - dimensioni_batch
- Numero di risultati da tentare per il recupero per gruppo. Se il criterio
limit
viene configurato, per impostazione predefinita viene usato il limite specificato, altrimenti il valore predefinito è20
. - solo chiavi
- Se
true
, restituisci solo chiavi anziché entità complete. Le query basate su chiavi sono più veloci ed economiche rispetto a quelle che restituiscono entità complete. - previsione
- 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 ed economiche rispetto a quelle che restituiscono entità complete.
Nota: la specifica di questo parametro può modificare i requisiti di indice della query.
- start_trigger
- Posizione del cursore da cui iniziare la query.
- end_trigger
- Posizione del cursore in cui terminare la query.
- Recupera e ignora il numero di risultati specificati dall'argomento
- get (read_policy=Strong_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_trigger=None, end_trigger=None
-
Esegue la query e restituisce il primo risultato, oppure
None
se non viene trovato alcun risultato.Argomenti
- Leggi_policy
- Leggi il criterio che specifica il livello di coerenza dei dati desiderato:
- FORTE_CONSISTENCY
- Garantisce i risultati più recenti, ma limitati a un singolo gruppo di entità.
- EVENTUAL_CONSISTENCY
- Possono includere più gruppi di entità, ma occasionalmente possono restituire risultati obsoleti. In generale, alla fine le query coerenti vengono eseguite più velocemente rispetto alle query con coerenza elevata, ma non vi è alcuna garanzia.
Nota: le query globali (non predecessori) ignorano questo argomento.
- data limite
- Tempo massimo, in secondi, per attendere che Datastore restituisca un risultato prima di verificarsi un errore. Accetta un valore intero o con virgola mobile. Non può essere impostata su un valore superiore al valore predefinito (60 secondi), ma può essere modificata verso il basso per assicurare che un'operazione specifica non riesca rapidamente (ad esempio, per restituire una risposta più rapida all'utente, riprovare a eseguire l'operazione o provarne un'altra o aggiungere l'operazione a una coda di attività).
- offset
- Numero di risultati da saltare prima di restituire il primo.
- solo chiavi
- Se
true
, restituisci solo chiavi anziché entità complete. Le query basate su chiavi sono più veloci ed economiche rispetto a quelle che restituiscono entità complete. - previsione
- 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 ed economiche rispetto a quelle che restituiscono entità complete.
Nota: la specifica di questo parametro può modificare i requisiti di indice della query.
- start_trigger
- Posizione del cursore da cui iniziare la query.
- end_trigger
- Posizione del cursore in cui terminare la query.
- fetch (limite, read_policy=Strong_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=Nessuno, start_tracker=Nessuno, end_trigger=Nessuno)
-
Esegue la query e restituisce un elenco (possibilmente vuoto) di risultati:
- Recupera e ignora il numero di risultati specificati dall'argomento
offset
. - Recupera e restituisce il numero massimo di risultati specificati dall'argomento
limit
.
Le prestazioni del metodo vengono scalate linearemente con la somma di
offset
+limit
.Nota: questo metodo è semplicemente un wrapper sottile intorno al metodo
run()
ed è meno efficiente e più efficiente in termini di memoria rispetto all'utilizzo diretto dirun()
. Utilizza raramentefetch()
, che viene fornito principalmente per praticità nei casi in cui hai la necessità di recuperare un elenco completo di risultati di query in memoria.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
- Il numero massimo di risultati da restituire.
Se il criterio viene impostato su
None
, verranno recuperati tutti i risultati disponibili. - Leggi_policy
- Leggi il criterio che specifica il livello di coerenza dei dati desiderato:
- FORTE_CONSISTENCY
- Garantisce i risultati più recenti, ma limitati a un singolo gruppo di entità.
- EVENTUAL_CONSISTENCY
- Possono includere più gruppi di entità, ma occasionalmente possono restituire risultati obsoleti. In generale, alla fine le query coerenti vengono eseguite più velocemente rispetto alle query con coerenza elevata, ma non vi è alcuna garanzia.
Nota: le query globali (non predecessori) ignorano questo argomento.
- data limite
- Tempo massimo, in secondi, per attendere che Datastore restituisca un risultato prima di verificarsi un errore. Accetta un valore intero o con virgola mobile. Non può essere impostata su un valore superiore al valore predefinito (60 secondi), ma può essere modificata verso il basso per assicurare che un'operazione specifica non riesca rapidamente (ad esempio, per restituire una risposta più rapida all'utente, riprovare a eseguire l'operazione o provarne un'altra o aggiungere l'operazione a una coda di attività).
- offset
- Numero di risultati da saltare prima di restituire il primo.
- solo chiavi
- Se
true
, restituisci solo chiavi anziché entità complete. Le query basate su chiavi sono più veloci ed economiche rispetto a quelle che restituiscono entità complete. - previsione
- 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 ed economiche rispetto a quelle che restituiscono entità complete.
Nota: la specifica di questo parametro può modificare i requisiti di indice della query.
- start_trigger
- Posizione del cursore da cui iniziare la query.
- end_trigger
- Posizione del cursore in cui terminare la query.
- Recupera e ignora il numero di risultati specificati dall'argomento
- count (read_policy=Strong_CONSISTENCY, deadline=60, offset=0, limit=1000, start_trigger=None, end_trigger=None
-
Restituisce il numero di risultati corrispondenti alla query. Questo risulta più veloce di un fattore costante rispetto al recupero effettivo di tutti i risultati, ma il tempo di esecuzione scala in modo lineare con la somma di
offset
+limit
. A meno che non venga previsto un numero di risultati ridotto, è meglio specificare un argomentolimit
; in caso contrario, il metodo continuerà fino al termine del conteggio o al timeout.Argomenti
- Leggi_policy
- Leggi il criterio che specifica il livello di coerenza dei dati desiderato:
- FORTE_CONSISTENCY
- Garantisce i risultati più recenti, ma limitati a un singolo gruppo di entità.
- EVENTUAL_CONSISTENCY
- Possono includere più gruppi di entità, ma occasionalmente possono restituire risultati obsoleti. In generale, alla fine le query coerenti vengono eseguite più velocemente rispetto alle query con coerenza elevata, ma non vi è alcuna garanzia.
Nota: le query globali (non predecessori) ignorano questo argomento.
- data limite
- Tempo massimo, in secondi, per attendere che Datastore restituisca un risultato prima di verificarsi un errore. Accetta un valore intero o con virgola mobile. Non può essere impostata su un valore superiore al valore predefinito (60 secondi), ma può essere modificata verso il basso per assicurare che un'operazione specifica non riesca rapidamente (ad esempio, per restituire una risposta più rapida all'utente, riprovare a eseguire l'operazione o provarne un'altra o aggiungere l'operazione a una coda di attività).
- offset
- Numero di risultati da saltare prima di conteggiare la prima.
- limite
- Il numero massimo di risultati da conteggiare.
- start_trigger
- Posizione del cursore da cui iniziare la query.
- end_trigger
- Posizione del cursore in cui terminare la query.
- index_list ()
-
Restituisce un elenco di indici utilizzati da una query eseguita, inclusi indici principali, composti, tipo e a proprietà singola.
Attenzione: la chiamata di questo metodo a una query non ancora eseguita genera un'eccezione
AssertionError
.Nota: questa funzionalità non è completamente supportata sul server di sviluppo. Se utilizzato con il server di sviluppo, il risultato è l'elenco vuoto o un elenco contenente esattamente un indice composto.
Ad esempio, il seguente codice stampa diverse 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 />")
Per ogni indice viene generato un output simile al seguente:
Kind: Greeting Has ancestor? False Property name: author Sort direction: ASCENDING Property name: date Sort direction: DESCENDING
- asterisco ()
-
Restituisce una stringa curriculum con codifica base64 che indica la posizione nel set di risultati della query dopo l'ultimo risultato. La stringa cursore è sicura per essere utilizzata 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: la chiamata di questo metodo a una query non ancora eseguita genera un'eccezione
AssertionError
.Nota: non tutte le query sono compatibili con i cursore. Consulta la pagina Query Datastore per ulteriori informazioni.
- with_curriculum (start_trigger, end_curriculum=Nessuno)
-
Specifica le posizioni iniziali e (facoltativamente) finali all'interno di un set di risultati di una query da cui recuperare i risultati. Le stringhe del cursore che indicano le posizioni iniziali e finali possono essere ottenute chiamando
cursor()
dopo una precedente chiamata della query. La query corrente deve essere identica a quella precedente, tra cui il tipo di entità, i filtri proprietà, i filtri predecessori e gli ordini.Argomenti
- start_trigger
- Stringa del cursore con codifica Base64 che specifica da dove iniziare la query.
- end_trigger
- Stringa del cursore con codifica Base64 che specifica dove terminare la query.