Cómo funciona la búsqueda en IBM Cloudant

Las definiciones de los índices de búsqueda se almacenan en documentos de diseño en forma de una función JavaScript que se ejecuta contra cada documento de la base de datos. La función define qué atributos se indexan, cuáles se almacenan en el índice pero no se pueden buscar y cómo se preprocesa cada atributo de texto antes de la indexación (utilizando un "analizador" de búsqueda elegido).

IBM Cloudant las búsquedas pueden actuar sobre toda la base de datos o, en el caso de bases de datos particionadas, sobre una única partición, donde options.partitioned es true en el documento de diseño.

Cuándo utilizar la búsqueda IBM Cloudant

IBM Cloudant La búsqueda es ideal para:

• Búsqueda de texto completo en función del idioma, búsquedas con comodines y consultas de rango simple en campos numéricos o de texto.
• Consultas flexibles sobre un conjunto de campos indexados.
• Consultas geoespaciales sencillas como encontrar lo más cercano o encontrar con un cuadro delimitador.
• Contar agregaciones en campos individuales dentro del conjunto de resultados, lo que se conoce como "faceting".

Cuándo no utilizar la búsqueda IBM Cloudant

Evite IBM Cloudant Buscar

• Agregación (distinta del facetado). Utilice Vistas en su lugar.

Crear un índice de búsqueda

Para crear un índice de búsqueda, añada una función JavaScript a un documento de diseño en la base de datos. Se crea un índice después de que se procese una solicitud de búsqueda o después de que el servidor detecte una actualización en el documento. La función index toma los parámetros siguientes:

1. Nombre de campo: el nombre del campo que desea utilizar cuando consulte el índice. Si establece este parámetro en default, este campo se consulta si no se especifica ningún campo en la sintaxis de consulta.
2. Datos que desea indexar, por ejemplo doc.address.country.
3. (Opcional) El tercer parámetro incluye los campos siguientes: boost, facet, index y store. Estos campos se describen con más detalle más adelante.

De forma predeterminada, una respuesta de índice de búsqueda devuelve 25 filas. El número de filas que se devuelve se puede modificar con el parámetro limit. Sin embargo, un conjunto de resultados de una búsqueda está limitado a 200 filas. Cada respuesta incluye un campo bookmark. Puede incluir el valor del campo bookmark en consultas posteriores para ver las respuestas.

Puede consultar la API con uno de los siguientes métodos: URI, panel de control de IBM Cloudant, curl o plugin de navegador, como Postman o RESTClient.

Consulte el siguiente documento de diseño de ejemplo que define un índice de búsqueda:

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

Tipo de particionamiento del índice de búsqueda

Un índice de búsqueda hereda el tipo de particionamiento del campo options.partitioned del documento de diseño que lo contiene.

Funciones de índice

Si intenta indexar mediante un campo de datos que no existe, la operación falla. Para evitar este problema, utilice una cláusula de protección adecuada.

Las funciones de indexación operan en un entorno con restricciones de memoria en el que el propio documento forma parte de la memoria que se utiliza en dicho entorno. La pila de código y el documento deben caber dentro de esta memoria. Los documentos están limitados a un tamaño máximo de 64 MB.

Dentro de un índice de búsqueda, no indexe el mismo nombre de campo con más de un tipo de datos. Si indexa el mismo nombre de campo con distintos tipos de datos en la misma función de índice de búsqueda, es posible que reciba un error. Este error se produce al consultar el índice de búsqueda que indica que el campo es « was indexed without position data ». Por ejemplo, no incluya estas dos líneas en la misma función de índice de búsqueda. Estas líneas indexan el campo myfield como dos tipos de datos diferentes, una serie "this is a string" y un número 123.

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

La función contenida en el campo de índice es una función JavaScript que se invoca para cada documento de la base de datos. La función toma el documento como un parámetro, extrae de este algunos datos y luego llama a la función definida en el campo index para indexar dichos datos.

La función index toma tres parámetros, donde el tercer parámetro es opcional.

El primer parámetro es el nombre del campo que se pretende utilizar al consultar el índice, el cual se especifica en la parte de sintaxis de Lucene de las consultas posteriores. En la consulta siguiente puede ver un ejemplo:

query=color:red

El nombre del campo Lucene color es el primer parámetro de la función index.

El parámetro query se puede abreviar como q, por lo que esta es otra forma de escribir la consulta:

q=color:red

Si se utiliza el valor especial "default" al definir el nombre, no tiene que especificar un nombre de campo en el momento de la consulta. El efecto es que la consulta se puede simplificar:

query=red

El segundo parámetro son los datos que se van a indexar. Tenga en cuenta la siguiente información cuando indexe los datos:

• Estos datos deben ser solo una serie, un número o un valor booleano. Otros tipos devuelven un error de la llamada de función de índice.
• Si se devuelve un error cuando la función está en ejecución, por este o por otro motivo, el documento no se añade a dicho índice de búsqueda.

El tercer parámetro, opcional, es un objeto JavaScript con los campos siguientes:

Si no define el parámetro store, los resultados de los datos de índice del documento no se devuelven como respuesta a una consulta.

Consulte la siguiente función de índice de búsqueda de ejemplo:

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

Analizadores

Los analizadores son valores que definen cómo reconocer términos dentro del texto. Para más información, véase Analizadores de búsqueda.

Los analizadores pueden resultar de ayuda si necesita indexar varios idiomas.

La siguiente tabla muestra una lista de analizadores genéricos compatibles con la búsqueda IBM Cloudant:

Consulte el siguiente documento de analizador de ejemplo:

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

Consultas

Después de crear un índice de búsqueda, puede consultarlo.

• Ejecute una consulta de partición con la solicitud siguiente:

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

• Ejecute una consulta global con la solicitud siguiente:

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

Especifique la búsqueda mediante el parámetro query.

Consulte el ejemplo siguiente que utiliza HTTP para consultar un índice particionado:

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

Consulte el ejemplo siguiente que utiliza la línea de mandatos para consultar un índice particionado:

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

El ejemplo Go anterior requiere el siguiente bloque de importación:

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

Consulte el ejemplo siguiente que utiliza HTTP para consultar un índice 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

Consulte el ejemplo siguiente que utiliza la línea de mandatos para consultar un índice 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))

El ejemplo Go anterior requiere el siguiente bloque de importación:

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
}

Paginación

Utilice la paginación de marcadores para las consultas de búsqueda. Para obtener detalles específicos y ejemplos, consulte el tema de la documentación de la API Paging on search index queries.

Sintaxis de consulta

La sintaxis de las consultas de búsqueda de IBM Cloudant se basa en la sintaxis de Lucene. Las consultas de búsqueda toman la forma name:value a menos que se omita el nombre, en cuyo caso utilizan el campo predeterminado, tal como se muestra en los ejemplos siguientes:

Consulte las siguientes expresiones de consulta de búsqueda de ejemplo:

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

Las consultas sobre varios campos se pueden combinar de forma lógica, y los grupos y los campos se pueden agrupar más. Los operadores lógicos disponibles distinguen entre mayúsculas y minúsculas y son AND, +, OR, NOT y -. Las consultas de rango se pueden ejecutar sobre series o números.

Si desea una búsqueda aproximada, puede ejecutar una consulta con ~ para encontrar términos parecidos al término de búsqueda. Por ejemplo, look~ encuentra los términos « book » y « took ».

Si los límites superiores de una consulta de rango son series que solo contienen dígitos numéricos, los límites se tratan como números, no como series. Por ejemplo, si realiza una búsqueda con la consulta mod_date:["20170101" TO "20171231"], los resultados incluyen documentos para los que mod_date está entre los valores numéricos 20170101 y 20171231, no entre las series "20170101" y "20171231".

Puede modificar la importancia de un término de búsqueda añadiendo ^ y un número positivo. Esta alteración crea coincidencias que contienen el término más o menos relevante, de forma proporcional a la potencia del valor de aumento. El valor predeterminado es 1, lo que significa que no hay incremento ni disminución en la fuerza de la coincidencia. El valor decimal entre 0 y 1 reduce la importancia, lo que hace que la fuerza de la coincidencia sea menor. Un valor mayor que uno aumenta la importancia, lo que hace que la fuerza de la coincidencia sea mayor.

Se da soporte a las búsquedas con caracteres comodín, tanto para un solo carácter (?) como para varios (*). Por ejemplo: dat? coincidiría con date y data, y dat* coincidiría con date,data,database, y dates. Los caracteres comodín deben estar después del término de búsqueda.

Utilice *:* para que se devuelvan todos los resultados.

Los conjuntos de resultados de las búsquedas están limitados a 200 filas y devuelven 25 filas de forma predeterminada. El número de filas que se devuelven se puede modificar utilizando el parámetro « limit ».

Si la consulta de búsqueda no especifica el argumento "group_field", la respuesta incluye un marcador. Si este marcador se proporciona más adelante como un parámetro de URL, la respuesta omite las filas que ya se han visto, lo que facilita y agiliza la obtención del siguiente conjunto de resultados.

La respuesta nunca incluye un marcador si se incluye el parámetro « "group_field" » en la consulta de búsqueda.

Las opciones group_field, group_limit y group_sort solo están disponibles cuando se realizan consultas globales.

Los siguientes caracteres requieren escape si desea realizar una búsqueda en ellos:

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

Para escapar uno de estos caracteres, precédalo de un carácter de barra inclinada invertida (\).

La respuesta a una consulta de búsqueda incluye un campo order para cada uno de los resultados. El campo order es una matriz en la que el primer elemento es el campo o los campos que se especifican en el parámetro sort. Si no se incluye el parámetro « sort » en la consulta, el campo « order » contiene la puntuación de relevancia de Lucene. Si utiliza la característica de sort by distance como se describe en el tema sobre Búsquedas geográficas, el primer elemento es la distancia desde un punto. La distancia se mide en kilómetros o en millas.

El segundo elemento de la matriz de clasificación se puede pasar por alto. Se utiliza solo para la resolución de problemas.

Facetas

La búsqueda de IBM Cloudant también da soporte a la búsqueda por facetas, lo que permite descubrir información agregada sobre coincidencias de forma rápida y sencilla. Puede comparar todos los documentos utilizando la sintaxis de consulta ?q=*:* especial y utilizar las facetas devueltas para definir mejor la consulta. Para indicar que un campo se debe indexar para consultas con facetas, establezca {"facet": true} en sus opciones.

Consulte la siguiente consulta de búsqueda de ejemplo, especificando que la búsqueda por facetas está habilitada:

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

Para utilizar facetas, todos los documentos del índice deben incluir todos los campos que tienen habilitado el uso de facetas. Si los documentos no incluyen todos los campos, recibirá el error bad_request con el siguiente motivo, "The field_name does not exist". Si cada documento no contiene todos los campos para facetas, cree índices distintos para cada campo. Si no crea índices distintos para cada campo, debe incluir solo los documentos que contengan todos los campos. Verifique que los campos existen en cada documento mediante una sola sentencia if.

Consulte la siguiente sentencia if de ejemplo para verificar que los campos necesarios existen en cada 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
        }
    }
}

Búsquedas geográficas

Además de buscar por el contenido de los campos textuales, también puede clasificar sus resultados según su distancia con respecto a una coordenada geográfica.

Para clasificar los resultados de este modo, debe indexar dos campos numéricos que representen la longitud y la latitud.

A continuación, puede consultar utilizando el campo de clasificación <distance...> especial, que toma cinco parámetros:

• Nombre del campo de longitud: el nombre del campo de longitud (mylon en el ejemplo).
• Nombre del campo de latitud: el nombre del campo de latitud (mylat en el ejemplo).
• Longitud del origen: la longitud del lugar con respecto a cuya distancia desea realizar la clasificación.
• Latitud del origen: la latitud del lugar con respecto a cuya distancia desea realizar la clasificación.
• Unidades: las unidades que se pueden utilizar son km para kilómetros o mi para millas. La distancia se devuelve en el campo de clasificación.

Puedes combinar la ordenación por distancia con cualquier otra consulta de búsqueda, como las búsquedas por rango de latitud y longitud, o consultas que incluyan información no geográfica.

De este modo, puede realizar búsquedas en un recuadro delimitador y limitar la búsqueda con criterios adicionales.

Consulte los siguientes datos geográficos de ejemplo:

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

Consulte el ejemplo siguiente de un documento de diseño que incluya un índice de búsqueda para los datos geográficos:

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

Consulte el ejemplo siguiente que utiliza HTTP para una consulta que clasifica las ciudades del hemisferio norte según su distancia con Nueva 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

Consulte el ejemplo siguiente que utiliza la línea de mandatos para una consulta que clasifica las ciudades del hemisferio norte según su distancia con Nueva 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))

El ejemplo Go anterior requiere el siguiente bloque de importación:

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

Consulte la siguiente respuesta (abreviada) que incluye una lista de ciudades del hemisferio norte clasificadas por su distancia con Nueva 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
            }
        }
    ]
}

Resaltado de términos de búsqueda

A veces resulta útil obtener el contexto en el que se ha mencionado un término de búsqueda para poder mostrar a un usuario los resultados más acentuados.

Para resultados resaltados, añada el parámetro highlight_fields a la consulta de búsqueda. Especifique los nombres de campo para los que desea fragmentos, en los que se devuelve el término de búsqueda resaltado.

De forma predeterminada, el término de búsqueda se coloca en los códigos <em> para resaltarlo, pero el resaltado se puede anular utilizando los parámetros highlights_pre_tag y highlights_post_tag.

La longitud de los fragmentos es de 100 caracteres de forma predeterminada. Se puede solicitar otra longitud con el parámetro highlights_size.

El parámetro highlights_number controla el número de fragmentos que se devuelven y el valor predeterminado es 1.

En la respuesta, se añade un campo highlights, con un subcampo por nombre de campo.

Para cada campo, recibirá una matriz de fragmentos con el término de búsqueda resaltado.

Para que el resaltado funciones, almacene el campo en el índice con la opción store: true.

Consulte el ejemplo siguiente que utiliza HTTP para realizar una búsqueda con el resaltado habilitado:

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

Observa el siguiente ejemplo de la línea comando para realizar una búsqueda con el resaltado activado:

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

El ejemplo Go anterior requiere el siguiente bloque de importación:

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

Consulte el ejemplo siguiente de resultados de búsqueda resaltados:

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

Metadatos de índice de búsqueda

Para recuperar información sobre un índice de búsqueda, envíe una solicitud GET al punto final _search_info, tal como se muestra en el ejemplo siguiente. DDOC hace referencia al documento de diseño que incluye el índice e INDEX_NAME es el nombre del índice.

Consulte el ejemplo siguiente que utiliza HTTP para solicitar metadatos de índice de búsqueda:

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

Consulte el ejemplo siguiente que utiliza la línea de mandatos para solicitar metadatos de índice de búsqueda:

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

El ejemplo Go anterior requiere el siguiente bloque de importación:

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

La respuesta incluye información sobre el índice, como el número de documentos del índice y el tamaño del índice en disco.

Consulte la siguiente respuesta de ejemplo después de solicitar metadatos de índice de búsqueda:

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