All Products
Search
Document Center

Initiate search requests

Last Updated: Sep 10, 2021

OpenSearch provides various search syntax to meet your search requirements in various scenarios.

URL

/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.

Protocol

HTTP

Request method

GET

Supported format

JSON

Request parameters

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

Parameter

Type

Required

Valid value

Default value

Description

query

string

Yes

Required. The body of the search request. The following clauses are supported: config clause, query clause, sort clause, filter clause, aggregate clause, distinct clause, and kvpairs clause.

fetch_fields

string

All display fields

The fields to be retrieved in this search. Separate multiple fields with semicolons (;). The fields correspond to default display fields in the OpenSearch console.

qp

string

Available rules

The query analysis rules to be used. Separate multiple rules with commas (,).

disable

string

No

Disables the enabled features that are specified by specific parameters.

first_rank_name

string

Name of the default rough sort expression

The name of the rough sort expression.

second_rank_name

string

Name of the default fine sort expression

The name of the fine sort expression.

user_id

string

No

The ID of your user that initiates the search request. Valid values: the long member ID of your user and the International Mobile Equipment Identity (IMEI) of the mobile device of your user. The former takes precedence over the latter.

abtest

string

No

This parameter is required if you use the A/B test feature.

raw_query

string

No

This parameter is required to train algorithms such as category prediction. We recommend that you set this parameter for all search requests.

re_search

string

No

The re-search policy. The re-search policy can be configured based on only the threshold of total hits.

biz

string

No

The business information about the search request, such as the business type of the source from which the search request is sent.

summary

string

The settings of search result summaries in OpenSearch

The settings of search result summaries. You can specify specific fields to be highlighted in red or truncated.

from_request_id

string

No

The source request that guides this search request. If the search query is recommended by the features such as drop-down suggestions, top searches, and hints, you can assign the ID of the search request that searches for the recommended search query to this parameter. This way, various metrics of the features can be calculated. You can assess the effect of the features based on the metrics and optimize the features based on the assessment result. For more information, see Drop-down suggestions.

query clause

string

Yes

Specifies search conditions.

config clause

string

Yes

Specifies the format of search results and the number of retrieved documents.

filter clause

string

Specifies filter conditions.

sort clause

string

Specifies the conditions that are used to sort documents. The sort clause supports sorting based on a single field of the INT type. The version of the OpenSearch API and OpenSearch SDKs must be V3.

fetch_fields

string

The fields to be returned in search results.

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.

Parameter

Type

Required

Valid value

Default value

Description

summary_field

string

Yes

The field for which you want to configure a summary.

summary_element

string

No

em

The HTML tag that is used to highlight terms in red. Left and right angle brackets are removed from the HTML tag.

summary_ellipsis

string

No

...

The ellipsis (...) at the end of the summary.

summary_snipped

int

No

1

The number of segments that are required in a summary.

summary_len

string

No

The length of a summary.

summary_element_prefix

string

No

The prefix that is used to highlight terms in red. The prefix must be a complete HTML tag, such as <em>.

summary_element_postfix

string

No

The suffix that is used to highlight terms in red. The suffix must be a complete HTML tag, such as </em>.

Response parameters

Parameter

Type

Description

status

string

The execution result of the search. Valid values: OK and FAIL. A value of OK indicates that the search is successful. A value of FAIL indicates that the search failed. In this case, troubleshoot errors based on the error code.

request_id

string

The ID of the request, which is used for troubleshooting.

result

string

The information about search results, which include the searchtime, total, num, viewtotal, items, and facet parameters.

errors

string

The error information, in which the error_message parameter indicates the error message. For more information about error codes, see Error codes.

  • 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": "18312345678",
                    "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.

Scroll searches

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.

Protocol

HTTP

HTTP request method

GET

Supported format

JSON

Request parameters

Parameter

Type

Required

Valid value

Default value

Description

scroll

STRING

Yes

You can set a value in units of weeks, days, hours, minutes, or seconds.

The validity period of the scroll ID to be returned for the first execution of the scroll search, in units of weeks (w), days (d), hours (h), minutes (m), or seconds (s). Example: 1m.

search_type

STRING

Yes

scan

The type of the scroll search. You need to specify this parameter only for the first execution of the scroll search. For the subsequent executions of the scroll search, you can specify the scroll_id parameter.

scroll_id

string

Yes

The ID that is returned for the scroll search. When you execute a scroll search for the first time, only a scroll ID is returned. To obtain search results, use this ID to execute the scroll search again. For subsequent executions of the scroll search, this ID is both required as a request parameter and returned as a response parameter.

query clause

string

Yes

Specifies search conditions.

config clause

string

Yes

Specifies the format of search results and the number of retrieved documents.

filter clause

string

Specifies filter conditions.

sort clause

string

Specifies the conditions that are used to sort documents. The sort clause supports sorting based on a single field of the INT type. The version of the OpenSearch API and OpenSearch SDKs must be V3.

fetch_fields

string

The fields to be returned in search results.

Response parameters

Parameter

Type

Description

status

string

The execution result of the search. Valid values: OK and FAIL. A value of OK indicates that the search is successful. A value of FAIL indicates that the search failed. In this case, troubleshoot errors based on the error code.

request_id

string

The ID of the request, which is used for troubleshooting.

result

string

The return results, which include the searchtime, total, num, viewtotal, items, facet, and scroll_id parameters.

errors

string

The error information, in which the error_message parameter indicates the error message. For more information about error codes, see Error codes.

Note

Return results of scroll searches support only the fullJSON and JSON formats.

Sample scroll search

Note

When you execute a scroll search, the start parameter that you specify in the config clause does not take effect. You can use the hit parameter in the config clause to specify the number of documents to be returned for each execution. Scroll searches do not support the aggregate, distinct, and rank clauses. Scroll searches support sorting based on a single field of the INT type. Scroll searches across applications are not supported. If the value of the scroll_id parameter in a request is invalid, an error occurs. Return results of scroll searches support only the fullJSON and JSON formats. When you execute a scroll search for the first time, only a scroll ID is returned. To obtain document data, use this ID to execute the scroll search again.

First request

Note

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

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

Note

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

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