Remarque : Python 2.7 n'est plus compatible à partir du 31 janvier 2024. Vos applications Python 2.7 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 Python.

Classe QueryOptions

La classe QueryOptions fournit des options pour le post-traitement des résultats de requête suivant les besoins de votre application. Vous construisez la classe en tant qu'objet options dans l'argument Query.options.

La classe Query est définie dans le module google.appengine.api.search.

Présentation

La classe QueryOptions fournit des options pour le post-traitement des résultats d'une requête spécifique. Les options incluent la possibilité de trier les résultats, de contrôler les champs de document à renvoyer, de produire des extraits de champs, ainsi que de calculer et trier suivant des expressions d'évaluation complexes.

Si vous souhaitez accéder de manière aléatoire aux pages de résultats de recherche, vous pouvez utiliser un décalage :

from google.appengine.api import search
...
# get the first set of results
page_size = 10
results = index.search(search.Query(query_string='some stuff',
    options=search.QueryOptions(limit=page_size))

# calculate pages
pages = results.number_found / page_size

# user chooses page and hence an offset into results
next_page = ith * page_size

# get the search results for that page
results = index.search(search.Query(query_string='some stuff',
    options=search.QueryOptions(limit=page_size, offset=next_page))

Par exemple, le fragment de code suivant émet une requête de recherche de documents basée sur la présence du terme first dans le champ subject et du terme good dans n'importe quel champ, avec les critères suivants : renvoi de 20 documents au plus, curseur de résultats sur la page de résultats suivante, renvoi d'un autre curseur pour l'ensemble de résultats suivants, tri par sujet en ordre décroissant, renvoi des champs d'auteur, de sujet et de résumé, ainsi que d'un extrait du champ de contenu.

...
results = index.search(search.Query(
    query='subject:first good',
    options=search.QueryOptions(
        limit=20,
        cursor=search.Cursor(),
        sort_options=search.SortOptions(
            expressions=[
                search.SortExpression(expression='subject', default_value='')],
            limit=1000),
        returned_fields=['author', 'subject', 'summary'],
        snippeted_fields=['content'])))

Constructeur

Le constructeur de la classe QueryOptions est défini comme suit :

class QueryOptions(limit=20, number_found_accuracy=None, cursor=None, offset=None, sort_options=None, returned_fields=None, ids_only=False, snippeted_fields=None, returned_expressions=None)

Permet de spécifier les options définissant les résultats de requête de recherche.

Arguments

limit: Limite sur le nombre de documents à renvoyer dans les résultats.
number_found_accuracy: Exactitude minimale requise pour SearchResults.number_found. Si cet argument est défini, l'exactitude est préservée jusqu'à au moins ce nombre. Par exemple, lorsqu'il est défini sur 100, tout objet SearchResults pour lequel number_found_accuracy <= 100 est exact.

Attention : Cette option peut considérablement accroître la latence et le coût, surtout lorsqu'elle est utilisée conjointement avec returned_fields.
cursor: Curseur décrivant où obtenir le jeu de résultats suivants ou bien où indiquer les curseurs suivants dans SearchResults.
offset: Le décalage représente le nombre de documents à sauter dans les résultats de la recherche. C'est une alternative à l'utilisation d'un curseur de requête. Il permet un accès aléatoire aux résultats. Les décalages sont plus coûteux (en termes d'heures d'utilisation de l'instance) que les curseurs. Vous pouvez utiliser soit un curseur, soit un décalage, mais pas les deux à la fois. L'utilisation d'un décalage signifie qu'aucun curseur n'est renvoyé dans ScoredDocument.cursor ou ScoredDocument.cursor.
sort_options: Objet SortOptions spécifiant un tri multidimensionnel à appliquer aux résultats de la recherche.
returned_fields: Itérable de noms de champs à renvoyer dans les résultats de recherche.
ids_only: Indique de renvoyer uniquement les identifiants de document, et aucun champ.
snippeted_fields: Itérable de noms de champs dont un extrait seulement doit être renvoyé dans les résultats de recherche.
returned_expressions: Itérable de FieldExpression à évaluer et à renvoyer dans les résultats de recherche.

Result value

Nouvelle instance de la classe QueryOptions.

Exceptions

TypeError: Si un argument iterator_options ou sort_options inconnu est transmis.
ValueError: Si ids_only et returned_fields sont utilisés conjointement.

Propriétés

Une instance de la classe Query possède les propriétés suivantes :

limit: Renvoie une limite sur le nombre de documents à renvoyer dans les résultats.
number_found_accuracy: Renvoie l'exactitude minimale requise pour SearchResults.number_found.
cursor: Renvoie le curseur pour la requête.
offset: Renvoie le nombre de documents à sauter dans les résultats de la recherche.
sort_options: Renvoie un objet SortOptions.
returned_fields: Renvoie un itérable des noms de champs à renvoyer dans les résultats de la recherche.
ids_only: Renvoie seulement dans les résultats de recherche.
snippeted_fields: Renvoie un itérable des noms de champs pour lesquels un extrait seulement doit être renvoyé dans les résultats.
returned_expressions: Renvoie un itérable d'objets FieldExpression à renvoyer dans les résultats.