OpenSearch:Traitement des recherches

La syntaxe de recherche avancée prend en charge un large éventail de requêtes.

/v3/openapi/apps/$app_name/search?fetch_fields=name&query=config=format:fulljson&&query=name:'testuser'&&sort=id

• $app_name : nom de l'application. Les éditions Advanced et Standard prenant en charge plusieurs applications, spécifiez un nom d'application pour cibler une version spécifique. Par exemple, utilisez un ID d'application pour accéder au service de recherche d'une application hors ligne.

• Cette URL n'inclut pas les détails tels que les en-têtes de requête et l'encodage.

• L'adresse de l'hôte est omise dans cette URL.

• Pour plus d'informations sur les paramètres de requête de cette URL (définitions, utilisation et exemples), consultez la section « Paramètres de requête » ci-dessous.

HTTP

GET

JSON

Pour savoir comment concaténer les paramètres de requête, reportez-vous au Mécanisme de signature de l'API V3.

Utilisation des paramètres de requête

• query : Combinez plusieurs clauses pour répondre à divers besoins de recherche. Les clauses du paramètre query sont reliées par &&. L'édition Industry Algorithm Edition prend en charge les recherches vides. Si vous transmettez une chaîne vide '' comme terme de recherche dans une clause query, le système retourne l'ensemble complet des résultats. Une erreur 2112 peut survenir lors d'une recherche vide, mais il s'agit d'un problème d'affichage qui n'affecte pas les résultats réels.

• fetch_fields : Afin de préserver les performances des requêtes, ne récupérez que les champs nécessaires. Si vous configurez ce paramètre dans le SDK ou l'API, il remplace les paramètres correspondants dans la console.

• qp : La configuration de ce paramètre dans le SDK ou l'API prévaut sur les réglages correspondants de la console.

Remarque : La page Search Test de la console affiche l'effet de qp ainsi que ses résultats. Ces informations ne sont actuellement pas disponibles via l'API ou le SDK.

• disable : Désactive des fonctionnalités spécifiques lors des requêtes. Vous pouvez désactiver des fonctions telles que l'analyse de requête (qp), la mise en surbrillance (summary), le classement grossier à fin (first_rank, second_rank) et la nouvelle recherche (re_search).

  Description

  • Permet de choisir les fonctionnalités à désactiver pendant une requête.

  • Prend actuellement en charge la désactivation de l'analyse de requête, de la mise en surbrillance, du classement grossier à fin et de la nouvelle recherche.

  Format :

  disable=function[;function]
  function=function_name[:function_param]

  • Exemples :

    • Pour désactiver l'analyse de requête, définissez disable=qp.

    • Pour désactiver la fonctionnalité spell_check au sein de l'analyse de requête, définissez disable=qp:spell_check. Le format est disable=qp:$qp_processor_name. Pour plus d'informations, consultez QueryProcessor.

    • Pour désactiver la nouvelle recherche, définissez disable=re_search.

• first_rank_name : Lorsqu'il est défini dans un appel SDK ou API, ce paramètre remplace le réglage correspondant dans la console.

• second_rank_name : Lorsqu'il est défini dans un appel SDK ou API, ce paramètre remplace le réglage correspondant dans la console.

• user_id :

  • La valeur user_id doit être encodée en URL dans les requêtes de recherche.

  • La fonctionnalité de statistiques de données utilise ce paramètre pour calculer les visiteurs uniques (UV).

  • Si vous avez intégré la collecte de données, assurez-vous que le user_id utilisé pour signaler les données comportementales correspond au user_id des requêtes de recherche.

• abtest : abtest=urlencode(scene_tag:urlencode(\$scene),flow_divider:urlencode(\$value)), où urlencode est la fonction d'encodage URL.

  • Définissez flow_divider sur l'ID de l'utilisateur final. Si aucun ID n'est disponible, utilisez l'ID de l'appareil ou l'adresse IP de l'utilisateur final. Ce paramètre est obligatoire.

  • scene_tag : Si vous ne configurez pas de tag de scène dans la console, le test A/B s'applique au trafic de toutes les scènes et vous n'avez pas besoin de définir scene_tag dans la requête.

• raw_query :

  Description

  • Ce paramètre sert à la prédiction de catégorie. La prédiction de catégorie, configurée dans l'analyse de requête, ne s'exécute que si les paramètres query et raw_query sont identiques.

  • Il est également utilisé pour l'entraînement des algorithmes, notamment pour la prédiction de catégorie. C'est pourquoi il convient de définir ce paramètre dans toutes les requêtes.

  • Attribuez à ce paramètre la requête originale saisie par l'utilisateur final.

  Format :

  raw_query=content

  • content : la requête originale.

• re_search :

  Description

  • Spécifie la stratégie de nouvelle recherche. Actuellement, seules les stratégies basées sur le seuil total_hits sont prises en charge.

  • Cette fonctionnalité nécessite la configuration de l'analyse de requête.

  • Une nouvelle recherche n'est pas déclenchée si tous les termes de la requête tokenisée ont le même poids de reconnaissance d'entité. Pour déclencher une nouvelle recherche, ajustez les poids de catégorie dans la reconnaissance d'entité.

  Format :

  re_search=strategy:threshold,params:total_hits#${COUNT}

  • COUNT : seuil total_hits. Le système déclenche une nouvelle recherche si le nombre total de résultats est inférieur à COUNT.

  • Exemple :

    • re_search=url_encode(strategy:threshold,params:total_hits#6)

• biz :

  Description

  • Fournit des informations métier pour la requête, telles que le type de trafic de la source.

    Format :

    biz=type:$TYPE

  • type : type de trafic, que vous pouvez définir. Utilisez cette valeur pour distinguer le trafic provenant de différentes sources dans les rapports.

  • Exemple :

    • biz=type:home_page

• vector_search :

  Paramètre	Type	Valeur par défaut	Description
  namespace	list<string>		Namespace dans lequel effectuer la recherche.
  threshold	float		Seuil de score minimum pour la récupération vectorielle.
  top_n	uint32		Nombre de meilleurs résultats à retourner lors de la récupération vectorielle.
  search_params.qc_scan_ratio	float	0,01	Ratio utilisé pour calculer max_scan_num. La formule est : nombre total de documents * scan_ratio.
  search_params.hnsw_ef	uint32	500	Définit la précision de la recherche. Une valeur plus élevée augmente le nombre de documents analysés et améliore le taux de rappel.

• vector_threshold :

• Description

  • Contrôle le seuil de score vectoriel pour le rappel vectoriel. Le système ne retourne que les documents dont le score vectoriel est inférieur à ce seuil.

• Format

  vector_threshold=14.0

  • La valeur doit être de type float.

  • Ce paramètre est facultatif. S'il est omis, le système utilise un seuil intégré.

• Résumé :

  • Les paramètres summary_element_prefix et summary_element_postfix doivent être définis conjointement.

  • Le paramètre summary_element interagit avec les paramètres summary_element_prefix et summary_element_postfix. Le dernier spécifié est prioritaire.

  • Le résumé et la mise en surbrillance ne peuvent pas être configurés séparément.

  • Les paramètres définis via le SDK ou l'API remplacent les paramètres correspondants dans la console.

Paramètre	Type	Obligatoire	Valeur	Valeur par défaut	Description
summary_field	string	Oui			Champ utilisé pour générer le résumé.
summary_element	string	Non		em	Balise de mise en surbrillance, spécifiée sous forme de nom de balise HTML sans chevrons.
summary_ellipsis	string	Non		…	Points de suspension à ajouter aux résumés tronqués.
summary_snippets	int	Non		1	Nombre d'extraits de résumé à retourner.
summary_len	string	Non			Longueur approximative de chaque extrait de résumé.
summary_element_prefix	string	Non			Préfixe pour les termes mis en surbrillance. Il doit s'agir d'une balise HTML complète, telle que <em>.
summary_element_postfix	string	Non			Suffixe pour les termes mis en surbrillance. Il doit s'agir d'une balise HTML complète, telle que </em>.

Résultats

Paramètre	Type	Description
status	string	Résultat de l'exécution. OK indique un succès et FAIL un échec. En cas d'échec de la requête, utilisez le code d'erreur retourné pour le dépannage.
request_id	string	ID unique de cette requête. Utilisez-le pour le dépannage.
result	JSON	Contient les résultats de recherche et les métadonnées. Cet objet comprend le temps de recherche (searchtime), le nombre total de correspondances trouvées (total), le nombre de résultats retournés (num), le nombre maximal de résultats pouvant être retournés (viewtotal), la liste des éléments de résultat (items) et les résultats de facette (facet).
errors	list	Liste d'erreurs. Chaque objet d'erreur contient un code et un message. Pour obtenir la description des codes d'erreur, consultez le document Code d'erreur.

• searchtime : Temps de traitement de la requête par le moteur, en secondes.

• Différences entre total, viewtotal et num : total correspond au nombre de résultats dans le moteur qui correspondent à une requête, en ignorant la clause config. Cette valeur est optimisée pour les grands ensembles de résultats. Toutefois, pour des raisons de performance et de pertinence, le moteur retourne un maximum de viewtotal résultats. Pour la pagination, start+hit doit être inférieur à viewtotal. total est généralement utilisé pour l'affichage. num représente le nombre réel d'éléments retournés pour la requête en cours ; cette valeur est contrainte par les paramètres start et hit de la clause config et ne dépassera pas la valeur hit.

• compute_cost : Tableau contenant un objet unique. Dans cet objet, index_name représente l'ID de l'application et value représente les LCU consommées par la requête.

• items : Contient les documents récupérés. Au sein de chaque objet document, l'objet fields contient le contenu récupéré.

• variableValue : Représente le résultat d'un paramètre personnalisé, tel que la valeur distance. Ce nœud n'est retourné que lorsque le paramètre format de la clause config est défini sur xml ou fulljson. Le format json ne retourne pas ce nœud par défaut.

• sortExprValues : Représente le score de tri du document.

• facet : Contient les informations retournées par la clause aggregate.

• Type de champ tableau : Dans les formats JSON et fulljson, les valeurs d'un tableau sont séparées par un caractère de tabulation (\t). Dans le format XML, ces valeurs sont séparées par un espace.

Exemple de recherche

Réponse JSON

{
 "result": {
  "searchtime": 0.009554,
  "total": 1,
  "compute_cost": [
   {
    "index_name": "110247758",
    "value": 0.304
   }
  ],
  "num": 1,
  "viewtotal": 1,
  "items": [
   {
    "variableValue": {

    },
    "sortExprValues": [
     "10000"
    ],
    "property": {

    },
    "attribute": {

    },
    "fields": {
     "size": "XL",
     "discount_price": "9.9",
     "pid": "950",
     "range_age": "18\t25",
     "detail": "Men's Lapel Jacket, New 2021 Spring & Fall Style, Lightweight Casual Zip-Up Youth Outerwear",
     "index_name": "110247758"
    }
   }
  ],
  "facet": []
 },
 "ops_request_misc": "%7B%22request%5Fid%22%3A%22162642700916781929257960%22%2C%22scm%22%3A%2220140713.110229359..%22%7D",
 "tracer": "",
 "request_id": "162642700916781929257960",
 "errors": [],
 "status": "OK"
}

Réponse d'erreur

{
 "result": {
  "searchtime": 0.003999,
  "total": 0,
  "compute_cost": [
   {
    "index_name": "110247758",
    "value": 0.232
   }
  ],
  "num": 0,
  "viewtotal": 0,
  "items": [],
  "facet": []
 },
 "ops_request_misc": "%7B%22request%5Fid%22%3A%22162642716516781913069826%22%2C%22scm%22%3A%2220140713.110229359..%22%7D",
 "tracer": "",
 "request_id": "162642716516781913069826",
 "errors": [
  {
   "code": 6127,
   "message": "Attribute does not exist."
  }
 ],
 "status": "FAIL"
}

• **Remarque : Un status à FAIL indique qu'une error s'est produite et qu'aucun result n'a été retourné. Cependant, une error peut toujours survenir même lorsque le status est OK et que des résultats sont retournés. Par exemple, vous pouvez recevoir des résultats malgré une 1000 server error (délai d'attente de recherche dépassé) ou une erreur 2112 (aucun index spécifié pour le fine ranking).**

Dépannage des résultats de requête

Si les résultats retournés par un appel d'API de recherche ne correspondent pas à vos attentes (résultats incohérents, absence de résultats ou nombre de résultats inattendu), utilisez les méthodes suivantes pour résoudre le problème :

• Comparez les instructions de requête utilisées par l'API et la page Search Test : Si les résultats d'un appel d'API diffèrent de ceux affichés sur la page Search Test de la console, comparez les instructions de requête réellement envoyées par chacun et vérifiez les différences dans la clause query.

• Vérifiez l'existence des données : Interrogez les données directement par leur clé primaire id pour confirmer leur existence. Cela permet d'écarter les problèmes liés aux délais de synchronisation des données.

• Résolvez les problèmes de tokenisation : Si vous soupçonnez que la tokenisation est à l'origine de résultats inattendus, ajoutez une intervention de tokenisation personnalisée pour optimiser les résultats.

• Ajustez la précision des requêtes vectorielles : Pour les requêtes vectorielles, si les résultats ne sont pas conformes aux attentes, essayez d'arrondir la valeur de la requête à 5 décimales et relancez la requête.

• Ordre de dépannage en l'absence de résultats :

  1. Vérifiez d'abord si total dans la réponse est égal à 0. total représente le nombre total de résultats dans le moteur correspondant aux critères de requête. Cette valeur est optimisée lorsque le nombre de résultats est élevé (voir la description des différences entre total, viewtotal et num dans la section « Réponse » de ce document).

  2. Si total n'est pas égal à 0 mais qu'aucun items n'est retourné, vérifiez les paramètres start et hit dans la clause config.

Recherche par défilement

Pour optimiser la vitesse, la recherche traditionnelle retourne un nombre limité de résultats parmi les plus pertinents. Par exemple, la search method peut rappeler un maximum de 5 000 documents. Lorsque vous avez besoin de davantage de résultats pour l'analyse, utilisez l'scroll API pour récupérer un ensemble de résultats plus vaste.

Clauses prises en charge

• Clause query

• Clause config (le paramètre start n'a aucun effet)

• Clause filter

• Clause sort (prend en charge uniquement un seul champ de type INT ; API v3 et SDK uniquement)

URL

Requête initiale

/v3/openapi/apps/$app_name/search?search_type=scan&scroll=1m&[query parameters]

Requête suivante

/v3/openapi/apps/$app_name/search?scroll_id=$scroll_id&scroll=1m&[query-parameters]

• $app_name : Nom de l'application.

• Les URL ci-dessus omettent l'adresse de l'hôte de l'application.

• Les deux URL de requête scroll ci-dessus omettent les en-têtes de requête, les paramètres de requête et l'encodage. Pour un exemple d'URL complète, consultez la description ci-dessous.

• La méthode scroll offre une prise en charge limitée de nombreuses fonctionnalités. Pour une liste détaillée des limitations, consultez les remarques ci-dessous.

Protocole de requête

HTTP

Méthode de requête HTTP

GET

Formats pris en charge

JSON

Paramètres de requête

Paramètre	Type	Obligatoire	Valeur	Valeur par défaut	Description
scroll	string	Oui	week, day, hour, minute, second		Définit la durée de maintien du contexte de recherche pour la prochaine requête scroll. Vous devez définir ce paramètre pour chaque requête. Par exemple, utilisez 1m pour 1 minute. Unités de temps prises en charge : w (semaine), d (jour), h (heure), m (minute) et s (seconde).
search_type	string	Oui	scan		Obligatoire pour la requête initiale. Pour les requêtes suivantes, omettez ce paramètre et utilisez le scroll_id pour récupérer le lot de résultats suivant.
scroll_id	string	Oui			La requête initiale retourne un scroll_id mais aucun document. Pour les requêtes suivantes, transmettez le scroll_id de la réponse précédente. Chaque réponse suivante retourne un nouveau scroll_id et le lot suivant de documents correspondants.
Clause query	string	Oui			Définit les critères de recherche.
Clause config	string	Oui			Spécifie le format de réponse et le nombre de documents à retourner.
Clause filter	string	Non			Définit les critères de filtrage.
Clause sort	string	Non			Détermine les conditions de tri des documents. Prend uniquement en charge le tri sur un seul champ entier. Cette clause est disponible uniquement dans l'API V3 et les SDK.
Paramètre fetch_fields	string	Non			Spécifie les champs de l'application à retourner dans les résultats.

Réponse

Paramètre	Type	Description
status	string	État de la requête. OK indique un succès et FAIL un échec. En cas d'échec, reportez-vous au code d'erreur retourné pour résoudre le problème.
request_id	string	ID de la requête, utilisé principalement pour le dépannage.
result	string	Charge utile de la réponse, comprenant le temps de recherche (searchtime), le nombre total (total), le nombre de résultats dans cette réponse (num), le nombre maximal de résultats pour la requête (viewtotal), la liste des résultats de recherche (items), les résultats de facette (facet) et l'ID de défilement (scroll_id).
errors	string	Contient les informations d'erreur, y compris le message d'erreur dans le champ error_message. Pour obtenir une explication de chaque error_code, reportez-vous à la documentation Codes d'erreur.

Remarque

L'opération scroll retourne les résultats uniquement au format fulljson ou JSON.

Défilement

Remarque

Remarque : Dans la clause config, start est ignoré. Utilisez la valeur hit pour spécifier le nombre de documents à retourner par requête. Les fonctionnalités telles que aggregate, distinct et les expressions de classement grossier à fin ne sont pas prises en charge. La clause sort prend uniquement en charge le tri sur un seul champ INT. Vous ne pouvez pas effectuer de requêtes scroll sur plusieurs applications. Fournir un scroll_id invalide retourne une erreur. Les seuls formats de réponse pris en charge sont fulljson et JSON. La première requête retourne uniquement un scroll_id et aucune donnée de document. Pour récupérer les données, envoyez une requête suivante avec le scroll_id de la réponse précédente.

Première requête

Remarque

Cet exemple omet les détails tels que les en-têtes de requête et l'encodage.

http://$host/v3/openapi/apps/app_schema_demo/search?query=config=start:0,hit:1,format:fulljson,rerank_size:200&&query=name:'search'&&sort=+id&&filter=id>0&search_type=scan&scroll=1m&fetch_fields=id;name;phone;int_arr;literal_arr;float_arr;cate_id

Réponse réussie

{
  "status": "OK",
  "request_id": "150150574119953661605242",
  "result": {
    "searchtime": 0.005029,
    "total": 1,
    "num": 0,
    "viewtotal": 1,
    "scroll_id": "eJxtUMtuhDAM/BrvOYQC5cABdulvRFFIirsm2TpBavv1Ndut1EMlS36NZ0Y2ZHMxbueceAjIuWCMnrPjRITLyfzZm83y9V QVGT8x80U3PxQNUqieVZV1/an4ItbTUBPSx5wgXqKdvOSbmuKR8ZYjGWWirB4tvToAiX7u3G2eCNK77vnz8GlGPAV6suKBeqxAn0OiTd7NGEnesspyoyFLF6hecn4JUKjVgp0K3FnkfMfIyPoDuYWegX9GeYOpicY9TG8gwOSuBL04X1 MMg3ROwCesLlG6X7a2o=",
    "items": [],
    "facet": []
  },
  "errors": [],
  "tracer": ""
}

Requêtes suivantes

Remarque

Cet exemple omet les détails relatifs aux en-têtes de requête et à l'encodage.

http://$host/v3/openapi/apps/app_schema_demo/search?fetch_fields=id;name;phone;int_arr;literal_arr;float_arr;cate_id&query=config=start:0,hit:1,format:fulljson,rerank_size:200&&query=name:'search'&&sort=+id&&filter=id>0&scroll=1m&scroll_id=eJxtUMtuhDAM/BrvOYQC5cABdulvRFFIirsm2TpBavv1Ndut1EMlS36NZ0Y2ZHMxbueceAjIuWCMnrPjRITLyfzZm83y9V+QVGT8x80U3PxQNUqieVZV1/an4ItbTUBPSx5wgXqKdvOSbmuKR8ZYjGWWirB4tvToAiX7u3G2eCNK77vnz8GlGPAV6suKBeqxAn0OiTd7NGEnesspyoyFLF6hecn4JUKjVgp0K3FnkfMfIyPoDuYWegX9GeYOpicY9TG8gwOSuBL04X1+MMg3ROwCesLlG6X7a2o=

Résultat

{
  "status": "OK",
  "request_id": "150150574119952551519970",
  "result": {
    "searchtime": 0.006293,
    "total": 1,
    "num": 1,
    "viewtotal": 1,
    "scroll_id": "eJxNT9tugzAM/RrznIRC4YEHaNlvRFFIhteQtE6Qtn39TNdJk2z5dnx8rIPJRdudcqKhl60Uir2Vp06ISv8b6s3QbZCVzpaCdp93XXBzg2wEW9MJ2dWq8q7YVXt0YckDLlBP0WyOw31N8YgYizZEnAUsjkx4VT4k8zexpjiNS/XYHX0NNkWP71BfVyxQjxLUxSfazFH4PYSPnCL3iMniDZq3jN98aFRCgGrZniy8/itkBHWGuYVeQH+B+QzTCUZ1NJ9gj4FVMfrQPr8Y+Hk+dgU14fIDVhtfTw==",
    "items": [
      {
        "fields": {
          "cate_id": "0",
          "float_arr": "0",
          "id": "1",
          "int_arr": "0",
          "literal_arr": "search",
          "name": "search",
          "phone": "123****5678",
          "index_name": "app_schema_demo"
        },
        "property": {},
        "attribute": {},
        "variableValue": {},
        "sortExprValues": [
          "1"
        ]
      }
    ],
    "facet": []
  },
  "errors": [],
  "tracer": ""
}