Query analysis API - OpenSearch - Alibaba Cloud Documentation Center

This topic provides details of the API of the query analysis service.

Service name

Service ID

Service description

QPS limit for API calls (Alibaba Cloud account and RAM users)

Query analysis service

ops-query-analyze-001

Provides query content analysis services powered by large language models and NLP capabilities. The service includes intent detection, similar question expansion, and NL2SQL processing for user input queries, effectively enhancing the retrieval and answer generation performance in RAG scenarios.

To use the NL2SQL service, you must first configure information such as table schemas and query examples in the console. For more information, see Configure the NL2SQL feature. After configuration, you can call the Query Analysis - NL2SQL service through the API by following the instructions in this document.

Note

To apply for higher QPS, submit a ticket.

The authentication information is obtained.
When you call an AI Search Open Platform service by using an API, you need to authenticate the caller's identity.
The service access address is obtained.
You can call a service over the Internet or a virtual private cloud (VPC). For more information, see Get service registration address.

General description

The request body must not exceed 8MB.

Request method

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/query-analyze/{service_id}

host: The address for calling the service, supports calling API services through both public network and VPC. For more information, see Query service endpoint.
service_id: The system built-in service ID, such as ops-query-analyze-001.

Request parameters

Header parameters

API-KEY authentication

Parameter	Type	Required	Description	Example value
Content-Type	String	Yes	Request type: application/json	application/json
Authorization	String	Yes	API-Key	Bearer OS-d1**2a

Body parameters

Parameter	Type	Required	Description	Example value
query	String	Yes	Content of this request.	How many people?
history	List<Message>	No	History messages.	[{ "content": "Where is the capital of China", "role": "user" }, { "content": "Beijing", "role": "assistant" }]
history.content	String	No	Message content.	Where is the capital of China
history.role	String	No	Message sender, current optional values for roles: system, user, assistant.	user
unctions	List<Function>	No	The enabled functions and corresponding parameters. Valid values: pre:Pre-processing. intent:Intent detection. similar_query:Expansion of similar query nl2sql:Natural language to SQL Note: By default, pre, intent, and similar_query are enabled. When nl2sql is enabled, intent and similar_query are disabled by default.
functions[].name	String	No	If you specify a function, you must specify name.
functions[].parameters	Map	No	The parameters of the function.
functions[].parameters.enable	boolean	No	Specifies whether to enable the function.	true

Response parameters

Parameter	Type	Description	Example value
request_id	String	The unique identifier assigned by the system for an API call.	A5B25952-4406-45BF-99EC-E8020246****
latency	Float/Int	Request duration, in ms.	10
result.query	String	Processed request.	How many people
result.queries	List<String>	Generated alternate queries.	[ "How many people in Beijing" ]
result.intent	String	Intent detection result.	Q&A pair
result.sql	Map	The nl2sql result.

Curl request example

curl -XPOST -H"Content-Type: application/json" 
\http://****.opensearch.aliyuncs.com/v3/openapi/workspaces/default/query-analyze/ops-query-analyze-001\
    -H "Authorization: Bearer Your API-Key" \
    -d'{
      "query":"What class is Jack in",
      "history":[
          {
            "role":"user",
            "content":"Where is the capital of China"
          },
          {
            "role":"assistant",
            "content":"Beijing"
          }
        ],
        "functions":[
          {
            "name":"pre",
            "parameters":
              {
                "enable":true
              }
          },
          {
            "name":"intent",
            "parameters":
              {
                "enable":true
              }
            },
            {
              "name":"similar_query",
              "parameters":
                {
                  "enable":true
                }
              },
              {
                "name":"nl2sql",
                "parameters":
                  {
                    "enable":true,
                    "config_name":"n_1726047726"
                  }
                }
              ]
            }'

Response example

Normal response example

{
  "request_id":"023FC760-E273-4163-B2DA-5CF28E2A****",
  "latency":6383,
  "usage":{
      "total_tokens":1082,
      "output_tokens":41,
      "input_tokens":1041
    },
    "result":{
      "query":"What class is Jack from",
      "queries":[
          "The class Jack from"
      ],
      "intent":"Q&A",
      "sql":{
          "text":"SELECT students.class FROM students WHERE students.name = 10002;"
      }
    }
}

Abnormal response example

In case of an error in the access request, the output result will indicate the error reason through code and message.

{
  "request_id":"19C54DAA-AD50-4B37-A48C-912A8F82****",
  "latency":0,
  "code":"InvalidParameter",
  "message":"Required parameter: query missing or invalid, please check the request parameter."
}

Status code description

HTTP status code	Error code	Description
200	-	Request successful, including task failure scenarios. The actual task status needs to be determined from result.status.
404	BadRequest.TaskNotExist	Task does not exist.
400	InvalidParameter	Invalid request.
500	InternalServerError	Internal error.