What is a search request? How do I initiate a search request? - OpenSearch

Executes a SQL query against an OpenSearch Retrieval Engine Edition instance over HTTP GET and returns results in JSON.

Prerequisites

Before you begin, ensure that you have:

An OpenSearch Retrieval Engine Edition instance
The username and password from the API Endpoint section of the Instance Details page

Request format

Property	Value
Protocol	HTTP
Method	GET
Response format	JSON

Sample URL:

sql?query=SELECT brand, COUNT(*) FROM phone GROUP BY (brand)&&kvpair=trace:INFO;formatType:json

The sample URL omits the endpoint host and request headers. For the full endpoint URL, see the Network Information tab on the Instance Details page.

Authenticate requests

All requests require an authorization header using HTTP Basic Authentication. The header value is the Base64 encoding of username:password.

Signature parameters:

Parameter	Type	Description
`accessUserName`	String	The username. View it in the API Endpoint section of the Instance Details page.
`accessPassWord`	String	The password. Modify it in the API Endpoint section of the Instance Details page.

To generate the Base64-encoded authorization value:

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 generated value looks like:

cm9vdDp******mdhbA==

Include it in the request header with the Basic prefix:

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

Request parameters

Parameter	Type	Required	Description
`query` clause	String	Yes	A complete SQL statement. For supported syntax, see query clause.
`kvpairs` clause	String	No	Additional key-value configuration pairs, such as `trace:INFO;formatType:json`. For available keys and values, see kvpair clause.

Sample cURL request

curl --location --request GET 'http://ha-cn-*******.public.ha.aliyuncs.com/query?sql=query=select * from index_hdf%26%26kvpair=trace:INFO;format:full_json' \
--header 'authorization: Basic ******************' \
--header 'host: ha-cn-*******.public.ha.aliyuncs.com'

This example uses a public endpoint. For endpoint details, see the Network Information tab on the Instance details page.

Response parameters

Parameter	Type	Description
`total_time`	String	The query ID. This parameter is used for troubleshooting.
`covered_percent`	Float	The coverage rate of the query across data shards.
`row_count`	Integer	The number of rows returned.
`format_type`	String	The response format. Reflects the `formatType` value set in the `kvpairs` clause.
`search_info`	Object	Additional search metadata.
`trace`	Array	Trace log entries. Populated when `trace:INFO` or a higher level is set in the `kvpairs` clause.
`sql_result`	Object	The query result set.
`sql_result.data`	2D Array	The result rows. Each inner array represents one row.
`sql_result.column_name`	Array	Column names corresponding to each position in the result rows.
`sql_result.column_type`	Array	Column data types, in the same order as `column_name`.
`error_info`	Object	Error details.
`error_info.ErrorCode`	Integer	The error code. `0` indicates success.
`error_info.Error`	String	A short error identifier. `ERROR_NONE` indicates success.
`error_info.Message`	String	A human-readable error message. Empty on success.

Sample responses

Success response

{
    "total_time": 4.557,
    "covered_percent": 1.0,
    "row_count": 1,
    "format_type": "full_json",
    "search_info": {},
    "trace": [],
    "sql_result": {
        "data": [
            [
                1
            ]
        ],
        "column_name": [
            "id"
        ],
        "column_type": [
            "int64"
        ]
    },
    "error_info": {
        "ErrorCode": 0,
        "Error": "ERROR_NONE",
        "Message": ""
    }
}

Error response

{
    "total_time": 15.96,
    "covered_percent": 0.0,
    "row_count": 0,
    "format_type": "full_json",
    "search_info": {},
    "trace": [],
    "sql_result": {
        "data": [],
        "column_name": [],
        "column_type": []
    },
    "error_info": {
        "ErrorCode": 8010,
        "Error": "call sql plan service failed.",
        "Message": "failed to get sql plan, error message is [IQUAN_EC_INTERNAL_ERROR] internal error : SQL validation failed. From line 1, column 15 to line 1, column 23: Object 'index_hdf' not found\nFrom line 1, column 15 to line 1, column 23: Object 'index_hdf' not found\norg.apache.flink.table.api.ValidationException: SQL validation failed. From line 1, column 15 to line 1, column 23: Object 'index_hdf' not found\n\tat org.apache.flink.table.planner.calcite.FlinkPlannerImpl.org$apache$flink$table$planner$calcite$FlinkPlannerImpl$$validate(FlinkPlannerImpl.scala:149)\n\tat org.apache.flink.table.planner.calcite.FlinkPlannerImpl.validate(FlinkPlannerImpl.scala:108)\n\tat org.apache.flink.table.planner.delegation.ParserImpl.validate(ParserImpl.java:91)\n\tat com.taobao.search.iquan.core.api.impl.SqlQueryableImpl$SqlWorkFlow.validateSql(SqlQueryableImpl.java:646)\n\tat com.taobao.search.iquan.core.api.impl.SqlQueryableImpl$SqlWorkFlow.process(SqlQueryableImpl.java:392)\n\tat com.taobao.search.iquan.core.api.impl.SqlQueryableImpl.select(SqlQueryableImpl.java:134)\n\tat com.taobao.search.iquan.client.common.service.SqlQueryService.sqlQuery(SqlQueryService.java:89)\n\tat com.taobao.search.iquan.client.IquanClient.sqlQuery(IquanClient.java:79)\nCaused by: org.apache.calcite.runtime.CalciteContextException: From line 1, column 15 to line 1, column 23: Object 'index_hdf' not found\n\tat sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)\n\tat sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62)\n\tat sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)\n\tat java.lang.reflect.Constructor.newInstance(Constructor.java:422)\n\tat org.apache.calcite.runtime.Resources$ExInstWithCause.ex(Resources.java:467)\n\tat org.apache.calcite.sql.SqlUtil.newContextException(SqlUtil.java:883)\n\tat org.apache.calcite.sql.SqlUtil.newContextException(SqlUtil.java:868)\n\tat org.apache.calcite.sql.validate.SqlValidatorImpl.newValidationError(SqlValidatorImpl.java:5032)\n\tat org.apache.calcite.sql.validate.IdentifierNamespace.resolveImpl(IdentifierNamespace.java:179)\n\tat org.apache.calcite.sql.validate.IdentifierNamespace.validateImpl(IdentifierNamespace.java:184)\n\tat org.apache.calcite.sql.validate.AbstractNamespace.validate(AbstractNamespace.java:84)\n\tat org.apache.calcite.sql.validate.SqlValidatorImpl.validateNamespace(SqlValidatorImpl.java:1067)\n\tat org.apache.calcite.sql.validate.SqlValidatorImpl.validateQuery(SqlValidatorImpl.java:1041)\n\tat org.apache.calcite.sql.validate.SqlValidatorImpl.validateFrom(SqlValidatorImpl.java:3202)\n\tat org.apache.calcite.sql.validate.SqlValidatorImpl.validateFrom(SqlValidatorImpl.java:3187)\n\tat org.apache.calcite.sql.validate.SqlValidatorImpl.validateSelect(SqlValidatorImpl.java:3450)\n\tat org.apache.calcite.sql.validate.SelectNamespace.validateImpl(SelectNamespace.java:60)\n\tat org.apache.calcite.sql.validate.AbstractNamespace.validate(AbstractNamespace.java:84)\n\tat org.apache.calcite.sql.validate.SqlValidatorImpl.validateNamespace(SqlValidatorImpl.java:1067)\n\tat org.apache.calcite.sql.validate.SqlValidatorImpl.validateQuery(SqlValidatorImpl.java:1041)\n\tat org.apache.calcite.sql.SqlSelect.validate(SqlSelect.java:232)\n\tat org.apache.calcite.sql.validate.SqlValidatorImpl.validateScopedExpression(SqlValidatorImpl.java:1016)\n\tat org.apache.calcite.sql.validate.SqlValidatorImpl.validate(SqlValidatorImpl.java:724)\n\tat org.apache.flink.table.planner.calcite.FlinkPlannerImpl.org$apache$flink$table$planner$calcite$FlinkPlannerImpl$$validate(FlinkPlannerImpl.scala:144)\n\t... 7 more\nCaused by: org.apache.calcite.sql.validate.SqlValidatorException: Object 'index_hdf' not found\n\tat sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)\n\tat sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62)\n\tat sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)\n\tat java.lang.reflect.Constructor.newInstance(Constructor.java:422)\n\tat org.apache.calcite.runtime.Resources$ExInstWithCause.ex(Resources.java:467)\n\tat org.apache.calcite.runtime.Resources$ExInst.ex(Resources.java:560)\n\t... 26 more\n"
    }
}

Error code 8010 indicates a SQL plan failure, typically caused by an invalid table or index name in the query.

Usage notes

If a query exceeds 30 KB in length, use the RESTful API instead. See Initiate search requests by using the RESTful API.