Paramètres de requête

Les paramètres de requête modifient le résultat des requêtes IBM Cloudant Query, en modifiant l'ordre de tri, les champs renvoyés ou la pagination des réponses. Les paramètres sont fournis dans la requête, à côté du champ selector.

Aperçu des paramètres

Ce document JSON utilise tous les paramètres de requête 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
	}

Spécification des champs à renvoyer

Il est possible de spécifier quels champs sont renvoyés pour un document lorsque vous effectuez une sélection à partir d'une base de données. Cela peut présenter des avantages :

  • Vos résultats se limitent uniquement aux parties du document qui sont nécessaires pour votre application.
  • Réduction de la taille de la réponse.

Les champs à renvoyer sont spécifiés à l'aide du tableau fields dans la requête. Les noms de zone fournis peuvent utiliser la notation décimale pour accéder aux sous-zones.

Cette requête ne renverra que les quatre champs spécifiés dans les documents résultats :

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

Seuls les champs de filtre spécifiés sont inclus dans la réponse. _id ou d'autres champs de métadonnées ne sont pas automatiquement inclus.

Tri des résultats

Utilisez le champ sort dans une requête pour spécifier l'ordre des résultats renvoyés. Le champ sort contient une liste de paires de noms de champs et de directions, exprimées sous forme de tableau. La première paire de nom de zone et de sens constitue le niveau supérieur de tri. D'autres paires, si elles sont fournies, spécifient le niveau de tri suivant.

La zone de tri peut correspondre à n'importe quelle zone. Utilisez la notation décimale si nécessaire pour les sous-zones.

La valeur de la direction est asc pour la montée et desc pour la descente :

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

Si vous excluez la valeur de sens, asc est utilisé par défaut. Pour le tri ascendant, on peut utiliser l'abréviation suivante :

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

Classiquement, l'une des exigences consiste à rechercher un contenu à l'aide d'un sélecteur, puis à trier les résultats en fonction de la zone spécifiée, dans le sens préféré.

Pour utiliser le tri, un index contenant les champs de tri doit être défini. Si vous utilisez l'index json, les champs doivent être spécifiés dans le même ordre que le tri.

Actuellement, IBM Cloudant Query ne prend pas en charge les zones multiples avec des ordres de tri différents ; par conséquent, le sens de toutes les zones doit être croissant ou décroissant.

Si le sens est croissant, vous pouvez utiliser une chaîne à la place d'un objet afin de spécifier les zones de tri.

Tri à l'aide d'index de texte

Pour les noms de champs dans les requêtes de tri sur un index text lorsque le type du champ à trier ne peut être déterminé, il peut être nécessaire de spécifier un type de champ, il peut être nécessaire de spécifier un type de champ. Exemple :

"sort": [ { "<fieldname>:string": "asc" } ]
Spécification du type de zone
Quel index est utilisé par la requête ? Exigence de type de zone
Index JSON Aucun
Index de texte de toutes les zones dans tous les documents Spécifiez la zone de tri dans la requête si la base de données contient des documents dans lesquels la zone de tri possède un type. De plus, spécifiez la zone de tri dans la requête si elle contient des documents dans lesquels la zone de tri possède un type différent.
Tout autre index de texte Spécifiez le type de toutes les zones de tri dans la requête.

Un index de texte de toutes les zones de tous les documents est créé lorsque vous utilisez la syntaxe : "index": {}.

L'ordre de tri est indéfini lorsque les zones contiennent des types de données différents. Cette caractéristique est une différence importante entre les index de texte et de vue. Le comportement de tri pour les zones avec des types de données différents pourra changer dans des versions ultérieures.

Pagination

IBM Cloudant Query prend en charge la pagination à l'aide de la zone de signet. Chaque réponse _find contient un signet, c'est-à-dire un jeton qu'IBM Cloudant utilise pour déterminer l'endroit où reprendre lorsque d'autres requêtes sont effectuées ultérieurement. Pour obtenir l'ensemble suivant de résultats de requête, ajoutez le signet qui a été reçu dans la réponse précédente à votre requête suivante. N'oubliez pas de garder le même sélecteur ; autrement, vous recevrez des résultats inattendus. Pour paginer vers l'arrière, vous pouvez utiliser un signet précédent pour revenir à l'ensemble de résultats précédent.

La présence d'un signet ne garantit pas un nombre plus élevé de résultats. Vous pouvez déterminer si vous êtes à la fin de l'ensemble de résultats en comparant le nombre de résultats qui sont renvoyés avec la taille de page demandée. Si les résultats renvoyés sont inférieurs à la limite, cela signifie qu'aucun autre résultat n'a été renvoyé dans l'ensemble de résultats.

Indication de l'utilisation d'un index spécifique

Pour exiger d'une requête qu'elle utilise un index spécifique, ajoutez le paramètre use_index à la requête. Il s'agit d'un indice; si l'index ne peut pas être utilisé pour la requête, un autre index sera utilisé.

La valeur du paramètre use_index peut être indiquée dans l'un des formats suivants :

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

Cet exemple de requête montre qu'il est possible d'obtenir un indice spécifique à l'aide de use_index:

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

Forcer l'utilisation d'un index spécifique

Combinez le paramètre allow_fallback avec use_index pour forcer l'utilisation d'un index spécifique. Si l'index ne peut pas être utilisé pour la requête, celle-ci renvoie une réponse d'erreur.

L'utilisation de "allow_fallback": false sans spécifier use_index empêchera l'utilisation de l'index intégré _all_docs.

Cet exemple de requête montre comment forcer un index spécifique en utilisant allow_fallback avec use_index:

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