Abfrage- und Sortieroptionen

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 Query 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 verschiedenen Abfrage- und Sortieroptionen werden durch Aufrufen von Setter-Methoden für Instanzen der Klassen QueryOptions.Builder und SortOptions.Builder angegeben, wie in diesem Beispiel:

try {
  // Build the SortOptions with 2 sort keys
  SortOptions sortOptions =
      SortOptions.newBuilder()
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("price")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValueNumeric(0))
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("brand")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValue(""))
          .setLimit(1000)
          .build();

  // Build the QueryOptions
  QueryOptions options =
      QueryOptions.newBuilder()
          .setLimit(25)
          .setFieldsToReturn("model", "price", "description")
          .setSortOptions(sortOptions)
          .build();

  // A query string
  String queryString = "product: coffee roaster AND price < 500";

  //  Build the Query and run the search
  Query query = Query.newBuilder().setOptions(options).build(queryString);
  IndexSpec indexSpec = IndexSpec.newBuilder().setName(indexName).build();
  Index index = SearchServiceFactory.getSearchService().getIndex(indexSpec);
  Results<ScoredDocument> result = index.search(query);
  return result;
} catch (SearchException e) {
  // handle exception...
}

QueryOptions

Zum Festlegen von Abfrageoptionen verwenden Sie QueryOptions.Builder. Sie haben keinen direkten Zugriff auf diese Attribute.

Diese Attribute steuern, wie viele Ergebnisse und in welcher Reihenfolge diese zurückgegeben werden. 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.

Property Beschreibung Standard Maximum
Limit Die maximale Anzahl von Dokumenten, die in den Ergebnissen zurückgegeben werden soll. 20 1000
NumberFoundAccuracy Dieses Attribut bestimmt die Genauigkeit des von Results.getNumberFound() 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 diese Property auf die Komplexität der Suche auswirken und Zeitlimitüberschreitungen verursachen kann.		 Wenn nicht angegeben, wird die Genauigkeit auf denselben 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). -
SortOptions 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.

Property Beschreibung Standard
ReturningIdsOnly 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).
FieldsToReturn 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).
ExpressionsToReturn 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. –
FieldsToSnippet 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 ExpressionsToReturn 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. Zum Festlegen der Sortieroptionen müssen Sie SortOptions.Builder verwenden. Sie haben keinen direkten Zugriff auf diese Attribute.

Die Attribute von SortOptions bestimmen Reihenfolge und Bewertung der Suchergebnisse.

Attribut Beschreibung Standard
SortExpressions Eine Liste von SortExpressions, die eine mehrdimensionale Sortierung von Dokumenten darstellt. –
MatchScorer 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:

Property 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
DefaultValue
DefaultValueDate
DefaultValueNumber		 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.