So funktioniert die Suche auf IBM Cloudant

Suchindexdefinitionen werden in Entwurfsdokumenten in Form einer JavaScript Funktion gespeichert, die gegen jedes Dokument in der Datenbank ausgeführt wird. Die Funktion definiert, welche Attribute indiziert werden, welche im Index gespeichert werden, aber nicht durchsuchbar sind, und wie jedes Textattribut vor der Indizierung vorverarbeitet wird (unter Verwendung eines ausgewählten Such-"Analyzers").

IBM Cloudant die Suche kann sich auf die gesamte Datenbank oder bei partitionierten Datenbanken auf eine einzelne Partition beziehen, für die options.partitioned im Entwurfsdokument angegeben ist true.

Wann sollte die Suche IBM Cloudant verwendet werden?

IBM Cloudant Die Suche ist ideal für:

• Sprachunterstützte Volltextsuche, Platzhaltersuche und einfache Bereichsabfragen in numerischen oder Textfeldern.
• Flexible Abfragen auf eine Reihe von indizierten Feldern.
• Einfache raumbezogene Abfragen wie die Suche nach dem nächstgelegenen Ort oder die Suche mit einem Begrenzungsrahmen.
• Zählungsaggregationen auf einzelnen Feldern innerhalb der Ergebnismenge - bekannt als "Facettierung".

Wann die Suche IBM Cloudant nicht verwendet werden sollte

Vermeiden Sie IBM Cloudant Suche nach

• Aggregation (anders als Facettierung). Verwenden Sie stattdessen Views.

Aufbau eines Suchindexes

Zum Erstellen eines Suchindex fügen Sie einem Entwurfsdokument in der Datenbank eine JavaScript-Funktion hinzu. Ein Index wird erstellt, wenn eine Suchanforderung verarbeitet wurde oder wenn der Server eine Dokumentaktualisierung erkannt hat. Die Indexfunktion (Feld index) akzeptiert die folgenden Parameter:

1. Feldname - Der Name des Felds, das Sie zum Abfragen des Index verwenden wollen. Wenn Sie diesen Parameter auf den Wert default setzen, wird dieses Feld abgefragt, wenn in der Abfragesyntax kein Feld angegeben wird.
2. Daten, die indexiert werden sollen. Beispiel: doc.address.country.
3. (Optional) Der dritte Parameter enthält die folgenden Felder: boost, facet, index und store. Diese Felder werden nachfolgend ausführlicher beschrieben.

Eine Suchindexantwort gibt standardmäßig 25 Zeilen zurück. Die Anzahl der Zeilen, die zurückgegeben werden, kann über den Parameter limit geändert werden. Allerdings ist die Ergebnismenge einer Suche auf 200 Zeilen begrenzt. Jede Antwort enthält ein Feld bookmark (Lesezeichen). Sie können den Wert des Felds bookmark in spätere Abfragen einfügen, um alle Antworten durchzusehen.

Sie können die API mit einer der folgenden Methoden abfragen: URI, IBM Cloudant Dashboard, Curl oder Browser-Plug-in wie Postman oder RESTClient.

Beispiel für ein Entwurfsdokument, das einen Suchindex definiert:

{
	"_id": "_design/search_example",
	"indexes": {
		"animals": {
			"index": "function(doc){ ... }"
		}
	}
}

Partitionierungstyp für Suchindizes

Ein Suchindex übernimmt den Partitionierungstyp aus dem Feld options.partitioned des Entwurfsdokuments, in dem er enthalten ist.

Indexfunktionen

Wenn Sie versuchen, ein Datenfeld zu indexieren, das nicht vorhanden ist, schlägt die Indexierung fehl. Zur Vermeidung dieses Problems verwenden Sie eine entsprechende Wächterklausel.

Ihre Indexierungsfunktionen operieren in einer Umgebung mit begrenztem Speicher, in der das Dokument selbst einen Teil des Speichers bildet, der in dieser Umgebung verwendet wird. Der Stack und das Dokument Ihres Codes muss in diesen Speicher passen. Dokumente sind auf eine maximale Größe von 64 MB begrenzt.

Indexieren Sie innerhalb eines Suchindex nicht denselben Feldnamen mit mehr als einem Datentyp. Wenn derselbe Feldname in derselben Suchindexfunktion mit unterschiedlichen Datentypen indexiert wird, wird ein Fehler angezeigt. Dieser Fehler tritt auf, wenn Sie den Suchindex abfragen, der das Feld „ was indexed without position data “ enthält. Schließen Sie zum Beispiel nicht beide der folgenden Zeilen in dieselbe Suchindexfunktion ein. Durch diese Zeilen wird das Feld myfield mit zwei unterschiedlichen Datentypen indexiert: einmal als Zeichenfolge "this is a string" und einmal als Zahl 123.

index("myfield", "this is a string");
index("myfield", 123);

Die Funktion, die in dem Indexfeld enthalten ist, ist eine JavaScript-Funktion, die für jedes Dokument in der Datenbank aufgerufen wird. Die Funktion empfängt das Dokument als Parameter, extrahiert einige Daten aus dem Dokument und ruft dann die Funktion auf, die im Feld index definiert ist, um die Daten zu indexieren.

Die Funktion index akzeptiert drei Parameter, wobei der dritte Parameter optional ist.

Der erste Parameter ist der Name des Feldes, das Sie bei der Abfrage des Indexes verwenden möchten; dieser wird im Lucene-Syntaxteil der nachfolgenden Abfragen angegeben. Die folgende Abfrage zeigt ein Beispiel:

query=color:red

Der Lucene-Feldname color ist der erste Parameter der Funktion index.

Der Parameter query kann zu q abgekürzt werden, sodass das folgende Beispiel eine alternative Schreibweise für die Abfrage darstellt.

q=color:red

Wenn der Sonderwert "default" beim Definieren des Namens verwendet wird, müssen Sie bei der Abfrage keinen Feldnamen angeben. Das hat den Effekt, dass die Abfrage vereinfacht werden kann:

query=red

Der zweite Parameter gibt die Daten an, die indexiert werden sollen. Berücksichtigen Sie die folgenden Informationen, wenn Sie Ihre Daten indexieren:

• Diese Daten dürfen nur die Typen Zeichenfolge, Zahl oder Boolesch haben. Andere Typen geben einen Fehler aus dem Aufruf der Indexfunktion zurück.
• Wenn während der Ausführung Ihrer Funktion aus diesem Grund oder aus einem anderen ein Fehler zurückgegeben wird, wird das Dokument diesem Suchindex nicht hinzugefügt.

Der dritte, optionale, Parameter ist ein JavaScript-Objekt mit den folgenden Feldern:

Wenn Sie den Parameter store nicht angeben, werden die Indexdatenergebnisse für das Dokument nicht in der Antwort auf eine Abfrage zurückgegeben.

Beispiel für eine Suchindexfunktion:

function(doc) {
	index("default", doc._id);
	if (doc.min_length) {
		index("min_length", doc.min_length, {"store": true});
	}
	if (doc.diet) {
		index("diet", doc.diet, {"store": true});
	}
	if (doc.latin_name) {
		index("latin_name", doc.latin_name, {"store": true});
	}
	if (doc.class) {
		index("class", doc.class, {"store": true});
	}
}

if (doc.min_length) {
	index("min_length", doc.min_length, {"store": true});
}

if (typeof doc.min_length === 'number') {
    index("min_length", doc.min_length, {"store": true});
}

if (typeof doc.min_length) !== 'undefined') {
	// The field exists, and does have a type, so we can proceed to index using it.
	...
}

Analysefunktionen

Analysefunktionen sind Einstellungen, die definieren, wie Begriffe in einem Text erkannt werden. Weitere Informationen finden Sie unter Suchanalysatoren.

Analysefunktionen können nützlich sein, wenn Sie mehrere Sprachen indexieren müssen.

Die folgende Tabelle zeigt eine Liste von generischen Analysatoren, die von der IBM Cloudant Suche unterstützt werden:

Beispiel für ein Dokument mit Angabe der Analysefunktion ('analyzer'):

{
	"_id": "_design/analyzer_example",
	"indexes": {
		"INDEX_NAME": {
			"index": "function (doc) { ... }",
			"analyzer": "$ANALYZER_NAME"
		}
	}
}

{
	"_id": "_design/analyzer_example",
	"indexes": {
		"INDEX_NAME": {
			"analyzer": {
				"name": "perfield",
				"default": "english",
				"fields": {
					"spanish": "spanish",
					"german": "german"
				}
			},
			"index": "function (doc) { ... }"
		}
	}
}

 "a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if",
 "in", "into", "is", "it", "no", "not", "of", "on", "or", "such",
 "that", "the", "their", "then", "there", "these", "they", "this",
 "to", "was", "will", "with"

{
	"_id": "_design/stop_words_example",
	"indexes": {
		"INDEX_NAME": {
			"analyzer": {
				"name": "portuguese",
				"stopwords": [
					"foo",
					"bar",
					"baz"
				]
			},
			"index": "function (doc) { ... }"
		}
	}
}

Host: $ACCOUNT.cloudant.com
POST /_search_analyze HTTP/1.1
Content-Type: application/json
{"analyzer":"keyword", "text":"ablanks@renovations.com"}

curl "https://$ACCOUNT.cloudant.com/_search_analyze" \
	-H "Content-Type: application/json" \
	-d '{"analyzer":"keyword", "text":"ablanks@renovations.com"}'

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostSearchAnalyzeOptions;
import com.ibm.cloud.cloudant.v1.model.SearchAnalyzeResult;
Cloudant service = Cloudant.newInstance();
PostSearchAnalyzeOptions searchAnalyzerOptions =
    new PostSearchAnalyzeOptions.Builder()
        .analyzer("keyword")
        .text("ablanks@renovations.com")
        .build();
SearchAnalyzeResult response =
    service.postSearchAnalyze(searchAnalyzerOptions).execute()
        .getResult();
System.out.println(response);

import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.postSearchAnalyze({
	analyzer: 'keyword',
	text: 'ablanks@renovations.com',
}).then(response => {
	console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_search_analyze(
	analyzer='keyword',
	text='ablanks@renovations.com'
).get_result()
print(response)

postSearchAnalyzeOptions := service.NewPostSearchAnalyzeOptions(
	"keyword",
	"ablanks@renovations.com",
)
searchAnalyzeResult, _, err := service.PostSearchAnalyze(postSearchAnalyzeOptions)
if err != nil {
	panic(err)
}
b, _ := json.MarshalIndent(searchAnalyzeResult, "", "  ")
fmt.Println(string(b))

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

{
	"tokens": [
		"ablanks@renovations.com"
	]
}

Host: $ACCOUNT.cloudant.com
POST /_search_analyze HTTP/1.1
Content-Type: application/json
{"analyzer":"standard", "text":"ablanks@renovations.com"}

curl "https://$ACCOUNT.cloudant.com/_search_analyze" -H "Content-Type: application/json"
	-d '{"analyzer":"standard", "text":"ablanks@renovations.com"}'

{
	"tokens": [
		"ablanks",
		"renovations.com"
	]
}

Abfragen

Wenn Sie einen Suchindex erstellt haben, können Sie ihn abfragen.

• Führen Sie eine Partitionsabfrage mit der folgenden Anforderung aus:

  GET /$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_search/$INDEX_NAME
  

• Führen Sie eine globale Abfrage mit der folgenden Anforderung aus:

  GET /$DATABASE/_design/$DDOC/_search/$INDEX_NAME
  

Geben Sie Ihre Suche mithilfe des Parameters query an.

Beispiel für die Verwendung von HTTP zum Abfragen eines partitionierten Index:

GET /$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_search/$INDEX_NAME?include_docs=true&query="*:*"&limit=1 HTTP/1.1
Content-Type: application/json
Host: $ACCOUNT.cloudant.com

Beispiel zur Abfrage eines partitionierten Index über die Befehlszeile:

curl "https://$ACCOUNT.cloudant.com/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_search/$INDEX_NAME?include_docs=true&query=\"*:*\"&limit=1"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostPartitionSearchOptions;
import com.ibm.cloud.cloudant.v1.model.SearchResult;
Cloudant service = Cloudant.newInstance();
PostPartitionSearchOptions searchOptions =
    new PostPartitionSearchOptions.Builder()
		.db("<db-name>")
		.partitionKey("<partition-key>")
		.ddoc("<ddoc>")
		.index("<index-name>")
		.query("*:*")
		.includeDocs(true)
		.limit(1)
		.build();
SearchResult response =
    service.postPartitionSearch(searchOptions).execute()
        .getResult();
System.out.println(response);

import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.postSearch({
	db: '<db-name>',
	partitionKey: '<partition-key>',
	ddoc: '<ddoc>',
	index: '<index-name>',
	query: '*:*',
	includeDocs: true,
	limit: 1
}).then(response => {
	console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_search(
	db='<db-name>',
	partition_key='<partition-key>',
	ddoc='<ddoc>',
	index='<index-name>',
	query='*:*',
	include_docs=True,
	limit=1
).get_result()
print(response)

postPartitionSearchOptions := service.NewPostPartitionSearchOptions(
	"<db-name>",
	"<partition-key>",
	"<ddoc>",
	"<index-name>",
	"*:*",
)
postPartitionSearchOptions.SetIncludeDocs(true)
postPartitionSearchOptions.SetLimit(1)
searchResult, _, err := service.PostPartitionSearch(postPartitionSearchOptions)
if err != nil {
	panic(err)
}
b, _ := json.MarshalIndent(searchResult, "", "  ")
fmt.Println(string(b))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

Beispiel für die Verwendung von HTTP zum Abfragen eines globalen Index:

GET /$DATABASE/_design/$DDOC/_search/$INDEX_NAME?include_docs=true&query="*:*"&limit=1 HTTP/1.1
Content-Type: application/json
Host: $ACCOUNT.cloudant.com

Beispiel zur Abfrage eines globalen Index über die Befehlszeile:

curl "https://$ACCOUNT.cloudant.com/$DATABASE/_design/$DDOC/_search/$INDEX_NAME?include_docs=true&query=\"*:*\"&limit=1"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostSearchOptions;
import com.ibm.cloud.cloudant.v1.model.SearchResult;
Cloudant service = Cloudant.newInstance();
PostSearchOptions searchOptions = new PostSearchOptions.Builder()
    .db("<db-name>")
    .ddoc("<ddoc>")
    .index("<index-name>")
    .query("*:*")
	.includeDocs(true)
	.limit(1)
    .build();
SearchResult response =
    service.postSearch(searchOptions).execute()
        .getResult();
System.out.println(response);

import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.postSearch({
	db: '<db-name>',
	ddoc: '<ddoc>',
	index: '<index-name>',
	query: '*:*',
	includeDocs: true,
	limit: 1
}).then(response => {
	console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_search(
	db='<db-name>',
	ddoc='<ddoc>',
	index='<index-name>',
	query='*:*',
	include_docs=True,
	limit=1
).get_result()
print(response)

postSearchOptions := service.NewPostSearchOptions(
	"<db-name>",
	"<ddoc>",
	"<index-name>",
	"*:*",
)
postSearchOptions.SetIncludeDocs(true)
postSearchOptions.SetLimit(1)
searchResult, _, err := service.PostSearch(postSearchOptions)
if err != nil {
	panic(err)
}
b, _ := json.MarshalIndent(searchResult, "", "  ")
fmt.Println(string(b))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

POST /db/_design/ddoc/_search/searchname HTTP/1.1
Content-Type: application/json
Host: $ACCOUNT.cloudant.com

curl "https://$ACCOUNT.cloudant.com/$DATABASE/_design/$DDOC/_search/$INDEX_NAME" -X POST -H "Content-Type: application/json" -d @search.json

{
    "q": "index:my query",
    "sort": "foo",
    "limit": 3
}

Seitenaufteilung

Verwenden Sie die Paginierung von Lesezeichen für Suchanfragen. Spezifische Details und Beispiele finden Sie in der API-Dokumentation zum Thema Paging bei Suchindexabfragen.

Abfragesyntax

Die Syntax für Suchanfragen bei „ IBM Cloudant “ basiert auf der Lucene-Syntax. Suchabfragen haben die Form name:value, sofern der Name nicht weggelassen wird. Wenn der Name weggelassen wird, wird das Standardfeld verwendet, wie in den folgenden Beispielen gezeigt.

Beispiele für Suchabfrageausdrücke:

// Birds
class:bird
// Animals that begin with the letter "l"
l*
// Carnivorous birds
class:bird AND diet:carnivore
// Herbivores that start with letter "l"
l* AND diet:herbivore
// Medium-sized herbivores
min_length:[1 TO 3] AND diet:herbivore
// Herbivores that are 2m long or less
diet:herbivore AND min_length:[-Infinity TO 2]
// Mammals that are at least 1.5m long
class:mammal AND min_length:[1.5 TO Infinity]
// Find "Meles meles"
latin_name:"Meles meles"
// Mammals who are herbivore or carnivore
diet:(herbivore OR omnivore) AND class:mammal
// Return all results
*:*

Abfragen über mehrere Felder können logisch kombiniert werden und Gruppen und Felder können noch weiter gruppiert werden. Die folgenden verfügbaren logischen Operatoren sind von der Groß-/Kleinschreibung abhängig: AND, +, OR, NOT und -. Bereichsabfragen können auf Zeichenfolgen oder Zahlen ausgeführt werden.

Wenn Sie eine Suche nach grober Übereinstimmung durchführen wollen, können Sie eine Abfrage mit ~ ausführen, um Begriffe zu finden, die dem Suchbegriff ähnlich sind. Zum Beispiel, look~ ergibt die Terme „ book “ und „ took “.

Wenn die Ober- und die Untergrenze einer Bereichsabfrage beides Zeichenfolgen sind, die nur numerische Ziffern enthalten, werden die Begrenzungen als Zahlen und nicht als Zeichenfolgen behandelt. Beispiel: Wenn Sie eine Suche mit der Abfrage mod_date:["20170101" TO "20171231"] durchführen, enthalten die Ergebnisse Dokumente, für die mod_date zwischen den numerischen Werten 20170101 und 20171231 liegt und nicht zwischen den Zeichenfolgen "20170101" und "20171231".

Sie können die Wichtigkeit eines Suchbegriffs ändern, indem Sie das Zeichen ^ und eine positive Zahl hinzufügen. Diese Änderung erzeugt Übereinstimmungen, die den Begriff proportional zum Einfluss des Boostwerts mit höherer oder niedriger Relevanz enthalten. Der Standardwert ist 1 und hat keinen Einfluss auf die Erhöhung oder Verringerung der Übereinstimmungsstärke. Ein Dezimalwert von 0 - 1 verringert die Wichtigkeit, und senkt die Übereinstimmungsstärke. Ein Wert größer 1 erhöht die Wichtigkeit und hebt die Übereinstimmungsstärke.

Platzhaltersuchen werden unterstützt, und zwar für Suchen nach Einzelzeichen (?) und Suchen nach mehreren Zeichen (*). Beispiel: dat? würde mit date und data übereinstimmen, und dat* würde mit date,data,database sowie dates übereinstimmen. Platzhalter müssen nach dem Suchbegriff angegeben werden.

Geben Sie *:* an, um alle Ergebnisse zurückzugeben.

Ergebnismengen aus Suchen sind auf 200 Zeilen begrenzt. Standardmäßig werden 25 Zeilen zurückgegeben. Die Anzahl der Zeilen, die zurückgegeben werden, kann über den Parameter limit geändert werden.

Wenn in der Suchabfrage kein Argument "group_field" angegeben wird, enthält die Antwort ein Lesezeichen ('bookmark'). Wenn dieses Lesezeichen später in einem URL-Parameter angegeben wird, überspringt die Antwort die Zeilen, die bereits angezeigt wurden, sodass der nächste Satz von Ergebnissen schnell und einfach abgerufen werden kann.

Die Antwort enthält nie ein Lesezeichen, wenn der Parameter "group_field" in der Suchabfrage angegeben wird.

Die Optionen group_field, group_limit und group_sort sind nur verfügbar, wenn Sie globale Abfragen durchführen.

Die folgenden Zeichen müssen mit Escapezeichen versehen werden, wenn nach ihnen gesucht werden soll:

+ - && || ! ( ) { } [ ] ^ " ~ * ? : \ /

Stellen Sie einem dieser Zeichen jeweils ein Backslash-Zeichen () als Escapezeichen voran.(\).

Die Antwort auf eine Suchabfrage enthält ein Feld order für jedes der Ergebnisse. Das Feld order ist ein Array, in dem das erste Element das Feld bzw. die Felder sind, die im Parameter sort angegeben wurden. Wenn in der Abfrage kein Parameter „ sort “ enthalten ist, enthält das Feld „ order “ den Lucene-Relevanzwert. Wenn Sie die Funktion "Nach Entfernung sortieren" (sort by distance) wie im Abschnitt Geographische Suchen erläutert verwenden, ist das erste Element die Entfernung von einem Punkt. Die Entfernung wird in Kilometern oder Meilen gemessen.

Das zweite Element im Array 'order' kann ignoriert werden. Es dient lediglich zu Fehlerbehebungszwecken.

Facettierung

IBM Cloudant Search unterstützt darüber hinaus eine Suche mit Facettierung, die eine schnelle und einfache Erkennung von zusammengefassten Informationen zu Übereinstimmungen ermöglicht. Sie können alle Dokumente mithilfe der speziellen Abfragesyntax ?q=*:* abgleichen und die zurückgegebenen Facetten zur Präzisierung Ihrer Abfrage verwenden. Um anzugeben, dass ein Feld für facettierte Abfragen indexiert werden muss, geben Sie {"facet": true} in den Optionen der Abfrage an.

Beispiel für eine Suchabfrage, in der die facettierte Suche aktiviert wird:

function(doc) {
    index("type", doc.type, {"facet": true});
    index("price", doc.price, {"facet": true});
}

Für die Verwendung von Facetten müssen alle Dokumente im Index alle Felder enthalten, für die die Facettierung aktiviert wird. Wenn Ihre Dokumente nicht alle Felder enthalten, empfangen Sie einen Fehler bad_request mit der folgenden Ursache: "Das Feld field_name ist nicht vorhanden." Wenn nicht jedes Dokument alle Felder für Facetten enthält, erstellen Sie für jedes Feld separate Indizes. Wenn Sie nicht separate Indizes für jedes Feld erstellen, müssen Sie nur Dokumente einschließen, die alle Felder enthalten. Stellen Sie durch eine einzelne Anweisung if sicher, dass die Felder in jedem Dokument vorhanden sind.

Beispiel für eine Anweisung if, die prüft, ob die erforderlichen Felder in jedem Dokument vorhanden sind:

if (typeof doc.town == "string" && typeof doc.name == "string") {
        index("town", doc.town, {facet: true});
        index("name", doc.name, {facet: true});        
    }

?q=*:*&counts=["type"]

{
    "total_rows":100000,
    "bookmark":"g...",
    "rows":[...],
    "counts":{
        "type":{
            "sofa": 10,
            "chair": 100,
            "lamp": 97
        }
    }
}

?q=*:*&ranges={"price":{"cheap":"[0 TO 100]","expensive":"{100 TO Infinity}"}}

{
    "total_rows":100000,
    "bookmark":"g...",
    "rows":[...],
    "ranges": {
        "price": {
            "expensive": 278682,
            "cheap": 257023
        }
    }
}

Geografische Suchen

Neben dem Suchen nach den Inhalten von Textfeldern können Sie Ihre Ergebnisse auch nach Entfernung von einem geografischen Punkt (Koordinaten) sortieren.

Zum Sortieren von Ergebnissen auf diese Weise müssen Sie zwei numerische Felder indexieren, die den Längengrad und den Breitengrad darstellen.

Sie können anschließend eine Abfrage unter Verwendung des besonderen Sortierfelds <distance...> ausführen, das fünf Parameter erfordert:

• Name des Längengradfelds - Der Name Ihres Längengradfelds (Beispiel: mylon).
• Name des Breitengradfelds - Der Name Ihres Breitengradfelds (Beispiel: mylat).
• Längengrad des Ursprungs - Der Längengrad des Ortes, von dem aus nach Entfernung sortiert werden soll.
• Breitengrad des Ursprungs - Der Breitengrad des Ortes, von dem aus nach Entfernung sortiert werden soll.
• Einheiten - Die einzuschließenden Einheiten: km für Kilometer oder mi für Meilen. Die Entfernung wird im Feld 'order' zurückgegeben.

Sie können die Sortierung nach Entfernung mit jeder anderen Suchanfrage kombinieren, beispielsweise mit Bereichssuchen nach Breiten- und Längengrad oder mit Suchanfragen, die nicht-geografische Informationen beinhalten.

Auf diese Weise können Sie in einer Manipulationsbox (Bounding Box) suchen und die Suche durch zusätzliche Kriterien eingrenzen.

Beispiel für geografische Daten:

{
    "name":"Aberdeen, Scotland",
    "lat":57.15,
    "lon":-2.15,
    "type":"city"
}

Beispiel für ein Entwurfsdokument, das einen Suchindex für die geografischen Daten enthält:

function(doc) {
    if (doc.type && doc.type == 'city') {
        index('city', doc.name, {'store': true});
        index('lat', doc.lat, {'store': true});
        index('lon', doc.lon, {'store': true});
    }
}

Beispiel für die Verwendung von HTTP, um eine Abfrage auszuführen, die Städte in der nördlichen Hemisphäre nach Entfernung von New York sortiert:

GET /examples/_design/cities-designdoc/_search/cities?q=lat:[0+TO+90]&sort="<distance,lon,lat,-74.0059,40.7127,km>" HTTP/1.1
Host: $ACCOUNT.cloudant.com

Beispiel für die Verwendung der Befehlszeile, um eine Abfrage auszuführen, die Städte in der nördlichen Hemisphäre nach Entfernung von New York sortiert:

curl "https://$ACCOUNT.cloudant.com/examples/_design/cities-designdoc/_search/cities?q=lat:\[0+TO+90\]&sort=\"<distance,lon,lat,-74.0059,40.7127,km>\""

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostSearchOptions;
import com.ibm.cloud.cloudant.v1.model.SearchResult;
import java.util.Arrays;
Cloudant service = Cloudant.newInstance();
PostSearchOptions searchOptions = new PostSearchOptions.Builder()
	.db("examples")
	.ddoc("cities-designdoc")
	.index("cities")
	.query("lat:\\[0+TO+90\\]")
	.sort(Arrays.asList("<distance,lon,lat,-74.0059,40.7127,km>"))
	.build();
SearchResult response =
    service.postSearch(searchOptions).execute()
        .getResult();
System.out.println(response);

import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.postSearch({
	db: 'examples',
	ddoc: 'cities-designdoc',
	index: 'cities',
	query: 'lat:\\[0+TO+90\\]',
	sort: ['<distance,lon,lat,-74.0059,40.7127,km>']
}).then(response => {
	console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_search(
	db='examples',
	ddoc='cities-designdoc',
	index='cities',
	query='lat:\\[0+TO+90\\]',
	sort=['<distance,lon,lat,-74.0059,40.7127,km>']
).get_result()
print(response)

postSearchOptions := service.NewPostSearchOptions(
	"examples",
	"cities-designdoc",
	"cities",
	"lat:\\[0+TO+90\\]",
)
postSearchOptions.SetSort([]string{"<distance,lon,lat,-74.0059,40.7127,km>"})
searchResult, _, err := service.PostSearch(postSearchOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(searchResult, "", "  ")
fmt.Println(string(b))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

Die folgende (gekürzte) Beispielantwort enthält eine Liste mit Städten der nördlichen Hemisphäre, die nach Entfernung zu New York sortiert sind:

{
    "total_rows": 205,
    "bookmark": "g1A...XIU",
    "rows": [
        {
            "id": "city180",
            "order": [
                8.530665755719783,
                18
            ],
            "fields": {
                "city": "New York, N.Y.",
                "lat": 40.78333333333333,
                "lon": -73.96666666666667
            }
        },
        {
            "id": "city177",
            "order": [
                13.756343205985946,
                17
            ],
            "fields": {
                "city": "Newark, N.J.",
                "lat": 40.733333333333334,
                "lon": -74.16666666666667
            }
        },
        {
            "id": "city178",
            "order": [
                113.53603438866077,
                26
            ],
            "fields": {
                "city": "New Haven, Conn.",
                "lat": 41.31666666666667,
                "lon": -72.91666666666667
            }
        }
    ]
}

Suchbegriffe hervorheben

Manchmal ist es nützlich, den Kontext abzurufen, in dem ein Suchbegriff erwähnt wurde, sodass Benutzern Ergebnisse mit hervorgehobenen Suchbegriffen angezeigt werden können.

Zum Abrufen von Ergebnisse mit Hervorhebungen fügen Sie der Suchabfrage den Parameter highlight_fields hinzu. Geben Sie die Feldnamen an, für die Sie Auszüge zurückgeben wollen, in denen der Suchbegriff hervorgehoben wird.

Ein Suchbegriff wird standardmäßig in <em>-Tags gesetzt, um ihn hervorzuheben, jedoch kann die Hervorhebung mit den Parametern highlights_pre_tag und highlights_post_tag überschrieben werden.

Die Länge der Fragmente beträgt standardmäßig 100 Zeichen. Mithilfe des Parameters highlights_size kann eine andere Länge angefordert werden.

Der Parameter highlights_number steuert die Anzahl der Fragmente, die zurückgegeben werden. Der Standardwert ist 1.

In der Antwort wird ein Feld highlights hinzugefügt, das je ein Unterfeld pro Feldname enthält.

Für jedes Feld empfangen Sie ein Array von Fragmenten, in denen der Suchbegriff hervorgehoben ist.

Damit die Hervorhebung funktioniert, müssen Sie das Feld im Index mit der Option store: true speichern.

Beispiel für die Verwendung von HTTP, um eine Suche mit aktivierter Hervorhebung durchzuführen:

GET /movies/_design/searches/_search/movies?q=movie_name:Azazel&highlight_fields=["movie_name"]&highlight_pre_tag=" "&highlight_post_tag=" "&highlights_size=30&highlights_number=2 HTTP/1.1
HOST: $ACCOUNT.cloudant.com
Authorization: ...

Im folgenden Beispiel sehen Sie die Befehlszeile für die Suche mit aktivierter Hervorhebung:

curl "https://$ACCOUNT.cloudant.com/movies/_design/searches/_search/movies?q=\"movie_name:Azazel\"&highlight_fields=\[\"movie_name\"\]&highlight_pre_tag=\" \"&highlight_post_tag=\" \"&highlights_size=30&highlights_number=2" \
	-X GET

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostSearchOptions;
import com.ibm.cloud.cloudant.v1.model.SearchResult;
import java.util.Arrays;
Cloudant service = Cloudant.newInstance();
PostSearchOptions searchOptions = new PostSearchOptions.Builder()
    .db("movies")
    .ddoc("searches")
    .index("movies")
    .query("movie_name:Azazel")
    .highlightFields(Arrays.asList("[\"movie_name\"]"))
    .highlightPreTag("\" \"")
    .highlightPostTag("\" \"")
    .highlightSize(30)
    .highlightNumber(2)
    .build();
SearchResult response =
    service.postSearch(searchOptions).execute()
        .getResult();
System.out.println(response);

import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.postSearch({
	db: 'movies',
	ddoc: 'searches',
	index: 'movies',
	query: 'movie_name:Azazel',
	highlightFields: ['["movie_name"]'],
	highlightPreTag: '" "',
	highlightPostTag: '" "',
	highlightSize: 30,
	highlightNumber: 2
}).then(response => {
	console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_search(
	db='movies',
	ddoc='searches',
	index='movies',
	query='movie_name:Azazel',
	highlight_fields=['["movie_name"]'],
	highlight_pre_tag='" "',
	highlight_post_tag='" "',
	highlight_size=30,
	highlight_number=2
).get_result()
print(response)

postSearchOptions := service.NewPostSearchOptions(
	"movies",
	"searches",
	"movies",
	"movie_name:Azazel",
)
postSearchOptions.SetHighlightFields([]string{"[\"movie_name\"]"})
postSearchOptions.SetHighlightPreTag("\" \"")
postSearchOptions.SetHighlightPostTag("\" \"")
postSearchOptions.SetHighlightSize(30)
postSearchOptions.SetHighlightNumber(2)
searchResult, _, err := service.PostSearch(postSearchOptions)
if err != nil {
	panic(err)
}
b, _ := json.MarshalIndent(searchResult, "", "  ")
fmt.Println(string(b))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

Beispiel für die Ergebnisse einer Suche mit Hervorhebungen:

{
    "highlights": {
        "movie_name": [
            " on the Azazel Orient Express",
            " Azazel manuals, you"
        ]
    }
}

Metadaten für Suchindizes

Zum Abrufen von Informationen zu einem Suchindex senden Sie eine GET-Anforderung an den Endpunkt _search_info, wie im folgenden Beispiel gezeigt. DDOC verweist auf das Entwurfsdokument, das den Index enthält, und INDEX_NAME ist der Name des Index.

Beispiel für die Verwendung von HTTP, um Metadaten für einen Suchindex anzufordern:

GET /$DATABASE/_design/$DDOC/_search_info/$INDEX_NAME HTTP/1.1

Beispiel für die Verwendung der Befehlszeile, um Metadaten für einen Suchindex anzufordern:

curl "https://$ACCOUNT.cloudant.com/$DATABASE/_design/$DDOC/_search_info/$INDEX_NAME" \
     -X GET

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.GetSearchInfoOptions;
import com.ibm.cloud.cloudant.v1.model.SearchInfoResult;
Cloudant service = Cloudant.newInstance();
GetSearchInfoOptions infoOptions =
    new GetSearchInfoOptions.Builder()
        .db("<db-name>")
        .ddoc("<ddoc>")
        .index("<index-name>")
        .build();
SearchInfoResult response =
    service.getSearchInfo(infoOptions).execute()
        .getResult();
System.out.println(response);

import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.getSearchInfo({
	db: '<db-name>',
	ddoc: '<ddoc>',
	index: '<index-name>'
}).then(response => {
	console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.get_search_info(
	db='<db-name>',
	ddoc='<ddoc>',
	index='<index-name>'
).get_result()
print(response)

getSearchInfoOptions := service.NewGetSearchInfoOptions(
	"<db-name>",
	"<ddoc>",
	"<index-name>",
)
searchInfoResult, _, err := service.GetSearchInfo(getSearchInfoOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(searchInfoResult, "", "  ")
fmt.Println(string(b))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

Die Antwort enthält Informationen zu Ihrem Index, wie zum Beispiel die Anzahl der Dokumente in dem Index und die Größe des Index auf Platte.

Beispielantwort nach einer Anforderung von Metadaten für einen Suchindex:

{
    "name": "_design/DDOC/INDEX",
    "search_index": {
        "pending_seq": 7125496,
        "doc_del_count": 129180,
        "doc_count": 1066173,
        "disk_size": 728305827,
        "committed_seq": 7125496
    }
}