文档首页/ 智能数据湖 AI DataLake/ API参考/ Aura相关API/ AuraSQL作业管理/ 在指定Session中执行SQL - ExecuteAuraV2SqlStatement
更新时间：2026-10-10 GMT+08:00
查看PDF
分享

在指定Session中执行SQL - ExecuteAuraV2SqlStatement

功能介绍

在指定的Session下执行SQL语句。

此接口支持异步和同步两种执行模式，由入参is_sync参数决定。如果是异步执行，配套使用接口查看SQL执行结果查询语句结果。

如果是同步执行，接口会等待一段时间接收结果，如果执行完毕会返回执行结果，如果没有执行完毕，会返回一个运行中状态，后续可以使用接口查看SQL执行结果查询语句结果。

调用方法

请参见如何调用API。

URI

POST /v2/workspaces/{workspace_id}/aura-sessions/statements

表1 路径参数

参数

是否必选

参数类型

描述

workspace_id

是

String

参数解释：工作空间的ID。获取方法请参见获取工作空间ID。

约束限制：不涉及。

取值范围：长度为1~36个字符，支持大小写英文字母、数字、连字符。

默认取值：不涉及。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

参数解释：用户Token，通过调用获取IAM用户Token接口获取。

约束限制：不涉及。

取值范围：不涉及。

默认取值：不涉及。
表3 请求Body参数

参数

是否必选

参数类型

描述

session_id

是

String

参数解释：Session的ID。可通过查看Session列表接口获取session_id。

约束限制：不涉及。

取值范围：长度为1~36个字符，支持大小写英文字母、数字、连字符。

默认取值：不涉及。

statement

是

String

参数解释：SQL statement信息。

约束限制：不涉及。

取值范围：长度为1~10000000个字符。

默认取值：不涉及。

limit

否

Integer

参数解释：返回结果集的最大行数限制。

约束限制：不涉及。

取值范围：1~2147483647，单位：行。

默认取值：不涉及。

bindings

否

Array<Array<String>>

参数解释：SQL语句的参数绑定列表，用于绑定变量传参。外层数组为绑定集合（实际使用首个元素 bindings[0]），内层数组为单条SQL的参数值列表，每个字符串元素为单个参数值。

约束限制：

  • 外层数组元素个数：0~1。

  • 内层数组元素个数：0~200。

  • 每个参数值字符串长度：0~500个字符。

取值范围：不涉及。

默认取值：不涉及。

is_sync

否

Boolean

参数解释：同步执行或异步执行。

约束限制：不涉及。

取值范围：

  • true：同步。

  • false：异步。

默认取值：true（未传时默认同步执行）。

resultset_fetch_mode

否

String

参数解释：获取结果集的方式。

约束限制：不涉及。

取值范围：

  • DEFAULT：直接返回结果集。

  • READ_OBS：返回结果集在桶上的路径，而不是直接返回结果集。

默认取值：DEFAULT。

wait_timeout

否

Integer

参数解释：SQL排队等待时间，单位：秒。

约束限制：不涉及。

取值范围：300~86400。

默认取值：不涉及。

max_retry_times

否

Integer

参数解释：资源不足时重试次数。

约束限制：不涉及。

取值范围：1~6000。

默认取值：不涉及。

statement_type

否

String

参数解释：作业类型。

约束限制：不涉及。

取值范围：

  • SQL：SQL查询。

  • JOB：作业。

默认取值：SQL。

statement_name

否

String

参数解释：作业名称。

约束限制：长度不超过64个字符，仅允许字母、数字、中文、下划线和连字符。

取值范围：不涉及。

默认取值：不涉及。

响应参数

状态码：200

表4 响应Body参数

参数

参数类型

描述

status

Integer

参数解释：语句的状态。

取值范围：

  • 0：成功。

  • -1：失败。

  • 1： 执行中。

  • 2：执行完成但无结果集。

  • 3：排队等待中。

  • 4：语句未正常执行。

session_id

String

参数解释：Session的ID。

取值范围：长度为1~36个字符，支持大小写英文字母、数字、连字符。

statement_id

String

参数解释：执行语句ID。

取值范围：长度为1~36个字符，支持大小写英文字母、数字、下划线。

results

Array of results objects

参数解释：语句执行结果列表，按语句执行顺序返回。
表5 results

参数

参数类型

描述

status

String

参数解释：SQL 执行结果状态。

取值范围：PGRES_TUPLES_OK（查询成功含结果集）、PGRES_COMMAND_OK（命令执行成功无结果集）、PGRES_FATAL_ERROR（查询失败）。

statement_id

String

参数解释：本次语句执行唯一标识。

取值范围：UUID。

num_rows

Long

参数解释：结果集行数。

取值范围：不涉及。

row_count

Long

参数解释：影响行数。

取值范围：不涉及。

page_count

Integer

参数解释：分页总数。

取值范围：不涉及。

page_no

Integer

参数解释：当前页码。

取值范围：不涉及。

err_code

String

参数解释：错误码。

取值范围：0 表示成功。

sql_state

String

参数解释：SQL 状态码。

取值范围：不涉及。

message

String

参数解释：执行消息。

result_set

result_set object

参数解释：结果集，仅查询成功（PGRES_TUPLES_OK）时含有效数据，否则为空对象 {}。
表6 result_set

参数

参数类型

描述

columns

Array of columns objects

参数解释：列元数据列表。

rows

Array<Array<String>>

参数解释：实际数据行，每行顺序与columns对应。
表7 columns

参数

参数类型

描述

name

String

参数解释：列名。

取值范围：长度为 1~64 个字符。

table_id

Integer

参数解释：表 ID。

column_id

Integer

参数解释：列 ID。

format

Integer

参数解释：格式。

type

Integer

参数解释：列类型 OID。

size

Integer

参数解释：列大小。

type_mod

Integer

参数解释：类型修饰符。

状态码：400

表8 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：错误码。

取值范围：长度为8~36个字符。

error_msg

String

参数解释：错误描述。

取值范围：长度为2~4096个字符。

solution_msg

String

参数解释：解决方案描述。

取值范围：长度为2~4096个字符。

状态码：401

表9 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：错误码。

取值范围：长度为8~36个字符。

error_msg

String

参数解释：错误描述。

取值范围：长度为2~4096个字符。

solution_msg

String

参数解释：解决方案描述。

取值范围：长度为2~4096个字符。

状态码：403

表10 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：错误码。

取值范围：长度为8~36个字符。

error_msg

String

参数解释：错误描述。

取值范围：长度为2~4096个字符。

solution_msg

String

参数解释：解决方案描述。

取值范围：长度为2~4096个字符。

状态码：404

表11 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：错误码。

取值范围：长度为8~36个字符。

error_msg

String

参数解释：错误描述。

取值范围：长度为2~4096个字符。

solution_msg

String

参数解释：解决方案描述。

取值范围：长度为2~4096个字符。

状态码：408

表12 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：错误码。

取值范围：长度为8~36个字符。

error_msg

String

参数解释：错误描述。

取值范围：长度为2~4096个字符。

solution_msg

String

参数解释：解决方案描述。

取值范围：长度为2~4096个字符。

状态码：500

表13 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：错误码。

取值范围：长度为8~36个字符。

error_msg

String

参数解释：错误描述。

取值范围：长度为2~4096个字符。

solution_msg

String

参数解释：解决方案描述。

取值范围：长度为2~4096个字符。

请求示例

在指定的Session下执行SQL语句。

POST /v2/workspaces/{workspace_id}/aura-sessions/statements

{
  "statement" : "select * from aaa",
  "limit" : 100,
  "session_id" : "6399466e-8908-xxxx-xxxx-48479c8b06f7",
  "bindings" : [ [ "string" ] ],
  "resultset_fetch_mode" : "DEFAULT",
  "is_sync" : true
}

响应示例

状态码：200

{
  "status" : 0,
  "session_id" : "6399466e-8908-xxxx-xxxx-48479c8b06f7",
  "statement_id" : "49131d25-1824-xxxx-xxxx-832bdd19dfd3",
  "results" : [ {
    "status" : "PGRES_TUPLES_OK",
    "statement_id" : "49131d25-1824-xxxx-xxxx-832bdd19dfd3",
    "num_rows" : 1,
    "row_count" : 1,
    "page_count" : 1,
    "page_no" : 1,
    "err_code" : "0",
    "sql_state" : "0",
    "message" : "",
    "result_set" : {
      "columns" : [ {
        "name" : "a",
        "table_id" : 0,
        "column_id" : 1,
        "format" : 0,
        "type" : 23,
        "size" : 4,
        "type_mod" : -1
      } ],
      "rows" : [ [ "1" ] ]
    }
  } ]
}

状态码：400

{
  "error_code" : "AIDataLake.00092031",
  "error_msg" : "Invalid parameter name",
  "solution_msg" : "Please enter parameters in the correct format."
}

状态码：401

{
  "error_code" : "APIG.1002",
  "error_msg" : "Incorrect token or token resolution failed",
  "solution_msg" : "Please obtain a valid token and retry."
}

状态码：403

{
  "error_code" : "AIDataLake.00090030",
  "error_msg" : "Unauthorized requests.",
  "solution_msg" : "Check permissions and retry after authorization."
}

状态码：404

{
  "error_code" : "AIDataLake.00090009",
  "error_msg" : "The resource does not exist.",
  "solution_msg" : "Please try to use correct info."
}

状态码：408

{
  "error_code" : "common.00000408",
  "error_msg" : "A timeout exception occurred.",
  "solution_msg" : "The request timed out while waiting for a response — check the backend service status and network, then retry; if the operation is long-running, increase the client timeout or split the request."
}

状态码：500

{
  "error_code" : "common.00000500",
  "error_msg" : "internal error",
  "solution_msg" : "An internal service error occurred. Please retry later; if the problem persists, contact technical support."
}

状态码

状态码

描述

200

请求成功。

400

非法请求。

401

未经授权。

403

请求被拒绝访问。

404

所请求的资源不存在。

408

请求超时。

500

服务器内部错误。
父主题： AuraSQL作业管理

相关文档