Process searches using the RESTful API-OpenSearch(Open Search)-阿里云帮助中心

Searches an index and returns matching documents based on the query conditions you specify.

Endpoint

POST /{indexName}/search

The endpoint shown above omits the host address and request headers. For the full host address, see Network information.

Attribute	Value
Protocol	HTTP
Method	POST
Format	JSON

Authentication

The authorization header uses HTTP Basic authentication. Encode your credentials as Base64(accessUserName:accessPassWord) and prefix the result with Basic.

Credentials

Parameter	Type	Description
`accessUserName`	String	The username. Find it on the Instance Details > Network Information page.
`accessPassWord`	String	The password. Modify it on the Instance Details > Network Information page.

Generate the authorization value

The following Java example generates a Base64-encoded authorization value from your credentials:

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);
    }
}

The output is a Base64-encoded string:

cm9vdDp******mdhbA==

Set the authorization request header with the Basic prefix:

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

Request body parameters

The request body contains a query field that accepts a search string composed of one or more clauses.

Parameter	Type	Required	Description
`query`	String	Yes	The search string. Cannot be empty. Supports the query clause, config clause, sort clause, filter clause, aggs clause, distinct clause, and kvpairs clause.

Supported clauses

Clause	Required	Description
`query clause`	Yes	Sets the search conditions.
`config clause`	No	Sets the response format and the number of documents to return.
`filter clause`	No	Sets filter conditions to narrow search results.
`sort clause`	No	Sets the sort order for returned documents.
`aggregate clause`	No	Sets aggregation statistics.
`distinct clause`	No	Deduplicates results by extracting documents for each user, ensuring results from each user are represented.
`kvpairs clause`	No	Defines custom parameters for the variable parts of sort expressions.

Request body example

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

Response parameters

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

result object fields

Field	Description
`searchtime`	The time, in seconds, that the engine took to process the request.
`totalHits`	The estimated total number of documents matching the query. This is an estimate when the result set is large. Does not account for the config clause.
`items`	The retrieved documents. Each item contains a `fields` object with the document content.
`sortExprValues`	The sort expression score for each document.
`variableValue`	The result of a custom parameter, such as a calculated distance. Returned only when the `format` parameter in the config clause is set to `xml` or `fulljson`. Not returned in `json` format by default.
`facet`	Aggregation results returned by the aggregate clause.

In json and fulljson formats, values in array fields are separated by \t. In xml format, values are separated by spaces.

Examples

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

The endpoint in this example uses the public network domain. For endpoint options, see Network information.

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