Remarque : Java 8 n'est plus pris en charge depuis le 31 janvier 2024. Vos applications Java 8 existantes continueront à fonctionner et à recevoir du trafic. Toutefois, App Engine peut bloquer le redéploiement des applications qui utilisent des environnements d'exécution après leur date de fin de compatibilité. Nous vous recommandons de migrer vers la dernière version compatible de Java.

Options de requête et de tri

Lorsque vous appelez la méthodesearch()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 classe Query comme argument de search() pour modifier ces options.

La classe Query vous permet de spécifier le nombre de documents à renvoyer à la fois. Elle vous 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 : extraits (fragments de champs de texte affichant le texte entourant une chaîne correspondante) et expressions de champ (champs avec des valeurs dérivées d'autres champs du document).

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

Rechercher avec la classe Query

Lorsque vous effectuez une recherche avec une instance de la classe Query, vous devez créer une instance de la classe en plusieurs étapes. Voici l'ordre général dans lequel procéder :

Créez une chaîne de requête.
Créez des SortOptions, si nécessaire.
Créez des QueryOptions.
Créez un objet Query qui comprend la chaîne de requête et les QueryOptions (facultatif).
Appelez la méthode de recherche sur l'objet Query.

Les différentes options de requête et de tri sont spécifiées en appelant des méthodes "setter" sur des instances des classes QueryOptions.Builder et SortOptions.Builder, comme dans l'exemple suivant :

try {
  // Build the SortOptions with 2 sort keys
  SortOptions sortOptions =
      SortOptions.newBuilder()
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("price")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValueNumeric(0))
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("brand")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValue(""))
          .setLimit(1000)
          .build();

  // Build the QueryOptions
  QueryOptions options =
      QueryOptions.newBuilder()
          .setLimit(25)
          .setFieldsToReturn("model", "price", "description")
          .setSortOptions(sortOptions)
          .build();

  // A query string
  String queryString = "product: coffee roaster AND price < 500";

  //  Build the Query and run the search
  Query query = Query.newBuilder().setOptions(options).build(queryString);
  IndexSpec indexSpec = IndexSpec.newBuilder().setName(indexName).build();
  Index index = SearchServiceFactory.getSearchService().getIndex(indexSpec);
  Results<ScoredDocument> result = index.search(query);
  return result;
} catch (SearchException e) {
  // handle exception...
}

QueryOptions

Vous devez utiliser QueryOptions.Builder pour définir les options de requête. Vous n'avez pas directement accès à ces propriétés.

Ces propriétés contrôlent le nombre de résultats et l'ordre dans lequel ils sont renvoyés. 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	Par défaut	Maximum
`Limit`	Nombre maximal de documents à renvoyer dans les résultats.	20	1 000
`NumberFoundAccuracy`	Cette propriété détermine l'exactitude du résultat renvoyé par `Results.getNumberFound()`. Elle limite le nombre de correspondances réellement comptées et arrête la recherche lorsque la limite est atteinte. Si le nombre de correspondances dans l'index est inférieur ou égal à la limite, le nombre renvoyé est exact. Sinon, le nombre est une estimation basée sur les correspondances trouvées, ainsi que sur la taille et la structure de l'index. Notez que la définition d'une valeur élevée pour cette propriété peut affecter la complexité de l'opération de recherche et provoquer des délais.	Si aucune valeur n'est renseignée, la précision est définie sur la même valeur que `Limit`.	25 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. Le curseur est mis à jour au fur et à mesure qu'il passe dans les requêtes successives, ce qui permet de poursuivre chaque nouvelle recherche à partir de la fin de la précédente. Le curseur et le décalage sont abordés dans la page Gérer les résultats.	Null. Les résultats contiendront tous les documents correspondants (jusqu'à la limite).	-
`SortOptions`	Définissez un objet `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	Par défaut
`ReturningIdsOnly`	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).
`FieldsToReturn`	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).
`ExpressionsToReturn`	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.	Aucune
`FieldsToSnippet`	Liste de noms de champs de texte. Un extrait est généré pour chaque champ. Il s'agit d'un champ calculé ajouté à la propriété Expressions des documents dans les résultats de la recherche. Le champ d'extrait a le même nom que le champ source. Cette option utilise implicitement la fonction Snippet avec seulement deux arguments, créant un extrait avec au plus une chaîne correspondante, basée sur la même chaîne de requête que celle utilisée par la recherche pour extraire les résultats : `snippet("query-string", field-name)`. L'option `ExpressionsToReturn` vous permet également de créer des extraits personnalisés en ajoutant une expression de champ qui appelle explicitement la fonction Snippet.	Aucune

SortOptions

Les propriétés de SortOptions contrôlent le classement et la notation des résultats de la recherche. Vous devez utiliser SortOptions.Builder pour définir les options de tri. Vous n'avez pas directement accès à ces propriétés.

Les propriétés de SortOptions contrôlent le classement et la notation des résultats de la recherche.

Propriété	Description	Par défaut
`SortExpressions`	Liste de `SortExpressions` représentant un tri de documents multidimensionnel.	Aucune
`MatchScorer`	Objet `MatchScorer` facultatif. Si cet objet est 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.	Aucune
`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. Notez que le terme "expression" comporte plusieurs significations lorsqu'il est question d'options de tri : l'option SortOption elle-même possède un attribut d'expression. Cet attribut est une liste d'objets SortExpression correspondant aux clés de tri. Enfin, chaque objet SortExpression contient un attribut d'expression qui spécifie comment calculer la valeur de la clé de tri. 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	Par défaut
`Expression`	Expression à évaluer lors du tri des résultats pour chaque document correspondant.	Aucune
`Direction`	Ordre de tri des résultats de la recherche, soit `ASCENDING` (croissant) ou `DESCENDING` (décroissant).	`DESCENDING`
`DefaultValue` `DefaultValueDate` `DefaultValueNumber`	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.	Aucune

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, et la valeur par défaut est de 1000 documents. 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 QueryOptions) 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 `MatchScorer` 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.