Un oggetto Query
rappresenta una query NDB, una richiesta di
un elenco ordinato e filtrato di entità.
Questa pagina contiene la documentazione di riferimento. Per una discussione generale sulle query NDB, consulta Query.
Opzioni query
Molti metodi di query richiedono un insieme standard di opzioni aggiuntive, sotto forma di argomenti delle parole chiave come keys_only=True
o come oggetto QueryOptions
passato con options=QueryOptions(...)
.
Le query supportano una serie di opzioni di configurazione.
Queste vengono specificate tramite argomenti di parole chiave nei metodi Query
:
Argomento | Tipo | Predefinita | 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 solo questi due campi impostati.
(vedi Query di proiezione).
|
compensare | 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; le dimensioni batch più grandi utilizzano più memoria, ma effettuano 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 (vedi Iteratori di query. Cursori di query). |
start_cursor | Cursor | None
| Punto di partenza per la ricerca (vedi Cursori delle query). |
end_cursor | Cursor | None
| Punto finale per la ricerca (vedi Cursori delle query). |
scadenza | int | Dipende da Context
| Sostituisce la scadenza RPC (che per impostazione predefinita è di 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 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, passa gli argomenti delle parole 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 mantenere un insieme di opzioni di query e utilizzarle in vari punti. Anche se puoi 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
- gentile
- Stringa di tipo facoltativa. Normalmente, il nome di una classe entità.
- ancestor
- Chiave predecessore facoltativa.
- filtri
- Nodo facoltativo che rappresenta un albero di 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 facoltativo o tupla di proprietà da proiettare.
- group_by
- Elenco o tupla facoltativo di proprietà in base alle quali eseguire il raggruppamento.
- default_options
- Oggetto
QueryOptions
facoltativo che offre opzioni di query predefinite da utilizzare quando viene eseguita la query.
Metodi di istanza
- filtro(filter1, filter2, ...)
- restituisce un nuovo
Query
con filtri aggiuntivi applicati. Accetta gli argomenti di filtro come descritto in Query.qry.filter(filter1).filter(filter2)
equivale aqry.filter(filter1, filter2)
- get(**q_options)
- Restituisci il primo risultato della query, se presente (altrimenti
None
). È un po' come chiamareq.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.
- ordine(order1, order2, ...)
- Restituisci un nuovo
Query
con ordini di ordinamento aggiuntivi applicati. Richiede uno o più argomenti che sono proprietà o proprietà "negate". Ad esempio, per ordinare gli utenti per età e "rompere i legami" per nome, potresti utilizzare un elemento simile aqry.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, puoi chiamare in modo simile a
qry.bind("USA", 49)
. Per associare parametri con nome, potresti chiamare in modo simile aqry.bind(region = "USA", threshold = 49)
.Restituisce un nuovo oggetto
Query
con i valori dei parametri associati. - count(limit=None, **q_options)
- Restituisci il numero di risultati della query, fino a un limite definito.
Viene restituito lo stesso risultato di
len(q.fetch(limit))
, ma in modo più efficiente.Argomenti
- limite
- Numero massimo di risultati da conteggiare
- **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 limite definito; restituisce un valore
Future
il cui risultato è un numero. Questa è la versione asincrona di count(). - fetch(limit, **q_options)
- Recupera un elenco di risultati delle query, fino a un limite definito.
Argomenti
- limite
- Numero massimo di risultati da conteggiare
- **q_options
- Sono supportati tutti gli argomenti delle parole chiave delle opzioni di query.
- fetch_async(limit, **q_options)
- Recupera in modo asincrono un elenco di risultati delle query, fino a un limite definito.
Restituisce un
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 l'utilizzo tramite il paging delle interfacce utente.
Argomenti
- page_size
- Verranno restituiti al massimo questi risultati.
- **q_options
- Sono supportati tutti gli argomenti delle parole chiave delle opzioni di query.
(results, cursor, more)
:- results elenco di risultati della query
- cursor un cursore di query che punta al batch 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. SeFalse
, non ci sono altri risultati; seTrue
, 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 di dire comune è passare il cursore al client utilizzandocursor.urlsafe()
e ricostruire il cursore in una richiesta successiva utilizzandoCursor(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 sulla 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 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 delle parole chiave delle opzioni di query.
Firma di callback Il callback viene solitamente chiamato con un'entità come argomento. Tuttavia, se
keys_only=True
è specificato, viene chiamato con una chiave. Se viene specificatopass_batch_into_callback=True
, il callback viene chiamato con tre argomenti: il batch attuale, l'indice all'interno del batch e l'entità oKey
in quell'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 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 totale dimap()
. Per impostazione predefinita, viene generato un elenco di valori restituiti per il callback. Se sostituisci una di un numero limitato di alternative specializzate, puoi organizzare diversamente. Controlla il codice sorgente ditasklets.MultiFuture
per l'implementazione predefinita e una descrizione del protocollo che l'oggettomerge_future
deve implementare. Le alternative dello stesso modulo includonoQueueFuture
,SerialQueueFuture
eReducingFuture
.Restituisce un elenco dei risultati di tutti i callback. (vedi "
merge_future
facoltativo" sopra). 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 di callback o un tasklet sui risultati della query. Questa è la versione asincrona di map().