Xiyan provides an OpenAPI with the same conversational capabilities as its official interface. Pass workspaceId, query, and other relevant parameters to perform question answering and data analysis in an existing workspace. Use this operation when a data source is associated in the Xiyan console and Xiyan can access your database over the Internet or a VPC to execute SQL. For usage, see https://help.aliyun.com/en/model-studio/gbi-best-practices.
Usage notes
Before calling this operation, make sure that you understand the billing methods and pricing of Xiyan.
Try it out
You can call this operation in OpenAPI Explorer without calculating a signature. After a successful call, OpenAPI Explorer can automatically generate SDK code examples.
Try it out
Authorization information
The following table describes the authorization information for this API operation. You can use this information in the Action element of a RAM policy statement to grant a RAM user or RAM role permission to call the operation. The columns are described as follows:
- Action: a specific permission.
- Access level: the access level of an action. Valid values: Write, Read, and List.
-
Resource type: the types of resources for which the action supports authorization:
- Required resource types are marked with an asterisk (*).
- Actions that do not support resource-level authorization use
All resources.
- Condition key: a condition key defined by the cloud service.
- Dependent action: an additional permission required to perform the action. The caller must also have permission to perform the dependent action.
| Action | Access level | Resource type | Condition key | Dependent action |
|---|---|---|---|---|
| dataanalysisgbi:RunDataAnalysis | none | *All resources * |
| None |
Request syntax
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| workspaceId | string | Yes | The Alibaba Cloud Model Studio workspace ID for this request. | llm-2v3934xtp49esw64 |
| body | object | No | The request body parameters. | |
| specificationType | string | No | The version to use for this request. If omitted, the default workspace version is used. Valid values:
| STANDARD_MIX |
| generateSqlOnly | boolean | No | Specifies that this request only generates and returns SQL without executing it. | true |
| query | string | Yes | The user query. | Which are the top ten best-selling products? |
| sessionId | string | No | The conversation ID returned in the service window callback message. | sessionID |
| dataRole | array | No | The data permission role names. Note Configure data permissions on the product page before obtaining the parameters for API calls. | |
| string | No | The specific data permission role name. | Administrator | |
| userParams | any | No | The custom parameters required by the data role. Required if the role is configured with external parameters. Note Configure data permissions on the product page before obtaining the parameters for API calls. | { "shopId":[ "1", "2" ], "userId":"10001" } |
| agentCtrlParams | any | No | The custom parameters passed through by the chat API. Currently supports skipping rewriting, skipping visualization, and enabling clarification of user questions. | { "withoutRewrite": true, "withoutVisualization": true, "enableChatMode": true } |
Response parameters
| Name | Type | Description | Example |
|---|---|---|---|
| object | Schema of Response | ||
| data | object | The returned information. | |
| errorMessage | string | The error message. | Access was denied, message: No such namespace namespaces/tech-scp-chain7. |
| event | string | The event type. Valid values:
| rewrite |
| evidence | string | The information used to assist model inference. | The current year is 2024. |
| requestId | string | The ID of the current request. | DA2578F7-88A5-5D6E-9305-33E724E97D60 |
| rewrite | string | The rewritten user input. | Query all keyword data and display it as a pie chart. |
| selector | array | The tables retrieved for SQL generation in this conversation. | |
| selector | string | The name of a retrieved table. | table_name1 |
| sessionId | string | The conversation ID. | sessionid1 |
| sql | string | The SQL statement generated in this conversation. | select p.product_id, p.product_name, sum(o.quantity) as total_sales from products p join orders o on p.product_id = o.product_id where o.order_date between '2022-10-22' and '2024-10-22' group by p.product_id, p.product_name having total_sales > 5 |
| sqlData | object | The structured SQL execution results. | |
| column | array | The queried field names in the SQL execution results. | |
| column | string | A specific field name. | product |
| data | array<object> | The structured data returned by SQL execution, which may contain multiple records. | |
| value | object | One record of structured data returned by SQL execution. | { "product_id": "29", "total_sales": "63", "product_name":"1L迷你电热水壶" } |
| sqlError | string | The reason why the task failed. | Can not issue data manipulation statements with executeQuery() |
| visualization | object | The information required by the visualization module. | |
| data | object | The structured information required by the visualization module. | |
| plotType | string | The chart type. Valid values:
| bar |
| xAxis | array | The x-axis content of the chart. | |
| xAxis | string | A field displayed on the x-axis. | product_name |
| yAxis | array | The y-axis content of the chart. | |
| yAxis | string | A field displayed on the y-axis. | total_sales |
| stack | boolean | Specifies whether to display a stacked bar chart. Takes effect only for bar charts. | false |
| option | string | The configuration used to initialize the frontend component. Takes effect only when chartsFramework=echarts in the agentCtrlParams request parameter. | { xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] }, yAxis: { type: 'value' }, series: [ { data: [150, 230, 224, 218, 135, 147, 260], type: 'line' } ] } |
| text | string | The analysis summary of the SQL execution results. | The query results show that all products with sales exceeding 5 in the past two years include: 2L large-capacity air fryer sold 109 units, Youth Edition sports wristband sold 119 units, 2L large-capacity fully automatic soy milk maker sold 106 units, wireless Bluetooth earphones fast-charging edition sold 84 units, 2L large-capacity portable juicer sold 136 units, Youth Edition smartwatch sold 104 units, wall-mounted eye-protection desk lamp sold 102 units, P30 phone 8+256G sold 83 units, 2L large-capacity electric kettle sold 84 units, men's electric makeup brush set sold 197 units, suitcase sold 82 units, bracelet sold 101 units, necklace sold 84 units, hair chain sold 89 units, wristwatch sold 98 units, ring sold 157 units, genuine leather handbag sold 136 units, trench coat and overcoat sold 76 units, sports travel bag sold 91 units, silk scarf sold 265 units, 1L mini air fryer sold 85 units, Deluxe Edition sports wristband sold 132 units, 1L mini fully automatic soy milk maker sold 81 units, Deluxe Edition wireless Bluetooth earphones (green) sold 122 units, 1L mini portable juicer sold 76 units, Deluxe Edition smartwatch sold 76 units, stick-on eye-protection desk lamp sold 109 units, M60 phone 16+512G sold 109 units, 1L mini electric kettle sold 63 units, and women's electric makeup brush set sold 158 units. |
| httpStatusCode | long | The HTTP status code for an individual event. Normally omitted and does not require processing. | 200 |
| attempts | array | An event field returned when SQL validation is enabled. Contains the SQL generated during each retry and the error reason. | |
| attempts | any | The SQL generated during each retry and the specific error information. | [{"sql":"SHOW TABLES","sqlError":"sql is invalid"},{"sql":"SHOW TABLES;","sqlError":"sql is invalid"}] |
| chat | object | A clarification event generated when the user question is ambiguous and clarification is enabled. | |
| text | string | The clarification question generated when the model determines that the user question does not match the associated data, to help the user clarify the request. | Do you want to query the creation time field in the orders table? |
| message | string | The system error message for troubleshooting. No user processing is required. | org.springframework.core.task.TaskRejectedException: ExecutorService in active state did not accept task: java.util.concurrent.CompletableFuture$AsyncSupply@25653b3b |
| code | string | The system error code for troubleshooting. No user processing is required. | NoAuth |
| httpStatusCode | long | The HTTP status code for the current request. Normally omitted and does not require processing. | 200 |
Examples
Sample success response
JSON format
Error codes
| HTTP status code | Error code | Error message | Description |
|---|---|---|---|
| 401 | NoAuth | Bad Request: Workspace.Illegal.Auth. | The current account does not have permission to access the specified workspace. |
| 401 | Internal.Error | Bad Request: Internal Error. | An internal error occurred. Contact customer service for troubleshooting. |