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 "GqlQuery"

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 GqlQuery stellt eine Abfrage zum Abrufen von Entitäten aus dem App Engine-Datenspeicher mithilfe der SQL-ähnlichen App Engine-Abfragesprache GQL dar. Eine vollständige Erläuterung der GQL-Syntax und -Funktionen finden Sie in der GQL-Referenz; siehe auch die zugehörige Klasse Query, die zum Vorbereiten von Abfragen Objekte und Methoden statt GQL verwendet.

GqlQuery 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 GQL-Abfrageobjekt, indem sie entweder direkt den GqlQuery-Konstruktor oder die Klassenmethode gql() der Modellklasse einer Entitätsart aufruft. Der GqlQuery-Konstruktor verwendet als Argument einen Abfragestring, eine vollständige GQL-Anweisung, die mit SELECT ... FROM model-name beginnt. Werte in WHERE-Klauseln können numerische oder String-Literale sein oder können die Parameterbindung für Werte verwenden. Parameter können entweder mit Positions- oder Schlüsselwortargumenten gebunden werden:

q = GqlQuery("SELECT * FROM Song WHERE composer = 'Lennon, John'")

q = GqlQuery("SELECT __key__ FROM Song WHERE composer = :1", "Lennon, John")

q = GqlQuery("SELECT * FROM Song WHERE composer = :composer", composer="Lennon, John")

Der Einfachheit halber haben die Klassen Model und Expando eine Klassenmethode gql(), die eine GqlQuery-Instanz zurückgibt. Bei dieser Methode wird ein GQL-Abfragestring ohne das Präfix SELECT ... FROM model-name verwendet, das impliziert wird:

q = Song.gql("WHERE composer = 'Lennon, John'")

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.

Constructor

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

class GqlQuery(query_string, *args, **kwds)

Erstellt eine Instanz der Klasse GqlQuery zum Abrufen von Entitäten aus dem App Engine-Datenspeicher unter Verwendung der GQL-Abfragesprache.

Argumente

query_string: String, der eine vollständige GQL-Anweisung enthält.
args: Positionsparameterwerte.
kwds: Schlüsselwortparameterwerte.

Instanzmethoden

Instanzen der Klasse GqlQuery haben die folgenden Methoden:

bind(*args, **kwds)

Bindet die Parameterwerte der Abfrage erneut. Die geänderte Abfrage wird ausgeführt, wenn nach dem erneuten Binden der Parameter zum ersten Mal auf die Ergebnisse zugegriffen wird.

Das erneute Binden von Parametern an ein vorhandenes GqlQuery-Objekt ist schneller als das Erstellen eines neuen GqlQuery-Objekts, da der Abfragestring nicht noch einmal geparst werden muss.

Argumente

args: Neue Positionsparameterwerte.
kwds: Neue Schlüsselwortparameterwerte.

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 diesen Parameter nicht angeben, wird der in der Klausel LIMIT des GQL-Abfragestrings angegebene Wert verwendet. Wenn der Wert explizit auf None festgelegt ist, werden alle verfügbaren Ergebnisse 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

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.

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.

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. Es wird höchstens ein Ergebnis aus dem Datastore abgerufen. Sofern vorhanden, wird die Klausel LIMIT des GQL-Abfragestrings ignoriert.

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.

Hinweis: Wenn dieser Parameter explizit angegeben wird, überschreibt er jeden in der Klausel LIMIT des GQL-Abfragestrings angegebenen Wert. Wird der Parameter jedoch weggelassen, überschreibt der Standardwert 1000 die Klausel LIMIT der GQL-Abfrage nicht. Er gilt nur, wenn die Klausel LIMIT nicht angegeben wurde.

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.GqlQuery(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.