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.

Klasse "Query"

Hinweis: Entwicklern von neuen Anwendungen wird dringend empfohlen, die NDB-Clientbibliothek zu verwenden. Diese bietet im Vergleich zur vorliegenden Clientbibliothek verschiedene Vorteile, z. B. das automatische Caching von Entitäten über die Memcache API. Wenn Sie derzeit die ältere DB-Clientbibliothek verwenden, finden Sie weitere Informationen im Leitfaden zur Migration von DB- zu NDB-Clientbibliotheken.

Die Klasse Query stellt eine Abfrage zum Abrufen von Entitäten aus dem App Engine Datastore dar. Weitere Informationen finden Sie auch unter der verwandten Klasse GqlQuery, die Abfragen mit GQL definiert, einer SQL-ähnlichen Abfragesprache.

Query ist im Modul google.appengine.ext.db definiert.

Hinweis: Der indexbasierte Abfragemechanismus unterstützt ein breites Spektrum an Abfragen und ist für die meisten Anwendungen geeignet. Allerdings werden einige Arten von Abfragen, die in anderen Datenbanktechnologien üblich sind, vom Abfragemodul in Datastore nicht unterstützt, insbesondere Join- und Aggregatabfragen. Weitere Informationen zu Einschränkungen bei Datastore-Abfragen finden Sie auf der Seite Datastore-Abfragen.

Einführung

Eine Anwendung erstellt ein Abfrageobjekt für eine bestimmten Entitätsart. Dazu ruft Sie entweder den Query-Konstruktor direkt auf:

class Song(db.Model):
  title = db.StringProperty()
  composer = db.StringProperty()
  date = db.DateTimeProperty()

q = db.Query(Song)

oder die Klassenmethode all() der Modellklasse der Art:

q = Song.all()

Ohne weitere Änderungen ruft die resultierende Instanz der Klasse Query alle vorhandenen Entitäten der angegebenen Art ab. Über Methodenaufrufe für das Objekt lässt sich die Abfrage dann mit zusätzlichen Filterkriterien, Ancestor-Bedingungen und Sortierreihenfolgen anpassen:

q.filter('title =', 'Imagine')
q.ancestor(ancestor_key)
q.order('-date')

Der Einfachheit halber geben alle diese Methoden das Abfrageobjekt selbst zurück und können deshalb in einer einzigen Anweisung kaskadiert werden:

q.filter('title =', 'Imagine').ancestor(key).order('-date')

Die Anwendung kann dann die Abfrage ausführen und folgendermaßen auf die Ergebnisse zugreifen:

Das Abfrageobjekt als iterierbar behandeln und übereinstimmende Entitäten nacheinander verarbeiten:
```
for song in q:
  print song.title
```
Dadurch wird implizit die Methode run() der Abfrage aufgerufen, um die übereinstimmenden Entitäten zu generieren. Das entspricht damit
```
for song in q.run():
  print song.title
```
Mit dem Keyword-Argument limit können Sie die Anzahl der zu verarbeitenden Ergebnisse begrenzen:
```
for song in q.run(limit=5):
  print song.title
```
Die Iteratorschnittstelle speichert Ergebnisse nicht im Cache, d. h. beim Erstellen eines neuen Iterators aus dem Abfrageobjekt wird dieselbe Abfrage von Anfang an wiederholt.
Rufen Sie die Methode get() der Abfrage auf, um die erste übereinstimmende Entität in Datastore abzurufen:
```
song = q.get()
print song.title
```
Rufen Sie die Methode fetch() der Abfrage auf, um eine Liste aller übereinstimmenden Entitäten mit einer bestimmten Anzahl an Ergebnissen abzurufen:
```
results = q.fetch(limit=5)
for song in results:
  print song.title
```
Wie bei run() speichert das Abfrageobjekt keine Ergebnisse im Cache, sodass ein erneutes Aufrufen von fetch() dieselbe Abfrage wiederholt.

Hinweis: Diese Methode sollte nach Möglichkeit nur in seltenen Fällen verwendet werden. Es ist fast immer besser, mit run() zu arbeiten.

Konstruktor

Der Konstruktor für die Klasse Query ist so definiert:

class Query (model_class=None, keys_only=False, cursor=None, namespace=None, projection=None, distinct=False)

Erstellt eine Instanz der Klasse Query zum Abrufen von Entitäten aus App Engine Datastore.

Ohne weitere Änderung ruft das resultierende Abfrageobjekt alle vorhandenen Entitäten der durch model_class angegebenen Art ab. Die Instanzmethoden filter(), ancestor(), und order() können dann verwendet werden, um die Abfrage mit zusätzlichen Filterkriterien, Ancestor-Bedingungen und Sortierreihenfolgen anzupassen.

Argumente

model_class

Klasse für Modell (oder Expando); stellt die Entitätsart dar, auf den die Abfrage angewendet wird.

keys_only

Wenn true, werden nur Schlüssel und keine vollständigen Entitäten zurückgegeben. Ausschließlich schlüsselbasierte Abfragen sind schneller und kostengünstiger als Abfragen, die vollständige Entitäten zurückgeben.

cursor

Cursorposition, an der die Abfrage fortgesetzt werden soll.

Namespace

Namespace für die Abfrage.

Projektion

Liste oder Tupel der Namen von Attributen, die zurückgegeben werden sollen. Es werden nur Entitäten mit den angegebenen Attributen zurückgegeben. Sofern nicht anders angegeben, werden standardmäßig ganze Entitäten zurückgegeben. Projektionsabfragen sind schneller und kostengünstiger als Abfragen, die vollständige Entitäten zurückgeben.

Hinweis: Wenn Sie diesen Parameter angeben, können die Indexanforderungen der Abfrage verändert werden.

distinct

Bei Projektionsabfragen gibt distinct=True an, dass nur vollständig eindeutige Ergebnisse in einem Ergebnissatz zurückgegeben werden. So wird nur das erste Ergebnis für Entitäten zurückgegeben, die für die projizierten Properties dieselben Werte haben.

True: Liefert das erste Ergebnis für jeden einzelnen Satz von Werten der Properties in der Projektion.
Falsch: Alle Ergebnisse werden zurückgegeben.

Instanzmethoden

Instanzen der Klasse Query haben die folgenden Methoden:

filter(property_operator, value)

Fügt der Abfrage einen Property-Filter hinzu. Die Abfrage liefert nur Entitäten, deren Properties alle ihre Filter erfüllen.

Argumente

property_operator

String bestehend aus einem Attributnamen und einem optionalen Vergleichsoperator (=, !=, <, <=, >, >=, IN ), getrennt durch ein Leerzeichen, zum Beispiel 'age >'. Wird nur ein Attributname ohne Vergleichsoperator angegeben, wertet der Filter standardmäßig auf Gleichheit (==) aus.

Wert

Wert zum Vergleich mit dem Property-Wert. Beispiel:

q.filter('height >', 42).filter('city =', 'Seattle')
q.filter('user =', users.get_current_user())

Der angegebene Vergleichswert sollte denselben Werttyp wie die zu vergleichende Property haben.

ancestor(ancestor)

Fügt der Abfrage einen Ancestor-Filter hinzu. Die Abfrage liefert nur Entitäten mit dem angegebenen Ancestor.

Argument

ancestor: Ancestor-Entität oder -Schlüssel.

order(property)

Legt für die Abfrage eine Sortierreihenfolge fest. Mehrere Sortierreihenfolgen werden in der angegebenen Reihenfolge angewendet.

Argument

property

--) für eine absteigende Reihenfolge. Durch das Weglassen des Bindestrichs wird standardmäßig aufsteigend sortiert. Beispiel:

# Order alphabetically by last name:
q.order('last_name')

# Order by height, tallest to shortest:
q.order('-height')

projection ()

Gibt das Tupel von Eigenschaften in der Projektion oder in None zurück.

is_keys_only ()

Gibt einen booleschen Wert zurück, der angibt, ob es sich um eine ausschließlich schlüsselbasierte Abfrage handelt.

run (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=None, batch_size=20, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Gibt einen iterierbaren Wert für eine Schleifenfunktion der Abfrageergebnisse zurück. Auf diese Weise können Sie die Operation der Abfrage mit Parametereinstellungen festlegen und iterativ auf die Ergebnisse zugreifen:

Ruft die vom Argument offset angegebene Anzahl von Ergebnissen ab und verwirft sie.
Ruft die mit dem Argument limit angegebene maximale Anzahl von Ergebnissen ab und gibt diese zurück.

Die Leistung der Schleife wird also linear mit der Summe von offset + limit skaliert. Wenn Sie wissen, wie viele Ergebnisse Sie abrufen möchten, sollten Sie immer einen expliziten limit-Wert festlegen.

Diese Methode verbessert die Leistung durch asynchrones Vorabrufen. Standardmäßig werden die Ergebnisse in kleinen Batches aus dem Datenspeicher abgerufen. So kann die Anwendung die Iteration stoppen und muss nicht mehr Ergebnisse abrufen, als benötigt werden.

Tipp: Wenn Sie alle verfügbaren Ergebnisse abrufen möchten, deren Anzahl unbekannt ist, legen Sie für batch_size einen großen Wert fest, z. B. 1000.

Tipp: Wenn Sie die Standardargumentwerte nicht ändern müssen, können Sie das Abfrageobjekt direkt zur Iteration und Steuerung der Schleifenfunktion verwenden. Dadurch wird implizit run() mit Standardargumenten aufgerufen.

Argumente

read_policy

Leserichtlinie, die das gewünschte Maß an Datenkonsistenz angibt:

STRONG_CONSISTENCY: Garantiert aktuelle Ergebnisse, ist jedoch auf nur eine Entitätengruppe beschränkt.
EVENTUAL_CONSISTENCY: Kann für mehrere Entitätengruppen gelten, gibt aber teilweise veraltete Ergebnisse zurück. Abfragen mit Eventual Consistency werden in der Regel schneller ausgeführt als Abfragen mit Strong Consistency. Es gibt jedoch keine Garantie hierfür.

Hinweis: Globale Nicht-Ancestor-Abfragen ignorieren dieses Argument.

deadline

Maximale Wartezeit in Sekunden, in der ein Ergebnis aus dem Datenspeicher zurückgegeben werden kann, bevor der Vorgang mit einem Fehler abgebrochen wird. Akzeptiert entweder eine Ganzzahl oder einen Gleitkommawert. Kann nicht auf einen höheren Wert als den Standardwert (60 Sekunden) festgelegt werden. Eine Anpassung auf einen niedrigeren Wert ist jedoch möglich, wenn ein bestimmter Vorgang schnell fehlschlagen soll. Dies kann beispielsweise nützlich sein, um eine schnellere Antwort an den Nutzer zu senden, den Vorgang zu wiederholen, einen anderen Vorgang auszuführen oder den Vorgang einer Aufgabenwarteschlange hinzuzufügen.

offset

Anzahl der Ergebnisse, die übersprungen werden sollen, bevor das erste Ergebnis zurückgegeben wird.

limit

Maximale Anzahl der zurückzugebenden Ergebnisse; Wenn sie weggelassen oder auf None gesetzt werden, werden alle verfügbaren Ergebnisse standardmäßig abgerufen.

batch_size

Anzahl der Ergebnisse, die pro Batch abgerufen werden sollen. Wenn limit festgelegt ist, wird standardmäßig das angegebene Limit verwendet. Andernfalls wird standardmäßig 20 verwendet.

keys_only

Projektion

Hinweis: Wenn Sie diesen Parameter angeben, können die Indexanforderungen der Abfrage verändert werden.

start_cursor

Cursorposition für den Start der Abfrage.

end_cursor

Cursorposition für das Ende der Abfrage.

get (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Führt die Abfrage aus und gibt das erste Ergebnis zurück oder None, wenn keine Ergebnisse gefunden werden.

Argumente

read_policy

Leserichtlinie, die das gewünschte Maß an Datenkonsistenz angibt:

STRONG_CONSISTENCY: Garantiert aktuelle Ergebnisse, ist jedoch auf nur eine Entitätengruppe beschränkt.
EVENTUAL_CONSISTENCY: Kann für mehrere Entitätengruppen gelten, gibt aber teilweise veraltete Ergebnisse zurück. Abfragen mit Eventual Consistency werden in der Regel schneller ausgeführt als Abfragen mit Strong Consistency. Es gibt jedoch keine Garantie hierfür.

Hinweis: Globale Nicht-Ancestor-Abfragen ignorieren dieses Argument.

deadline

offset

Anzahl der Ergebnisse, die übersprungen werden sollen, bevor das erste Ergebnis zurückgegeben wird.

keys_only

Projektion

Hinweis: Wenn Sie diesen Parameter angeben, können die Indexanforderungen der Abfrage verändert werden.

start_cursor

Cursorposition für den Start der Abfrage.

end_cursor

Cursorposition für das Ende der Abfrage.

fetch (limit, read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Führt die Abfrage aus und gibt eine (möglicherweise leere) Ergebnisliste zurück:

Ruft die vom Argument offset angegebene Anzahl von Ergebnissen ab und verwirft sie.
Ruft die mit dem Argument limit angegebene maximale Anzahl von Ergebnissen ab und gibt diese zurück.

Die Leistung der Methode wird daher linear mit der Summe von offset + limit skaliert.

Hinweis: Diese Methode ist lediglich ein Thin Wrapper für die Methode run() und ineffizienter sowie speicherintensiver als die direkte Verwendung von run(). Sie sollten fetch() nur selten verwenden. Sie dient hauptsächlich der Einfachheit halber, wenn Sie eine vollständige speicherinterne Liste von Abfrageergebnissen abrufen müssen.

Tipp: Die Methode fetch() ist so konzipiert, dass nur die vom Argument limit angegebene Anzahl an Ergebnissen abgerufen wird. Um alle verfügbaren Ergebnisse einer Abfrage abzurufen, deren Anzahl nicht bekannt ist, verwenden Sie run() mit einem umfangreichen Batch wie run(batch_size=1000) anstelle von fetch().

Argumente

limit

Maximale Anzahl der zurückzugebenden Ergebnisse; Bei Festlegung auf None werden alle verfügbaren Ergebnisse abgerufen.

read_policy

Leserichtlinie, die das gewünschte Maß an Datenkonsistenz angibt:

STRONG_CONSISTENCY: Garantiert aktuelle Ergebnisse, ist jedoch auf nur eine Entitätengruppe beschränkt.
EVENTUAL_CONSISTENCY: Kann für mehrere Entitätengruppen gelten, gibt aber teilweise veraltete Ergebnisse zurück. Abfragen mit Eventual Consistency werden in der Regel schneller ausgeführt als Abfragen mit Strong Consistency. Es gibt jedoch keine Garantie hierfür.

Hinweis: Globale Nicht-Ancestor-Abfragen ignorieren dieses Argument.

deadline

offset

Anzahl der Ergebnisse, die übersprungen werden sollen, bevor das erste Ergebnis zurückgegeben wird.

keys_only

Projektion

Hinweis: Wenn Sie diesen Parameter angeben, können die Indexanforderungen der Abfrage verändert werden.

start_cursor

Cursorposition für den Start der Abfrage.

end_cursor

Cursorposition für das Ende der Abfrage.

count (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=1000, start_cursor=None, end_cursor=None)

Gibt die Anzahl der Ergebnisse zurück, die mit der Abfrage übereinstimmen. Dies ist um einen konstanten Faktor schneller als das Abrufen aller Ergebnisse, aber die Laufzeit wird trotzdem linear mit der Summe von offset + limit skaliert. Solange die Anzahl der erwarteten Ergebnisse nicht zu klein ist, empfiehlt es sich, ein Argument limit anzugeben. Andernfalls wird die Methode fortgesetzt, bis die Zählung abgeschlossen oder abgelaufen ist.

Argumente

read_policy

Leserichtlinie, die das gewünschte Maß an Datenkonsistenz angibt:

STRONG_CONSISTENCY: Garantiert aktuelle Ergebnisse, ist jedoch auf nur eine Entitätengruppe beschränkt.
EVENTUAL_CONSISTENCY: Kann für mehrere Entitätengruppen gelten, gibt aber teilweise veraltete Ergebnisse zurück. Abfragen mit Eventual Consistency werden in der Regel schneller ausgeführt als Abfragen mit Strong Consistency. Es gibt jedoch keine Garantie hierfür.

Hinweis: Globale Nicht-Ancestor-Abfragen ignorieren dieses Argument.

deadline

offset

Anzahl der Ergebnisse, die übersprungen werden sollen, bevor das erste gezählt wird.

limit

Maximale Anzahl der zu zählenden Ergebnisse.

start_cursor

Cursorposition für den Start der Abfrage.

end_cursor

Cursorposition für das Ende der Abfrage.

index_list ()

Gibt eine Liste der Indexe zurück, die von einer ausgeführten Abfrage verwendet werden, unter anderem Hauptindexe, zusammengesetzte Indexe, Artindexe sowie Indexe mit einzelnen Attributen.

Achtung: Das Aufrufen dieser Methode für eine noch nicht ausgeführte Abfrage löst die Ausnahme AssertionError aus.

Hinweis: Diese Funktion wird auf dem Entwicklungsserver nicht vollständig unterstützt. Bei Verwendung mit dem Entwicklungsserver wird entweder die leere Liste oder eine Liste ausgegeben, die genau einen zusammengesetzten Index enthält.

Der folgende Code gibt beispielsweise verschiedene Informationen zu den von einer Abfrage verwendeten Indexen aus:

# other imports ...
import webapp2
from google.appengine.api import users
from google.appengine.ext import db

class Greeting(db.Model):
  author = db.StringProperty()
  content = db.StringProperty(multiline=True)
  date = db.DateTimeProperty(auto_now_add=True)

class MainPage(webapp2.RequestHandler):
  def get(self):
    user = users.get_current_user()
    q = db.Query(Greeting)
    q.filter("author =", user.user_id())
    q.order("-date")
    q.fetch(100)
    index_list = q.index_list()
    for ix in index_list:
      self.response.out.write("Kind: %s" % ix.kind())
      self.response.out.write("<br />")
      self.response.out.write("Has ancestor? %s" % ix.has_ancestor())
      self.response.out.write("<br />")
      for name, direction in ix.properties():
        self.response.out.write("Property name: "+name)
        self.response.out.write("<br />")
        if direction == db.Index.DESCENDING:
          self.response.out.write("Sort direction: DESCENDING")
        else:
          self.response.out.write("Sort direction: ASCENDING")
        self.response.out.write("<br />")

Dies erzeugt für jeden Index eine Ausgabe wie die folgende:

Kind: Greeting
Has ancestor? False
Property name: author
Sort direction: ASCENDING
Property name: date
Sort direction: DESCENDING

cursor ()

Gibt einen base64-codierten Cursorstring zurück. Dieser gibt die Position im Ergebnissatz der Abfrage nach dem letzten abgerufenen Ergebnis an. Der Cursorstring kann in den HTTP-Parametern GET und POST sicher verwendet und auch im Datastore oder Memcache gespeichert werden. Mit einem zukünftigen Aufruf der gleichen Abfrage kann dieser String über den Parameter start_cursor oder die Methode with_cursor() bereitgestellt werden, um das Abrufen von Ergebnissen an dieser Position fortzusetzen.

Achtung: Das Aufrufen dieser Methode für eine noch nicht ausgeführte Abfrage löst die Ausnahme AssertionError aus.

Hinweis: Nicht alle Abfragen sind mit Cursors kompatibel. Weitere Informationen finden Sie auf der Seite Datastore-Abfragen.

with_cursor (start_cursor, end_cursor=None)

Gibt die Start- und (optional) Endpositionen in der Ergebnismenge einer Abfrage an, ab denen Ergebnisse abgerufen werden sollen. Die Cursorstrings, die die Start- und Endpositionen angeben, können nach einem vorherigen Aufruf der Abfrage mit cursor() abgerufen werden. Die aktuelle Abfrage muss mit dem vorherigen Aufruf identisch sein, einschließlich Entitätsart, Attributfilter, Ancestor-Filter und Sortierreihenfolgen.

Argumente

start_cursor: Base64-codierter Cursorstring, der den Start der Abfrage angibt.
end_cursor: Base64-codierter Cursorstring, der das Ende der Abfrage angibt.