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 Python 3 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é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 :

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

Les constructeurs QueryOptions et SortOptions utilisent des arguments nommés, comme illustré dans cet exemple :

def query_options():
    index = search.Index('products')
    query_string = "product: piano AND price < 5000"

    # Create sort options to sort on price and brand.
    sort_price = search.SortExpression(
        expression='price',
        direction=search.SortExpression.DESCENDING,
        default_value=0)
    sort_brand = search.SortExpression(
        expression='brand',
        direction=search.SortExpression.DESCENDING,
        default_value="")
    sort_options = search.SortOptions(expressions=[sort_price, sort_brand])

    # Create field expressions to add new fields to the scored documents.
    price_per_note_expression = search.FieldExpression(
        name='price_per_note', expression='price/88')
    ivory_expression = search.FieldExpression(
        name='ivory', expression='snippet("ivory", summary, 120)')

    # Create query options using the sort options and expressions created
    # above.
    query_options = search.QueryOptions(
        limit=25,
        returned_fields=['model', 'price', 'description'],
        returned_expressions=[price_per_note_expression, ivory_expression],
        sort_options=sort_options)

    # Build the Query and run the search
    query = search.Query(query_string=query_string, options=query_options)
    results = index.search(query)
    for scored_document in results:
        print(scored_document)

QueryOptions

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	Valeur par défaut	Maximum
limit	Nombre maximal de documents à renvoyer dans les résultats.	20	1 000
number_found_accuracy	Cette propriété détermine l'exactitude du résultat renvoyé par SearchResults.number_found(). 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 ou que la valeur est définie sur None, 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).	-
sort_options	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	Valeur par défaut
ids_only	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).
returned_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).
returned_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.	Aucune
snippeted_fields	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 returned_expressions 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 l'ordre et la notation des résultats de recherche.

Propriété	Description	Par défaut
expressions	Liste de SortExpressions représentant un tri de documents multidimensionnel.	Aucune
match_scorer	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.	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. 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	Valeur 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
default_value	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, 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.