SQL 查询接口

本章介绍通过 AIR Open API 提交 SQL、分批获取查询结果和取消查询的方法。三个接口均使用 POST，请求体和响应体均为 JSON。

调用说明

请求头需包含 Authorization: Bearer <登录 JWT 或 API Key> 和 Content-Type: application/json。Authorization 中的凭据用于身份认证；响应中的 nextToken 是查询结果续取令牌，只能放在 next 或 cancel 接口请求体的 token 字段中，不能替代登录凭据。

查询令牌与提交查询时的用户、租户和工作空间绑定；续取或取消时必须使用相同身份。每个新生成的查询令牌有效期为一小时，请在有效期内使用。示例中的令牌均为占位符。

接口响应使用统一结构：

字段	类型	说明
success	boolean	接口请求是否成功。true 不表示异步查询已经完成，应查看 data.status。
data	object	接口返回的数据；失败时可能为空。
errorCode	string	失败时的错误码；成功时可能为空。
errorMsg	string	失败时的错误信息；成功时可能为空。
traceId	string	请求追踪 ID。

提交 SQL 查询

请求方式与地址：POST /api/v1/sql/queries

参数	位置	必填	类型	说明
sql	body	是	string	要执行的 SQL；不能为空或全为空白字符。

请求示例：

POST /api/v1/sql/queries
Authorization: Bearer <登录 JWT 或 API Key>
Content-Type: application/json

{"sql":"SELECT 1 AS value"}

响应的 data 字段：

字段	类型	说明
status	string	提交成功后为 RUNNING，表示应继续调用 next 获取结果。
nextToken	string	首次调用 next 所需的查询令牌。

响应示例：

{
  "success": true,
  "data": {
    "status": "RUNNING",
    "nextToken": "<查询令牌-1>"
  },
  "errorCode": null,
  "errorMsg": null,
  "traceId": "<请求追踪 ID>"
}

续取 SQL 查询结果

请求方式与地址：POST /api/v1/sql/queries/next

参数	位置	必填	类型	说明
token	body	是	string	首次调用时使用 submit 响应的 nextToken；后续调用使用上一次 next 响应的 nextToken。

请求示例：

POST /api/v1/sql/queries/next
Authorization: Bearer <登录 JWT 或 API Key>
Content-Type: application/json

{"token":"<查询令牌-1>"}

响应的 data 字段：

字段	类型	说明
status	string	RUNNING 表示查询尚未结束；FINISHED 表示查询结束。
columns	object[]	结果列定义；暂无列信息时为 []。
columns[].name	string	列名。
columns[].type	string	列的数据类型。
columns[].index	integer	列在每行 rows 中的位置，从 0 开始。
rows	array[]	当前批次的数据行，行内的值按 columns 顺序排列；暂无数据时为 []。
nextToken	string 或 null	下一次调用 next 或取消查询时使用的令牌；查询结束时为 null。
hasNext	boolean	是否还可续取；为 false 时续取结束。
updateType	string 或 null	SQL 更新操作的类型；查询结果不涉及更新操作时可能为 null。
updateCount	integer 或 null	SQL 更新操作影响的行数；不涉及更新操作时可能为 null。

首次调用 next 如果返回 RUNNING，说明查询尚未结束。此时 rows 可能为空，表示当前批次还没有准备好数据；也可能已经包含部分数据。先处理本次 rows，再把本次响应的新 nextToken 放入下一次 next 请求体的 token 字段。每次返回 RUNNING 时都重复此步骤，直到返回 FINISHED 且 hasNext=false；不要一直重用首次提交得到的令牌。

尚无数据时的响应示例：

{
  "success": true,
  "data": {
    "status": "RUNNING",
    "columns": [],
    "rows": [],
    "nextToken": "<查询令牌-2>",
    "hasNext": true,
    "updateType": null,
    "updateCount": null
  },
  "errorCode": null,
  "errorMsg": null,
  "traceId": "<请求追踪 ID>"
}

下一次请求使用响应中的新令牌：

POST /api/v1/sql/queries/next
Authorization: Bearer <登录 JWT 或 API Key>
Content-Type: application/json

{"token":"<查询令牌-2>"}

查询结束时的响应示例：

{
  "success": true,
  "data": {
    "status": "FINISHED",
    "columns": [
      {"name": "value", "type": "integer", "index": 0}
    ],
    "rows": [[1]],
    "nextToken": null,
    "hasNext": false,
    "updateType": null,
    "updateCount": null
  },
  "errorCode": null,
  "errorMsg": null,
  "traceId": "<请求追踪 ID>"
}

取消 SQL 查询

请求方式与地址：POST /api/v1/sql/queries/cancel

参数	位置	必填	类型	说明
token	body	是	string	要取消的查询当前可用的令牌，例如最近一次响应的 nextToken。

请求示例：

POST /api/v1/sql/queries/cancel
Authorization: Bearer <登录 JWT 或 API Key>
Content-Type: application/json

{"token":"<当前查询令牌>"}

响应的 data.status 为 CANCELED：

{
  "success": true,
  "data": {
    "status": "CANCELED"
  },
  "errorCode": null,
  "errorMsg": null,
  "traceId": "<请求追踪 ID>"
}

错误说明

查询接口返回 success=false 时，可根据 errorCode 判断原因；具体错误文案可能随语言设置及下游返回内容变化。身份认证失败由认证过滤器处理，使用其自身的错误响应。

错误码	说明
DWS_34_0001	SQL 查询请求无效，例如 sql 为空。
DWS_34_0002	查询令牌无效，例如令牌为空、格式错误，或与当前用户、租户、工作空间不匹配。
DWS_34_0003	查询令牌已过期，或查询在引擎端已失效。
DWS_34_0004	SQL 查询执行失败。
DWS_34_0005	与 Tardis 交互失败，或其响应不完整。
DWS_34_0006	当前请求缺少用于执行查询的用户名。
DWS_34_0007	提交查询时缺少租户集群 ID。

错误响应示例：

{
  "success": false,
  "data": null,
  "errorCode": "DWS_34_0001",
  "errorMsg": "SQL 查询请求无效",
  "traceId": "<请求追踪 ID>"
}