Asking Data Questions in Natural Language

Function

This is a natural language query API that allows you to input data query questions in natural language and receive the corresponding SQL and data as output.

URI

POST /v1/{project_id}/nl-query

**Table 1** URI parameter
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For how to obtain the project ID, see Obtaining a Project ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. Obtain a user token by calling IAM's "Obtaining a User Token" API. X-Subject-Token in the response header is the desired user token.
X-Workspace-Id	Yes	String	Workspace ID. For how to obtain it, see Obtaining a Workspace ID.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
subject_id	Yes	String	ID of the intelligent analysis assistant.
dialog_id	Yes	String	Dialog ID. If you do not want to trigger multi-turn Q&A, you need to pass in a different dialog ID each time you make a request.
message_content	Yes	String	Question.
need_insight	No	Boolean	Whether intelligent insights are required.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
query_data	Array<Array<QueryCellInfo>>	Data queried by the user.
sql_text	String	SQL statements generated by the query.
insight	String	Intelligent insights generated by the query.

**Table 5** QueryCellInfo
Parameter	Type	Description
caption	String	Attribute name, which is sourced from the dataset configuration information.
data_type	String	Attribute type. Enumerated values: DATE NUMBER STRING
level_type	String	Date type. Enumerated values: yearLevel quarterLevel monthLevel weekLevel dayLevel hourLevel minuteLevel secondLevel ymdhmsLevel
cell_raw_value	Object	Original value of a cell.
cell_value	Object	Converted value of a cell, which is used for display purposes.
model_type	String	Attribute type. The options include measure (metric), dimension, and metric (indicator). Enumerated values: measure dimension metric
cell_converted_value	String	Converted value of a cell that is of the String type. It is used to ensure accuracy by converting the value to a String type when the number is too large.

Example Request

Ask data questions in natural language.

POST https://{endpoint}/v1/{project_id}/nl-query
{
  "message_content" : "What was the company's revenue in November of last year?",
  "dialog_id" : "66xxxx02x5axxx9xx12fxxx9c2xxxx6d",
  "subject_id" : "xa4axxx4-9xx9-4xx2-9xxx-3axxxxf4a5c3"
}

Example Response

Status code: 200

The request for the nl-query parameter is successful.

{
  "query_data" : [ [ {
    "caption" : "Revenue",
    "data_type" : "NUMBER",
    "level_type" : null,
    "cell_raw_value" : null,
    "cell_value" : "Revenue",
    "model_type" : "measure",
    "cell_converted_value" : null
  }, {
    "caption" : "Revenue",
    "data_type" : "NUMBER",
    "level_type" : null,
    "cell_raw_value" : "423xxx214.32",
    "cell_value" : "423xxx214.32",
    "model_type" : "measure",
    "cell_converted_value" : null
  } ] ],
  "sql_text" : "SELECT xxx AS xxx FROM xxx.xxx AS xxx",
  "insight" : "Query results: The company's revenue in November of last year was xxx. Suggested areas for exploration: xxx. Business recommendations: xxx."
}