Python 2.7 è deprecato. Non potrai eseguire il deployment di applicazioni Python 2.7, anche se la tua organizzazione in precedenza utilizzava una policy dell'organizzazione per riattivare i deployment dei runtime legacy. Le tue applicazioni Python 2.7 esistenti continueranno a essere eseguite e a ricevere traffico. Ti consigliamo di eseguire la migrazione all'ultima versione supportata di Python.

La classe Query

Nota:gli sviluppatori che creano nuove applicazioni sono fortemente incoraggiati a utilizzare la libreria client NDB, che offre diversi vantaggi rispetto a questa libreria client, ad esempio la memorizzazione automatica nella cache 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 recuperare le 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 di aggregazione non sono supportati nel motore di query Datastore. Consulta la pagina Query Datastore per i limiti relativi alle query Datastore.

Introduzione

Un'applicazione crea un oggetto query per un determinato tipo di entità chiamando il costruttore Query direttamente

class Song(db.Model):
  title = db.StringProperty()
  composer = db.StringProperty()
  date = db.DateTimeProperty()

q = db.Query(Song)

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

q = Song.all()

Senza ulteriori modifiche, l'istanza risultante della classe Query recupererà tutte le entità esistenti del tipo specificato. Le chiamate di metodo sull'oggetto possono quindi essere utilizzate per personalizzare la query con criteri di filtro aggiuntivi, condizioni di antenato e ordini di 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 concatenati 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 un 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 a
```
for song in q.run():
  print song.title
```
Puoi impostare un limite al numero di risultati da elaborare con l'argomento parola chiave limit:
```
for song in q.run(limit=5):
  print song.title
```
L'interfaccia dell'iteratore non memorizza nella cache i risultati, quindi la creazione di un nuovo iteratore dall'oggetto query ripete la stessa query 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 per run(), l'oggetto query non memorizza nella cache i risultati, quindi la chiamata di fetch() una seconda volta riemette la stessa query.

Nota:dovresti utilizzare questo metodo raramente; è quasi sempre meglio utilizzare run() invece.

Costruttore

Il costruttore della classe Query è definito come segue:

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

Crea un'istanza della classe Query per recuperare le 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 dell'istanza filter(), ancestor(), e order() possono quindi essere utilizzati per personalizzare la query con criteri di filtro aggiuntivi, condizioni di antenato e ordini di ordinamento.

Argomenti

model_class

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

keys_only

Se true, restituisci solo le chiavi anziché le entità complete. Le query basate solo su chiavi sono più veloci ed economiche di quelle 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 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 di quelle che restituiscono entità complete.

Nota:la specifica di questo parametro potrebbe modificare i requisiti di indice della query.

distinct

Nel caso di query di proiezione, distinct=True specifica che in un insieme di risultati verranno restituiti solo risultati completamente unici. Verrà restituito solo il primo risultato per le entità che hanno gli stessi valori per le proprietà proiettate.

Vero: Restituisci solo il primo risultato per ogni insieme distinto di valori per le proprietà nella proiezione.
Falso: Vengono restituiti tutti i risultati.

Metodi dell'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 di proprietà e un operatore di confronto facoltativo (=, !=, <, <=, >, >=, IN), separati da uno spazio: ad esempio, 'age >'. Se viene specificato solo un nome di proprietà senza un operatore di confronto, il filtro esegue un confronto di uguaglianza (=) per impostazione predefinita.

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à confrontata.

ancestor (ancestor)

Aggiunge un filtro predecessore alla query. La query restituirà solo le entità con l'antenato specificato.

Argomento

ancestor: Entità o chiave predecessore.

order (property)

Aggiunge un ordinamento alla query. Se viene aggiunto più di un ordine di ordinamento, questi verranno applicati nell'ordine specificato.

Argomento

proprietà

Stringa che indica il nome della proprietà in base alla quale eseguire l'ordinamento, facoltativamente preceduta da un trattino (-) per specificare l'ordine decrescente. Se non viene specificato il trattino, l'ordine predefinito è 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 None.

is_keys_only ()

Restituisce un valore booleano che indica se la query è una query solo 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 iterabile per scorrere i 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 e scarta il numero di risultati specificato dall'argomento offset.
Recupera e restituisce fino al numero massimo di risultati specificato dall'argomento limit.

Il rendimento del ciclo viene quindi scalato 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 recupero 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 elevato, ad esempio 1000.

Suggerimento:se non devi modificare i valori predefiniti degli argomenti, puoi utilizzare direttamente l'oggetto query come iterabile per controllare il ciclo. Questo chiama 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 è limitato a un singolo gruppo di entità.
EVENTUAL_CONSISTENCY: Può estendersi a più gruppi di entità, ma occasionalmente potrebbe restituire risultati non aggiornati. In generale, le query con coerenza finale vengono eseguite più rapidamente rispetto alle query con coerenza forte, ma non è garantito.

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

deadline

Tempo massimo, in secondi, di attesa prima che Datastore restituisca un risultato prima di interrompere l'operazione con un errore. Accetta un valore intero o con virgola mobile. Non può essere impostato su un valore superiore a quello predefinito (60 secondi), ma può essere ridotto 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'operazione diversa o aggiungere l'operazione a una coda di attività).

offset

Numero di risultati da ignorare prima di restituire il primo.

limite

Il numero massimo di risultati da restituire. Se omesso o impostato su None, per impostazione predefinita verranno recuperati tutti i risultati disponibili.

batch_size

Numero di risultati da tentare di recuperare per batch. Se limit è impostato, il valore predefinito è il limite specificato; altrimenti, il valore predefinito è 20.

keys_only

Se true, restituisci solo le chiavi anziché le entità complete. Le query basate solo su chiavi sono più veloci ed economiche di quelle che restituiscono entità complete.

proiezione

Nota:la specifica di questo parametro potrebbe modificare i requisiti di indice della query.

start_cursor

Posizione del cursore da cui iniziare la query.

end_cursor

Posizione del cursore in cui terminare la query.

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

Esegue la query e restituisce il primo risultato o None se non vengono trovati risultati.

Argomenti

read_policy

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

STRONG_CONSISTENCY: Garantisce i risultati più recenti, ma è limitato a un singolo gruppo di entità.
EVENTUAL_CONSISTENCY: Può estendersi a più gruppi di entità, ma occasionalmente potrebbe restituire risultati non aggiornati. In generale, le query con coerenza finale vengono eseguite più rapidamente rispetto alle query con coerenza forte, ma non è garantito.

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

deadline

offset

Numero di risultati da ignorare prima di restituire il primo.

keys_only

Se true, restituisci solo le chiavi anziché le entità complete. Le query basate solo su chiavi sono più veloci ed economiche di quelle che restituiscono entità complete.

proiezione

Nota:la specifica di questo parametro potrebbe modificare i requisiti di indice della query.

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 di risultati (eventualmente vuoto):

Recupera e scarta il numero di risultati specificato dall'argomento offset.
Recupera e restituisce fino al numero massimo di risultati specificato dall'argomento limit.

Il rendimento del metodo viene quindi scalato in modo lineare con la somma di offset + limit.

Nota:questo metodo è semplicemente un wrapper sottile intorno al metodo run() ed è meno efficiente e richiede più memoria rispetto all'utilizzo diretto di run(). Dovresti utilizzare fetch() raramente; viene fornito principalmente per comodità nei casi in cui devi recuperare un elenco completo in memoria dei risultati della query.

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

Argomenti

limite

Il 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 è limitato a un singolo gruppo di entità.
EVENTUAL_CONSISTENCY: Può estendersi a più gruppi di entità, ma occasionalmente potrebbe restituire risultati non aggiornati. In generale, le query con coerenza finale vengono eseguite più rapidamente rispetto alle query con coerenza forte, ma non è garantito.

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

deadline

offset

Numero di risultati da ignorare prima di restituire il primo.

keys_only

Se true, restituisci solo le chiavi anziché le entità complete. Le query basate solo su chiavi sono più veloci ed economiche di quelle che restituiscono entità complete.

proiezione

Nota:la specifica di questo parametro potrebbe modificare i requisiti di indice della query.

start_cursor

Posizione del cursore da cui iniziare la query.

end_cursor

Posizione del cursore in cui 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 linearmente con la somma di offset + limit. A meno che non sia previsto un numero ridotto di risultati, è consigliabile specificare un argomento limit; in caso contrario, il metodo continuerà finché non avrà terminato il conteggio o non si verificherà 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 è limitato a un singolo gruppo di entità.
EVENTUAL_CONSISTENCY: Può estendersi a più gruppi di entità, ma occasionalmente potrebbe restituire risultati non aggiornati. In generale, le query con coerenza finale vengono eseguite più rapidamente rispetto alle query con coerenza forte, ma non è garantito.

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

deadline

offset

Numero di risultati da ignorare 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 degli indici utilizzati da una query eseguita, inclusi gli indici primari, composti, di tipo e a singola proprietà.

Attenzione: l'invocazione di questo metodo su una query che non è ancora stata eseguita genererà 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 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 simile al seguente per ogni indice:

Kind: Greeting
Has ancestor? False
Property name: author
Sort direction: ASCENDING
Property name: date
Sort direction: DESCENDING

cursor ()

Restituisce una stringa cursore con codifica Base64 che indica la posizione nel set di risultati della query dopo l'ultimo risultato recuperato. La stringa del cursore può essere utilizzata in modo sicuro nei parametri HTTP GET e POST e può anche essere archiviata in Datastore o Memcache. Una futura chiamata 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: l'invocazione di questo metodo su una query che non è ancora stata eseguita genererà 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, end_cursor=None)

Specifica le posizioni iniziale e (facoltativamente) 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 una precedente chiamata della query. La query attuale deve essere identica a quella precedente, inclusi il tipo di entità, i filtri delle proprietà, i filtri degli antenati e gli ordinamenti.

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 terminare la query.

La classe Query Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Introduzione

Costruttore

Metodi dell'istanza

La classe Query