Initiate search requests by using the RESTful API - OpenSearch

OpenSearch provides diverse search syntax to meet your search requirements in a variety of scenarios.

URL

/{indexName}/search

The sample URL omits information such as request headers and the encoding method.
The sample URL also omits the endpoint that is used to connect to an OpenSearch application.

Protocol

HTTP

Request method

POST

Supported format

JSON

Request signature

You can use the following method to calculate the request signature. The request signature is stored in the authorization header.

Parameter	Type	Description
accessUserName	String	The username. You can view the username on the Network Information tab of the Instance Details page.
accessPassWord	String	The password. You can change the password on the Network Information tab of the Instance Details page.

import com.aliyun.darabonba.encode.Encoder;
import com.aliyun.darabonbastring.Client;

public class GenerateAuthorization {

    public static void main(String[] args) throws Exception {
        String accessUserName = "username";
        String accessPassWord = "password";
        String realmStr = "" + accessUserName + ":" + accessPassWord + "";
        String authorization = Encoder.base64EncodeToString(Client.toBytes(realmStr, "UTF-8"));
        System.out.println(authorization);
    }
}

Valid format for the value of the authorization header:

cm9vdDp******mdhbA==

Note: You must add the Basic prefix when you specify the authorization header in an HTTP request.

authorization: Basic cm9vdDp******mdhbA==

Request parameters

Parameter	Type	Required	Description
query	String	Yes	The body of the search request. This parameter cannot be left empty. The following clauses are supported: query clause, config clause, sort clause, filter clause, aggs clause, distinct clause, and kvpairs clause.
query clause	String	Yes	The search conditions.
config clause	String	No	The format of search results and the number of documents to retrieve.
filter clause	String	No	The filter conditions.
sort clause	String	No	The conditions that are used to sort documents.
aggs clause	String	No	The clause that is used to collect statistical information.
distinct clause	String	No	The clause that is used to extract documents from each user so that the documents of each user can be displayed.
kvpairs clause	String	No	The clause that is used to define the parameters used in mutable parts of a sort expression.

Sample request body

{
  "query": "index_id: 0",
  "config" : {
      "format":"json"
  }
}

Response parameters

Parameter	Type	Description
result	json	The search results.
errors	String	The error message.

Fields in the result parameter:

searchtime: the period of time that was taken by the engine to complete the search. Unit: seconds.
totalHits: the number of results that meet the conditions in the engine for a single search regardless of the config clause. If the number of results is large, this value is optimized.
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 field is returned only if the format parameter of the config clause is set to xml or fulljson. By default, this field is not returned if the format parameter is set to json.
sortExprValues: the sort score of a document.
facet: the statistics returned by the aggs clause.
Field of the ARRAY type: If the response is in the JSON or fullJSON format, data is separated with tab characters (\t). If the response is in the XML format, data is separated with spaces.

Sample cURL request

curl --location --request POST 'http://ha-cn-*********.public.ha.aliyuncs.com/index_hdfs/search' \
--header 'authorization: Basic *******************' \
--header 'host: ha-cn-*********.public.ha.aliyuncs.com' \
--header 'Content-Type: application/json' \
--data-raw '{
  "query": "index_id: 1",
  "config" : {
      "format":"json"
  }
}'

Note

In this example, a public endpoint is used. For more information, see the "Network Information tab" section in the Instance details topic.

Sample search responses

Sample success response

{
    "result": {
        "searchtime": 0.010385,
        "numHits": 1,
        "totalHits": 1,
        "coveredPercent": 100.0,
        "items": [
            {
                "fields": {
                    "id": "1",
                    "name": "aliyun",
                    "age": "20"
                },
                "properties": {},
                "attributes": {},
                "variableValues": {},
                "sortExprValues": [
                    "10000"
                ]
            }
        ],
        "facet": []
    },
    "errors": []
}

Sample error response

{
    "result": {
        "searchtime": 0.000094,
        "numHits": 0,
        "totalHits": 0,
        "coveredPercent": 0.0,
        "facet": []
    },
    "errors": [
        {
            "code": 1013,
            "message": "QueryClause: index not exist. Index name:index_id"
        }
    ]
}