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 damitfor 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 vonfetch()
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 GqlQuery
ist so definiert:
- class GqlQuery(query_string, query_string, query_string)
-
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 neuenGqlQuery
-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, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY)
-
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 explizitenlimit
-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 aufNone
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äßig20
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.
- Ruft die vom Argument
- get (read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY)
-
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 KlauselLIMIT
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
- 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.
- 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.
- fetch (limit, read_policy=STRONG_CONSISTENCY, deadline=STRONG_CONSISTENCY, offset=STRONG_CONSISTENCY, keys_only=STRONG_CONSISTENCY, projection=STRONG_CONSISTENCY, start_cursor=STRONG_CONSISTENCY, end_cursor=STRONG_CONSISTENCY)
-
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 vonrun()
. Sie solltenfetch()
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 Argumentlimit
angegebene Anzahl an Ergebnissen abgerufen wird. Um alle verfügbaren Ergebnisse einer Abfrage abzurufen, deren Anzahl nicht bekannt ist, verwenden Sierun()
mit einem umfangreichen Batch wierun(batch_size=1000)
anstelle vonfetch()
.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
- 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.
- 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.
- Ruft die vom Argument
- count (read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY)
-
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 Argumentlimit
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
- 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 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 Standardwert1000
die KlauselLIMIT
der GQL-Abfrage nicht. Er gilt nur, wenn die KlauselLIMIT
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
undPOST
sicher verwendet und auch im Datastore oder Memcache gespeichert werden. Mit einem zukünftigen Aufruf der gleichen Abfrage kann dieser String über den Parameterstart_cursor
oder die Methodewith_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, start_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.