NDB-Abfrageklasse

Ein Query-Objekt stellt eine NDB-Abfrage dar, also eine Anfrage bezüglich einer gefilterten, sortierten Liste von Entitäten.

Diese Seite enthält eine Referenzdokumentation. Eine allgemeine Beschreibung von NDB-Abfragen finden Sie unter Abfragen.

Abfrageoptionen

Viele Abfragemethoden enthalten zusätzliche Standardoptionen in Form von Schlüsselwortargumenten wie keys_only=True oder als QueryOptions-Objekt, das mit options=QueryOptions(...) übergeben wird.

Abfragen unterstützen eine Vielzahl von Konfigurationsoptionen. Diese werden durch Schlüsselwortargumente für die Query-Methoden angegeben:

Argument Typ Standardeinstellung Beschreibung
keys_only bool False Alle Vorgänge geben Schlüssel statt Entitäten zurück.
Projektion Tupel (oder Liste) von Properties (oder Strings) None Operationen geben Entitäten zurück, die ausschließlich die festgelegten Properties enthalten. projection=[Article.title, Article.date] oder projection=['title', 'date'] ruft Entitäten mit nur diesen beiden festgelegten Feldern ab (siehe Projektionsabfragen).
offset int 0 Anzahl der zu überspringenden Abfrageergebnisse.
Limit int Kein Limit Maximale Anzahl der Abfrageergebnisse, die zurückgegeben werden sollen.
batch_size int 20 Batchgröße.

Beeinflusst nur die Effizienz von Abfragen. Bei größeren Batches wird mehr Speicher verwendet, aber die Zahl der RPC-Aufrufe ist geringer.
prefetch_size int None Überschreibt die Batchgröße für den ersten zurückgegebenen Batch.
produce_cursors bool False Generiert Cursor aus der Abfrage (siehe Abfrage-Iteratoren. Abfrage-Cursor.)
start_cursor Cursor None Startpunkt für die Suche (siehe Abfrage-Cursor).
end_cursor Cursor None Endpunkt für die Suche (siehe Abfrage-Cursor).
deadline int Je nach Context Überschreibt das RPC-Zeitlimit (das standardmäßig fünf Sekunden beträgt, wenn es beim Erstellen von Context nicht überschrieben wird)
read_policy ndb.EVENTUAL_CONSISTENCY Die Leserichtlinie. Auf ndb.EVENTUAL_CONSISTENCY festgelegt, um eventuell schnellere Ergebnisse zu generieren. Es wird dabei nicht darauf gewartet, dass der Datenspeicher ausstehende Änderungen auf alle zurückgegebenen Datensätze anwendet.

Um eine Abfrage mit bestimmten Optionen auszuführen, übergeben Sie die Schlüsselwortargumente an die entsprechende Methode: 

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

Es kann vorkommen, dass Sie eine Reihe von Abfrageoptionen beibehalten und an verschiedenen Stellen verwenden möchten. Sie können sie einfach in einem Wörterbuch beibehalten und dieses mithilfe von **kwds an die Methode übergeben. Sie können aber auch ein QueryOptions-Objekt erstellen und es mit dem Schlüsselwortargument für Optionen übergeben. Die folgenden zwei Beispiele sind gleichwertig: 

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

Konstruktor

In der Regel erstellt eine Anwendung eine Query durch Aufruf von Model.query(). Abfragen können aber auch mit ndb.Query() durchgeführt werden.

Argumente

Typ
Optionaler String für die Art. Normalerweise der Name einer Entitätsklasse.
ancestor
Optionaler Ancestor-Schlüssel
filters
Optionaler Knoten, der eine Filterausdrucksstruktur darstellt
orders
Optionales datastore_query.Order-Objekt
app
Optionale Anwendungs-ID
Namespace
Optionaler Namespace. Wenn keine Angabe erfolgt, wird der bei der Ausführung der Abfrage festgelegte Standard-Namespace verwendet.
projection
Optionale Liste oder Tupel von Properties, die projiziert werden sollen
group_by
Optionale Liste oder Tupel von Properties, nach denen gruppiert werden soll
default_options
Optionales QueryOptions-Objekt, das zur Ausführung der Abfrage Standardabfrageoptionen zur Verfügung stellt

Instanzmethoden

filter(filter1, filter2, ...)
Gibt eine neue Query mit zusätzlichen angewendeten Filtern zurück. Verwendet Filterargumente, wie unter Abfragen erläutert. qry.filter(filter1).filter(filter2) entspricht qry.filter(filter1, filter2)
get(**q_options)
Gibt das erste Abfrageergebnis zurück, falls vorhanden (andernfalls None). Ähnlich verhält es sich, wenn q.fetch(1) aufgerufen und das erste Element der Ergebnisliste zurückgegeben wird.

Argumente

**q_options
Alle Schlüsselwortargumente für Abfrageoptionen werden unterstützt.
order(order1, order2, ...)
Gibt eine neue Query mit zusätzlichen angewendeten Sortierreihenfolgen zurück. Verwendet ein oder mehrere Argumente, bei denen es sich um Attribute oder "negierte" Attribute handelt. Beispiel: Zum Sortieren von Nutzern nach Alter und, falls mehrere Treffer vorhanden sind, nach Name können Sie beispielsweise qry.order(-Account.birthday, Account.name) verwenden.
bind(...values...)
Diese Funktion ist für GQL-Abfragen vorgesehen, die Parameterbindungen (:1, :2 usw.) oder benannte Bindungen (:foo, :bar usw.) verwenden. Es bindet die übergebenen Werte an die Parameter.

Zum Binden von Parametern können Sie beispielsweise qry.bind("USA", 49) aufrufen. Zum Binden von benannten Parametern können Sie beispielsweise qry.bind(region = "USA", threshold = 49) aufrufen.

Gibt ein neues Query-Objekt mit den gebundenen Parameterwerten zurück

count(limit=None, **q_options)
Gibt die Anzahl der Abfrageergebnisse bis zu einem Grenzwert zurück. Hier wird dasselbe Ergebnis wie mit len(q.fetch(limit)) zurückgegeben, allerdings effizienter.

Argumente

limit
Die maximale Anzahl von Ergebnissen, die gezählt werden können.
**q_options
Alle Schlüsselwortargumente für Abfrageoptionen und Kontextoptionen werden unterstützt.
count_async(limit, **q_options)
Zählt die Anzahl der Abfrageergebnisse asynchron bis zu einem Grenzwert. Gibt ein Objekt vom Typ Future zurück, dessen Ergebnis eine Zahl ist. Dies ist die asynchrone Version von count().
fetch(limit, **q_options)
Ruft eine Liste von Abfrageergebnissen bis zu einem Limit ab

Argumente

limit
Die maximale Anzahl von Ergebnissen, die gezählt werden können.
**q_options
Alle Schlüsselwortargumente für Abfrageoptionen werden unterstützt.
fetch_async(limit, **q_options)
Ruft eine Liste von Abfrageergebnissen bis zu einem Grenzwert asynchron ab. Gibt ein Objekt vom Typ Future zurück, dessen Ergebnis eine Ergebnisliste ist. Dies ist die asynchrone Version von fetch().
fetch_page(page_size, **q_options)
Ruft eine „Seite“ mit Ergebnissen ab. Dies ist eine spezielle Methode von Paging-Benutzerschnittstellen.

Argumente

page_size
Diese Anzahl von Ergebnissen wird maximal zurückgegeben.
**q_options
Alle Schlüsselwortargumente für Abfrageoptionen werden unterstützt.
Gibt ein Tupel (results, cursor, more) zurück:
  • results: Liste mit Abfrageergebnissen
  • cursor: Abfrage-Cursor, der auf den „nächsten“ Batch von Ergebnissen verweist. Wenn keine weiteren Ergebnisse vorhanden sind, lautet der Wert None.
  • more bool: Zeigt an, ob nach diesem Batch wahrscheinlich noch weitere Ergebnisse vorhanden sind. Bei False gibt es keine weiteren Ergebnisse. Bei True gibt es wahrscheinlich weitere Ergebnisse.

Wenn Sie die nächste Seite abrufen möchten, übergeben Sie mit start_cursor=cursor den von einem Aufruf zurückgegebenen Cursor an den nächsten Aufruf. Eine gängige Vorgehensweise besteht darin, den Cursor mit cursor.urlsafe() an den Client zu übergeben und diesen Cursor bei einer nachfolgenden Anfrage mit Cursor(urlsafe=string) zu rekonstruieren.

fetch_page_async(page_size, **q_options)
Ruft eine „Seite“ mit Ergebnissen asynchron ab. Dies ist die asynchrone Version von fetch_page().
get_async(**q_options)
Gibt das erste Abfrageergebnis asynchron zurück, falls vorhanden (andernfalls None). Dies ist die asynchrone Version von get().
iter(**q_options)
Konstruiert einen Iterator über die Abfrage und gibt ihn zurück

Argumente

**q_options
Alle Schlüsselwortargumente für Abfrageoptionen werden unterstützt.

Gibt ein QueryIterator-Objekt zurück.

map(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
Ordnet eine Callback-Funktion oder ein Tasklet über die Abfrageergebnisse zu. Dies bedeutet, dass die Funktion (oder das Tasklet) auf jede Entität in den Abfrageergebnissen angewendet wird.

Argumente

callback
Eine Funktion oder ein Tasklet, die bzw. das auf jedes Ergebnis angewendet werden soll
pass_batch_into_callback
Bei True wird der Callback mit Argumenten für Batchinformationen wie nachfolgend beschrieben aufgerufen.
merge_future
Optionale abgeleitete Future-Klasse; siehe unten
**q_options
Alle Schlüsselwortargumente für Abfrageoptionen werden unterstützt.

Rückrufsignatur: Die Rückrufsignatur wird normalerweise mit einer Entität als Argument aufgerufen. Gilt jedoch keys_only=True, wird sie mit einem Schlüssel (Key) aufgerufen. Wenn pass_batch_into_callback=True angegeben ist, wird der Callback mit drei Argumenten aufgerufen: dem aktuellen Batch, dem Index innerhalb des Batches und der Entität oder dem Key bei diesem Index. Der Rückgabe des Rückrufs ist beliebig. Wenn der Callback None entspricht, wird von einem trivialen Callback ausgegangen, der lediglich die übergebene Entität oder den übergebenen Schlüssel zurückgibt.

Optionales merge_future: merge_future ist ein erweitertes Argument, mit dem Sie die Vorgehensweise beim Kombinieren der Callback-Ergebnisse zum Gesamtrückgabewert map() überschreiben können. Standardmäßig wird eine Liste von Rückgabewerten für den Callback erstellt. Wenn Sie eine Alternative einer geringen Anzahl von speziellen Alternativen ersetzen, können Sie eine andere Anordnung vornehmen. Die Standardimplementierung und eine Beschreibung des Protokolls, das das merge_future-Objekt implementieren muss, finden Sie im Quellcode für tasklets.MultiFuture. Alternativen aus demselben Modul sind QueueFuture, SerialQueueFuture und ReducingFuture.

Gibt eine Liste der Ergebnisse aller Rückrufe zurück. (Weitere Informationen finden Sie unter „Optionales merge_future“ oben.) Es wird zurückgegeben, wenn die Abfrage vollständig ausgeführt wurde und alle Rückrufe zurückgegeben wurden.

map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
Ordnet eine Callback-Funktion oder ein Tasklet asynchron über die Abfrageergebnisse zu. Dies ist die asynchrone Version von map().