Comment fonctionne la recherche sur IBM Cloudant

Les définitions de l'index de recherche sont stockées dans les documents de conception sous la forme d'une fonction JavaScript qui est exécutée pour chaque document de la base de données. La fonction définit les attributs qui sont indexés, ceux qui sont stockés dans l'index mais ne sont pas consultables et la manière dont chaque attribut de texte est prétraité avant l'indexation (à l'aide d'un "analyseur" de recherche choisi).

IBM Cloudant les recherches peuvent porter sur l'ensemble de la base de données ou, dans le cas des bases de données partitionnées, sur une seule partition où options.partitioned est true dans le document de conception.

Quand utiliser la recherche IBM Cloudant

IBM Cloudant La recherche est idéale pour :

• Recherche plein texte tenant compte de la langue, recherche par caractères génériques et requêtes simples sur des champs numériques ou textuels.
• Requêtes flexibles sur un ensemble de champs indexés.
• Requêtes géospatiales simples telles que trouver le plus proche ou trouver avec une boîte de délimitation.
• Agrégations de comptage sur des champs individuels dans l'ensemble de résultats - connues sous le nom de "facettes".

Quand ne pas utiliser la recherche IBM Cloudant

Éviter IBM Cloudant Rechercher

• Agrégation (autre que par facettes). Utilisez plutôt Views.

Construire un index de recherche

Pour créer un index de recherche, ajoutez une fonction JavaScript à un document de conception se trouvant dans la base de données. Un index est généré une fois qu'il a traité une demande de recherche ou une fois que le serveur a détecté une mise à jour de document. La fonction index admet les paramètres suivants :

1. Nom de zone : nom de la zone à utiliser lorsque vous interrogez l'index. Si vous associez ce paramètre à la valeur default, cette zone est interrogée si aucune zone n'est spécifiée dans la syntaxe de requête.
2. Données à indexer, par exemple doc.address.country.
3. (Facultatif) Le troisième paramètre inclut les zones suivantes : boost, facet, index et store. Celles-ci sont décrites plus en détail ultérieurement.

Par défaut, une réponse d'index de recherche renvoie 25 lignes. Vous pouvez changer le nombre de lignes qui est renvoyé avec le paramètre limit. Cependant, un résultat défini à partir d'une recherche sera limité à 200 lignes. Chaque réponse inclut une zone bookmark. Vous pouvez inclure la valeur de la zone bookmark dans des requêtes ultérieures pour examiner les réponses.

Vous pouvez interroger l'API avec l'une des méthodes suivantes : URI, tableau de bord IBM Cloudant, curl ou plug-in de navigateur tel que Postman ou RESTClient.

Voici un exemple de document de conception qui définit un index de recherche :

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

Type de partitionnement d'index de recherche

Un index de recherche hérite du type de partitionnement de Zone options.partitioned du document de conception qui le contient.

Fonctions d'index

Si vous tentez d'effectuer l'indexation en utilisant une zone de données qui n'existe pas, l'indexation échoue. Pour éviter ce problème, utilisez une clause de protection appropriée.

Vos fonctions d'indexation s'exécutent dans un environnement à contraintes de mémoire où le document lui-même fait partie de la mémoire utilisée dans cet environnement. La pile et le document de votre code doivent s'insérer dans cette mémoire. La taille des documents ne peut pas dépasser 64 Mo.

Dans un index de recherche, n'indexez pas le même nom de zone avec plusieurs types de données. Si le même nom de zone est indexé avec des types de données différents dans la même fonction d'index de recherche, une erreur peut survenir. Cette erreur se produit lorsque vous interrogez l'index de recherche contenant le champ « was indexed without position data ». Par exemple, n'incluez pas les lignes ci-dessous dans la même fonction d'index de recherche. Ces lignes indexent la zone myfield comme s'il s'agissait de deux types de données différents : sous forme de chaîne "this is a string" et sous forme de nombre 123.

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

La fonction contenue dans la zone d'index est une fonction JavaScript appelée pour chaque document de la base de données. La fonction admet le document comme paramètre, en extrait des données, puis appelle la fonction qui est définie dans la zone index pour indexer ces données.

La fonction index admet trois paramètres, où le troisième paramètre est facultatif.

Le premier paramètre correspond au nom du champ que vous comptez utiliser lors de l'interrogation de l'index, qui est spécifié dans la partie syntaxe Lucene des requêtes suivantes. Voici un exemple de requête contenant ce paramètre :

query=color:red

Le nom de zone Lucene color est le premier paramètre de la fonction index.

Le paramètre query peut être abrégé en q. Ainsi, vous pouvez également écrire la requête comme suit :

q=color:red

Si la valeur spéciale "default" est utilisée lorsque vous définissez le nom, il n'est pas nécessaire de spécifier un nom de zone au moment de la requête. Ainsi, la requête peut être simplifiée :

query=red

Le deuxième paramètre correspond aux données à indexer. Gardez à l'esprit les informations suivantes lorsque vous indexez vos données :

• Ces données doivent correspondre à une chaîne, un nombre ou une valeur booléenne. Les autres types renvoient une erreur depuis l'appel de fonction d'index.
• Si une erreur est renvoyée lorsque votre fonction s'exécute, pour cette raison ou pour toute autre raison, le document n'est pas ajouté à cet index de recherche.

Le troisième paramètre, qui est facultatif, est un objet JavaScript possédant les zones suivantes :

Si vous ne définissez pas le paramètre store, les résultats de données d'index pour le document ne sont pas renvoyés en réponse à une requête.

Voici un exemple de fonction d'index de recherche :

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

Analyseurs

Les analyseurs sont des paramètres qui définissent la façon de reconnaître les termes dans le texte. Pour plus d'informations, voir Analyseurs de recherche.

Ils peuvent être utiles si vous avez besoin d'indexer plusieurs langues.

Le tableau suivant présente une liste d'analyseurs génériques pris en charge par la recherche IBM Cloudant

Voici un exemple de document d'analyseur :

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

Requêtes

Après avoir créé un index de recherche, vous pouvez l'interroger.

• Exécutez une requête de partition avec la demande suivante :

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

• Exécutez une requête globale avec la demande suivante :

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

Spécifiez votre recherche avec le paramètre query.

Voici un exemple qui utilise HTTP pour interroger un index partitionné :

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

Voici un exemple qui utilise la ligne de commande pour interroger un index partitionné :

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

L'exemple précédent de Go requiert le bloc d'importation suivant :

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

Voici un exemple qui utilise HTTP pour interroger un index global :

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

Voici un exemple qui utilise la ligne de commande pour interroger un index global :

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

L'exemple précédent de Go requiert le bloc d'importation suivant :

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
}

Pagination

Utiliser la pagination des signets pour les requêtes de recherche. Pour plus de détails et d'exemples, voir la rubrique de la documentation de l'API intitulée Paging on search index queries(pagination sur les requêtes d'index de recherche).

Syntaxe de requête

La syntaxe des requêtes de recherche d' IBM Cloudant s repose sur la syntaxe de Lucene. Les requêtes de recherche sont au format name:value sauf si le nom est omis, auquel cas elles utilisent la zone par défaut, comme illustré dans les exemples suivants :

Voici des exemples d'expression de requête de recherche :

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

Les requêtes sur plusieurs zones peuvent être combinées logiquement et les groupes et zones peuvent être regroupés plus précisément. Les opérateurs logiques disponibles sont sensibles à la casse ; il s'agit de AND, +, OR, NOT et -. Des requêtes de plage peuvent être exécutées sur des chaînes ou des nombres.

Si vous voulez effectuer une recherche avec correspondance partielle, vous pouvez exécuter une requête avec ~ pour rechercher des termes similaires au terme de recherche. Par exemple, look~ donne les expressions book et took.

Si les limites supérieures d'une requête de plage sont des chaînes contenant uniquement des chiffres, elles sont traitées comme des nombres et non comme des chaînes. Par exemple, si vous effectuez une recherche en utilisant la requête mod_date:["20170101" TO "20171231"], les résultats incluent les documents pour lesquels mod_date est compris entre les valeurs numériques 20170101 et 20171231, et non entre les chaînes "20170101" et "20171231".

Vous pouvez modifier l'importance d'un terme de recherche en ajoutant ^ et un nombre positif. Cette altération crée des correspondances qui contiennent le terme de façon plus ou moins pertinente, proportionnellement à la puissance de la valeur de pondération. La valeur par défaut est 1, ce qui signifie que la puissance de la correspondance n'est ni augmentée ni diminuée. La valeur décimale 0 ou 1 diminue l'importance et affaiblit la correspondance. Une valeur supérieure à 1 augmente l'importance et renforce la correspondance.

Les recherches de caractères génériques sont prises en charge pour les recherches de caractères simples (?) et multiples (*). Par exemple : dat? correspondrait à date et data, et dat* correspondrait à date,data,database, et dates. Les caractères génériques doivent être situés après le terme de recherche.

Utilisez *:* pour renvoyer tous les résultats.

Les ensembles de résultats des recherches ne peuvent pas contenir plus de 200 lignes et en contiennent 25 par défaut. Vous pouvez changer le nombre de lignes renvoyées avec le paramètre limit.

Si la requête de recherche ne spécifie pas l'argument "group_field", la réponse inclut un signet. Si ce signet est fourni ultérieurement en tant que paramètre d'URL, la réponse ignore les lignes qui ont déjà été envoyées, ce qui accélère et facilite l'obtention de l'ensemble de résultats suivant.

La réponse n'inclut jamais de signet si le paramètre "group_field" est inclus dans la requête de recherche.

Les options group_field, group_limit et group_sort ne sont disponibles que lorsque vous effectuez des requêtes globales.

Vous devez mettre en échappement les caractères suivants si vous voulez les rechercher :

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

Pour échapper à l'un de ces caractères, insérez avant une barre oblique inversée (\).

La réponse à une requête de recherche inclut une zone order pour chaque résultat. La zone order est un tableau dans lequel le premier élément est la ou les zones spécifiées dans le paramètre sort. Si aucun paramètre « sort » n'est inclus dans la requête, alors le champ « order » contient le score de pertinence Lucene. Si vous utilisez la fonction de sort by distance comme décrit dans Recherches géographiques, le premier élément est la distance à partir d'un point. La distance est mesurée en kilomètres ou miles.

Le deuxième élément dans le tableau de tri peut être ignoré. Il est utilisé pour le traitement des incidents uniquement.

Création de facettes

IBM Cloudant Search prend également en charge la recherche par facettes, qui permet une reconnaissance rapide et facile des informations agrégées sur les correspondances. Vous pouvez faire correspondre tous les documents à l'aide de la syntaxe de requête ?q=*:* spéciale et utiliser les facettes renvoyées pour affiner votre requête. Afin d'indiquer qu'une zone doit être indexée pour les requêtes par facettes, définissez {"facet": true} dans ses options.

Voici un exemple de requête de recherche qui spécifie que la recherche par facettes est activée :

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

Pour que vous puissiez utiliser des facettes, tous les documents de l'index doivent inclure toutes les zones pour lesquelles les facettes sont activées. Si vos documents n'incluent pas toutes les zones, une erreur bad_request s'affiche et indique que la zone field_name n'existe pas. Si chacun des documents ne contient pas toutes les zones pour les facettes, créez des index distincts pour chaque zone. Si vous ne créez pas d'index distinct pour chaque zone, vous devez inclure uniquement des documents contenant toutes les zones. Vérifiez que les zones existent dans chaque document à l'aide d'une instruction if unique.

Voici un exemple d'instruction if permettant de vérifier que les zones requises existent dans chaque document :

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

Recherches géographiques

En plus de la recherche par contenu de zones de texte, vous pouvez également trier vos résultats en fonction de leur distance par rapport à une coordonnée géographique.

Pour trier vos résultats ainsi, vous devez indexer deux zones numériques représentant la longitude et la latitude.

Vous pouvez ensuite effectuer une requête à l'aide de la zone de tri spéciale <distance...>, ce qui prend cinq paramètres :

• Nom de la zone de longitude : nom de votre zone de longitude (mylon dans l'exemple).
• Nom de la zone de latitude : nom de votre zone de latitude (mylat dans l'exemple).
• Longitude de l'origine : longitude de l'emplacement en fonction duquel vous voulez effectuer un tri selon la distance.
• Latitude de l'origine : latitude de l'emplacement en fonction duquel vous voulez effectuer un tri selon la distance.
• Unités : les unités pouvant être utilisées sont km pour kilomètres et mi pour miles. La distance est renvoyée dans la zone de tri.

Vous pouvez associer le tri par distance à n'importe quelle autre requête de recherche, telle que les recherches par plage de latitude et de longitude, ou les requêtes portant sur des informations non géographiques.

Ainsi, vous pouvez effectuer une recherche dans une boîte de délimitation et restreindre la recherche à l'aide de critères supplémentaires.

Voici un exemple de données géographiques :

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

Voici un exemple de document de conception incluant un index de recherche pour les données géographiques :

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

Voici un exemple utilisant HTTP pour une requête qui trie les villes de l'hémisphère nord en fonction de leur distance de 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

Voici un exemple utilisant la ligne de commande pour une requête qui trie les villes de l'hémisphère nord en fonction de leur distance de 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))

L'exemple précédent de Go requiert le bloc d'importation suivant :

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

Voici un exemple de réponse (abrégée) incluant la liste des villes de l'hémisphère nord qui sont triées en fonction de leur distance de 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
            }
        }
    ]
}

Mise en évidence des termes de recherche

Parfois, il est utile d'obtenir le contexte dans lequel un terme de recherche a été mentionné afin de pouvoir afficher des résultats davantage mis en évidence pour un utilisateur.

Pour obtenir des résultats davantage mis en évidence, ajoutez le paramètre highlight_fields à la requête de recherche. Spécifiez les noms de zone pour lesquels vous voulez obtenir des extraits, dans lesquels le terme de recherche est mis en évidence.

Par défaut, le terme de recherche est placé dans les balises <em> pour le mettre en évidence, mais la mise en évidence peut être remplacée à l'aide des paramètres highlights_pre_tag et highlights_post_tag.

Par défaut, la longueur des fragments est de 100 caractères. Vous pouvez demander une longueur différente avec le paramètre highlights_size.

Le paramètre highlights_number contrôle le nombre de fragments renvoyés. Sa valeur par défaut est 1.

Dans la réponse, la zone highlights est ajoutée, avec une sous-zone par nom de zone.

Pour chaque zone, vous obtenez un tableau de fragments dans lesquels le terme de recherche est mis en évidence.

Pour que la mise en évidence fonctionne, stockez la zone dans l'index à l'aide de l'option store: true.

Voici un exemple qui utilise HTTP pour effectuer une recherche avec mise en évidence activée :

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

Voici un exemple illustrant la ligne de commande permettant d'effectuer une recherche avec la mise en évidence activée :

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

L'exemple précédent de Go requiert le bloc d'importation suivant :

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

Voici un exemple de résultats de recherche mis en évidence :

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

Métadonnées d'index de recherche

Pour extraire des informations sur un index de recherche, vous envoyez une demande GET au noeud final _search_info, conformément à l'exemple ci-après. DDOC référence un document de conception qui inclut l'index et INDEX_NAME est le nom de l'index.

Voici un exemple qui utilise HTTP pour demander des métadonnées d'index de recherche :

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

Voici un exemple qui utilise la ligne de commande pour demander des métadonnées d'index de recherche :

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

L'exemple précédent de Go requiert le bloc d'importation suivant :

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

La réponse inclut des informations sur l'index, comme le nombre de documents dans l'index et la taille de l'index sur le disque.

Voici un exemple de réponse suite à la demande de métadonnées d'index de recherche :

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