Use the HA3 access engine to initiate search requests - OpenSearch

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

URL

query?query=fetch_fields:name&&config=start:0,hit:100,format:json&&cluster=general&&sort=id

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 in this topic.

Protocol

HTTP

Request method

GET

Supported format

JSON

Request signature

You can calculate the request signature by using the parameters described in the following table. The request signature is stored in the authorization parameter.

Parameter	Type	Description
accessUserName	string	The username. You can view the username in the API Endpoint section of the Instance Details page.
accessPassWord	string	The password. You can change the password in the API Endpoint section 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 value format for the authorization parameter:

cm9vdDp******mdhbA==

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

Example:

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

Request parameters

Parameter	Type	Required	Description
query	string	Yes	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.
query clause	string	Yes	Specifies search conditions.
config clause	string	No	Specifies the format of search results and the number of documents to be retrieved.
filter clause	string	No	Specifies filter conditions.
sort clause	string	No	Specifies the conditions that are used to sort documents.
aggregate clause	string	No	Collects statistical information.
distinct clause	string	No	Extracts documents from each user. This way, the documents of each user can be displayed.
kvpairs clause	string	No	Defines the parameters used in mutable parts of a sort expression.

Usage of request parameters

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

Response parameters

Parameter	Type	Description
requestId	string	The query ID. This parameter is used for troubleshooting.
result	JSON	The search results.
code	string	The error code returned if the request failed.
message	string	The error message returned if the request failed.

Response parameters 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 parameter is displayed only if the format of the config clause is XML or fullJSON. By default, the variableValue parameter is not displayed if the format of the config clause is JSON.
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 cURL command

curl --location --request GET 'http://ha-*****.aliyuncs.com/query?query=query=index_id:1%26%26config=start:0,hit:100,format:json%26%26cluster=general%26%26sort=id' \
--header 'authorization: Basic bWF************yZ2Fs' \
--header 'host: ha-cn-******aliyuncs.com'

Note

In the preceding 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

{
  "requestId": "70028435-****-****-****-42A2CBD360F3",
	"result": {
		"searchtime": 0.003488,
		"numHits": 1,
		"totalHits": 1,
		"coveredPercent": 100,
		"items": [
			{
				"fields": {
					"id": "1",
					"embedding": "0.00156,-0.09226,-0.09548,0.00942,0.06419,0.07005",
					"url": "url_address"
				},
				"properties": {
					
				},
				"attributes": {
					
				},
				"variableValues": {
					
				},
				"sortExprValues": [
					"10000"
				]
			}
		],
		"facet": []
	}
}

Sample error response

{
    "requestId": "70028435-****-****-****-42A2CBD360F3",
    "code": "InstanceNotExist",
    "message": "Instance not exist, can't query"
}