Hinweis: Python 2.7 hat am 31. Januar 2024 das Ende des Supports erreicht. Ihre vorhandenen Python 2.7-Anwendungen werden weiterhin ausgeführt und erhalten Traffic. App Engine kann die erneute Bereitstellung von Anwendungen, die Laufzeiten verwenden, jedoch nach dem Enddatum des Supports blockieren. Wir empfehlen die Migration zur neuesten unterstützten Version von Python.

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.
Projektion: 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().