自然语言查数接口 - InvokeNlQuery

功能介绍

自然语言查数接口。输入为自然语言数据查询问题，返回查询到的数据和对应的SQL。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见权限和授权项。

URI

POST /v1/{project_id}/nl-query

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	参数解释：项目ID。获取方法请参见获取项目ID。约束限制：不涉及取值范围：不涉及默认取值：不涉及

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	参数解释：用户Token。通过调用IAM服务获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。约束限制：不涉及取值范围：不涉及默认取值：不涉及
X-Workspace-Id	是	String	参数解释：工作空间ID。获取方法请参见获取工作空间ID。约束限制：不涉及取值范围：不涉及默认取值：不涉及

表3 请求Body参数
参数	是否必选	参数类型	描述
subject_id	是	String	参数解释：智能分析助手ID。取值范围：不涉及
dialog_id	是	String	参数解释：对话ID。取值范围：不涉及
dataset_id_list	否	Array of strings	参数解释：数据集ID。取值范围：不涉及
message_content	是	String	参数解释：查询问题。取值范围：不涉及
need_insight	否	Boolean	参数解释：是否需要智能见解。取值范围：不涉及
simplify_response	否	Boolean	参数解释：是否简化输出结果。取值范围：不涉及

响应参数

状态码：200

表4 响应Body参数
参数	参数类型	描述
query_data	Array<Array<QueryCellInfo>>	用户所查询到的数据。在请求体simplify_response为False的时候返回。
header	Array of QueryHeaderCell objects	用户所查询到的数据内容的列信息，在请求体simplify_response为true时返回。
data	Array<Array<Object>>	参数解释：用户所查询到的数据内容。取值范围：不涉及
sql_text	String	参数解释：用户查询所生成的SQL。取值范围：不涉及
insight	String	参数解释：用户查询所生成的智能见解。取值范围：不涉及

表5 QueryCellInfo
参数	参数类型	描述
caption	String	参数解释：属性名称，来自数据集配置信息。取值范围：不涉及
data_type	String	参数解释：属性类型。取值范围：不涉及
level_type	String	参数解释：日期类型。取值范围：不涉及
cell_raw_value	Object	参数解释：单元格原始值。取值范围：不涉及
cell_value	Object	参数解释：单元格转换后的值。取值范围：不涉及
model_type	String	参数解释：属性类型。取值范围：度量维度指标
cell_converted_value	String	参数解释： String类型的单元格转换值。取值范围：不涉及

表6 QueryHeaderCell
参数	参数类型	描述
caption	String	参数解释：字段名称。取值范围：不涉及
data_type	String	参数解释：数据类型。取值范围：不涉及
level_type	String	参数解释：日期层级结构。取值范围：不涉及
model_type	String	参数解释：字段类型。取值范围：不涉及

请求示例

自然语言查数。

POST https://{endpoint}/v1/{project_id}/nl-query

{
  "message_content" : "去年11月公司的收入是多少",
  "dialog_id" : "66xxxx02x5axxx9xx12fxxx9c2xxxx6d",
  "subject_id" : "xa4axxx4-9xx9-4xx2-9xxx-3axxxxf4a5c3",
  "need_insight" : true
}

自然语言查数，对结果精简。

POST https://{endpoint}/v1/{project_id}/nl-query

{
  "message_content" : "去年11月公司的收入是多少",
  "dialog_id" : "66xxxx02x5axxx9xx12fxxx9c2xxxx6d",
  "subject_id" : "xa4axxx4-9xx9-4xx2-9xxx-3axxxxf4a5c3",
  "need_insight" : true,
  "simplify_response" : true
}

响应示例

状态码：200

nl-query请求返回体。

{
  "header" : [ {
    "caption" : "收入",
    "data_type" : "NUMBER",
    "level_type" : null,
    "model_type" : "measure"
  } ],
  "data" : [ [ "423xxx214.32" ] ],
  "sql_text" : "SELECT xxx AS xxx FROM xxx.xxx AS xxx",
  "insight" : "查询结果: 去年11月公司的收入为xxx。建议探索的方向：xxx。业务建议：xxx。"
}