Nota: Python 2.7 ha raggiunto 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 rideployment delle applicazioni che utilizzano i runtime al termine del periodo di assistenza. Ti consigliamo di eseguire la migrazione alla versione più recente di Python supportata.

Questa pagina è stata tradotta dall'API Cloud Translation.

Classe Query

Nota: gli sviluppatori che creano nuove applicazioni sono vivamente invitati a utilizzare la libreria client NDB, che offre diversi vantaggi rispetto a questa libreria client, ad esempio la memorizzazione nella cache automatica delle entità tramite l'API Memcache. Se al momento utilizzi la libreria client DB precedente, leggi la guida alla migrazione da DB a NDB

La classe Query rappresenta una query per il recupero delle entità da Datastore di App Engine. (Vedi anche il corso correlato 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 indici supporta una vasta 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, le unioni e le query aggregate non sono supportate nel motore di query di Datastore. Consulta: Pagina Query Datastore per conoscere i limiti delle 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)

oppure il metodo di classe all() della classe del modello del tipo:

q = Song.all()

Senza ulteriori modifiche, l'istanza di classe risultante Query recupererà tutte le entità esistenti del tipo specificato. Le chiamate al metodo sull'oggetto possono quindi essere utilizzate per personalizzare la query criteri di filtro aggiuntivi, condizioni predecessore e ordinamento:

q.filter('title =', 'Imagine')
q.ancestor(ancestor_key)
q.order('-date')

Per comodità, tutti questi metodi restituiscono l'oggetto query stesso in modo che possano essere applicati in cascata in un'unica 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 query come iterabile per elaborare le entità corrispondenti una alla volta:
```
for song in q:
  print song.title
```
Viene chiamato implicitamente il metodo run() della query per generare le entità corrispondenti. È quindi equivalente a
```
for 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 nel 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 chiamando fetch() una seconda volta viene ripetuta la stessa query.

Nota:raramente dovresti usare questo metodo. è quasi sempre preferibile usare run() .

Costruttore

Il costruttore della classe Query è definito come segue:

Query class (model_class=Nessuno, keys_only=False, cursor=None, namespace=None, projection=Nessuna, distinct=False)

Crea un'istanza di classe Query per il recupero delle entità da App Engine Datastore.

Senza ulteriori modifiche, l'oggetto query risultante recupererà tutte le entità esistenti del tipo specificato da model_class. La metodi istanza filter(), ancestor(), e order() può quindi essere utilizzato per personalizzare la query con criteri di filtro aggiuntivi, le condizioni dei predecessori e l'ordinamento.

Argomenti

model_class

Classe Model (o Expando) che rappresenta il tipo di entità a cui si applica la query.

keys_only

Se true, restituisce solo le chiavi anziché le entità complete. Query basate solo sulle chiavi sono più veloci ed economici di quelli che restituiscono entità complete.

cursore

Posizione del cursore in cui riprendere la query.

namespace

Spazio dei nomi da utilizzare per la query.

proiezione

Elenco o tupla di nomi delle proprietà da restituire. Verranno restituite solo le entità che possiedono le proprietà specificate. Se non specificato, per impostazione predefinita vengono restituite intere entità. Query di proiezione sono più veloci ed economici di quelli che restituiscono entità complete.

Nota:se specifichi questo parametro, i requisiti di indice della query potrebbero cambiare.

distinct

Nel caso delle 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 entità che hanno gli stessi valori per delle proprietà oggetto della previsione.

Vero: Restituisce solo il primo risultato per ogni insieme distinto di valori per le proprietà nella proiezione.
Falso: Tutti i risultati vengono restituiti.

Metodi istanza

Le istanze della classe Query hanno i seguenti metodi:

filter (property_operator, value)

Aggiunge un filtro proprietà alla query. La query restituirà solo le entità le cui proprietà soddisfano tutti i filtri.

Argomenti

property_operator

Stringa composta da un nome della 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 operatore di confronto, il filtro mette a confronto l'uguaglianza (=) per impostazione predefinita.

value

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 uguale tipo di valore dell'immobile da confrontare.

predecessore (predecessore)

Aggiunge un filtro antenato alla query. La query restituirà solo entità con il predecessore specificato.

Argomento

antenato: Ente o chiave principale.

order (proprietà)

Aggiunge un ordine di ordinamento alla query. Se viene aggiunto più di un ordinamento, queste saranno applicate nell'ordine specificato.

Argomento

proprietà

Stringa che fornisce il nome della proprietà in cui ordinare, facoltativamente preceduto da un trattino (-) per specificare l'ordine decrescente. Se ometti il trattino, per impostazione predefinita viene specificato l'ordine crescente. Ad esempio:

# Order alphabetically by last name:
q.order('last_name')

# Order by height, tallest to shortest:
q.order('-height')

projection ()

Restituisce la tupla di proprietà nella proiezione o in None.

is_keys_only ()

Restituisce un valore booleano che indica se la query è composta da sole chiavi.

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 comando iterabile per il loop dei risultati della query. Ciò ti 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.

Pertanto, le prestazioni del ciclo variano in modo lineare con la somma di offset + limit. Se sai quanti risultati vuoi recuperare, devi sempre impostare un valore limit 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 numero è sconosciuto, imposta batch_size su un valore elevato, ad esempio 1000.

Suggerimento: se non devi modificare i valori dell'argomento predefiniti, puoi semplicemente utilizzare l'oggetto query direttamente come iterazione per controllare il loop. Viene chiamato implicitamente run() con gli argomenti predefiniti.

Argomenti

read_policy

Leggi le norme che specificano il livello di coerenza dei dati desiderato:

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 genere, le query eventualmente coerenti vengono eseguite più velocemente delle query fortemente coerenti, ma non c'è alcuna garanzia.

Nota: le query globali (non predecessori) ignorano questo argomento.

deadline

Tempo massimo, in secondi, di attesa che Datastore restituisca un risultato prima di interrompere con un errore. Accetta un valore intero o con 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 l'operazione, provare un'altra operazione o aggiungere l'operazione a una coda di attività).

offset

Numero di risultati da saltare prima di restituire il primo.

limit

Numero massimo di risultati da restituire. Se il criterio viene omesso o impostato su None, tutti i risultati disponibili verranno recuperati per impostazione predefinita.

batch_size

Numero di risultati da tentare di recuperare per batch. Se il criterio limit viene configurato, il valore predefinito corrisponde al limite specificato. In caso contrario, il valore predefinito è 20.

keys_only

Se true, restituisce solo le chiavi anziché le entità complete. Query basate solo sulle chiavi sono più veloci ed economici di quelli 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 in cui terminare la query.

trova (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=Nessuna, start_cursor=None, end_cursor=Nessuno)

Esegue la query e restituisce il primo risultato oppure None se non viene trovato alcun risultato.

Argomenti

read_policy

Leggi le norme che specificano il livello di coerenza dei dati desiderato:

STRONG_CONSISTENCY: Garantisce i risultati più recenti, ma limitati a una singola gruppo di entità.
EVENTUAL_CONSISTENCY: Può includere più gruppi di entità, ma a volte può restituire risultati obsoleti. In genere, le query eventualmente coerenti vengono eseguite più velocemente delle query fortemente coerenti, ma non c'è alcuna garanzia.

Nota: le query globali (non predecessori) ignorano questo argomento.

deadline

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à. Query di proiezione sono più veloci ed economici di quelli 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 in cui terminare la query.

fetch (limit, read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Esegue la query e restituisce un elenco (eventualmente vuoto) di risultati:

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 involucro attorno al run() ed è meno efficiente e utilizza più memoria rispetto all'uso diretto di run(). Raramente dovresti usare fetch(). viene fornito principalmente per praticità nei casi in cui sia necessario recuperare un elenco completo in memoria dei risultati delle query.

Suggerimento: il metodo fetch() è progettato per recupera solo il numero di risultati specificato dall'argomento limit. Per recuperare tutti i risultati disponibili per una query quando il loro numero è sconosciuto, usa run() con un batch di grandi dimensioni, ad esempio run(batch_size=1000), anziché fetch().

Argomenti

limit

Numero massimo di risultati da restituire. Se impostato su None, verranno recuperati tutti i risultati disponibili.

read_policy

Leggi le norme che specificano il livello di coerenza dei dati desiderato:

STRONG_CONSISTENCY: Garantisce i risultati più recenti, ma limitati a una singola gruppo di entità.
EVENTUAL_CONSISTENCY: Può includere più gruppi di entità, ma a volte può restituire risultati obsoleti. In genere, le query eventualmente coerenti vengono eseguite più velocemente delle query fortemente coerenti, ma non c'è alcuna garanzia.

Nota: le query globali (non predecessori) ignorano questo argomento.

deadline

offset

Numero di risultati da saltare prima di restituire il primo.

keys_only

Se true, restituisce solo le chiavi anziché le entità complete. Query basate solo sulle chiavi sono più veloci ed economici di quelli 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à. Query di proiezione sono più veloci ed economici di quelli 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.

count (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=1000, start_cursor=None, end_cursor=None)

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 che il conteggio dei risultati sia ridotto, è meglio specificare un argomento limit; in caso contrario, il metodo continuerà fino al termine del conteggio o al verificarsi di un timeout.

Argomenti

read_policy

Leggi le norme che specificano il livello di coerenza dei dati desiderato:

STRONG_CONSISTENCY: Garantisce i risultati più recenti, ma limitati a una singola gruppo di entità.
EVENTUAL_CONSISTENCY: Può includere più gruppi di entità, ma a volte può restituire risultati obsoleti. In genere, le query eventualmente coerenti vengono eseguite più velocemente delle query fortemente coerenti, ma non c'è alcuna garanzia.

Nota: le query globali (non predecessori) ignorano questo argomento.

deadline

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, di tipo e a proprietà singola.

Attenzione: richiamando questo metodo su una query non ancora eseguita, verrà generato AssertionError un'eccezione.

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 composito.

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 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 è sicura da utilizzare nei parametri HTTP GET e POST e può essere archiviata anche in Datastore o Memcache. Un'invocazione futura della stessa query può fornire questa stringa tramite il parametro start_cursor o il metodo with_cursor() per riprendere il recupero dei risultati da questa posizione.

Attenzione: richiamando questo metodo su una query non ancora eseguita, verrà generato AssertionError un'eccezione.

Nota: non tutte le query sono compatibili con i cursori. Per ulteriori informazioni, consulta la pagina Query Datastore.

with_cursor (start_cursor, end_cursor=Nessuno)

Specifica le posizioni iniziale e (facoltativa) finale 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 chiamando cursor() dopo un'invocazione precedente della query. La query corrente deve essere identica a quella invocata in precedenza, inclusi il tipo di entità, i filtri delle proprietà, i filtri degli antenati e gli ordini di 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.