Abfrage- und Sortieroptionen

Diese API wird für Laufzeiten der ersten Generation unterstützt und kann beim Upgrade auf entsprechende Laufzeiten der zweiten Generation verwendet werden. Wenn Sie die App Engine Python 3-Laufzeit aktualisieren, lesen Sie die Migrationsanleitung, um mehr über Ihre Migrationsoptionen für gebündelte Legacy-Dienste zu erfahren.

Wenn Sie die Methode search() nur mit einem Abfragestring aufrufen, werden die Ergebnisse entsprechend den Standardabfrageoptionen zurückgegeben:

• Dokumente werden in absteigender Rangfolge zurückgegeben
• Dokumente werden in Gruppen von jeweils 20 zurückgegeben
• Abgerufene Dokumente enthalten alle ihre ursprünglichen Felder

Sie können diese Optionen ändern. Dazu verwenden Sie eine Instanz der Klasse Abfrage als Argument für search().

Mit der Query-Klasse können Sie angeben, wie viele Dokumente gleichzeitig zurückgegeben werden sollen. Außerdem haben Sie die Möglichkeit, den Inhalt der abgerufenen Dokumente anzupassen. Sie können auch nur Dokumentkennungen abfragen oder die Anforderung festlegen, dass Dokumente nur eine Teilmenge ihrer Felder enthalten. Darüber hinaus haben Sie die Möglichkeit, in den abgerufenen Dokumenten benutzerdefinierte Felder zu erstellen: Snippets (Fragmente von Textfeldern, die den Text um einen übereinstimmenden String herum anzeigen) und Feldausdrücke (Felder mit Werten, die von anderen Feldern im Dokument abgeleitet werden).

Neben den Abfrageoptionen kann die Abfrageklasse auch eine Instanz der Klasse SortOptions enthalten. Mit Sortieroptionen lassen sich die Sortierreihenfolge ändern und die Ergebnisse nach mehreren Schlüsseln sortieren.

Mit der Query-Klasse suchen

Wenn Sie eine Suche mit einer Instanz der Query-Klasse ausführen, muss die Klasseninstanz in mehreren Schritten erstellt werden. Allgemein gehen Sie so vor:

1. Erstellen Sie einen Abfragestring.
2. Erstellen Sie SortOptions, falls erforderlich.
3. Erstellen Sie QueryOptions.
4. Erstellen Sie ein Query-Objekt, das den Abfragestring und die (optionalen) QueryOptions enthält.
5. Rufen Sie die Suchmethode für das Query-Objekt auf.

Die Konstruktoren QueryOptions und SortOptions verwenden benannte Argumente wie in diesem Beispiel:

def query_options():
    index = search.Index('products')
    query_string = "product: piano AND price < 5000"

    # Create sort options to sort on price and brand.
    sort_price = search.SortExpression(
        expression='price',
        direction=search.SortExpression.DESCENDING,
        default_value=0)
    sort_brand = search.SortExpression(
        expression='brand',
        direction=search.SortExpression.DESCENDING,
        default_value="")
    sort_options = search.SortOptions(expressions=[sort_price, sort_brand])

    # Create field expressions to add new fields to the scored documents.
    price_per_note_expression = search.FieldExpression(
        name='price_per_note', expression='price/88')
    ivory_expression = search.FieldExpression(
        name='ivory', expression='snippet("ivory", summary, 120)')

    # Create query options using the sort options and expressions created
    # above.
    query_options = search.QueryOptions(
        limit=25,
        returned_fields=['model', 'price', 'description'],
        returned_expressions=[price_per_note_expression, ivory_expression],
        sort_options=sort_options)

    # Build the Query and run the search
    query = search.Query(query_string=query_string, options=query_options)
    results = index.search(query)
    for scored_document in results:
        print(scored_document)

QueryOptions

Diese Attribute steuern, wie viele Ergebnisse zurückgegeben werden und in welcher Reihenfolge dies geschieht. Die Versatz- und Cursoroptionen unterstützen die Paginierung. Diese Optionen schließen sich gegenseitig aus. Mit ihnen wird festgelegt, welche ausgewählten Dokumente in den Ergebnissen zurückgegeben werden sollen.

Attribut	Beschreibung	Standard	Maximum
limit	Die maximale Anzahl von Dokumenten, die in den Ergebnissen zurückgegeben werden soll.	20	1000
number_found_accuracy	Dieses Attribut bestimmt die Genauigkeit des von SearchResults.number_found() zurückgegebenen Ergebnisses. Sie legt ein Limit für die Anzahl der tatsächlich gezählten Übereinstimmungen fest und stoppt die Suche, wenn das Limit erreicht wurde. Wenn die Anzahl der Übereinstimmungen im Index kleiner oder gleich dem Limit ist, ist die zurückgegebene Anzahl genau. Andernfalls ist die Anzahl eine Schätzung basierend auf den gefundenen Übereinstimmungen und der Größe und Struktur des Index. Beachten Sie, dass sich das Festlegen eines hohen Werts für dieses Attribut auf die Komplexität der Suche auswirken und Zeitlimitüberschreitungen verursachen kann.	Wenn nicht angegeben oder auf None festgelegt, wird die Genauigkeit auf den gleichen Wert wie limit festgelegt.	25.000
offset	Der Versatz des ersten Dokuments in den zurückzugebenden Ergebnissen.	0. Die Ergebnisse enthalten alle übereinstimmenden Dokumente (bis zum Limit).	1.000
cursor	Gruppen von Dokumenten können auch mit einem Cursor anstelle eines Versatzes in einer sortierten Reihenfolge abgerufen werden. Ein Cursor wird aktualisiert, wenn er in aufeinanderfolgende Abfragen übergeben und aus diesen herausgegeben wird. Damit kann jede neue Suche am Ende der vorherigen Suche fortgesetzt werden. Cursor und Versatz werden auf der Seite Ergebnisse verarbeiten erläutert.	Null. Die Ergebnisse enthalten alle übereinstimmenden Dokumente (bis zum Limit).	-
sort_options	Legen Sie ein SortOptions-Objekt fest, um die Reihenfolge der Suchergebnisse zu steuern. Eine Instanz von SortOptions hat ihre eigenen Attribute. Diese werden weiter unten erläutert.	Null. Die Dokumente werden in absteigender Reihenfolge sortiert.	-

Diese Properties bestimmen, welche Dokumentfelder in den Ergebnissen angezeigt werden.

Attribut	Beschreibung	Standard
ids_only	Legen Sie dafür True oder False fest. Bei Angabe von True enthalten die in den Ergebnissen zurückgegebenen Dokumente nur IDs und keine Felder.	False (gibt alle Felder zurück).
returned_fields	Gibt an, welche Dokumentfelder in die Ergebnisse einzuschließen sind. Es können höchstens 100 Felder angegeben werden.	Alle Dokumentfelder werden zurückgegeben (bis zu 100 Felder).
returned_expressions	Feldausdrücke, die berechnete Felder beschreiben, die jedem in den Suchergebnissen zurückgegebenen Dokument hinzugefügt werden. Diese Felder gehören dann zur Ausdrucks-Property des Dokuments. Der Feldwert ergibt sich aus einem Feldausdruck, der ein oder mehrere Dokumentfelder enthalten kann.	–
snippeted_fields	Eine Liste der Namen von Textfeldern. Für jedes Feld wird ein Snippet generiert. Dies ist ein berechnetes Feld, das dem Ausdrucksattribut der Dokumente in den Suchergebnissen hinzugefügt wird. Das Snippet-Feld hat den gleichen Namen wie sein Quellfeld. Diese Option verwendet implizit die Snippet-Funktion mit nur zwei Argumenten. Dabei wird ein Snippet mit höchstens einem übereinstimmenden String anhand des gleichen Abfragestrings erstellt, mit dem die Suche die Ergebnisse ermittelt hat: snippet("query-string", field-name). Sie können mit der Option returned_expressions auch benutzerdefinierte Snippets anlegen. Fügen Sie dazu einen Feldausdruck hinzu, der die Snippet-Funktion explizit aufruft.	–

SortOptions

Die Attribute von SortOptions bestimmen Reihenfolge und Bewertung der Suchergebnisse.

Attribut	Beschreibung	Standard
expressions	Eine Liste von SortExpressions, die eine mehrdimensionale Sortierung von Dokumenten darstellt.	–
match_scorer	Ein optionales MatchScorer-Objekt. Wenn vorhanden, werden die Dokumente entsprechend der Häufigkeit des Suchbegriffs bewertet. Die Bewertung steht als _score-Feld zur Verfügung. Die Bewertung von Dokumenten kann sowohl in Bezug auf die abrechnungsfähigen Vorgänge als auch auf die Ausführungszeit aufwendig sein und Suchvorgänge verlangsamen. Verwenden Sie die Bewertungsfunktion nur, wenn es nötig ist.	–
limit	Maximale Anzahl der Objekte, die bewertet und/oder sortiert werden sollen. Die Höchstzahl ist 10.000.	1.000

Nach mehreren Schlüsseln sortieren

Sie können die Suchergebnisse nach mehreren Sortierschlüsseln sortieren. Ein Schlüssel kann dabei ein einfacher Feldname oder ein Wert sein, der aus mehreren Feldern berechnet wird. Der Begriff „Ausdruck“ hat im Zusammenhang mit Sortieroptionen mehrere Bedeutungen: Die SortOption selbst hat ein Ausdrucksattribut. Dieses Attribut ist eine Liste von SortExpression-Objekten, die Sortierschlüsseln entsprechen. Schließlich enthält jedes Objekt vom Typ SortExpression ein Ausdrucksattribut, das festlegt, wie der Wert des Sortierschlüssels berechnet wird. Dieser Ausdruck muss nach den Regeln, die im nächsten Abschnitt dargestellt werden, erstellt werden.

Mit SortExpression lassen sich auch die Richtung der Sortierung und ein Standardschlüsselwert festlegen. Der Standardschlüsselwert wird verwendet, wenn der Ausdruck für ein Dokument nicht berechnet werden kann. Es folgt die vollständige Liste der Properties:

Attribut	Beschreibung	Standard
expression	Ein Ausdruck, der ausgewertet wird, wenn Ergebnisse für jedes übereinstimmende Dokument sortiert werden.	–
direction	Die Richtung zum Sortieren der Suchergebnisse, entweder ASCENDING oder DESCENDING.	DESCENDING
default_value	Der Standardwert des Ausdrucks, wenn kein Feld vorhanden ist und für ein Dokument nicht berechnet werden kann. Für Textsortierungen muss ein Textwert angegeben werden. Für numerische Sortierungen muss ein numerischer Wert angegeben werden.	–

Nach mehrwertigen Feldern sortieren

Wenn Sie nach einem Feld eines bestimmten Typs mit mehreren Werten sortieren, wird nur der erste Wert verwendet, der dem Feld zugewiesen ist. Angenommen, es gibt zwei Dokumente, DokA und DokB, die beide ein Textfeld namens „Farbe” enthalten. In DokA sind dem Feld „Farbe” zwei Werte in der Reihenfolge „rot, blau” zugewiesen, in DokB zwei Werte in der Reihenfolge „grün, rot”. Wenn Sie eine Sortierung mit dem Textfeld „Farbe“ vornehmen, wird DokA nach dem Wert „rot“ und DokB nach dem Wert „grün“ sortiert. Die anderen Feldwerte werden nicht für die Sortierung verwendet.

Sortieren oder nicht sortieren

Wenn Sie keine Sortieroptionen angeben, werden die Suchergebnisse automatisch in absteigender Reihenfolge zurückgegeben. In diesem Fall ist die Anzahl der zurückgegebenen Dokumente nicht begrenzt. Wenn Sie hingegen Sortieroptionen festlegen, wird erst nach einer Auswahl der übereinstimmenden Dokumente sortiert. Die Größe der Sortierung wird durch das explizite Attribut "SortOptions.limit" gesteuert. Sie können nie mehr als 10.000 Dokumente sortieren, der Standardwert ist 1.000. Wenn die Anzahl der übereinstimmenden Dokumente die durch "SortOptions.limit" angegebene Anzahl überschreitet, wird nur diese begrenzte Anzahl in der Suche abgerufen, sortiert und zurückgegeben. Die Dokumente, die sortiert werden sollen, werden aus der in absteigender Rangfolge geordneten Liste aller übereinstimmenden Dokumente ausgewählt. Es ist möglich, dass eine Abfrage mehr übereinstimmende Dokumente zurückgibt, als sortiert werden können. Wenn Sie Sortieroptionen verwenden und jedes übereinstimmende Dokument abgerufen werden muss, achten Sie darauf, dass die Abfrage nicht mehr Dokumente zurückgibt, als sortiert werden können.

Ausdrücke schreiben

Mit Ausdrücken werden Feldausdrücke definiert, die in „QueryOptions“ festgelegt werden, sowie Sortierausdrücke, die in SortOptions angegeben werden. Sie werden als Strings geschrieben:

"price * quantity"
"(men + women)/2"
"min(daily_use, 10) * rate"
"snippet('rose', flower, 120)"

Ausdrücke mit Zahlenfeldern können die arithmetischen Operatoren (+, -, *, /) und die integrierten numerischen Funktionen enthalten, die unten aufgeführt sind. Für Ausdrücke mit GeoPoint-Feldern stehen die GeoPoint- und Entfernungsfunktionen zur Verfügung. Ausdrücke für Text- und HTML-Felder können die Snippet-Funktion verwenden.

Ausdrücke können auch die folgenden speziellen Begriffe enthalten:

Begriff	Beschreibung
_rank	Die Rang-Property eines Dokuments. Es kann in Feld- und Sortierausdrücken verwendet werden.
_score	Die einem Dokument zugewiesene Bewertung, wenn Sie MatchScorer in SortOptions verwenden. Dieser Begriff kann nur in Sortierausdrücken und nicht in Feldausdrücken verwendet werden.

Numerische Funktionen

In Ausdrücken zur Definition numerischer Werte für FieldExpressions und SortExpressions können die im Folgenden aufgeführten integrierten Funktionen verwendet werden. Die Argumente müssen Zahlen, Feldnamen oder Ausdrücke mit Zahlen und Feldnamen sein.

Funktion	Beschreibung	Beispiel
max	Gibt das größte Argument zurück.	max(recommended_retail_price, discount_price, wholesale_price)
min	Gibt das kleinste Argument zurück.	min(height, width, length)
log	Gibt den natürlichen Logarithmus zurück.	log(x)
abs	Gibt den absoluten Wert zurück.	abs(x)
pow	Benötigt zwei numerische Argumente. Der Aufruf "pow (x, y)" berechnet den Wert von x, der mit y potenziert ist.	pow(x, 2)
count	Benötigt einen Feldnamen als Argument. Gibt die Anzahl der Felder im Dokument mit diesem Namen zurück. Denken Sie daran, dass ein Dokument mehrere Felder unterschiedlichen Typs mit dem gleichen Namen enthalten kann. Hinweis: count kann nur in FieldExpressions verwendet werden. Es kann nicht in SortExpressions genutzt werden.	count(user)

Geopunktfunktionen

Diese Funktionen können für Ausdrücke mit Geopunktfeldern verwendet werden.

Funktion	Beschreibung	Beispiel
geopoint	Definiert einen Geopunkt anhand eines Längen- und Breitengrads.	geopoint(-31.3, 151.4)
distance	Berechnet die Entfernung in Metern zwischen zwei Geopunkten. Beide Argumente können der Name eines Geopunktfelds oder ein Aufruf der Geopunktfunktion sein. Allerdings darf nur ein Argument ein Feldname sein.	distance(geopoint(23, 134), store_location)

Snippets

Ein Snippet ist ein Fragment eines Textfelds, das mit einem Abfragestring übereinstimmt und den umgebenden Text enthält. Snippets werden durch Aufruf der snippet-Funktion erstellt:

snippet(query, body, [max_chars])

query

Ein Abfragestring in Anführungszeichen, der den Text angibt, der im Feld gesucht werden soll.

body

Der Name eines Text-, HTML- oder Atomfelds.

max_chars

Die maximale Anzahl an Zeichen, die im Snippet zurückgegeben werden soll. Dieses Argument ist optional und standardmäßig auf 160 Zeichen festgelegt.

Die Funktion gibt einen HTML-String zurück. Der String enthält ein Snippet aus dem Wert des Textfelds mit dem Text in Fettschrift, der mit der Abfrage übereinstimmt.