Abfrage-Cursor

Mit Abfrage-Cursors kann eine Anwendung die Ergebnisse einer Abfrage in praktischen Batches abrufen. Sie werden statt ganzzahliger Offsets für die Paginierung empfohlen. Weitere Informationen zur Strukturierung von Abfragen für Ihre Anwendung finden Sie unter Abfragen.

Abfrage-Cursors

Mit Abfrage-Cursors kann eine Anwendung die Ergebnisse einer Abfrage in praktischen Batches ohne den Overhead eines Abfrage-Offsets abrufen. Nach Ausführung eines Abrufvorgangs kann die Anwendung einen Cursor abrufen, bei dem es sich um einen intransparenten base64-codierten String handelt, der die Indexposition des letzten abgerufenen Ergebnisses markiert. Die Anwendung kann diesen String speichern (beispielsweise in Datastore, in Memcache, in der Aufgabennutzlast einer Aufgabenwarteschlange oder eingebettet in einer Webseite als HTTP-GET- oder -POST-Parameter). Dann kann sie den Cursor als Ausgangspunkt für einen nachfolgenden Abrufvorgang verwenden, um den nächsten Batch Ergebnisse ab dem Punkt abzurufen, an dem der vorherige Abrufvorgang beendet wurde. Für den Abruf kann auch ein Endcursor angegeben werden, um den Umfang der zurückgegebenen Ergebnisse zu begrenzen.

Offsets und Cursors im Vergleich

Datastore unterstützt zwar ganzzahlige Offsets, aber Sie sollten diese nach Möglichkeit nicht verwenden. Verwenden Sie stattdessen Cursors. Die Verwendung eines Offsets verhindert nur die Rückgabe der übersprungenen Entitäten an Ihre Anwendung, die Entitäten werden jedoch dennoch intern abgerufen. Die übersprungenen Entitäten wirken sich auf die Latenz der Abfrage aus. Außerdem werden Ihrer Anwendung die Lesevorgänge in Rechnung gestellt, die für deren Abruf erforderlich sind. Wenn Cursors anstelle von Offsets verwendet werden, können Sie diese Kosten vermeiden.

Beispiel für einen Abfrage-Cursor

In Python erhält eine Anwendung nach dem Abrufen von Abfrageergebnissen durch das Aufrufen der Methode cursor() des Query-Objekts einen Cursor. Zum Abrufen weiterer Ergebnisse ab dem Punkt des Cursors erstellt die Anwendung eine ähnliche Abfrage mit identischem Entitätstyp, identischen Filtern sowie identischen Sortierfolgen und leitet den Cursor an die Methode with_cursor() der Abfrage weiter. Erst dann erfolgt der Abruf:

from google.appengine.api import memcache
from google.appengine.ext import db

# class Person(db.Model): ...
    
# Start a query for all Person entities
people = Person.all()
    
# If the application stored a cursor during a previous request, use it
person_cursor = memcache.get('person_cursor')
if person_cursor:
  people.with_cursor(start_cursor=person_cursor)
    
# Iterate over the results
for person in people:
  # Do something
    
# Get updated cursor and store it for next time
person_cursor = people.cursor()
memcache.set('person_cursor', person_cursor)

Einschränkungen von Cursors

Cursors unterliegen folgenden Einschränkungen:

  • Ein Cursor kann nur von der Anwendung, die die ursprüngliche Abfrage durchgeführt hat, und nur zur Fortsetzung derselben Abfrage verwendet werden. Um den Cursor bei einem nachfolgenden Abrufvorgang zu verwenden, müssen Sie die ursprüngliche Abfrage genau rekonstruieren, einschließlich der Entitätsart, des Ancestor-Filters, der Attributfilter und der Sortierfolgen. Ergebnisse können mit einem Cursor nur abgerufen werden, wenn genau die Abfrage eingerichtet wird, aus der er ursprünglich generiert wurde.
  • Da die Operatoren != und IN mit mehreren Abfragen implementiert werden, unterstützen Abfragen, die diese Operatoren verwenden, keine Cursor.
  • Cursors funktionieren häufig nicht wie erwartet bei Abfragen, die einen Ungleichheitsfilter oder eine Sortierfolge bei einem Attribut mit mehreren Werten verwenden. Die Deduplizierungslogik für derartige mehrwertige Attribute bleibt zwischen Abrufvorgängen nicht bestehen, weshalb dasselbe Ergebnis mehr als einmal zurückgegeben werden kann.
  • Bei neuen App Engine-Versionen können sich die Details der internen Implementierung ändern, sodass Cursors, die davon abhängen, ungültig werden. Wenn eine Anwendung versucht, einen Cursor zu verwenden, der nicht mehr gültig ist, löst Datastore eine BadRequestError-Ausnahme aus.

Cursors und Datenaktualisierungen

Die Position des Cursors ist als die Position in der Ergebnisliste nach dem letzten zurückgegebenen Ergebnis definiert. Ein Cursor ist keine relative Position in der Liste (er ist kein Offset). Er ist eine Markierung, zu der Datastore springen kann, wenn ein Indexscan nach Ergebnissen gestartet wird. Wenn sich die Ergebnisse einer Abfrage zwischen Cursorverwendungen ändern, berücksichtigt die Abfrage nur Änderungen, die in Ergebnissen nach dem Cursor auftreten. Wenn für die Abfrage ein neues Ergebnis vor der Position des Cursors angezeigt wird, wird dieses beim Abrufen der Ergebnisse nach der Position des Cursors nicht zurückgegeben. Dasselbe gilt, wenn eine Entität kein Ergebnis einer Abfrage mehr ist, aber vor der Position des Cursors angezeigt wurde; in diesem Fall ändern sich die Ergebnisse nach der Position des Cursors nicht. Auch wenn das letzte zurückgegebene Ergebnis aus den Ergebnissen entfernt wird, kann der Cursor die Position des nächsten Ergebnisses bestimmen.

Beim Abrufen von Abfrageergebnissen können Sie einen Start- und einen Endcursor einsetzen, um fortlaufende Ergebnisse aus Datastore zurückzugeben. Wenn Sie beim Abrufen der Ergebnisse einen Start- und einen Endcursor verwenden, ist nicht garantiert, dass der Umfang der Ergebnisse dem Umfang beim Generieren der Cursors entspricht. Das liegt daran, dass es passieren kann, dass Entitäten in Datastore zwischen dem Zeitpunkt der Generierung der Cursors und deren Verwendung in einer Abfrage hinzugefügt oder gelöscht werden.

Weitere Informationen