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. OpenSearch provides advanced and standard applications. This parameter is required. Search requests are sent to the online version of the application.

• The sample URL omits information such as parameters in the request header and the encoding method.

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

• 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 the OpenSearch API V3.

Usage of request parameters

• query: You can specify multiple clauses to meet various search requirements. The clauses in the query parameter are connected by &&.

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

• qp: The qp parameter that is set in an SDK or an API operation takes precedence over the query analysis rules that are specified in the OpenSearch console.

• 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 the 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

    • Disable the re-search feature: disable=re_search

• first_rank_name: The first_rank_name parameter that is set in an SDK or an API operation takes precedence over the rough sort expression that is specified in the OpenSearch console.

• second_rank_name: The second_rank_name parameter that is set in an SDK or an API operation takes precedence over the fine sort expression that is specified in the OpenSearch console.

• user_id:

  • When you set 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 set the user_id parameter when you report behavior data in the same way as you set the user_id parameter in the search request.

• Format of the abtest parameter:abtest=urlencode(scene_tag:urlencode(\$scene),flow_divider:urlencode(\$value)), where urlencode is the URL encoding function.

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

  • scene_tag: the indicator of the test scene. If you do not configure tests for search requests in all scenes, this parameter is not required.

• 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 to train algorithms such as category prediction models. We recommend that you set 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 based on only the threshold of total hits.

  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

• summary:

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

  • The summary_element parameter and the pair of the summary_element_prefix and summary_element_postfix parameters affect each other. The configuration that appears latter takes precedence over the configuration that appears former.

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

  • The summary parameter that is set in an SDK or an API operation takes precedence over 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 engine returns results the number of which 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 total parameter is usually 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.

• 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 of the config clause is XML or fullJSON, and is not displayed when the format is JSON by default.

• 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

Response in the JSON format

{
    "status": "OK",
    "request_id": "155310917017444091100003",
    "result": {
        "searchtime": 0.031081,
        "total": 1,
        "num": 1,
        "viewtotal": 1,
        "compute_cost": [
            {
                "index_name": "84922",
                "value": 0.292
            }
        ],
        "items": [
            {
                "cat_id": "84922",
                "text_field": "The Basketball legend Kobe likes meinv",
                "index_name": "84922"
            }
        ],
        "facet": []
    },
    "qp": [
        {
            "app_name": "84922",
            "query_correction_info": [
                {
                    "index": "default",
                    "original_query": "Applet iphone charger",
                    "corrected_query": "Apple iphone charger",
                    "correction_level": 1,
                    "processor_name": "spell_check"
                }
            ]
        }
    ],
    "errors": [],
    "tracer": "",
    "ops_request_misc": "%7B%22request%5Fid%22%3A%22155310917017444091100003%22%7D"
}

Error response

{
    "status": "OK",
    "request_id": "150149648719953661651650",
    "result": {
        "searchtime": 0.402225,
        "total": 1,
        "num": 0,
        "viewtotal": 0,
        "items": [
         {
                "fields": {
                    "id": "10",
                    "name": "This is the title of a new <em>document</em>",
                    "phone": "13900001111",
                    "index_name": "app_schema_demo"
                },
                "property": {},
                "attribute": {},
                "variableValue": {},
               "sortExprValues": [
                    "10",
                    "10000.1354238242"
                ]
            }
        ],
        "facet": []
    },
    "errors": [
        {
            "code": 1000,
            "message": "Server error."
        }
    ],
    "tracer": "",
    "ops_request_misc":"%7B%22request%5Fid%22%3A%22156680563319723149105067%22%2C%22scm%22%3A%2220140713.115106..%22%7D"
}

• 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 1000 server error that indicates that the search times out or 2112 that indicates that the index specified in the fine sort is invalid, results may be returned.

For regular searches, the purpose is to retrieve the most matched results in the shortest period of time possible. Therefore, the number of documents that can be contained in return results is limited. For example, the return results of a regular search cannot contain more than 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, which supports sorting based on a single field 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 also omits the endpoint that is used to connect to OpenSearch.

• The preceding two scroll request URLs omit information such as parameters in the request header 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

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=

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": "13900001111",
          "index_name": "app_schema_demo"
        },
        "property": {},
        "attribute": {},
        "variableValue": {},
        "sortExprValues": [
          "1"
        ]
      }
    ],
    "facet": []
  },
  "errors": [],
  "tracer": ""
}