Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
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.
Ü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 queryforacctinqry.fetch(10,offset=20):# Skip the first 20printacct
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:
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.
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.
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.
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.
cursor: Abfrage-Cursor, der auf den „nächsten“ Batch von Ergebnissen verweist. Wenn keine weiteren Ergebnisse vorhanden sind, lautet der Wert None.
morebool: 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
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.
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.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-09-04 (UTC)."],[[["\u003cp\u003eThis documentation covers how to use NDB queries within the legacy App Engine standard environment's first-generation runtimes, noting that for App Engine Python 3, a migration guide is recommended.\u003c/p\u003e\n"],["\u003cp\u003eAn NDB \u003ccode\u003eQuery\u003c/code\u003e object is used to request a filtered and sorted list of entities, and you can create one using the \u003ccode\u003e<var>Model</var>.query()\u003c/code\u003e method or directly using \u003ccode\u003endb.Query()\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eQueries can be configured using various keyword arguments or a \u003ccode\u003eQueryOptions\u003c/code\u003e object, allowing for customizations such as returning only keys (\u003ccode\u003ekeys_only\u003c/code\u003e), limiting results (\u003ccode\u003elimit\u003c/code\u003e), skipping results (\u003ccode\u003eoffset\u003c/code\u003e), or specifying a data projection (\u003ccode\u003eprojection\u003c/code\u003e).\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eQuery\u003c/code\u003e object has several instance methods like \u003ccode\u003efilter()\u003c/code\u003e, \u003ccode\u003eorder()\u003c/code\u003e, \u003ccode\u003eget()\u003c/code\u003e, \u003ccode\u003ecount()\u003c/code\u003e, \u003ccode\u003efetch()\u003c/code\u003e, \u003ccode\u003efetch_page()\u003c/code\u003e, \u003ccode\u003emap()\u003c/code\u003e and their async versions, allowing for advanced query customization, execution, and data retrieval.\u003c/p\u003e\n"],["\u003cp\u003eQuery methods often accept keyword arguments, such as \u003ccode\u003elimit\u003c/code\u003e, \u003ccode\u003eoffset\u003c/code\u003e, \u003ccode\u003ekeys_only\u003c/code\u003e, and \u003ccode\u003eprojection\u003c/code\u003e, to refine the results, and these same options can be used in a \u003ccode\u003eQueryOptions\u003c/code\u003e object.\u003c/p\u003e\n"]]],[],null,["# NDB Query Class\n\n| This page describes how to use the legacy bundled services and APIs. This API can only run in first-generation runtimes in the App Engine standard environment. If you are updating to the App Engine Python 3 runtime, refer to the [migration guide](/appengine/migration-center/standard/migrate-to-second-gen/python-differences) to learn about your migration options for legacy bundled services.\n\nA `Query` object represents an NDB query, a request for\na filtered, sorted list of entities.\n\nThis page contains reference documentation. For a general discussion\nof NDB queries, see [Queries](/appengine/docs/legacy/standard/python/ndb/queries).\n\nQuery Options\n-------------\n\nMany query methods take a standard set of additional\noptions, either in the form of keyword arguments such as\n`keys_only=True`, or as\n`QueryOptions` object passed with\n`options=QueryOptions(...)`.\n\nQueries support a variety of configuration options.\nThese are specified by keyword arguments to the `Query` methods:\n\nTo run a query with a specific set of options,\npass the keyword arguments to the applicable method:\n\n```python\nqry = Employee.query().filter(...).order(...) # Create a query\nfor acct in qry.fetch(10, offset=20): # Skip the first 20\n print acct\n```\n\nOccasionally, you might want to keep a set of query options\naround and use them in various places. While you could just\nkeep them in a dictionary and pass this dictionary to the\nmethods using `**kwds`, you can also create a\n`QueryOptions` object and pass\nit using the options keyword argument.\nThe following two examples are equivalent:\n\n```python\nqo = ndb.QueryOptions(keys_only=True, offset=20)\nresults = qry.fetch(10, options=qo)\nresults = qry.fetch(10, keys_only=True, offset=20)\n```\n\nConstructor\n-----------\n\nTypically, an application creates a `Query` by calling\n\u003cvar translate=\"no\"\u003eModel\u003c/var\u003e`.query()`. But it's also possible to call\n`ndb.Query()`.\n\n**Arguments**\n\nkind\n: Optional kind string. Normally, the name of a entity class.\n\nancestor\n: Optional ancestor Key.\n\nfilters\n: Optional Node representing a filter expression tree.\n\norders\n: Optional `datastore_query.Order` object.\n\napp\n: Optional app id.\n\nnamespace\n: Optional namespace. If not specified,\n the default namespace at the time the query is executed will be used.\n\nprojection\n: Optional list or tuple of properties to project.\n\ngroup_by\n: Optional list or tuple of properties to group by.\n\ndefault_options\n: Optional\n [QueryOptions](/appengine/docs/legacy/standard/python/ndb/queryclass#kwdargs_options) object\n giving default query options to be used when the query is executed.\n\nInstance Methods\n----------------\n\nfilter(\u003cvar translate=\"no\"\u003efilter1, filter2, ...\u003c/var\u003e)\n: Returns a new `Query` with additional filter(s) applied.\n Takes filter arguments as described in\n [Queries](/appengine/docs/legacy/standard/python/ndb/queries).\n `qry.filter(`\u003cvar translate=\"no\"\u003efilter1\u003c/var\u003e`).filter(`\u003cvar translate=\"no\"\u003efilter2\u003c/var\u003e`)`\n is equivalent to\n `qry.filter(`\u003cvar translate=\"no\"\u003efilter1\u003c/var\u003e`, `\u003cvar translate=\"no\"\u003efilter2\u003c/var\u003e`)`\n\nget(\\*\\*q_options)\n: Returns the first query result, if any (otherwise `None`).\n This is similar to calling `q.fetch(1)` and returning\n the first item of the list of results.\n\n **Arguments**\n\n \\*\\*q_options\n : All [query options keyword arguments](#kwdargs_options)\n are supported.\n\norder(\u003cvar translate=\"no\"\u003eorder1\u003c/var\u003e, \u003cvar translate=\"no\"\u003eorder2\u003c/var\u003e, ...)\n: Returns a new `Query` with additional sort order(s) applied.\n Takes one or more arguments which are properties or \"negated\" properties.\n For example, to sort users by age and \"break ties\" by name, you might\n use something like `qry.order(-Account.birthday, Account.name)`\n\nbind(\u003cvar translate=\"no\"\u003e...values...\u003c/var\u003e)\n: This function is for use with GQL queries that use parameter\n bindings (`:1`, `:2`, etc.) or named bindings\n (`:foo`, `:bar`, etc.). It binds the passed\n values to the parameters.\n\n To bind parameters, you might call something like\n `qry.bind(\"USA\", 49)`.\n To bind named parameters, you might call something like\n `qry.bind(region = \"USA\", threshold = 49)`.\n\n Returns a new `Query` object with the parameter values bound.\n\ncount(limit=None, \\*\\*q_options)\n: Returns the number of query results, up to a limit.\n This returns the same result as `len(q.fetch(limit))` but more\n efficiently.\n\n **Arguments**\n\n limit\n : How many results to count at most\n\n \\*\\*q_options\n : All [query options keyword arguments](#kwdargs_options)\n and [context options](/appengine/docs/legacy/standard/python/ndb/functions#context_options)\n are supported.\n\ncount_async(limit, \\*\\*q_options)\n: Asynchronously counts the number of query results, up to a limit;\n it returns a [Future](/appengine/docs/legacy/standard/python/ndb/futureclass)\n whose result is a number.\n This is the asynchronous version of [count()](#Query_count).\n\nfetch(limit, \\*\\*q_options)\n\n: Fetch a list of query results, up to a limit. **Arguments**\n\n limit\n : How many results to count at most\n\n \\*\\*q_options\n : All [query options keyword arguments](#kwdargs_options)\n are supported.\n\nfetch_async(limit, \\*\\*q_options)\n: Asynchronously fetch a list of query results, up to a limit.\n Returns a [Future](/appengine/docs/legacy/standard/python/ndb/futureclass)\n whose result is a list of results.\n This is the asynchronous version of [fetch()](#Query_fetch).\n\nfetch_page(page_size, \\*\\*q_options)\n\n: Fetch a \"page\" of results. This is a specialized method for use by paging user interfaces. **Arguments**\n\n page_size\n : At most this many results will be returned.\n\n \\*\\*q_options\n : All [query options keyword arguments](#kwdargs_options)\n are supported.\n\n Returns a tuple `(`\u003cvar translate=\"no\"\u003eresults\u003c/var\u003e`,\n `\u003cvar translate=\"no\"\u003ecursor\u003c/var\u003e`, `\u003cvar translate=\"no\"\u003emore\u003c/var\u003e`)`:\n\n - \u003cvar translate=\"no\"\u003eresults\u003c/var\u003e list of query results\n - \u003cvar translate=\"no\"\u003ecursor\u003c/var\u003e a [query cursor](/appengine/docs/legacy/standard/python/ndb/queries#cursors) pointing to the \"next\" batch of results. If there are no more results, this might be `None`.\n - \u003cvar translate=\"no\"\u003emore\u003c/var\u003e `bool` indicating whether there are (likely) more results after this batch. If `False`, there are no more results; if `True`, there are *probably* more results.\n\n To fetch the next page,\n pass the cursor returned by one call to the next call using\n `start_cursor=`\u003cvar translate=\"no\"\u003ecursor\u003c/var\u003e.\n A common idiom is to pass the cursor to\n the client using \u003cvar translate=\"no\"\u003ecursor\u003c/var\u003e`.urlsafe()`\n and to reconstruct that cursor on a subsequent request using\n `Cursor(urlsafe=`\u003cvar translate=\"no\"\u003estring\u003c/var\u003e`)`.\n\nfetch_page_async(page_size, \\*\\*q_options)\n: Asynchronously fetch a \"page\" of results. This is the asynchronous version\n of [fetch_page()](#Query_fetch_page).\n\nget_async(\\*\\*q_options)\n: Asynchronously returns the first query result, if any\n (otherwise `None`). This is the asynchronous version\n of [get()](#Query_get).\n\niter(\\*\\*q_options)\n\n: Constructs and returns an iterator over the query. **Arguments**\n\n \\*\\*q_options\n : All [query options keyword arguments](#kwdargs_options)\n are supported.\n\n Returns a [QueryIterator](/appengine/docs/legacy/standard/python/ndb/queries#iterators) object.\n\nmap(callback, pass_batch_into_callback=None, merge_future=None, \\*\\*q_options)\n\n: Map a callback function or tasklet over the query results. That is, apply the function (or tasklet) to each entity in the query results. **Arguments**\n\n callback\n : A function or tasklet to be applied to each result.\n\n pass_batch_into_callback\n : If `True`, calls the callback with batch information\n arguments as described below.\n\n merge_future\n : Optional [Future](/appengine/docs/legacy/standard/python/ndb/futureclass) subclass;\n see below.\n\n \\*\\*q_options\n : All [query options keyword arguments](#kwdargs_options)\n are supported.\n\n *Callback signature* The callback is normally called with an entity\n as argument. However, if\n `keys_only=True` is given, it is called\n with a [Key](/appengine/docs/legacy/standard/python/ndb/keyclass).\n If `pass_batch_into_callback=True` is given, the callback is\n called with three arguments: the current batch, the index within\n the batch, and the entity or `Key` at that index.\n The callback can\n return whatever it wants. If the callback is `None`, a trivial\n callback is assumed that just returns the entity or key passed in.\n\n *Optional `merge_future`* The `merge_future`\n is an advanced argument\n that can be used to override how the callback results are combined\n into the overall `map()` return value. By default, a list of\n callback return values is produced. By substituting one of a\n small number of specialized alternatives you can arrange\n otherwise. See the source code for\n `tasklets.MultiFuture` for the default\n implementation and a description of\n the protocol the `merge_future`\n object must implement. Alternatives from the same\n module include `QueueFuture`, `SerialQueueFuture`\n and `ReducingFuture`.\n\n Returns a list of the results of all the callbacks.\n (But see 'optional `merge_future`' above.) It returns\n when the query has run to completion and all callbacks have returned.\n\nmap_async(callback, pass_batch_into_callback=None, merge_future=None, \\*\\*q_options)\n: Asynchronously map a callback function or tasklet over the query results.\n This is the asynchronous version of [map()](#map)."]]
