Options de requête et de tri

Lorsque vous appelez la méthode Index.Search en utilisant seulement une chaîne de requête, les résultats sont renvoyés en fonction des options de requête par défaut :

  • Les documents sont renvoyés triés par ordre décroissant.
  • Les documents sont renvoyés par groupes de 20 à la fois.
  • Les documents récupérés contiennent tous leurs champs d'origine.

Vous pouvez utiliser une instance de la structure SearchOptions comme argument de Search pour modifier ces options.

La structure SearchOptions permet de spécifier le nombre de documents à renvoyer à la fois. Il permet également de personnaliser le contenu des documents récupérés. Vous ne pouvez demander que des identifiants de documents ou des documents ne contenant qu'un sous-ensemble de leurs champs. Vous pouvez également créer des champs personnalisés dans les documents récupérés en utilisant des expressions de champ (champs avec des valeurs dérivées d'autres champs du document).

Outre les options de requête, la structure "SearchOptions" peut également inclure une instance de la structure SortOptions. À l'aide des options de tri, vous pouvez modifier l'ordre de tri et trier les résultats sur plusieurs clés.

SearchOptions

Ces propriétés contrôlent le nombre de résultats renvoyés et leur ordre de tri. Les options de décalage et de curseur, qui s'excluent l'une l'autre, permettent d'effectuer la pagination. Elles spécifient les documents à renvoyer dans les résultats.

Propriété Description Valeur par défaut Maximum
Limit Nombre maximal de documents à renvoyer dans les résultats. 20 1 000
Offset Décalage du premier document dans les résultats à renvoyer. 0. Les résultats contiendront tous les documents correspondants (jusqu'à la limite). 1 000
Cursor Utilisé à la place d'un décalage, un curseur permet d'extraire des groupes de documents selon un ordre de tri. Un curseur est mis à jour au fur et à mesure qu'il parcourt les requêtes successives, ce qui permet de poursuivre chaque nouvelle recherche à partir de la fin de la précédente. Le curseur et l'offset sont traités dans la page de référence Recherche Go. Null. Les résultats contiendront tous les documents correspondants (jusqu'à la limite). -
Sort Définit une structure SortOptions pour contrôler l'ordre des résultats de la recherche. Une instance SortOptions possède son propre ensemble de propriétés comme décrit ci-dessous. Null. Les résultats sont triés par rang de document décroissant. -

Ces propriétés contrôlent les champs de document qui apparaissent dans les résultats.

Propriété Description Valeur par défaut
IDsOnly Définissez-la sur true ou false. Lorsque la valeur est true, les documents renvoyés dans les résultats ne contiennent que des identifiants et aucun champ. false (renvoie tous les champs).
Fields Spécifie les champs de document à inclure dans les résultats. Vous ne pouvez pas spécifier plus de 100 champs. Renvoie tous les champs du document (jusqu'à 100 champs).
Expressions Expressions de champ décrivant les champs calculés qui sont ajoutés à chaque document renvoyé dans les résultats de la recherche. Ces champs sont ajoutés à la propriété Expressions du document. La valeur du champ est spécifiée en écrivant une expression qui peut inclure un ou plusieurs champs de document. Aucun

SortOptions

Les propriétés de SortOptions contrôlent l'ordre et la notation des résultats de recherche.

Propriété Description Par défaut
Expressions Tranche de SortExpressions représentant un tri de documents multidimensionnel. Aucun
Scorer Un emplacement Scorer facultatif. Si présent, les documents sont notés en fonction de la fréquence des termes de recherche. Le score est renvoyé dans le champ _score. La notation des documents peut être coûteuse (en opérations facturables et en temps d'exécution) et peut ralentir vos recherches. Utilisez les scores avec parcimonie. Aucun
Limit Nombre maximal d'objets à marquer et/ou à trier. Ne peut pas être supérieur à 10 000. 1 000

Trier sur plusieurs clés

Il est possible de classer les résultats de la recherche en fonction de plusieurs clés de tri. Chaque clé peut être un simple nom de champ ou une valeur calculée à partir de plusieurs champs. Cette expression est construite selon les règles de la section suivante.

Une SortExpression définit également l'ordre de tri et une valeur de clé par défaut à utiliser si l'expression ne peut pas être calculée pour un document. Voici la liste complète des propriétés :

Propriété Description Valeur par défaut
Expr Expression à évaluer lors du tri des résultats pour chaque document correspondant. Aucun
Reverse Si true, inverse l'ordre de tri des résultats de la recherche qui s'affichent alors par ordre croissant (au lieu de l'ordre décroissant par défaut). false
Default Valeur par défaut de l'expression, si aucun champ n'est présent et ne peut être calculé pour un document. Une valeur de texte doit être spécifiée pour les tris de texte. Une valeur numérique doit être spécifiée pour les tris numériques. Aucun

Trier sur des champs à valeurs multiples

Lorsque vous triez sur un champ à valeurs multiples d'un type particulier, seule la première valeur affectée au champ est utilisée. Prenons l'exemple de deux documents, DocA et DocB, qui comportent tous les deux un champ de texte nommé "couleur". Deux valeurs sont attribuées au champ "couleur" de DocA dans un ordre précis (rouge, bleu) et deux valeurs à DocB dans un ordre précis (vert, rouge). Lorsque vous effectuez un tri en spécifiant le champ de texte "couleur", DocA est trié sur la valeur "rouge" et DocB sur la valeur "vert". Les autres valeurs de champ ne sont pas utilisées pour le tri.

Trier ou ne pas trier

Si vous ne spécifiez aucune option de tri, les résultats de la recherche sont automatiquement classés par ordre décroissant. Il n'y a pas de limite au nombre de documents retournés dans ce cas. Si vous spécifiez des options de tri, le tri est effectué une fois tous les documents correspondants sélectionnés. Il existe une propriété explicite, SortOptions.Limit, qui contrôle la taille du tri. Il n'est pas possible de trier plus de 10 000 documents, la valeur par défaut étant 1 000. S'il y a plus de documents correspondants que le nombre spécifié par SortOptions.Limit, la recherche ne permet que d'extraire, de trier et de renvoyer ce nombre limité de résultats. Les documents à trier sont sélectionnés dans la liste de tous les documents correspondants et classés par ordre décroissant. Il peut arriver qu'une requête sélectionne plus de documents correspondants que vous ne pouvez en trier. Si vous utilisez des options de tri et qu'il est important de récupérer chaque document correspondant, vous devez vous assurer que votre requête ne renverra pas plus de documents que vous ne pouvez en trier.

Écrire des expressions

Les expressions sont utilisées pour définir les expressions de champ (définies dans les SearchOptions) et les expressions de tri définies dans les SortOptions. Elles sont écrites sous forme de chaînes :

"price * quantity"
"(men + women)/2"
"min(daily_use, 10) * rate"
"snippet('rose', flower, 120)"

Les expressions impliquant des champs numériques peuvent utiliser les opérateurs arithmétiques (+, -, *, /) et les fonctions numériques intégrées répertoriées ci-dessous. Les expressions impliquant des champs de points géographiques peuvent utiliser les fonctions Geopoint et Distance. Les expressions pour les champs Texte et HTML peuvent utiliser la fonction Snippet.

Les expressions peuvent également inclure ces termes spéciaux :

Terme Description
_rank Propriété de rang d'un document. S'utilise dans les expressions de champ et de tri.
_score Score attribué à un document lorsqu'un Scorer est inclus dans les SortOptions. Ce terme ne peut apparaître que dans les expressions de tri. Il ne peut pas être utilisé dans les expressions de champ.

Fonctions numériques

Les expressions permettant de définir des valeurs numériques pour FieldExpressions et SortExpressions peuvent utiliser ces fonctions intégrées. Les arguments doivent être des nombres, des noms de champs ou des expressions utilisant des nombres et des noms de champs.

Fonction Description Exemple
max Renvoie le plus grand de ses arguments. max(recommended_retail_price, discount_price, wholesale_price)
min Renvoie le plus petit de ses arguments. min(height, width, length)
log Renvoie le logarithme naturel. log(x)
abs Renvoie la valeur absolue. abs(x)
pow Prend deux arguments numériques. L'appel pow(x, y) calcule la valeur de x élevée à la puissance y. pow(x, 2)
count Prend un nom de champ comme argument. Renvoie le nombre de champs du document portant ce nom. N'oubliez pas qu'un document peut contenir plusieurs champs de types différents portant le même nom. Remarque : count ne peut être utilisé que dans FieldExpressions. Cette fonction ne peut pas apparaître dans SortExpressions. count(user)

Fonctions Geopoint

Ces fonctions peuvent être utilisées pour les expressions impliquant des champs de points géographiques.

Fonction Description Exemple
geopoint Définit un point géographique à partir d'une latitude et d'une longitude. geopoint(-31.3, 151.4)
distance Calcule la distance en mètres entre deux points géographiques. Notez que l'un des deux arguments peut être le nom d'un champ de point géographique ou un appel de la fonction Geopoint. Cependant, un seul argument peut être un nom de champ. distance(geopoint(23, 134), store_location)

Extraits

Un extrait ("snippet") est un fragment d'un champ de texte qui correspond à une chaîne de requête et inclut le texte environnant. Les extraits sont créés via un appel à la fonction snippet :

snippet(query, body, [max_chars])

query
Chaîne de requête entre guillemets spécifiant le texte à rechercher dans le champ.
body
Nom d'un champ texte, HTML ou Atom.
max_chars
Nombre maximal de caractères à renvoyer dans l'extrait. Cet argument est facultatif. La valeur par défaut est 160 caractères.

La fonction renvoie une chaîne HTML. La chaîne contient un extrait de la valeur du champ "body", avec le texte correspondant à la requête en caractères gras.