Datenspeicherabfragen

Bei einer Datastore-Abfrage werden Entitäten aus Cloud Datastore abgerufen, die eine Reihe bestimmter 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 der angegebenen Art 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 Cloud 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
Beispiel:

q := datastore.NewQuery("Person").Filter("Height <=", maxHeight)

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 eine Property mit dem angegebenen Namen enthält, deren Wert mit dem in dem Filter angegebenen Wert in der vom Vergleichsoperator beschriebenen Weise verglichen wird.

Einer der folgenden Vergleichsoperatoren kann verwendet werden:

Operator Bedeutung
= Gleich
< Weniger als
<= Kleiner als oder gleich
> Größer als
>= Größer als oder gleich

Schlüsselfilter

Zum Filtern mit dem Wert eines Entitätsschlüssels verwenden Sie das spezielle Attribut __key__.

q := datastore.NewQuery("Person").Filter("__key__ >", lastSeenKey)

Bei einem Vergleich auf Ungleichheit werden die Schlüssel nach den folgenden Kriterien in folgender Reihenfolge angeordnet:

  1. Ancestor-Pfad
  2. Entitätsart
  3. 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 getestet wird, die einen benutzerdefinierten Index erfordert.

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:

q := datastore.NewQuery("Person").Ancestor(ancestorKey)

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 __key__ als Attributnamen angeben:

q := datastore.NewQuery("").Filter("__key__ >", lastSeenKey)

Ancestor-Abfragen

Bei einer Abfrage mit einem Ancestor-Filter sind die Ergebnisse auf die angegebene Entität und ihre Nachfolger begrenzt:

// Create two Photo entities in the datastore with a Person as their ancestor.
tomKey := datastore.NewKey(ctx, "Person", "Tom", 0, nil)

wPhoto := Photo{URL: "http://example.com/some/path/to/wedding_photo.jpg"}
wKey := datastore.NewKey(ctx, "Photo", "", 0, tomKey)
_, err := datastore.Put(ctx, wKey, wPhoto)
// check err

bPhoto := Photo{URL: "http://example.com/some/path/to/baby_photo.jpg"}
bKey := datastore.NewKey(ctx, "Photo", "", 0, tomKey)
_, err = datastore.Put(ctx, bKey, bPhoto)
// check err

// Now fetch all Photos that have tomKey as an ancestor.
// This will populate the photos slice with wPhoto and bPhoto.
q := datastore.NewQuery("Photo").Ancestor(tomKey)
var photos []Photo
_, err = q.GetAll(ctx, &photos)
// check err
// do something with photos

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:

q := datastore.NewQuery("").Ancestor(ancestorKey).Filter("__key__ >", lastSeenKey)

Im folgenden Beispiel wird gezeigt, wie alle Entitäten abgerufen werden, die Nachfolger eines bestimmten Ancestors sind:

tomKey := datastore.NewKey(ctx, "Person", "Tom", 0, nil)

weddingPhoto := &Photo{URL: "http://example.com/some/path/to/wedding_photo.jpg"}
_, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Photo", tomKey), weddingPhoto)

weddingVideo := &Video{URL: "http://example.com/some/path/to/wedding_video.avi"}
_, err = datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Video", tomKey), weddingVideo)

// The following query returns both weddingPhoto and weddingVideo,
// even though they are of different entity kinds.
q := datastore.NewQuery("").Ancestor(tomKey)
t := q.Run(ctx)
for {
	var x interface{}
	_, err := t.Next(&x)
	if err == datastore.Done {
		break
	}
	if err != nil {
		log.Errorf(ctx, "fetching next Photo/Video: %v", err)
		break
	}
	// Do something (e.g. switch on types)
	doSomething(x)
}

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.

q := datastore.NewQuery("Person").KeysOnly()

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.

Beachten Sie, dass eine ausschließlich schlüsselbasierte Abfrage mehr als 1.000 Ergebnisse zurückgeben kann. Mit GetAll lassen sich jedoch jeweils nur 1.000 Schlüssel abrufen und es wird bei einem größeren Ergebnis ein Fehler ausgegeben. Daher empfehlen wir, der Abfrage ein Limit von 1.000 Schlüsseln hinzuzufügen.

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)

In Go wird die absteigende Sortierfolge durch einen Bindestrich (-) vor dem Attributnamen angegeben. Durch das Weglassen des Bindestrichs wird standardmäßig die aufsteigende Reihenfolge angegeben. Beispiel:

// Order alphabetically by last name:
q := datastore.NewQuery("Person").Order("LastName")

// Order by height, tallest to shortest:
q = datastore.NewQuery("Person").Order("-Height")

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:

q := datastore.NewQuery("Person").Order("LastName").Order("-Height")

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 jedes Attribut einer Entität einen einfachen Index vor. Eine App Engine-Anwendung kann weitere benutzerdefinierte Indexe in der Indexkonfigurationsdatei index.yaml definieren. 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 Go Datastore API bietet einen Abfragetyp zum Vorbereiten und Ausführen von Abfragen.

type Person struct {
	FirstName string
	LastName  string
	City      string
	BirthYear int
	Height    int
}

func handle(w http.ResponseWriter, r *http.Request) {
	ctx := appengine.NewContext(r)

	// The Query type and its methods are used to construct a query.
	q := datastore.NewQuery("Person").
		Filter("LastName =", "Smith").
		Filter("Height <=", maxHeight).
		Order("-Height")

	// To retrieve the results,
	// you must execute the Query using its GetAll or Run methods.
	var people []Person
	if _, err := q.GetAll(ctx, &people); err != nil {
		// Handle error.
	}
	// ...
}

Weitere Informationen