Come funziona la ricerca su IBM Cloudant

Le definizioni degli indici di ricerca sono memorizzate nei documenti di progettazione sotto forma di una funzione JavaScript che viene eseguita su ogni documento del database. La funzione definisce quali attributi sono indicizzati, quali sono memorizzati nell'indice ma non sono ricercabili e come ogni attributo di testo viene pre-elaborato prima dell'indicizzazione (utilizzando un "analizzatore" di ricerca scelto).

IBM Cloudant le ricerche possono agire sull'intero database o, per i database partizionati, su una singola partizione dove options.partitioned è true nel documento di progettazione.

Quando utilizzare la ricerca su IBM Cloudant

IBM Cloudant La ricerca è ideale per:

• Ricerca full-text consapevole della lingua, ricerche con caratteri jolly e semplici query di intervallo su campi numerici o di testo.
• Query flessibili su un insieme di campi indicizzati.
• Semplici query geospaziali, come Trova il più vicino o Trova con un riquadro di delimitazione.
• Aggregazioni di conteggio su singoli campi all'interno dell'insieme di risultati, note come "faceting".

Quando non utilizzare la ricerca su IBM Cloudant

Evitare IBM Cloudant Ricerca di

• Aggregazione (diversa dalla sfaccettatura). Utilizzare invece le viste.

Creare un indice di ricerca

Per creare un indice di ricerca, si aggiunge una funzione JavaScript a un documento di design nel database. Un indice si costruisce dopo l'elaborazione di una richiesta di ricerca o dopo che il server rileva un aggiornamento di un documento. La funzione index accetta i seguenti parametri:

1. Nome del campo - Il nome del campo che si desidera utilizzare quando si interroga l'indice. Se si imposta questo parametro su default, il campo viene interrogato se non è specificato alcun campo nella sintassi della query.
2. Dati che si desidera indicizzare, ad esempio doc.address.country.
3. (Facoltativo) Il terzo parametro comprende i seguenti campi: boost, facet, index, e store. Questi campi sono descritti in dettaglio più avanti.

Per impostazione predefinita, la risposta di un indice di ricerca restituisce 25 righe. Il numero di righe restituite può essere modificato utilizzando il parametro limit. Tuttavia, il set di risultati di una ricerca è limitato a 200 righe. Ogni risposta include un campo bookmark. È possibile includere il valore del campo bookmark nelle query successive per esaminare le risposte.

È possibile interrogare l'API utilizzando uno dei seguenti metodi: URI, IBM Cloudant Dashboard, curl o un plug-in del browser, come Postman o RESTClient.

Si veda il seguente esempio di documento di progettazione che definisce un indice di ricerca:

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

Tipo di partizionamento dell'indice di ricerca

Un indice di ricerca eredita il tipo di partizionamento dal options.partitioned campo del documento di progettazione in cui è contenuto.

Funzioni dell'indice

Se si tenta di indicizzare utilizzando un campo dati che non esiste, l'operazione fallisce. Per evitare questo problema, utilizzare una clausola di protezione appropriata.

Le funzioni di indicizzazione operano in un ambiente a memoria limitata, dove il documento stesso costituisce una parte della memoria utilizzata. Lo stack e il documento del codice devono rientrare in questa memoria. I documenti sono limitati a una dimensione massima di 64 MB.

All'interno di un indice di ricerca, non indicizzare lo stesso nome di campo con più di un tipo di dati. Se lo stesso nome di campo viene indicizzato con tipi di dati diversi nella stessa funzione di indice di ricerca, potrebbe verificarsi un errore. Questo errore si verifica quando si interroga l'indice di ricerca che contiene il campo was indexed without position data. Ad esempio, non includere entrambe le righe nella stessa funzione di indice di ricerca. Queste righe indicizzano il campo myfield come due tipi di dati diversi, una stringa "this is a string" e un numero 123.

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

La funzione contenuta nel campo dell'indice è una funzione JavaScript che viene richiamata per ogni documento del database. La funzione prende il documento come parametro, estrae alcuni dati da esso e poi chiama la funzione definita nel campo index per indicizzare tali dati.

La funzione index accetta tre parametri, di cui il terzo è opzionale.

Il primo parametro è il nome del campo che si intende usare quando si interroga l'indice, che viene specificato nella parte della sintassi di Lucene delle query successive. Un esempio è rappresentato dalla seguente query:

query=color:red

Il nome del campo Lucene color è il primo parametro della funzione index.

Il parametro query può essere abbreviato in q, quindi un altro modo di scrivere la query è mostrato nell'esempio seguente.

q=color:red

Se si usa il valore speciale "default" quando si definisce il nome, non è necessario specificare il nome del campo al momento della query. L'effetto è che la query può essere semplificata:

query=red

Il secondo parametro è il dato da indicizzare. Tenere presente le seguenti informazioni quando si indicizzano i dati:

• Questi dati devono essere solo una stringa, un numero o un booleano. Altri tipi restituiscono un errore dalla chiamata alla funzione indice.
• Se durante l'esecuzione della funzione viene restituito un errore, per questo o altri motivi, il documento non viene aggiunto all'indice di ricerca.

Il terzo parametro, opzionale, è un oggetto JavaScript con i seguenti campi:

Se non si imposta il parametro store, i risultati dei dati dell'indice per il documento non vengono restituiti in risposta a una query.

Vedere il seguente esempio di funzione indice di ricerca:

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.
	...
}

Analizzatori

Gli analizzatori sono impostazioni che definiscono come riconoscere i termini all'interno del testo. Per ulteriori informazioni, vedere Analizzatori di ricerca.

Gli analizzatori possono essere utili se è necessario indicizzare più lingue.

La tabella seguente mostra un elenco di analizzatori generici supportati dalla ricerca IBM Cloudant:

Si veda il seguente esempio di documento di analisi:

{
	"_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"
	]
}

Query

Dopo aver creato un indice di ricerca, è possibile interrogarlo.

• Eseguire una query di partizione utilizzando la seguente richiesta:

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

• Eseguire una query globale utilizzando la seguente richiesta:

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

Specificare la ricerca utilizzando il parametro query.

Vedere l'esempio seguente che utilizza HTTP per interrogare un indice partizionato:

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

Si veda il seguente esempio che utilizza la riga di comando per interrogare un indice partizionato:

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))

Il precedente esempio di Go richiede il seguente blocco di importazione:

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

Vedi l'esempio seguente che utilizza HTTP per interrogare un indice globale:

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

Si veda il seguente esempio che utilizza la riga di comando per interrogare un indice globale:

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))

Il precedente esempio di Go richiede il seguente blocco di importazione:

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
}

Paginazione

Utilizzare la paginazione dei segnalibri per le query di ricerca. Per dettagli ed esempi specifici, consultare l'argomento della documentazione API Paging on search index queries.

Sintassi della query

La sintassi delle query di ricerca IBM Cloudant è basata sulla sintassi di Lucene. Le query di ricerca assumono la forma di name:value, a meno che il nome non venga omesso, in tal caso utilizzano il campo predefinito, come mostrato negli esempi seguenti:

Si vedano i seguenti esempi di espressioni di query di ricerca:

// 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
*:*

Le query su più campi possono essere combinate logicamente, e i gruppi e i campi possono essere ulteriormente raggruppati. Gli operatori logici disponibili distinguono tra maiuscole e minuscole e sono AND,+,OR,NOT e - Le query di intervallo possono essere eseguite su stringhe o numeri.

Se si desidera una ricerca confusa, è possibile eseguire una query con ~ per trovare termini simili al termine di ricerca. Ad esempio, look~ trova i termini book e took.

Se i limiti superiori di una query di intervallo sono entrambi stringhe che contengono solo cifre numeriche, i limiti vengono trattati come numeri e non come stringhe. Ad esempio, se si effettua una ricerca utilizzando la query mod_date:["20170101" TO "20171231"], i risultati includono i documenti per i quali mod_date è compreso tra i valori numerici 20170101 e 20171231, non tra le stringhe "20170101" e "20171231".

È possibile modificare l'importanza di un termine di ricerca aggiungendo ^ e un numero positivo. Questa alterazione crea corrispondenze che contengono il termine più o meno rilevante, proporzionale alla potenza del valore di boost. Il valore predefinito è 1, che significa nessun aumento o diminuzione della forza della corrispondenza. Un valore decimale di 0 - 1 riduce l'importanza, rende la forza della corrispondenza più debole. Un valore maggiore di uno aumenta l'importanza, che rende più forte la forza della corrispondenza.

Sono supportate le ricerche con caratteri jolly, per ricerche con caratteri singoli ?) e multipli *). Ad esempio, dat? corrisponderebbe a date e data, mentre dat* corrisponderebbe a date,data,database, e dates. I caratteri jolly devono essere inseriti dopo il termine di ricerca.

Utilizzare *:* per restituire tutti i risultati.

I set di risultati delle ricerche sono limitati a 200 righe, e restituiscono 25 righe per impostazione predefinita. Il numero di righe che vengono restituite può essere cambiato utilizzando il parametro limit.

Se la query di ricerca non specifica l'argomento "group_field", la risposta include un segnalibro. Se questo segnalibro viene fornito in seguito come parametro di tipo " URL ", la risposta salta le righe già visualizzate, rendendo più facile e veloce ottenere la serie di risultati successiva.

La risposta non include mai un segnalibro se il parametro "group_field" è incluso nella query di ricerca.

Le opzioni group_field, group_limit e group_sort sono disponibili solo quando si eseguono query globali.

I seguenti caratteri richiedono l'escape se si vuole effettuare una ricerca su di essi:

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

Per sfuggire a uno di questi caratteri, utilizzare un carattere backslash precedente \).

La risposta a una query di ricerca include un campo order per ciascuno dei risultati. Il campo order è un array in cui il primo elemento è il campo o i campi specificati nel parametro nel parametro sort. Se nessun parametro sort è incluso nella query, il campo order contiene il punteggio di rilevanza di Lucene. Se si utilizza la funzione sort by distance come descritto in Ricerche geografiche, il primo elemento è la distanza da un punto. La distanza viene misurata utilizzando i chilometri o le miglia.

Il secondo elemento dell'array di ordini può essere ignorato. Viene utilizzato esclusivamente a scopo di risoluzione dei problemi.

Sfaccettatura

IBM Cloudant La ricerca supporta anche la ricerca sfaccettata, che consente di scoprire informazioni aggregate sulle corrispondenze in modo rapido e semplice. È possibile trovare una corrispondenza tra tutti i documenti utilizzando la sintassi speciale ?q=*:* della query, e utilizzare le sfaccettature restituite per affinare la query. Per indicare che un campo deve essere indicizzato per le query sfaccettate, impostare {"facet": true} nelle opzioni.

Vedere il seguente esempio di query di ricerca, specificando che la ricerca sfaccettata è abilitata:

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

Per utilizzare le faccette, tutti i documenti dell'indice devono includere tutti i campi per i quali sono state attivate le faccette. Se i documenti non includono tutti i campi, si riceve un errore con il seguente motivo: bad_request Il file field_name non esiste" Se ogni documento non contiene tutti i campi per le faccette, creare indici separati per ogni campo. Se non si creano indici separati per ogni campo, è necessario includere solo i documenti che contengono tutti i campi. Verificare che i campi esistano in ogni documento utilizzando una singola istruzione if.

Vedere il seguente esempio di dichiarazione if per verificare che i campi richiesti esistano in ogni documento:

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
        }
    }
}

Ricerche geografiche

Oltre alla ricerca in base al contenuto dei campi testuali, è possibile ordinare i risultati in base alla distanza da una coordinata geografica.

Per ordinare i risultati in questo modo, è necessario indicizzare due campi numerici che rappresentano la longitudine e la latitudine.

È quindi possibile eseguire la query utilizzando il campo speciale <distance...> sort, che richiede cinque parametri:

• Nome del campo longitudine - Il nome del campo longitudine mylon nell'esempio).
• Nome del campo latitudine - Il nome del campo latitudine mylat nell'esempio).
• Longitudine di origine - La longitudine del luogo da cui si desidera ordinare per distanza.
• Latitudine di origine - La latitudine del luogo da cui si desidera ordinare per distanza.
• Unità - Le unità da utilizzare includono km per i chilometri o mi per le miglia. La distanza viene restituita nel campo dell'ordine.

È possibile combinare l'ordinamento per distanza con qualsiasi altra query di ricerca, come la ricerca per intervallo di latitudine e longitudine, o query che coinvolgono informazioni non geografiche.

In questo modo, è possibile effettuare la ricerca in un'area delimitata, e restringere la ricerca con altri criteri.

Si veda il seguente esempio di dati geografici:

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

Si veda l'esempio seguente di un documento di progettazione che include un indice di ricerca per i dati geografici:

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});
    }
}

Si veda il seguente esempio che utilizza HTTP per una query che ordina le città dell'emisfero settentrionale in base alla loro distanza da New York:

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

Si veda il seguente esempio che utilizza la riga di comando per una query che ordina le città dell'emisfero settentrionale in base alla loro distanza da New York:

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))

Il precedente esempio di Go richiede il seguente blocco di importazione:

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

Si veda il seguente esempio di risposta (abbreviata) che include un elenco di città dell'emisfero settentrionale ordinate in base alla distanza da New York:

{
    "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
            }
        }
    ]
}

Evidenziare i termini di ricerca

A volte è utile ottenere il contesto in cui un termine di ricerca è stato menzionato in modo da poter mostrare all'utente dei risultati più enfatizzati.

Per ottenere risultati più enfatizzati, aggiungere il parametro highlight_fields alla query di ricerca. Specificare i nomi dei campi di cui si desidera ottenere gli estratti, con il termine di ricerca evidenziato.

Per impostazione predefinita, il termine di ricerca viene inserito nei tag <em> per evidenziarlo, ma l'evidenziazione può essere sovrascritta utilizzando i parametri highlights_pre_tag e highlights_post_tag.

La lunghezza dei frammenti è di 100 caratteri per impostazione predefinita. È possibile richiedere una lunghezza diversa con il parametro highlights_size.

Il parametro highlights_number controlla il numero di frammenti restituiti, e il valore predefinito è 1.

Nella risposta, viene aggiunto un campo highlights, con un sottocampo per ogni nome di campo.

Per ogni campo, riceve un array di frammenti con il termine di ricerca evidenziato.

Affinché l'evidenziazione funzioni, memorizzare il campo nell'indice usando l'opzione store: true.

Vedi l'esempio seguente che utilizza HTTP per cercare con l'evidenziazione abilitata:

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: ...

Si veda l'esempio seguente che mostra la riga di comando per la ricerca con l'evidenziazione abilitata:

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))

Il precedente esempio di Go richiede il seguente blocco di importazione:

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

Si veda il seguente esempio di risultati di ricerca evidenziati:

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

Metadati dell'indice di ricerca

Per recuperare informazioni su un indice di ricerca, si invia una GET richiesta all'endpoint _search_info, come mostrato nell'esempio seguente. DDOC si riferisce al documento di progettazione che include l'indice, e INDEX_NAME è il nome dell'indice.

Vedi l'esempio seguente che utilizza HTTP per richiedere i metadati dell'indice di ricerca:

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

Si veda il seguente esempio che utilizza la riga di comando per richiedere i metadati dell'indice di ricerca:

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))

Il precedente esempio di Go richiede il seguente blocco di importazione:

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

La risposta include informazioni sull'indice, come il numero di documenti presenti nell'indice e la dimensione dell'indice su disco.

Vedere il seguente esempio di risposta dopo aver richiesto i metadati dell'indice di ricerca:

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