OpenSearch:Initiate search requests

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

• $app_name: the name of the application. An advanced or a standard OpenSearch application has an online version and an offline version. When you initiate a search request, you must specify the ID of the application to which you want to send the request. Generally, you can set this parameter the ID of an online application. You can also specify the ID of an offline application to perform searches in the offline application.

• The sample URL omits information such as the request headers and the encoding method.

• The sample URL also omits the endpoint that is used to connect to an OpenSearch application.

• For more information about the definitions, usage, and example values of all the request parameters that are concatenated in the preceding URL, see the "Request parameters" section of this topic.

HTTP

GET

JSON

For more information about the concatenating rule of the request parameters, see Signature method of OpenSearch API V3.

Usage of request parameters

• query: You can specify multiple clauses to meet various search requirements. Connect the clauses in the query parameter with &&.

• fetch_fields: The size of returned text data has a great impact on search performance. We recommend that you specify only the required fields. The fetch_fields parameter that is configured in an SDK or an API operation overwrites the default display fields that are specified in the OpenSearch console.

• qp: The qp parameter that is configured in an SDK or an API operation overwrites the query analysis rules that are specified in the OpenSearch console.

Note: You can view the validation process and results of the qp parameter on the Search Test page in the OpenSearch console. You cannot view the validation process or results by using an SDK or an API operation.

• disable: You can disable the features that are specified by parameters such as qp, summary, first_rank, second_rank, and re_search.

  Description

  • You can use this parameter to disable specific features during a search.

  • You can disable features such as query analysis, highlights in red, rough and fine sorts, and re-search.

  Parameter format

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

  • Examples:

    • Disable the query analysis feature: disable=qp

    • Disable the spelling correction feature in query analysis: Disable=qp:spell_check. Format: disable=qp:$qp_processor_name. For more information, see QueryProcessor.

    • Disable the re-search feature: disable=re_search

• first_rank_name: The first_rank_name parameter that is configured in an SDK or an API operation overwrites the rough sort expression that is specified in the OpenSearch console.

• second_rank_name: The second_rank_name parameter that is configured in an SDK or an API operation overwrites the fine sort expression that is specified in the OpenSearch console.

• user_id:

  • When you configure this parameter in the search request, you must perform URL encoding on the value of this parameter.

  • The statistics about unique visitors (UVs) are collected based on the parameter when the data statistics feature is used.

  • If the data collection feature is used, we recommend that you configure the user_id parameter when you report behavioral data in the same way as you configure the user_id parameter in the search request.

• abtest: The value of this parameter is in the following format: abtest=urlencode(scene_tag:urlencode(\$scene),flow_divider:urlencode(\$value)). urlencode is the function that is used to encode URLs.

  • We recommend that you replace flow_divider with the ID of your user. You can also use the ID or IP address of the device of your user. This parameter is required.

  • scene_tag: the indicator of the test scene. If you do not specify this parameter in the OpenSearch console, A/B test is run based on the search requests in all scenes.

• raw_query:

  Description

  • This parameter is used for searches based on category prediction. Search results are sorted based on category prediction only when the search query is the same as the value of the raw_query parameter.

  • This parameter is used for the algorithms that are used to train models such as category prediction models. We recommend that you configure this parameter for all search requests.

  • We recommend that you set this parameter to the search query that is entered by your user.

  Parameter format

  raw_query=content

  • content: the original search query.

• re_search:

  Description

  • This parameter is used to configure a re-search policy. The re-search policy can be configured only based on the threshold of total hits.

  • You must enable the query analysis feature if you configure this parameter.

  • During a query, if the weights of query terms after analysis are the same, a re-search is not triggered. You need to configure the weight of each category for the named entity recognition (NER) feature.

  Parameter format

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

  • COUNT: the minimum number of total hits that are allowed if you do not want to trigger a re-search. When the number of total hits is less than the value of the COUNT parameter, a re-search is performed.

  • Example:

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

• biz:

  Description

  • This parameter is used to describe the business information about the request, such as the business type of the source from which the search request is sent.

    Parameter format

    biz=type:$TYPE

  • type: the type of the source from which the search request is sent. You can customize the value of this parameter. This parameter helps collect the statistics about request sources in reports.

  • Example:

    • biz=type:home_page

• vector_threshold:

• summary:

  • The summary_element_prefix and summary_element_postfix parameters must be used in pairs.

  • Either the summary_element parameter or the pair of the summary_element_prefix and summary_element_postfix parameters is valid. Whichever of them is configured later takes effect.

  • Summaries and the settings used to highlight terms in red cannot be separately configured.

  • The summary parameter that is configured in an SDK or an API operation overwrites the settings of search result summaries in the OpenSearch console.

Response parameters

• searchtime: the period of time that was taken by the engine to complete the search. Unit: seconds.

• Difference between the total, viewtotal, and num parameters: The total parameter indicates the number of results that meet the conditions in the engine for a single search regardless of the config clause. If the number of the results is large, the value of the total parameter is optimized. However, to ensure search performance and relevance, the number of results that the engine returns is less than or equal to the value of the viewtotal parameter. If you require paging, the sum of the values of the start and hit parameters must be less than the value of the viewtotal parameter. The value of the total parameter is generally used for display. The num parameter indicates the number of entries returned for this search request. The value of this parameter is limited by the start and hit parameters in the config clause and does not exceed the value of the hit parameter.

• compute_cost: an array with only one map element. The index_name parameter indicates the ID of the application. The value parameter indicates the logical computing units (LCUs) that are consumed in this search request.

• items: the search results. The fields parameter indicates the content of a search result.

• variableValue: the value of a custom parameter, such as the value of the distance parameter. The variableValue parameter is displayed only when the format parameter in the config clause is xml or fulljson. By default, the variableValue parameter is not displayed when the format parameter is set to json.

• sortExprValues: the sort score of a document.

• facet: the statistics returned by the aggregate clause.

• Field of the ARRAY type: If the response is in the JSON or fullJSON format, data is separated by tab characters (\t). If the response is in the XML format, data is separated by spaces.

Sample search responses

JSON format

{
 "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": "Male Jacket Lapel 2021 in Spring and Autumn New Style Youth Thin Casual Zip-up Jacket",
     "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"
}

Sample error response

{
 "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 not exist."
  }
 ],
 "status": "FAIL"
}

• Note: The value of the status parameter is FAIL when an error is reported, and no result is returned. The value of the status parameter is OK when both the error and results are returned. If an error such as the 1000 server error or the 2112 error is returned, results may be returned. The 1000 server error indicates that the search times out. The 2112 error indicates that the index specified in the fine sort is invalid.

In traditional search scenarios, the purpose is to retrieve the most matched results in the shortest period of time. Therefore, the number of documents that can be contained in results is limited. For example, the results of a search can contain up to 5,000 documents. However, in some scenarios, you may need more results for analysis. In this case, you can use scroll searches to obtain more search results.

Supported clauses

• The query clause.

• The config clause: The start parameter is invalid.

• The filter clause.

• The sort clause. You can specify sorting conditions only based on one field and the field must be of the INT type. The version of the OpenSearch API and OpenSearch SDKs must be V3.

URL

First search

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

Subsequent search

/v3/openapi/apps/$app_name/search?scroll_id=$scroll_id&scroll=1m&Request parameters

• $app_name: the name of the application.

• The sample URL omits the endpoint that is used to connect to an OpenSearch application.

• The preceding two scroll request URLs omit information such as parameters in the request header, the request parameters, and the encoding method. For more information about the complete scroll request URL, see the "Sample scroll search" section of this topic.

• Scroll searches support a limited number of features, and most features are not supported. For more information about the feature limits of scroll searches, see the note in the "Sample scroll search" section of this topic.

HTTP

GET

JSON

First request

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

Sample success response

{
  "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": ""
}

Subsequent request

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=

Sample success response

{
  "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": ""
}