All Products
Search
Document Center

OpenSearch:Initiate search requests

Last Updated:Feb 28, 2024

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

Protocol

HTTP

Request method

GET

Supported format

JSON

Request signature

You can calculate the request signature by using the following parameters.

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 modify 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 value format returned 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

Value range

Default value

Description

query

string

Yes

The body of the search request. This parameter cannot be left empty. 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 retrieved documents.

filter clause

string

No

Specifies filter conditions.

sort clause

string

No

Specifies the sort order for the retrieved documents.

aggregate clause

string

No

Specifies the statistics about the retrieved documents.

distinct clause

string

No

Extracts documents from each user so that the documents of each user can be displayed.

kvpairs clause

string

No

Assigns values to fields that are referenced in the mutable part 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 ID of the request, which is used for troubleshooting.

result

JSON

The return result.

code

string

The error code.

message

string

The error message.

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 the results is large, the value of the total parameter 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 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

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