Ein Abfragestring enthält Unicode-Zeichen. Die maximale Länge eines Abfragestrings beträgt 2.000 Zeichen. Alle Abfragestrings enthalten mindestens einen Feldwert. Es wird empfohlen, Feldwerte kleinzuschreiben, da bei der Suche in Atom-, Text- und HTML-Feldern die Groß-/Kleinschreibung nicht berücksichtigt wird und ein Abfragestring auch die booleschen Operatoren AND, OR und NOT enthalten kann. Diese Operatoren werden durch ihre Großschreibung erkannt.
Kommas sind in Abfragestrings nur zum Trennen der Argumente einer Funktion zulässig (z. B. distance(home, geopoint(35.2, 40.5)) > 100) oder wenn sie Teil eines in Anführungszeichen gesetzten Strings sind.
Ein Abfragestring kann unterschiedlich aufgebaut sein. Es gibt zwei Möglichkeiten, eine Abfrage zu erstellen: mit und ohne Feldnamen. Eine globale Suche verwendet einen Abfragestring, der nur Feldwerte enthält:
Eine Feldsuche verwendet einen Abfragestring, der einen oder mehrere Ausdrücke enthält, die Feldnamen und Feldwerte angeben:
In diesem Dokument wird beschrieben, wie Abfragestrings für globale und Feldsuchen erstellt werden und wie die Suchlogik im jeweiligen Fall funktioniert.
Wir empfehlen das Logging von Abfragestrings in Ihrer Anwendung, wenn Sie eine Liste der ausgeführten Abfragen speichern möchten.
Globale Suche
Mit der globalen Suche kann auf der Basis von Werten eines beliebigen Dokumentfelds nach Dokumenten gesucht werden. Schreiben Sie einen Abfragestring, der einen oder mehrere Feldwerte enthält, um eine globale Suche durchzuführen. Der Suchalgorithmus erkennt den Typ jedes Werts und durchsucht alle Dokumentfelder, die diesen Wert enthalten könnten.
Einwertige Abfragen
Eine Suche mit einem Abfragestring, der einen einzelnen Wert enthält, wird nach den folgenden Regeln behandelt:
Wenn der Abfragestring aus einem Wort (red) oder aus einem String in Anführungszeichen ("red rose") besteht, werden bei der Suche alle Dokumente in einem Index abgerufen, die Folgendes enthalten:
- Ein Text- oder HTML-Feld, das das Wort oder den String in Anführungszeichen enthält (Groß- und Kleinschreibung wird nicht berücksichtigt)
- Ein Atomfeld mit einem Wert, der dem Wort oder dem String in Anführungszeichen entspricht (bei der Übereinstimmung wird nicht zwischen Groß- und Kleinschreibung unterschieden)
Wenn es sich beim Abfragestring um eine Zahl handelt ("3,14159"), ruft die Suche alle Dokumente ab, die Folgendes enthalten:
- Ein Text- oder HTML-Feld, das ein Token enthält, welches mit der in der Abfrage vorhandenen Nummer übereinstimmt (das Textfeld "Er brauchte 5 Minuten" entspricht der Abfrage "5", aber nicht "5,0")
- Ein Atomfeld, das exakt mit der Zahl übereinstimmt, die in der Abfrage angegeben ist
Wenn der Abfragestring aus einem Datum im Format JJJJ-MM-TT besteht, ruft die Suche alle Dokumente ab, die Folgendes enthalten:
- Ein Datumsfeld, dessen Wert diesem Datum entspricht (führende Nullen im Abfragestring sind optional, "2012-07-04" und "2012-7-4" sind dasselbe Datum)
- Ein Text- oder HTML-Feld, das ein Token enthält, das mit dem in der Abfrage angezeigten Datum genau übereinstimmt
- Ein Atomfeld, das exakt dem Datum in der Abfrage entspricht
Sie können den booleschen Operator NOT (Großbuchstaben) einer Ein-Wort-Abfrage voranstellen. Das Ergebnis ist dann eine Liste von Dokumenten, welche keine Felder enthalten, die nach den obigen Regeln mit dem Abfragewert übereinstimmen. Die Abfrage NOT red ruft also alle Dokumente ab, die weder Text- noch HTML-Felder mit „red“ und keine Atomfelder mit dem Wert red enthalten.
Vielleicht haben Sie bemerkt, dass wir noch nicht auf Geopunktfelder eingegangen sind. Derzeit besteht noch keine Möglichkeit, einen Geopunktrohwert als String anzugeben, sodass Geopunkte auch nicht in globalen Suchen verwendet werden können.
Mehrwertige Abfragen
In einem String für eine globale Suche können Sie mehrere Werte (getrennt durch Leerzeichen) angeben. Der Leerraum zwischen Wörtern, Strings in Anführungszeichen, Zahlen und Datumsangaben wird implizit als AND-Operator behandelt. Die beiden folgenden Suchstrings sind fast identisch. Sie unterscheiden sich darin, wie bei der globalen Suche Atomfelder behandelt werden. Dies wird im Folgenden erläutert:
query = "small red"
query = "small AND red"
Wenn Sie eine globale Suche mit mehreren Werten ausführen, wird jeder Wert im String einzeln mit den Feldern abgeglichen, wobei bei Atomfeldern anders verfahren wird:
- Abfragewerte können in einem Text- oder HTML-Feld in beliebiger Reihenfolge enthalten sein
- Unterschiedliche Werte können in unterschiedlichen Feldern enthalten sein
- Atomfelder werden nur durchsucht, wenn der Abfragestring keine booleschen Operatoren (
AND,OR,NOT) enthält. Der gesamte Abfragestring muss einem Atomfeld entsprechen.
Beachten Sie die dritte Regel zu Atomfeldern. Der Abfragestring „red small“ enthält nicht den booleschen Operator AND, obwohl dies impliziert ist. Bei der Suche wird deshalb nach übereinstimmenden Atomfeldern gesucht. Der String „red AND small“ enthält dagegen einen booleschen Operator, sodass der Abfragestring bei der Suche nicht mit Atomfeldern abgeglichen wird.
Im folgenden Beispiel werden vier Dokumente gezeigt, die mit dem Abfragestring „rose bud“ (Rose Knospe) abgerufen wurden. Jedes Dokument hat zwei Textfelder und ein Atomfeld. In der Kommentarspalte wird erläutert, warum jedes dieser Dokumente die Vorgaben der Abfrage erfüllt.
| Dok.-ID: | Textfeld 1 | Textfeld 2 | Atomfeld | Kommentar |
|---|---|---|---|---|
| 1 | mächtig wie eine Rose | eine Knospe, sie alle zu binden | Dornenbusch | Übereinstimmende Werte können in unterschiedlichen Feldern enthalten sein. |
| 2 | breit wie ein Fluss | wie die Knospe einer Rose | Steppenläufer | Übereinstimmende Werte können in beliebiger Reihenfolge im selben Text- oder HTML-Feld enthalten sein, außerdem kann weiterer Text zwischen ihnen liegen. |
| 3 | tief wie der Ozean | die Boyband Rose Knospe | blaue Mütze | Übereinstimmende Werte können in beliebiger Reihenfolge im selben Text- oder HTML-Feld enthalten sein. |
| 4 | groß wie ein Berg | der schöne Garten | Rose Knospe | Das Atomfeld stimmt überein, da sein Wert dem gesamten Abfragestring entspricht. |
Würden Sie die Werte in der Abfrage umkehren und stattdessen nach „Knospe Rose“ suchen, würden die Dokumente 1, 2 und 3 ebenfalls zurückgegeben, Dokument 4 jedoch nicht. Setzen Sie den Suchtext in einem Abfragestring in Anführungszeichen, um in Atom-, Text- und HTML-Feldern nach einer exakten Zeichenfolge zu suchen. Bei der Suche nach "rose bud" (Rose Knospe) werden in diesem Beispiel nur die Dokumente 3 und 4 zurückgegeben.
Boolesche Operatoren
Sie können auch komplexere globale Suchen ausführen, z. B. den booleschen Operator NOT für einen Wert angeben oder zwischen Werten die Operatoren AND und OR verwenden. Diese Operatoren müssen großgeschrieben werden. Wenn sie in einem String in Anführungszeichen enthalten sind, werden sie als Teil des Feldwerts behandelt, nicht als Operatoren. Sie können in einem Abfragestring Klammern verwenden, um die Logik zu verdeutlichen.
Die booleschen Operatoren werden von der höchsten bis zur niedrigsten Priorität folgendermaßen eingestuft: NOT, OR, AND.
NOT cat AND dogs OR horses --> (NOT cat) AND (dogs OR horses)
NOT cat OR dogs AND horses --> ((NOT cat) OR dogs) AND horses
Wortstammerkennung
Wenn Sie nach gängigen Varianten eines Worts suchen möchten, z. B. nach Pluralformen und Verbendungen, können Sie den Stemming-Operator ~ (Tilde-Zeichen) verwenden. Hierbei handelt es sich um einen Präfixoperator, der einem Wert ohne Leerzeichen vorangestellt werden muss. So entspricht der Wert ~cat „cat“ oder „cats“, während der Wert ~dog „dog“ oder „dogs“ entspricht. Bei der Verwendung des Stem-Algorithmus muss man sich über die gewünschten Ergebnisse im Klaren sein. So entspricht der Wert ~care „care“ und „caring“, aber nicht „cares“ oder „cared“. Der Stem-Operator kann nur für die Suche in Text- und HTML-Feldern verwendet werden.
Tokenisierung
Bei der Indexierung eines Dokuments werden dessen Felder tokenisiert. Ähnlich werden auch die Werte in einem Abfragestring in Token umgewandelt. Dies hat zur Folge, dass auf den ersten Blick einwertige Abfragen in Wirklichkeit als mehrwertige Abfragen behandelt werden. Beispiel:
"real-time" --> "real time"
"2001-12-15" --> "2001 12 15"
"1.5" --> "1 5"
Feldsuche
Bei einer Feldsuche wird anhand des Feldnamens in bestimmten Dokumentfeldern nach Werten gesucht. Ein Abfragestring für eine Feldsuche setzt sich aus einem oder mehreren Ausdrücken zusammen, in denen ein Feldname, ein relationaler Operator und ein Feldwert angegeben werden. Welche relationalen Operatoren verfügbar sind, hängt vom Feldtyp ab. Der Gleichheitsoperator, der entweder durch einen Doppelpunkt oder das Gleichheitszeichen dargestellt wird, kann für alle Feldtypen verwendet werden. Nachfolgend sind einige Feldabfragestrings für verschiedene Feldtypen aufgeführt:
query = "pet = dog"
query = "author = \"Ray Bradbury\""
query = "color:red"
query = "NOT color:red"
query = "price < 500"
query = "birthday>=2011-05-10"
Die Verwendung von Leerzeichen vor und nach einem relationalen Operator ist optional. Wie bei Abfragestrings für globale Suchen kann der Wert eines Text-, HTML- oder Atomfelds zur Festlegung eines Strings in Anführungszeichen gesetzt und ein Ausdruck für einen Feldwert durch Voranstellen des großgeschriebenen NOT negiert werden.
Abfragen von Atomfeldern
Der Wert eines Atomfeldes ist ein Zeichenstring. Bei Abfragen von Atomfeldern wird die Groß-/Kleinschreibung nicht beachtet. Wenn Sie in Ihrer Abfrage einen Feldwert mit Leerzeichen oder Interpunktion angeben, achten Sie darauf, den Wert im Abfragestring in Anführungszeichen zu setzen. Bei Atomfeldern ist der einzige gültige relationale Operator der Gleichheitsoperator. Der Inhalt eines Atomfelds muss vollständig mit dem Abfragewert übereinstimmen. Dies gilt auch für alle kombinierenden oder Akzentzeichen im Unicode-Format in dem Feld. Die Wortstammerkennung wird für Atomfelder nicht unterstützt.
| Abfragestring | Kommentare |
|---|---|
"weather=stormy"
|
Der Gleichheitsoperator ist in jedem Format gültig. Ruft Dokumente mit einem Wetterfeld mit dem Wert "stormy" ab. |
"Title: \"Tom&Jerry\""
|
Wenn Sie nach einem Atomfeld suchen, das Leerzeichen oder Sonderzeichen enthält, müssen Sie den entsprechenden Wert in Anführungszeichen setzen. |
"Color = (red OR blue)"
|
Sie können Klammern und den logischen Operator OR verwenden, um eine Liste mit alternativen Feldwerten anzugeben. |
Abfragen von Text- und HTML-Feldern
Der einzige gültige relationale Operator für Text- und HTML-Felder ist der Gleichheitsoperator. In diesem Fall besagt der Operator "Feld enthält Wert" und nicht "Feld entspricht Wert". Mit dem Stem-Operator können Sie nach Varianten eines Wortes suchen. Außerdem können Sie auch die Operatoren OR und AND verwenden, um komplexe boolesche Ausdrücke für den Feldwert anzugeben. Wenn ein boolescher Operator in einem String in Anführungszeichen enthalten ist, wird er nicht speziell behandelt, sondern einfach als Teil der abzugleichenden Zeichenfolge betrachtet. Beim Durchsuchen von HTML-Feldern wird der Text in HTML-Markup-Tags ignoriert. Bei Abfragen von Text- und HTML-Feldern wird die Groß-/Kleinschreibung nicht beachtet. Wenn diese Felder indexiert werden, werden alle darin enthaltenen kombinierenden oder Akzentzeichen im Unicode-Format "normalisiert", d. h., in ihre Äquivalente ohne Akzente umgewandelt. Kombinierende Zeichen und Akzente werden auch in Abfragestrings für diese Felder normalisiert, sodass die Felder unabhängig davon übereinstimmen, ob in der Abfrage die Formen mit Akzenten enthalten sind oder nicht.
| Abfragestring | Kommentare |
|---|---|
"Comment = great" |
Der Gleichheitsoperator ist in jedem Format gültig. Ruft Dokumente mit einem Kommentarfeld ab, in dem mindestens einmal das Wort "great" im Feld "Comment" enthalten ist. |
"Comment = (great big ball)"
|
Wenn Sie nach zwei oder mehr Wörtern in beliebiger Reihenfolge in einem Feld suchen möchten, schließen Sie die Wörter in Klammern ein. Mit diesem Abfragestring werden Dokumente mit einem Kommentarfeld abgerufen, in dem alle drei Wörter in beliebiger Reihenfolge mit einer beliebigen Anzahl anderer Wörter dazwischen enthalten sind. Das Leerzeichen zwischen den Wörtern stellt ein implizites "Logisches Und" (wie der Operator AND) dar. In der zweiten Variante ist es explizit eingefügt. |
"Comment = \"insanely great\""
|
Wenn Sie nach einem bestimmten Textstring suchen möchten, setzen Sie ihn in Anführungszeichen. Mit dieser Abfrage werden Dokumente abgerufen, in deren Kommentarfeld die Wortfolge "insanely great" enthalten ist und ebenso "insanely-great", also die gleiche Wortfolge in tokenisierter Form. |
"pet = ~dog"
|
Mit dem Stemming-Operator werden Varianten des Wortes "dog" im Feld "pet" abgeglichen. |
"Color = (red OR blue)" |
Wenn Sie anhand einer Liste von Alternativen nach einer Übereinstimmung suchen möchten, setzen Sie die Liste in Klammern und fügen Sie zwischen den Alternativen den Operator OR ein. Mit dieser Abfrage werden Dokumente abgerufen, deren Feld "Color" entweder "red" oder "blue" oder beides enthält. |
"weather = ((rain OR snow) AND cold)" |
Sie können mit den logischen Operatoren OR und AND in Verbindung mit Klammern einen komplexeren Feldwert festlegen. |
"weather = \"rain OR shine\"" |
Da das logische OR in einen String in Anführungszeichen eingebettet ist, wird es nicht als relationaler Operator behandelt. Mit diesem Abfragestring werden Dokumente mit einem Feld "weather" abgerufen, das die Zeichenfolge "rain or shine" enthält. |
Abfragen von Zahlenfeldern
Der Wert eines Zahlenfelds kann als Ganzzahl, Dezimalzahl oder Exponentialzahl geschrieben sein.
Gültige relationale Operatoren für Zahlenfelder sind die Gleichheitsoperatoren sowie die Operatoren kleiner als/größer als (<, <=, >, >=). Beachten Sie, dass es keinen Ungleichheitsoperator (!=) gibt. Nachfolgend sehen Sie einige Beispiele für Abfragestrings für Zahlenfelder:
"quantity = 10000"
"size: 4"
"price < 9.99"
"theta > 1.5E-2"
Abfragen von Datumsfeldern
Ein Datumsfeldwert muss im Format yyyy-mm-dd form eingegeben werden. Für einstellige Monate und Tage sind führende Nullen optional. Gültige relationale Operatoren für Datumsfelder sind die Gleichheitsoperatoren sowie die Operatoren kleiner als/größer als (<, <=, >, >=). Beachten Sie, dass es keinen Ungleichheitsoperator gibt. Sie können einem Ausdruck auch den NOT-Operator voranstellen, wenn Sie ihn negieren möchten. Nachfolgend sehen Sie einige Beispiele für Abfragestrings für Datumsfelder:
"start_date: 2012-05-20"
"end_date: 2013-5-1"
"birthday >= 2000-12-31"
"NOT birthday = 2000-12-25"
Abfragen von Geopunktfeldern
Für Geopunktfelder können keine relationalen Operatoren verwendet werden. Deshalb gibt es keine Möglichkeit, Geopunktfelder in einem Abfragestring direkt zu benennen. Die Search API bietet zwei spezielle Funktionen für Abfragen von Geopunktfeldern:
geopoint(lat,long)- Definiert einen Geopunkt anhand eines Längen- und Breitengrads.
distance(point1, point2)- Berechnet die Entfernung zwischen zwei Geopunkten in Metern. Jeder Punkt kann mithilfe des Namens eines Geopunktfelds oder eines Aufrufs der Geopunktfunktion angegeben werden. Sie können nicht zwei Feldnamen als Argumente für diese Funktion angeben. Mindestens ein Argument muss eine Konstante sein.
Mit diesen Funktionen lassen sich Abfragen erstellen, die Standorte relativ zu einer konstanten Position abrufen. In den folgenden Beispielen wird angenommen, dass der Index Dokumente mit den Geopunktfeldern "survey_marker" und "home" enthält.
| Abfragestring | Kommentare |
|---|---|
"distance(survey_marker, geopoint(35.2, 40.5)) < 100" |
Sucht nach Markierungen, die höchstens 99 Meter von einem bestimmten Geopunkt entfernt sind. |
"distance(home, geopoint(35.2, 40.5)) > 100" |
Sucht nach Häusern, die mindestens 101 Meter von einem bestimmten Geopunkt entfernt sind. |
Anwendungen, die Standortbestimmung verwenden, empfangen in der Regel Informationen vom Browser. Wenn der Nutzer dies zulässt, kann sein Standort aus seiner IP-Adresse abgeleitet werden, oder er kann eine Postleitzahl eingeben. Die Position kann auch von anderen APIs wie der Google Maps Geolocation API bezogen werden.
Abfragen von mehreren Feldern
Sie können für Feldabfragen mehrere Ausdrücke in einer Abfrage kombinieren. Dazu listen Sie diese durch Leerzeichen getrennt hintereinander auf. Damit wird zwischen allen Ausdrücken ein implizites AND eingefügt, d. h. alle Ausdrücke müssen erfüllt werden, damit ein Dokument abgerufen wird. Sie können dabei auch AND- und OR-Operatoren explizit zwischen Ausdrücken einfügen und mit Klammern die Logik verdeutlichen.
| Abfragestring | Kommentare |
|---|---|
"product=piano manufacturer=steinway""product=piano AND manufacturer=steinway"
|
Mit diesen Abfragen werden alle Steinway-Klaviere abgerufen. Das Leerzeichen zwischen den Begriffen stellt ein implizites "Logisches Und" (wie der Operator AND) dar. In der zweiten Variante wurde dieser Operator explizit eingefügt. |
"product=piano AND NOT manufacturer=steinway"
|
Ruft alle Klaviere ab, die nicht von Steinway sind. |
"product=piano AND price<2000" |
Mit dieser Abfrage werden preiswerte Klaviere abgerufen. |
Globale und Feldsuchen mischen
Ein Abfragestring kann eine beliebige Anzahl von Ausdrücken für globale Suchen und Feldsuchen enthalten. Leerzeichen zwischen Ausdrücken werden wie AND behandelt. Sie können auch explizit OR und AND mit Klammern verwenden. Jeder Ausdruck wird nach den Regeln behandelt, die diesem Begriff zugeordnet sind.
| Abfragestring | Kommentare |
|---|---|
"keyboard great price<5000"
|
Ruft Dokumente ab, in denen die Wörter „great“ und „keyboard“ in beliebigen Text-, HTML- oder Atomfeldern enthalten sind und es ein Preisfeld mit einem Wert unter 5.000 gibt.
Der AND-Operator ist impliziert, das zweite Format ist äquivalent.
|
"keyboard OR product=piano" |
Ruft Dokumente mit einem Produktfeld ab, das "piano" enthält, oder Dokumente mit einem Text-, HTML- oder Atomfeld, in dem "keyboard" enthalten ist. |