Bei einer Datastore-Abfrage werden Entitäten aus Cloud Datastore abgerufen, die einen Satz von angegebenen Bedingungen erfüllen.
Eine typische Abfrage umfasst:
- Eine Entitätsart, auf die die Abfrage angewendet wird
- Optionale Filter, die auf den Attributwerten, Schlüsseln und Ancestors der Entität beruhen
- Optionale Sortierfolgen zur Anordnung der Ergebnisse
Bei der Ausführung ruft die Abfrage alle Entitäten des angegebenen Typs ab, die alle Filterbedingungen erfüllen, und sortiert sie in der angegebenen Reihenfolge. Abfragen werden schreibgeschützt ausgeführt.
Auf dieser Seite werden die Struktur und Arten von Abfragen beschrieben, die in App Engine zum Abrufen von Daten aus Datastore verwendet werden.
Filter
Die Filter einer Abfrage legen Einschränkungen für die Attribute, Schlüssel und Ancestors der Entitäten fest, die abgerufen werden sollen.
Attributfilter
In einem Attributfilter wird Folgendes angegeben:
- Ein Attributname
- Ein Vergleichsoperator
- Ein Attributwert
Der Attributwert muss von der Anwendung angegeben werden; er kann keine anderen Attribute referenzieren oder anhand anderer Attribute berechnet werden. Eine Entität erfüllt den Filter, wenn sie ein Attribut mit dem angegebenen Namen enthält, dessen Wert dem im Filter angegebenen Wert in der vom Vergleichsoperator beschriebenen Weise entspricht.
Es können folgende Vergleichsoperatoren verwendet werden (definiert als Enum-Konstanten in der verschachtelten Klasse
Query.FilterOperator
):
Operator | Bedeutung |
---|---|
EQUAL |
Gleich |
LESS_THAN |
Kleiner als |
LESS_THAN_OR_EQUAL |
Kleiner als oder gleich |
GREATER_THAN |
Größer als |
GREATER_THAN_OR_EQUAL |
Größer als oder gleich |
NOT_EQUAL |
Ungleich |
IN |
Element von (entspricht einem der Werte in einer angegebenen Liste) |
Mit dem Operator NOT_EQUAL
werden zwei Abfragen ausgeführt: eine Abfrage, bei der der Filter NOT_EQUAL
durch den Filter LESS_THAN
ersetzt wird, und eine andere Abfrage, bei der er durch den Filter GREATER_THAN
ersetzt wird. In beiden Fällen bleiben alle anderen Filter unverändert. Danach werden die Ergebnisse in der entsprechenden Reihenfolge zusammengeführt. Eine Abfrage kann jeweils nur einen Filter NOT_EQUAL
enthalten. Ist dies der Fall, kann sie keine anderen Ungleichheitsfilter enthalten.
Mit dem Operator IN
werden ebenfalls mehrere Abfragen ausgeführt und zwar jeweils eine Abfrage für jedes Element in der angegebenen Liste, wobei alle anderen Filter unverändert bleiben und der Filter IN
durch den Filter EQUAL
ersetzt wird. Die Ergebnisse werden in der Reihenfolge der Elemente in der Liste zusammengeführt. Wenn eine Abfrage mehr als einen IN
-Filter enthält, werden mehrere Abfragen ausgeführt, und zwar jeweils eine für jede mögliche Kombination von Werten in den IN
-Listen.
Eine einzelne Abfrage, die die Operatoren NOT_EQUAL
oder IN
enthält, ist auf maximal 30 Unterabfragen begrenzt.
Weitere Informationen darüber, wie Abfragen mit NOT_EQUAL
und IN
in einem JDO/JPA-Framework in mehrere Abfragen umgesetzt werden, finden Sie im Artikel Abfragen mit den Filtern != und IN.
Schlüsselfilter
Zum Filtern mit dem Wert eines Entitätsschlüssels verwenden Sie das spezielle Attribut Entity.KEY_RESERVED_PROPERTY
:
Aufsteigende Sortierungen für Entity.KEY_RESERVED_PROPERTY
werden ebenfalls unterstützt.
Bei einem Vergleich auf Ungleichheit werden die Schlüssel nach den folgenden Kriterien in folgender Reihenfolge angeordnet:
- Ancestor-Pfad
- Entitätstyp
- Kennzeichnung (Schlüsselname oder numerische ID)
Elemente des Ancestor-Pfads werden ähnlich verglichen: nach Art (String), dann nach Schlüsselname oder numerischer ID. Arten und Schlüsselnamen sind Strings und werden nach Bytewert sortiert; numerische IDs sind ganze Zahlen und werden numerisch sortiert. Wenn Entitäten mit derselben übergeordneten Entität und derselben Art eine Mischung aus Schlüsselnamen-Strings und numerischen IDs verwenden, stehen die Entitäten mit numerischen IDs vor den Entitäten mit Schlüsselnamen.
Abfragen auf Schlüssel verwenden genau wie Abfragen auf Attribute Indexe und erfordern in denselben Fällen benutzerdefinierte Indexe, allerdings mit einigen Ausnahmen: Ungleichheitsfilter oder eine aufsteigende Sortierfolge für Schlüssel erfordern keinen benutzerdefinierten Index, eine absteigende Sortierfolge für Schlüssel hingegen schon. Wie bei allen Abfragen erstellt der Entwicklungs-Webserver entsprechende Einträge in der Indexkonfigurationsdatei, wenn eine Abfrage, die einen benutzerdefinierten Index erfordert, getestet wird.
Ancestor-Filter
Sie können für das Filtern von Datastore-Abfragen einen bestimmten Ancestor angeben, sodass nur Entitäten zurückgegeben werden, die von diesem Ancestor abstammen:
Besondere Abfragetypen
Einige spezifische Abfragetypen müssen besonders erwähnt werden:
Typlose Abfragen
Mit einer typlosen Abfrage ohne Ancestor-Filter werden alle Entitäten einer Anwendung aus Datastore abgerufen. Dazu gehören auch Entitäten, die durch andere App Engine-Features erstellt und verwaltet werden, beispielsweise Statistikentitäten und Blobstore-Metadatenentitäten (sofern vorhanden). Derartige typlose Abfragen können keine Filter oder Sortierfolgen für Attributwerte enthalten. Sie können jedoch zum Filtern von Entitätsschlüsseln verwendet werden, wenn Sie Entity.KEY_RESERVED_PROPERTY
als Propertynamen angeben:
Ancestor-Abfragen
Bei einer Abfrage mit Ancestor-Filter sind die Ergebnisse auf die angegebene Entität und deren untergeordnete Entitäten begrenzt.
Typlose Ancestor-Abfragen
Mit einer typlosen Abfrage, die einen Ancestor-Filter enthält, werden der angegebene Ancestor und alle seine untergeordneten Entitäten unabhängig vom Typ abgerufen. Für diesen Abfragetyp sind keine benutzerdefinierten Indexe erforderlich. Wie alle typlosen Abfragen dürfen sie keine Filter oder Sortierfolgen für Propertywerte enthalten, das Filtern nach dem Schlüssel der Entität ist jedoch möglich:
Im folgenden Beispiel wird gezeigt, wie alle Entitäten abgerufen werden, die Nachfolger eines bestimmten Ancestors sind:
Ausschließlich schlüsselbasierte Abfragen
Eine ausschließlich schlüsselbasierte Abfrage gibt nur die Schlüssel der Ergebnisentitäten statt der Entitäten selbst mit einer niedrigeren Latenz und niedrigeren Kosten zurück.
Häufig ist es wirtschaftlicher, zuerst eine ausschließlich schlüsselbasierte Abfrage durchzuführen und dann einen Teil der Entitäten aus den Ergebnissen abzurufen, als eine allgemeine Abfrage auszuführen, die mehr Entitäten abrufen kann, als tatsächlich benötigt werden.
Projektionsabfragen
Manchmal benötigen Sie aus den Ergebnissen einer Abfrage eigentlich nur die Werte einiger bestimmter Attribute. In solchen Fällen haben Sie die Möglichkeit, mit einer Projektionsabfrage nur die Attribute abzurufen, die Sie tatsächlich interessieren. Dies führt zu niedrigerer Latenz und zu geringeren Kosten als beim Abruf ganzer Entitäten. Weitere Informationen dazu finden Sie auf der Seite zu Projektionsabfragen.
Sortierfolgen
Eine Abfrage-Sortierfolge gibt Folgendes an:
- Ein Attributname
- Eine Sortierfolge (aufsteigend oder absteigend)
Beispiel:
Wenn eine Abfrage mehrere Sortierfolgen enthält, werden diese in der angegebenen Abfolge angewendet. Im folgenden Beispiel wird zuerst aufsteigend nach Nachname und dann absteigend nach Körpergröße sortiert:
Wenn keine Sortierfolgen angegeben sind, werden die Ergebnisse in der Reihenfolge zurückgegeben, in der sie aus Datastore abgerufen werden.
Hinweis: Aufgrund der Art und Weise, wie Datastore Abfragen ausführt, muss Folgendes beachtet werden: Wenn in einer Abfrage Ungleichheitsfilter für ein Attribut und Sortierfolgen für andere Attribute angegeben sind, muss das Attribut, das mit Ungleichheitsfiltern verwendet wird, vor den anderen Attributen einsortiert werden.
Indexe
Bei jeder Datastore-Abfrage werden die Ergebnisse anhand eines oder mehrerer Indexe berechnet, die Entitätsschlüssel in einer von den Indexattributen vorgegebenen Reihenfolge und optional auch die Ancestors der Entität enthalten. Diese Indexe werden inkrementell aktualisiert, um die von den Anwendungen durchgeführten Änderungen an den Entitäten widerzuspiegeln und so ohne weitere Berechnung exakte Ergebnisse für alle Abfragen zur Verfügung zu stellen.
App Engine gibt für jede Property einer Entität einen einfachen Index vor.
Eine App Engine-Anwendung kann weitere benutzerdefinierte Indexe in der Indexkonfigurationsdatei mit der Bezeichnung datastore-indexes.xml
definieren, die im Verzeichnis Ihrer Anwendung /war/WEB-INF/appengine-generated
generiert wird. Der Entwicklungsserver fügt dieser Datei automatisch Vorschläge hinzu, wenn er Abfragen ermittelt, die mit den vorhandenen Indexen nicht ausgeführt werden können.
Sie können die Indexe vor dem Hochladen der Anwendung von Hand optimieren.
Beispiel einer Abfrageschnittstelle
Die Low-Level Java Datastore API bietet die Klasse Query
zum Erstellen von Abfragen und die Schnittstelle PreparedQuery
zum Abrufen von Entitäten aus Datastore:
Beachten Sie die Verwendung von FilterPredicate
und CompositeFilter
zum Erstellen von Filtern. Wenn Sie nur einen Filter pro Abfrage festlegen möchten, verwenden Sie ausschließlich FilterPredicate
:
Wenn Sie aber mehr als einen Filter für eine Abfrage angeben möchten, müssen Sie CompositeFilter
verwenden, wobei mindestens zwei Filter erforderlich sind. Im Beispiel oben wird der Shortcut-Helper CompositeFilterOperator.and
genutzt. Das folgende Beispiel zeigt eine Möglichkeit, um einen zusammengesetzten OR-Filter zu erstellen:
Nächste Schritte
- So legen Sie fest, was Abfragen zurückgeben, und steuern Abfrageergebnisse noch gezielter
- Informationen zu den allgemeinen Einschränkungen für Datastore-Abfragen
- Erfahren Sie mehr über Abfrage-Cursors, mit denen eine Anwendung die Ergebnisse einer Abfrage in praktischen Batches abrufen kann
- Datenkonsistenz und ihre Funktionsweise mit verschiedenen Abfragetypen in Datastore