查询SparkSql作业列表 - ListSparkSqls

功能介绍

查询工作空间下SparkSql作业列表，此接口为同步接口。支持按作业状态、创建时间、SQL片段等条件进行过滤查询，调用成功后直接返回作业列表数据。可通过查看SparkSql作业详情接口查看作业详细信息。

调用方法

URI

GET /v2/workspaces/{workspace_id}/spark-sqls

表1 路径参数
参数	是否必选	参数类型	描述
workspace_id	是	String	参数解释：工作空间ID，用于资源隔离。可在控制台的工作空间页面查看。约束限制：不涉及。取值范围：只能由英文字母、数字及中划线组成，且长度为32~36个字符。默认取值：不涉及。

表2 Query参数
参数	是否必选	参数类型	描述
marker	否	String	参数解释：作业ID游标位置，用于分页查询。约束限制：不涉及。取值范围：采用UUID格式，长度为36个字符。默认取值：首次查询可不传或传空字符串，后续查询传入上次返回的next_marker值。
limit	否	Integer	参数解释：查询记录数，用于指定返回的作业数量。约束限制：不涉及。取值范围：1~100。默认取值：10。
endpoint_name	否	String	参数解释：端点名称，用于指定查询的SparkSql执行环境。约束限制：不涉及。取值范围：只能由英文小写字母、数字及中划线组成，以英文小写字母开头，以英文小写字母或数字结尾，且长度为1~63个字符。默认取值：不涉及。
statement	否	String	参数解释：SQL片段，用于模糊查询包含指定SQL片段的作业。约束限制：不涉及。取值范围：长度为1~128个字符。默认取值：不涉及。
create_time_after	否	Long	参数解释：用于查询创建时间在该时间点之后的作业。约束限制：不涉及。取值范围：采用unix时间戳格式，单位为毫秒，最小值为1764061598000。默认取值：不涉及。
create_time_before	否	Long	参数解释：用于查询创建时间在该时间点之前的作业。约束限制：不涉及。取值范围：采用unix时间戳格式，单位为毫秒，最小值为1764061598000。默认取值：不涉及。
states	否	Array of strings	参数解释：SparkSql作业的状态列表，用于按状态过滤作业。约束限制：数组元素数量不能超过10个。
statement_types	否	Array of strings	参数解释：作业类型列表，用于按作业类型过滤作业。约束限制：数组元素数量不能超过4个。
statement_id	否	String	参数解释：SparkSql作业ID，用于查询指定作业。约束限制：不涉及。取值范围：只能由英文字母（不区分大小写）、数字、下划线及中划线组成，且长度为1~64个字符。默认取值：不涉及。
create_user_id	否	String	参数解释：作业创建者ID，用于按创建者过滤作业。约束限制：不涉及。取值范围：长度为1~256个字符。默认取值：不涉及。
labels	否	String	参数解释：作业标签，用于按标签过滤作业。格式为“key=value”，其中“=”需要URL编码为“%3D”。约束限制：不涉及。取值范围：长度为1~1024个字符。默认取值：不涉及。

请求参数

表3 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	参数解释：用户Token。约束限制：不涉及。取值范围：长度不超过65534个字符。默认取值：不涉及。

响应参数

状态码：200

表4 响应Body参数
参数	参数类型	描述
page_info	SparkMarkerPageInfo object	参数解释：分页游标信息，用于标识分页查询的位置和数量。
statements	Array of ListSparkSqlResItem objects	参数解释：详细的SparkSql作业列表，包含作业ID、状态、SQL内容等信息。

表5 SparkMarkerPageInfo
参数	参数类型	描述
next_marker	String	参数解释：下一页游标，用于标识下一页数据的起始位置。为空表示没有更多数据。取值范围：采用UUID格式，长度为36个字符，例如：6c98db52-cac2-4ff1-9a91-b7793e95557d。
current_count	Integer	参数解释：当前页数据条数，用于标识当前返回的数据数量。取值范围：大于等于0的整数，最大不超过100。

表6 ListSparkSqlResItem
参数	参数类型	描述
statement_id	String	参数解释：SparkSql作业的ID，用于唯一标识一次SparkSql作业执行。取值范围：采用UUID格式，长度为36个字符，例如：80ceaaff-3cfc-4162-a56f-70031ea4fa91。
client_token	String	参数解释：SparkSql作业事务ID，用于防止重复提交。取值范围：采用UUID格式，长度为36个字符，例如：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。
endpoint_name	String	参数解释：端点名称，用于指定SparkSql执行环境。取值范围：只能由英文小写字母、数字及中划线组成，以英文小写字母开头，以英文小写字母或数字结尾，且长度为1~63个字符。
catalog_context	SparkSqlCatalogContextResponse object	参数解释：Catalog上下文信息，用于指定作业使用的数据目录和数据库。
statement	String	参数解释：用户SQL语句，用于执行数据查询、数据操作等任务。取值范围：长度不超过500000个字符。
parameters	Array of SparkSqlParameter objects	参数解释：用户SQL内容的占位符参数列表，用于动态替换SQL中的参数。
state	String	参数解释：SparkSql作业的状态，用于标识作业的执行状态。取值范围： QUEUED：排队中。 RUNNING：运行中。 CANCELING：取消中。 CANCELED：已取消。 FAILED：运行失败。 QUEUED_TIMEOUT：排队超时。 RUNNING_TIMEOUT：运行超时。 SUCCEED：运行成功。
statement_type	String	参数解释：SQL作业类型，用于标识作业的类型。取值范围： DDL：创建修改删除元数据类型的作业、DESC/SHOW等语句。 DCL：权限授权与回收类型的作业。 DQL：查询语句SELECT。 DML：向表追加、删除、更新新数据类型的作业。
error	SparkSqlErrorDto object	参数解释：SparkSql作业错误详情，包含错误描述、错误码等信息。
result	SparkSqlResultResponse object	参数解释：SparkSql作业结果信息，包含查询结果的格式和路径等。
metric_statistics	SparkSqlMetricStatisticsResponse object	参数解释：SparkSql作业的指标统计信息，包含读取数据量、输出数据量、计算资源使用情况等。
log_url	String	参数解释：日志OBS归档路径，用于存储作业执行日志。取值范围：采用OBS路径格式，例如：obs://bucket/path/log。
create_time	Long	参数解释：作业创建时间，采用unix时间戳格式。取值范围：单位为毫秒。
start_time	Long	参数解释：作业开始运行时间，采用unix时间戳格式。取值范围：单位为毫秒。
end_time	Long	参数解释：作业结束时间，采用unix时间戳格式。取值范围：单位为毫秒。
create_user	SparkCreateUser object	参数解释：创建作业的用户信息。

表7 SparkSqlCatalogContextResponse
参数	参数类型	描述
catalog_name	String	参数解释：Catalog名称，用于指定作业使用的数据目录。取值范围：长度不超过128个字符。
database_name	String	参数解释：默认数据库名称，用于指定作业使用的数据库。取值范围：长度不超过128个字符。

表8 SparkSqlParameter
参数	参数类型	描述
key	String	参数解释：占位符的键，用于在SQL语句中标识参数位置。例如：SQL语句中的${key}。约束限制：不涉及。取值范围：长度为1~128个字符。默认取值：不涉及。
value	String	参数解释：占位符的值，用于替换SQL语句中的占位符。根据value_type的不同，值的格式也不同。 STRING：字符串，例如：“xxx”。 DECIMAL：定点数，例如：“12.1”。 INTEGER：整数，例如：“13”。 DATE：日期时间戳，例如：“1779188276372”。 TIMESTAMP：时间戳，例如：“1779188276372”。取值范围：长度为1~512个字符。默认取值：不涉及。
value_type	String	参数解释：占位符类型，用于标识占位符值的数据类型。约束限制：不涉及。取值范围： STRING：字符串类型。 DECIMAL：定点数类型。 INTEGER：整型类型。 DATE：日期类型。 TIMESTAMP：时间类型。默认取值：STRING。

表9 SparkSqlErrorDto
参数	参数类型	描述
message	String	参数解释：SparkSql错误描述，用于说明错误的具体原因。取值范围：长度为1~1024个字符，例如：表不存在。
sql_state	String	参数解释：SparkSql错误码，用于标识错误的类型。取值范围：采用标准SQL错误码格式，例如：42P01。
error_class	String	参数解释：SparkSql错误类型，用于标识错误的分类。取值范围：长度为1~128个字符，例如：SCHEMA_ALREADY_EXISTS。
line	Integer	参数解释：报错行号，用于定位SQL语句中的错误位置。取值范围：大于0的整数，例如：2。
start_position	Integer	参数解释：报错起始位置，用于定位SQL语句中错误的起始字符位置。取值范围：大于0的整数，例如：2。

**表10** SparkSqlResultResponse
参数	参数类型	描述
result_format	String	参数解释：查询类SQL结果格式，用于指定结果的存储格式。取值范围：csv、arrow。
result_path	String	参数解释：查询类SQL结果的OBS路径，用于存储SQL查询的结果数据。取值范围：采用OBS路径格式，例如：obs://bucket/path/result。
execution_profile_path	String	参数解释：作业执行计划的存储路径，用于存储作业的执行计划信息。取值范围：采用OBS路径格式，例如：obs://bucket/path/profile。

**表11** SparkSqlMetricStatisticsResponse
参数	参数类型	描述
bad_records	Long	参数解释：脏数据行数，用于标识处理过程中发现的错误数据行数。取值范围：大于等于0的整数。
input_bytes	Long	参数解释：读取数据字节数，用于标识作业读取的数据量。取值范围：大于等于0的整数，单位为字节。
input_records	Long	参数解释：读取数据行数，用于标识作业读取的数据记录数。取值范围：大于等于0的整数。
output_bytes	Long	参数解释：输出数据字节数，用于标识作业输出的数据量。取值范围：大于等于0的整数，单位为字节。
output_records	Long	参数解释：输出数据行数，用于标识作业输出的数据记录数。取值范围：大于等于0的整数。
cpu_time	Long	参数解释：计算使用CPU秒数，用于标识作业消耗的计算资源。取值范围：大于等于0的整数，单位为秒。

**表12** SparkCreateUser
参数	参数类型	描述
user_id	String	参数解释：创建作业的用户ID，用于标识作业创建者。取值范围：长度为1~256个字符。
user_name	String	参数解释：创建作业的用户名称，用于标识作业创建者。取值范围：长度为1~256个字符。

状态码：400

**表13** 响应Body参数
参数	参数类型	描述
error_code	String	参数解释：错误码，用于标识具体的错误类型。取值范围：长度为0~64个字符。
error_msg	String	参数解释：错误描述信息，用于说明错误原因。取值范围：长度为0~512个字符。
solution_msg	String	参数解释：解决方案描述。取值范围：长度为0~4096个字符。

状态码：401

**表14** 响应Body参数
参数	参数类型	描述
error_code	String	参数解释：错误码，用于标识具体的错误类型。取值范围：长度为0~64个字符。
error_msg	String	参数解释：错误描述信息，用于说明错误原因。取值范围：长度为0~512个字符。
solution_msg	String	参数解释：解决方案描述。取值范围：长度为0~4096个字符。

状态码：403

**表15** 响应Body参数
参数	参数类型	描述
error_code	String	参数解释：错误码，用于标识具体的错误类型。取值范围：长度为0~64个字符。
error_msg	String	参数解释：错误描述信息，用于说明错误原因。取值范围：长度为0~512个字符。
solution_msg	String	参数解释：解决方案描述。取值范围：长度为0~4096个字符。

状态码：500

**表16** 响应Body参数
参数	参数类型	描述
-	String	错误信息。

请求示例

查询工作空间下所有处于运行中或已成功状态的SparkSql作业，每页查询2条，状态过滤为“RUNNING”和“SUCCEED”。

GET /v2/workspaces/{workspace_id}/spark-sqls?limit=2&states=RUNNING&states=SUCCEED

响应示例

状态码：200

查询SparkSql作业列表成功。

{
  "page_info" : {
    "next_marker" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "current_count" : 2
  },
  "statements" : [ {
    "statement_id" : "6c98db52-cac2-4ff1-9a91-b7793e95557d",
    "client_token" : "019f2601-c9b5-7d94-80f1-b9d3185433fe",
    "endpoint_name" : "spark-endpoint-01",
    "statement_type" : "DQL",
    "state" : "RUNNING",
    "catalog_context" : {
      "catalog_name" : "hive_catalog",
      "database_name" : "default"
    },
    "statement" : "SELECT * FROM table_name LIMIT 100",
    "log_url" : "obs://db1/AIDataLake/Workspace_xxx/Spark/Endpoint_xxx/jobs/logs/2026_06_01/sql-engine-xxx/",
    "create_time" : 1698776400000,
    "start_time" : 1698776500000,
    "create_user" : {
      "user_id" : "user123",
      "user_name" : "admin"
    }
  }, {
    "statement_id" : "01928d08-b98a-73ce-91df-a7a0dc984207",
    "client_token" : "01928d08-b96b-71fb-95ce-cce0789db8de",
    "endpoint_name" : "spark-sql-01",
    "statement_type" : "UNRESOLVED",
    "state" : "RUNNING",
    "catalog_context" : {
      "catalog_name" : "hive_catalog",
      "database_name" : "db01"
    },
    "statement" : "select * from inventory limit 10",
    "log_url" : "obs://db1/AIDataLake/Workspace_xxx/Spark/Endpoint_xxx/jobs/logs/2026_06_01/sql-engine-xxx/",
    "create_time" : 1782898538890,
    "start_time" : 1782898615461,
    "create_user" : {
      "user_id" : "user456",
      "user_name" : "admin"
    }
  } ]
}

状态码：400

请求参数错误。

{
  "error_code" : "AIDataLake.01011001",
  "error_msg" : "Invalid parameter statement",
  "solution_msg" : "Please check the input parameters according to the documentation(statement for spark sql)."
}

状态码：401

认证失败。

{
  "error_code" : "AIDataLake.01011003",
  "error_msg" : "auth token not exists in header",
  "solution_msg" : "Please check if auth token is included in the request header."
}

状态码：403

权限不足。

{
  "error_code" : "AIDataLake.01011005",
  "error_msg" : "current account has no permission",
  "solution_msg" : "Please connect administrators to add permission."
}