Classe di query NDB

Un oggetto Query rappresenta una query NDB, una richiesta di un elenco filtrato e ordinato di entità.

Questa pagina contiene la documentazione di riferimento. Per una discussione generale sulle query NDB, consulta la sezione Query.

Opzioni query

Molti metodi di query utilizzano un insieme standard di opzioni aggiuntive, sotto forma di argomenti di parole chiave come keys_only=True o di oggetto QueryOptions passato con options=QueryOptions(...).

Le query supportano una varietà di opzioni di configurazione. Questi vengono specificati da argomenti parola chiave per i metodi Query:

Argomento Tipo Predefinito Descrizione
keys_only bool False Tutte le operazioni restituiscono chiavi anziché entità.
projection tupla (o elenco) di proprietà (o stringhe) None Le operazioni restituiscono entità con solo le proprietà specificate impostate. projection=[Article.title, Article.date] o projection=['title', 'date'] recupera le entità con questi due campi impostati. (Vedi Query di proiezione.)
offset int 0 Numero di risultati della query da ignorare.
limite int Nessun limite Numero massimo di risultati della query da restituire.
batch_size int 20 Dimensioni del batch.

Influisce solo sull'efficienza delle query: i batch di dimensioni maggiori utilizzano più memoria, ma effettuano meno chiamate RPC.
prefetch_size int None Sostituisce le dimensioni del primo batch restituito.
produce_cursors bool False Genera cursori dalla query (vedi Iteratori di query. cursori di query).
start_cursor Cursor None Punto di partenza della ricerca (vedi Cursori delle query).
end_cursor Cursor None Punto finale della ricerca (vedi Cursori delle query).
scadenza int Dipende da Context Esegue l'override della scadenza RPC (il valore predefinito è 5 secondi se non viene eseguito l'override al momento della creazione di Context)
read_policy ndb.EVENTUAL_CONSISTENCY Il criterio per la lettura. Imposta su ndb.EVENTUAL_CONSISTENCY per ottenere risultati forse più rapidi senza attendere che Datastore applichi le modifiche in attesa a tutti i record restituiti.

Per eseguire una query con un insieme specifico di opzioni, trasmetti gli argomenti della parola chiave al metodo applicabile: 

qry = Employee.query().filter(...).order(...) # Create a query
for acct in qry.fetch(10, offset=20): # Skip the first 20
  print acct

Di tanto in tanto, potresti voler mantenere un insieme di opzioni di query e utilizzarle in varie posizioni. Sebbene tu possa semplicemente tenerli in un dizionario e passare questo dizionario ai metodi utilizzando **kwds, puoi anche creare un oggetto QueryOptions e passarlo utilizzando l'argomento parola chiave delle opzioni. I seguenti due esempi sono equivalenti: 

qo = ndb.QueryOptions(keys_only=True, offset=20)
results = qry.fetch(10, options=qo)
results = qry.fetch(10, keys_only=True, offset=20)

Costruttore

In genere, un'applicazione crea un Query chiamando Model.query(). Ma è anche possibile chiamare ndb.Query().

Argomenti

kind
Stringa di tipo facoltativa. Normalmente, il nome di una classe di entità.
ancestor
Chiave predecessore facoltativa.
filtri
Nodo facoltativo che rappresenta una struttura ad albero delle espressioni di filtro.
ordini
Oggetto datastore_query.Order facoltativo.
app
ID app facoltativo.
spazio dei nomi
Spazio dei nomi facoltativo. Se non specificato, verrà utilizzato lo spazio dei nomi predefinito al momento dell'esecuzione della query.
proiezione
Elenco o tuple di proprietà facoltativo per il progetto.
group_by
Elenco o tupla di proprietà facoltativo in base a cui raggruppare.
default_options
Oggetto QueryOptions facoltativo che fornisce opzioni di query predefinite da utilizzare quando la query viene eseguita.

Metodi di istanza

filtro(filter1, filter2, ...)
restituisce un nuovo Query con filtri aggiuntivi applicati. Accetta argomenti di filtro come descritto in Query. qry.filter(filter1).filter(filter2) equivale a qry.filter(filter1, filter2)
get(**q_options)
Restituisci il primo risultato della query, se presente (in caso contrario None). Questa operazione è simile alla chiamata a q.fetch(1), che restituisce il primo elemento dell'elenco dei risultati.

Argomenti

**q_options
Sono supportati tutti gli argomenti di parole chiave per le opzioni di query.
order(order1, order2, ...)
Restituisci un nuovo Query con altri ordinamenti applicati. Prende uno o più argomenti che sono proprietà o proprietà "negate". Ad esempio, per ordinare gli utenti per età e "interruzione dei legami" per nome, potresti usare una parola come qry.order(-Account.birthday, Account.name)
bind(...values...)
Questa funzione deve essere utilizzata con le query GQL che utilizzano associazioni di parametri (:1, :2 e così via) o associazioni denominate (:foo, :bar e così via). Associa i valori passati ai parametri.

Per associare i parametri, potresti chiamare qualcosa come qry.bind("USA", 49). Per associare i parametri denominati, puoi chiamare qualcosa come qry.bind(region = "USA", threshold = 49).

Restituisce un nuovo oggetto Query con i valori parametro associati.

count(limit=Nessuno, **q_options)
Restituisci il numero di risultati della query, fino a un limite. Questo restituisce lo stesso risultato di len(q.fetch(limit)), ma in modo più efficiente.

Argomenti

limite
Quanti risultati conteggiare al massimo
**q_options
Sono supportati tutti gli argomenti delle parole chiave delle opzioni di query e le opzioni di contesto.
count_async(limit, **q_options)
Conta in modo asincrono il numero di risultati della query, fino a un determinato limite, restituisce un Future il cui risultato è un numero. Questa è la versione asincrona di count().
fetch(limite, **q_options)
Recupera un elenco dei risultati delle query, fino a un limite.

Argomenti

limite
Quanti risultati conteggiare al massimo
**q_options
Sono supportati tutti gli argomenti di parole chiave per le opzioni di query.
fetch_async(limit, **q_options)
Recupera in modo asincrono un elenco dei risultati delle query, fino a un limite. Restituisce un valore Future il cui risultato è un elenco di risultati. Questa è la versione asincrona di fetch().
fetch_page(page_size, page_size)
Recupera una "pagina" di risultati. Si tratta di un metodo specializzato per il paging delle interfacce utente.

Argomenti

page_size
Verranno restituiti al massimo questo numero di risultati.
**q_options
Sono supportati tutti gli argomenti di parole chiave per le opzioni di query.
Restituisce una tupla (results, cursor, more):
  • results elenco di risultati della query
  • cursor un cursore di query che punta al gruppo di risultati "successivo". Se non ci sono altri risultati, potrebbe essere None.
  • more bool che indica se ci sono (probabilmente) più risultati dopo questo batch. Se False non ci sono altri risultati; se True, ci sono probabilmente altri risultati.

Per recuperare la pagina successiva, passa il cursore restituito da una chiamata alla chiamata successiva utilizzando start_cursor=cursor. Un modo comune è passare il cursore al client utilizzando cursor.urlsafe() e ricostruire il cursore in una richiesta successiva utilizzando Cursor(urlsafe=string).

fetch_page_async(page_size, **q_options)
Recupera in modo asincrono una "pagina" di risultati. Questa è la versione asincrona di fetch_page().
get_async(**q_options)
Restituisci in modo asincrono il primo risultato della query, se presente (altrimenti None). Questa è la versione asincrona di get().
iter(**q_options)
Crea e restituisce un iteratore per la query.

Argomenti

**q_options
Sono supportati tutti gli argomenti di parole chiave per le opzioni di query.

Restituisce un oggetto QueryIterator.

map(callback, pass_batch_into_callback=Nessuno, merge_future=Nessuno, **q_options)
Mappa una funzione o un tasklet di callback sui risultati della query. In altre parole, applica la funzione (o il tasklet) a ciascuna entità nei risultati della query.

Argomenti

richiamata
Una funzione o un tasklet da applicare a ciascun risultato.
pass_batch_into_callback
Se True, chiama il callback con argomenti delle informazioni batch, come descritto di seguito.
merge_future
Sottoclasse Future facoltativa; vedi di seguito.
**q_options
Sono supportati tutti gli argomenti di parole chiave per le opzioni di query.

Firma di callback Il callback viene solitamente chiamato con un'entità come argomento. Tuttavia, se viene fornito un valore keys_only=True, viene chiamato con una chiave. Se viene indicato pass_batch_into_callback=True, il callback viene chiamato con tre argomenti: il batch corrente, l'indice all'interno del batch e l'entità o Key in tale indice. Il callback può restituire ciò che vuole. Se il callback è None, si presume un callback banale che restituisce solo l'entità o la chiave trasmessa.

merge_future (Facoltativo) merge_future è un argomento avanzato che può essere utilizzato per sostituire il modo in cui i risultati del callback vengono combinati nel valore restituito map() complessivo. Per impostazione predefinita, viene generato un elenco di valori restituiti per il callback. Sostituendo una delle poche alternative specializzate disponibili puoi organizzare diversamente. Visualizza il codice sorgente di tasklets.MultiFuture per l'implementazione predefinita e una descrizione del protocollo che l'oggetto merge_future deve implementare. Le alternative per lo stesso modulo includono QueueFuture, SerialQueueFuture e ReducingFuture.

Restituisce un elenco dei risultati di tutti i callback. (vedi la sezione "merge_future facoltativo" in alto). Restituisce quando la query è stata eseguita fino al completamento e sono stati restituiti tutti i callback.

map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
Mappa in modo asincrono una funzione o un tasklet di callback sui risultati della query. Questa è la versione asincrona di map().