Options de requête et de tri

Cette API est compatible avec les environnements d'exécution de première génération et peut être utilisée lors de la mise à niveau vers des environnements d'exécution de deuxième génération correspondants. Si vous effectuez une mise à jour vers l'environnement d'exécution Go 1.12+ d'App Engine, consultez le guide de migration pour en savoir plus sur les options de migration des anciens services groupés.

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