Nota: il 31 gennaio 2024 è stato raggiunto il termine del supporto di Python 2.7. Le applicazioni Python 2.7 esistenti continueranno a essere eseguite e a ricevere traffico. Tuttavia, App Engine potrebbe bloccare il nuovo deployment delle applicazioni che utilizzano i runtime dopo la data di fine del supporto. Ti consigliamo di eseguire la migrazione alla versione più recente di Python supportata.

Questa pagina è stata tradotta dall'API Cloud Translation.

Classe GqlQuery

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 al momento utilizzi la libreria client DB precedente, leggi la guida alla migrazione da DB a NDB

La classe GqlQuery rappresenta una query per il recupero delle entità da App Engine Datastore utilizzando GQL, il linguaggio di query di App Engine simile a SQL. Per una discussione completa della sintassi e delle funzionalità di GQL, consulta il riferimento GQL; consulta 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 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 la pagina Query Datastore per informazioni sui limiti delle query Datastore.

Introduzione

Un'applicazione crea un oggetto query GQL chiamando direttamente il costruttore GqlQuery o il metodo di classe gql() della classe del modello di un tipo di entità. Il costruttore GqlQuery accetta come argomento una stringa di query,un'istruzione GQL completa che inizia con SELECT ... FROM model-name. I valori nelle clausole WHERE possono essere literal numerici o di stringa oppure possono utilizzare la definizione dei parametri per i valori. I parametri possono essere associati utilizzando argomenti posizionali o con 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 comodità, le classi Model e Expando hanno un metodo di classe gql() che restituisce un'istanza di 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 un elemento 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 dell'iteratore non memorizza nella cache i risultati, pertanto la creazione di un nuovo iteratore dall'oggetto query reitera 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 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 a fetch() una seconda volta emette la stessa query.

Nota:raramente dovrai utilizzare questo metodo. È quasi sempre meglio utilizzare run() invece.

Costruttore

Il costruttore della classe GqlQuery è definito come segue:

class GqlQuery (query_string, *args, **kwds)

Crea un'istanza della classe GqlQuery per recuperare le 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 istanza

Le istanze della classe GqlQuery hanno i seguenti metodi:

bind (*args, **kwds)

Ricollega i valori dei parametri della query. La query modificata verrà eseguita la prima volta che si accede ai risultati dopo che i relativi parametri sono stati sottoposti a rebound.

Il ricoinvolgimento dei parametri a un oggetto GqlQuery esistente è più rapido della creazione di un nuovo oggetto GqlQuery, perché la stringa di query non deve essere analizzata di nuovo.

Argomenti

args: Nuovi valori dei parametri posizionali.
kwds: Nuovi valori dei parametri delle parole chiave.

projection ()

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

is_keys_only ()

Restituisce un valore booleano che indica se la query è una query solo con 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 oggetto iterabile per eseguire il looping sui 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 ignora il numero di risultati specificato dall'argomento offset.
Recupera e restituisce fino al 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 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 un elemento iterabile per controllare il ciclo. Viene chiamato implicitamente run() con gli argomenti predefiniti.

Argomenti

read_policy

Leggi i criteri 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ù rapidamente rispetto alle query fortemente coerenti, ma non c'è alcuna garanzia.

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

deadline

Tempo massimo, in secondi, di attesa per il ritorno di un risultato da parte di Datastore prima dell'interruzione 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 questo parametro viene omesso, verrà utilizzato il valore specificato nella clausola LIMIT della stringa di query GQL. Se impostato esplicitamente su None, 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; in caso contrario, 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 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 dell'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. Dal Datastore viene recuperato al massimo un risultato; la clausola LIMIT della stringa di query GQL, se presente, viene ignorata.

Argomenti

read_policy

Leggi i criteri 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ù rapidamente rispetto alle query fortemente coerenti, ma non c'è alcuna garanzia.

Nota:le query globali (non antenate) 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

Nota:la specifica di questo parametro potrebbe modificare i requisiti dell'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 (eventualmente vuoto) di risultati:

Recupera e ignora 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 è quindi proporzionale in modo lineare alla somma di offset + limit.

Nota: questo metodo è solo un wrapper sottile del metodo run() ed è meno efficiente e richiede una maggiore quantità di memoria rispetto all'utilizzo diretto di run(). Dovresti raramente dover utilizzare fetch(); viene fornito principalmente per praticità 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 numero è sconosciuto, utilizza 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 i criteri 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ù rapidamente rispetto alle query fortemente coerenti, ma non c'è alcuna garanzia.

Nota:le query globali (non antenate) 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

Nota:la specifica di questo parametro potrebbe modificare i requisiti dell'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 è comunque proporzionale in modo lineare alla 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 i criteri 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ù rapidamente rispetto alle query fortemente coerenti, ma non c'è alcuna garanzia.

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

deadline

offset

Numero di risultati da saltare prima di conteggiare il primo.

limit

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 1000 non sostituisce la clausola LIMIT della query GQL e si applica solo se non è stata specificata alcuna clausola LIMIT.

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 gli indici principali, composti, di tipo e di proprietà singola.

Attenzione: l'invocazione di questo metodo su una query che non è ancora stata eseguita comporterà 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.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 />")

Viene generato 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

cursor ()

Restituisce una stringa cursore codificata in base64 che indica la posizione nel set di risultati della query successiva all'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: l'invocazione di questo metodo su una query che non è ancora stata eseguita comporterà un'eccezione AssertionError.

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

with_cursor (cursor_inizio, cursor_fine=None)

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 dove iniziare la query.
end_cursor: Stringa del cursore con codifica Base64 che specifica dove terminare la query.