Parámetros de consulta

Los parámetros de consulta modifican la salida de las solicitudes de consulta de IBM Cloudant, alterando el orden de clasificación, los campos devueltos o paginando las respuestas. Los parámetros se suministran en la consulta, junto al campo selector.

Resumen de parámetros

Este documento JSON utiliza todos los parámetros de consulta disponibles:

{
  // Query selector
	"selector": {
		"year": {
			"$gt": 2010
		}
	},
	// Specify fields to return
	"fields": ["_id", "_rev", "year", "title"],
	// Specify sort order
	"sort": [{"year": "asc"}],
	// Return a maximum number of results
	"limit": 10,
	// Start returning results from a previous bookmark (pagination)
	"bookmark":"g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJB"
	// Hint to use a specific index for a query
	"use_index": "_design/32372935e14bed00cc6db4fc9efca0f1537d34a8",
	// Disallow using a different index than the specified index
  "allow_fallback": false
	}

Especificación de los campos a devolver

Es posible especificar qué campos se devuelven para un documento cuando se selecciona de una base de datos. Esto puede ofrecer ventajas:

  • Los resultados están limitados a solo aquellas partes del documento que son necesarias para la aplicación.
  • Una reducción en el tamaño de la respuesta.

Los campos a devolver se especifican utilizando la matriz fields en la consulta. Los nombres de campo proporcionados pueden utilizar la notación con puntos para acceder a los subcampos.

Esta consulta sólo devolverá los cuatro campos especificados de los documentos resultantes:

{
	"selector": {
		"Actor_name": "Robert De Niro"
	},
	"fields": [
		"Actor_name",
		"Movie_year",
		"_id",
		"_rev"
	]
}

En la respuesta sólo se incluyen los campos de filtro especificados. _id u otros campos de metadatos no se incluyen automáticamente.

Clasificación de resultados

Utilice el campo sort en una consulta para especificar cómo se ordenan los resultados devueltos. El campo sort contiene una lista de pares de nombre de campo y dirección, expresados como una matriz. El primer par de nombre de campo y dirección constituye el nivel superior de clasificación. Otros pares, si se proporcionan, especifican el siguiente nivel de ordenación.

El campo de clasificación puede ser cualquier campo. Utilice la notación de puntos si es necesario para los subcampos.

El valor de la dirección es asc para ascendente, y desc para descendente:

"sort": [{ "fieldName1": "desc" }, { "fieldName2": "desc" }]

Si excluye el valor de dirección, se utiliza asc como valor predeterminado. Para la ordenación ascendente, se puede utilizar la siguiente abreviatura:

"sort": [ "fieldName1", "fieldName2" ]

Un requisito típico consiste en buscar algún contenido mediante un selector y luego clasificar los resultados según el campo especificado, en la dirección que se prefiera.

Para utilizar la ordenación, debe definirse un índice que contenga los campos de ordenación. Si se utiliza json index, los campos deben especificarse en el mismo orden que la ordenación.

Actualmente, IBM Cloudant Query no da soporte a varios campos con diferentes órdenes de clasificación, por lo que la dirección debe ser todo ascendente o todo descendente.

Si la dirección es ascendente, puede utilizar una serie en lugar de un objeto para especificar los campos de clasificación.

Clasificación mediante índices de texto

Para nombres de campo en consultas de ordenación contra un índice text en las que no se puede determinar el tipo del campo que se está ordenando, puede ser necesario especificar un tipo de campo. Por ejemplo:

"sort": [ { "<fieldname>:string": "asc" } ]
Cuándo especificar el tipo de campo
¿Qué índice se utiliza por consulta? Requisito del tipo de campo
Índice JSON Ninguna
Índice de texto de todos los campos en todos los documentos Especifique el campo de clasificación en la consulta si la base de datos contiene documentos en los que el campo de clasificación tiene un tipo. Especifique también el campo de clasificación en la consulta si contiene documentos en los que el campo de clasificación tiene un tipo distinto.
Cualquier otro índice de texto Especifique el tipo de todos los campos de clasificación de la consulta.

Cuando se utiliza la sintaxis, se crea un índice de texto de todos los campos de todos los documentos: "index": {}.

El orden de clasificación no está definido cuando los campos contienen distintos tipos de datos. Esta característica es una diferencia importante entre los índices de texto y de vista. El comportamiento de la clasificación para los campos con distintos tipos de datos puede cambiar en futuras versiones.

Paginación

IBM Cloudant Query da soporte a la paginación por el campo de marcador. Cada respuesta _find contiene un marcador, que es una señal que IBM Cloudant utiliza para determinar desde dónde se va a reanudar desde cuando más adelante se realicen consultas. Para obtener el siguiente conjunto de resultados de una consulta, añada el marcador que se ha recibido en la respuesta anterior a la solicitud siguiente. Recuerde mantener el selector igual; de lo contrario recibirá resultados inesperados. Para paginar hacia atrás, puede utilizar un marcador anterior para devolver el conjunto de resultados anterior.

La presencia de un marcador no garantiza más resultados. Puede probar si está al final del conjunto de resultados comparando el número de resultados que se devuelven con el tamaño de página solicitado. Si los resultados devueltos son menores que el límite, significa que no se han devuelto más resultados en el conjunto de resultados.

Indicación del uso de un índice específico

Para indicar a una consulta que utilice un índice específico, añada el parámetro use_index a la consulta. Se trata de una sugerencia; si el índice no puede utilizarse para la consulta, se utilizará un índice alternativo.

El valor del parámetro use_index toma uno de los formatos siguientes:

  • "use_index": "$DDOC"
  • "use_index": ["$DDOC","$INDEX_NAME"]

Este ejemplo de consulta muestra la sugerencia de un índice específico con use_index:

{
	"selector": {
		"$text": "Pacino",
		"year": 2010
	},
	"use_index": "_design/32372935e14bed00cc6db4fc9efca0f1537d34a8"
}

Forzar el uso de un índice específico

Combine el parámetro allow_fallback con use_index para forzar el uso de un índice específico. Si el índice no puede utilizarse para la consulta, ésta devolverá una respuesta de error.

El uso de "allow_fallback": false sin especificar use_index impedirá el uso del índice incorporado _all_docs.

Este ejemplo de consulta muestra cómo forzar un índice específico utilizando allow_fallback con use_index:

{
	"selector": {
		"$text": "Pacino",
		"year": 2010
	},
	"use_index": "_design/32372935e14bed00cc6db4fc9efca0f1537d34a8",
  "allow_fallback": false
}