How to handle searches with the RESTful API-OpenSearch(Open Search)-阿里云帮助中心

The system provides a rich search syntax to support various search scenarios.

URL

/{indexName}/search

The preceding URL does not include details such as request header parameters and encoding.
The preceding URL does not include the host address for accessing the application.

Request protocol

HTTP

Request method

POST

Supported format

JSON

Signature mechanism

Calculate the signature (authorization) using the following method

Parameter	Type	Description
accessUserName	String	The username. Find it on the Instance Details > Network Information page.
accessPassWord	String	The password. Change it on the Instance Details > Network Information 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);
    }
}

Format of the authorization response

cm9vdDp******mdhbA==

Note: Add the Basic prefix when you set the authorization parameter for an HTTP request. For example:

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

Query body parameters

Parameter	Type	Required	Description
query	String	Yes	The search entity. It cannot be empty. The main supported clauses are query clause, config clause, sort clause, filter clause, aggs clause, distinct clause, and kvpairs clause.
query clause	String	Yes	Sets the search conditions.
config clause	String	No	Sets the data format for document retrieval and the number of documents to retrieve.
filter clause	String	No	Sets the filter conditions.
sort clause	String	No	Sets the document sorting conditions.
aggregate clause	String	No	Sets the statistics information.
distinct clause	String	No	The discretize clause extracts documents for each user. This ensures that each user has an opportunity to have their documents displayed.
kvpairs clause	String	No	Defines parameters for the variable parts of a sort expression in the kvpairs clause.

Query body example

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

Return parameters

Parameter	Type	Description
result	JSON	The actual returned result.
errors	String	The error message.

Description of return parameters:

searchtime: The time the engine takes to process the query, in seconds.
totalHits: The number of results that match the query conditions, excluding the config clause. If the number of results is large, this value is optimized.
items: Contains the retrieved data. The fields object contains the content retrieved from the search.
variableValue: The returned value of a custom parameter, such as the distance value. The variableValue node is displayed only when the format in the config clause is set to xml or fulljson. By default, this node is not displayed for the JSON format.
sortExprValues: The sorting score of the corresponding document.
facet: Stores the information returned by the Aggregate clause.
array field type: The returned data is separated by tab characters (\t) in JSON and fulljson formats, and by spaces in XML format.

curl example

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

The endpoint in the example is a public network access domain name. For more information, see Network Information.

Search examples

Normal 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": []
}

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"
        }
    ]
}