Classe di query NDB

Un oggetto Query rappresenta una query NDB, ovvero 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 Query.

Opzioni query

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

Le query supportano una serie di opzioni di configurazione. Questi vengono specificati dagli argomenti delle parole chiave per i metodi Query:

Argomento Tipo Predefinito Descrizione
keys_only bool False Tutte le operazioni restituiscono chiavi anziché entità.
proiezione 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 solo questi due campi impostati. (Consulta la sezione Query di proiezione.)
compensazione int 0 Numero di risultati della query da saltare.
limite int Nessun limite Numero massimo di risultati della query da restituire.
batch_size int 20 Dimensione del batch.

Influisce solo sull'efficienza delle query. I batch di dimensioni maggiori utilizzano più memoria, ma eseguono meno chiamate RPC.
prefetch_size int None Sostituisce la dimensione del batch per il primo batch restituito.
produce_cursors bool False Genera cursori dalla query (consulta Iteratori di query. Cursori di query).
start_cursor Cursor None Punto di partenza per la ricerca (vedi Cursori di query).
end_cursor Cursor None Punto di fine della ricerca (vedi Cursori di query).
scadenza int Dipende da Context Sostituisce la scadenza RPC (che per impostazione predefinita è di 5 secondi se non sostituita 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

A volte, potresti voler conservare un insieme di opzioni di query e utilizzarle in vari punti. Anche se potresti semplicemente conservarli in un dizionario e passarlo ai metodi utilizzando **kwds, puoi anche creare un oggetto QueryOptions e passarlo utilizzando l'argomento della parola chiave options. 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(). È però possibile chiamare anche ndb.Query().

Argomenti

kind
Stringa tipo facoltativa. Di solito, il nome di una classe di entità.
antenato
Chiave antenato facoltativa.
filtri
Nodo facoltativo che rappresenta un albero di espressioni di filtro.
orders
Oggetto
datastore_query.Order facoltativo.
app
ID app facoltativo.
namespace
Spazio dei nomi facoltativo. Se non specificato, verrà utilizzato lo spazio dei nomi predefinito al momento dell'esecuzione della query.
proiezione
Elenco facoltativo o tupla di proprietà da proiettare.
group_by
Elenco o tupla facoltativi di proprietà per il raggruppamento.
default_options
Oggetto facoltativo QueryOptions che fornisce le opzioni di query predefinite da utilizzare quando la query viene eseguita.

Metodi istanza

filter(filter1, filter2, ...)
Restituisce un nuovo Query con uno o più filtri aggiuntivi applicati. Accetta gli argomenti del filtro come descritto in Query. qry.filter(filter1).filter(filter2) è equivalente a qry.filter(filter1, filter2)
get(**q_options)
Restituisce il primo risultato della query, se esistente (in caso contrario None). È simile a chiamare q.fetch(1) e restituire il primo elemento dell'elenco dei risultati.

Argomenti

**q_options
Sono supportati tutti gli argomenti delle parole chiave delle opzioni di query.
order(order1, order2, ...)
Restituisce un nuovo Query con un ordine di ordinamento aggiuntivo o più. Accetta uno o più argomenti che sono proprietà o proprietà "negate". Ad esempio, per ordinare gli utenti per età e "risolvere i casi in cui più utenti hanno lo stesso valore" in base al nome, potresti utilizzare qualcosa di simile a qry.order(-Account.birthday, Account.name)
bind(...values...)
Questa funzione è da utilizzare con le query GQL che utilizzano associazioni di parametri (:1, :2 e così via) o associazioni denominate (:foo, :bar e così via). Collega i valori passati ai parametri.

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

Restituisce un nuovo oggetto Query con i valori dei parametri legati.

count(limit=None, **q_options)
Restituisce 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

limit
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)
Conteggia in modo asincrono il numero di risultati della query, fino a un limite; restituisce un Future il cui risultato è un numero. Questa è la versione asincrona di count().
fetch(limit, **q_options)
Recupero di un elenco di risultati di query, fino a un limite.

Argomenti

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

Argomenti

page_size
Al massimo verranno restituiti questo numero di risultati.
**q_options
Sono supportati tutti gli argomenti delle parole chiave delle opzioni di query.
Restituisce una tupla (results, cursor, more):
  • results elenco dei risultati della query
  • cursor un cursor di query che rimanda al "batch successivo" di risultati. Se non ci sono altri risultati, potrebbe essere None.
  • more bool che indica se sono presenti (probabilmente) altri risultati dopo questo batch. Se False, non ci sono altri risultati; se True, probabilmente ci sono altri risultati.

Per recuperare la pagina successiva, passa il cursore restituito da una chiamata alla chiamata successiva utilizzando start_cursor=cursor. Un'espressione idiomatica 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)
Recupero in modo asincrono di una "pagina" di risultati. Questa è la versione asincrona di fetch_page().
get_async(**q_options)
Restituisce in modo asincrono il primo risultato della query, se esistente (in caso contrario None). Questa è la versione asincrona di get().
iter(**q_options)
Costruisce e restituisce un iteratore per la query.

Argomenti

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

Restituisce un oggetto QueryIterator.

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

Argomenti

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

Firma del callback Il callback viene chiamato in genere con un'entità come argomento. Tuttavia, se viene fornito keys_only=True, viene chiamato con una chiave. Se viene specificato 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 quell'indice. Il callback può restituire ciò che vuole. Se il callback è None, viene assunto un callback banale che restituisce solo l'entità o la chiave passata.

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

Restituisce un elenco dei risultati di tutti i richiami. (ma vedi "facoltativo merge_future" sopra). Restituisce un valore quando la query è stata completata e tutti i callback sono stati restituiti.

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