文档首页/ 智能数据洞察 DataArts Insight/ API参考/ 智能分析助手/ 自然语言查数接口 - InvokeNlQuery
更新时间:2025-11-25 GMT+08:00
分享

自然语言查数接口 - 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。

取值范围:

不涉及

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

状态码

状态码

描述

200

nl-query请求返回体。

错误码

请参见错误码

相关文档