文档首页/ 智能数据洞察 DataArts Insight/ API参考/ 智能分析助手/ 自然语言查数接口
更新时间：2025-05-26 GMT+08:00
在线调试
CLI示例
查看PDF
分享

自然语言查数接口

功能介绍

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

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。如果不想触发多轮问答能力，需每次调用请求时传入不同的dialog_id。

message_content

是

String

查询问题。

need_insight

否

Boolean

是否需要智能见解。

simplify_response

否

Boolean

是否简化输出结果，默认为False。设置为False的时候查询数据为响应体的query_data部分。设置为True的时候查询数据为响应体的header和data部分。

响应参数

状态码：200

表4 响应Body参数

参数

参数类型

描述

query_data

Array<Array<QueryCellInfo>>

用户所查询到的数据。在请求体simplify_response为False的时候返回。

header

Array of QueryHeaderCell objects

用户所查询到的数据内容的列信息，在请求体simplify_response为true时返回。

data

Array<Array<Object>>

用户所查询到的数据内容，在请求体simplify_response为true时返回。内层列表为每一行的数据，和header对应。

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类型的单元格转换值。用于当数值过大时，转化为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请求返回体。

错误码

请参见错误码。

父主题： 智能分析助手

相关文档