更新时间:2026-01-08 GMT+08:00

提交SQL作业(推荐)

功能介绍

该API用于通过执行SQL语句的方式向队列提交作业。

作业包含以下类型:DDL、DCL、IMPORT、QUERY和INSERT。其中,IMPORT与导入数据(废弃)的功能一致,区别仅在于实现方式不同。

另外,用户可使用其他API来对作业进行查询和管理。具体操作有:

该API当响应消息中“job_type”为“DCL”时,为同步操作。

URI

  • URI格式:

    POST /v1.0/{project_id}/jobs/submit-job

  • 参数说明
    表1 URI参数

    参数名称

    是否必选

    参数类型

    说明

    project_id

    是

    String

    参数解释:

    项目编号,用于资源隔离。获取方式请参考获取项目ID。

    示例: 48cc2c48765f481480c7db940d6409d1

    约束限制:

    无

    取值范围:

    只能由英文字母和数字组成,且长度为[1-64]个字符。

    默认取值:

    无

请求消息

表2 请求参数

参数名称

是否必选

参数类型

说明

sql

是

String

参数解释:

待执行的SQL语句。

约束限制:

无

取值范围:

无

默认取值:

无

currentdb

否

String

参数解释:

SQL语句执行所在的数据库。当创建新数据库时,不需要提供此参数。

约束限制:

无

取值范围:

只能包含数字、英文字母和下划线,但不能是纯数字,且不能以下划线开头。

默认取值:

无

queue_name

否

String

参数解释:

待提交作业的队列名称。

约束限制:

无

取值范围:

名称只能包含数字、英文字母和下划线,但不能是纯数字,且不能以下划线开头。

默认取值:

无

conf

否

Array of Strings

参数解释:

用户以“key/value”的形式设置用于此作业的配置参数。

约束限制:

无

取值范围:

目前支持的配置项请参考表3。

默认取值:

无

tags

否

Array of Objects

参数解释:

作业的标签。具体请参考表4。

约束限制:

无

取值范围:

无

默认取值:

无

engine_type

否

String

参数解释:

选择执行作业的引擎类型。

约束限制:

无

取值范围:

  • spark:spark引擎

默认取值:

spark

表3 conf参数说明

参数名称

描述

spark.sql.files.maxRecordsPerFile

参数解释:

要写入单个文件的最大记录数。如果该值为零或为负,则没有限制。

约束限制:

无

取值范围:

无

默认取值:

0

spark.sql.autoBroadcastJoinThreshold

参数解释:

配置执行连接时显示所有工作节点的表的最大字节大小。通过将此值设置为“-1”,可以禁用显示。

约束限制:

当前仅支持运行命令ANALYZE TABLE COMPUTE statistics noscan的配置单元元存储表,和直接根据数据文件计算统计信息的基于文件的数据源表。

取值范围:

无

默认取值:

209715200

spark.sql.shuffle.partitions

参数解释:

为连接或聚合过滤数据时使用的默认分区数。

约束限制:

无

取值范围:

无

默认取值:

200

spark.sql.dynamicPartitionOverwrite.enabled

参数解释:

配置DLI在覆盖写之前,是否删除所有符合条件的分区。

约束限制:

无

取值范围:

  • 当前配置设置为“false”时,DLI在覆盖写之前,会删除所有符合条件的分区。

    例如,分区表中有一个“2021-01”的分区,当使用INSERT OVERWRITE语句向表中写入“2021-02”这个分区的数据时,会把“2021-01”的分区数据也覆盖掉。

  • 当前配置设置为“true”时,DLI不会提前删除分区,而是在运行时覆盖那些有数据写入的分区。

默认取值:

false

spark.sql.files.maxPartitionBytes

参数解释:

读取文件时要打包到单个分区中的最大字节数。

约束限制:

无

取值范围:

无

默认取值:

134217728

spark.sql.badRecordsPath

参数解释:

Bad Records的路径。

约束限制:

无

取值范围:

无

默认取值:

无

dli.sql.sqlasync.enabled

参数解释:

DDL和DCL语句是否异步执行,值为“true”时启用异步执行。

约束限制:

无

取值范围:

无

默认取值:

true

dli.sql.job.timeout

参数解释:

设置作业运行超时时间,超时取消。单位:秒。

约束限制:

无

取值范围:

无

默认取值:

无

spark.sql.optimizer.dynamicPartitionPruning.enabled

参数解释:

该配置项用于启用或禁用动态分区修剪。在执行SQL查询时,动态分区修剪可以帮助减少需要扫描的数据量,提高查询性能。

约束限制:

无

取值范围:

  • 配置为true时,代表启用动态分区修剪,SQL会在查询中自动检测并删除那些不满足WHERE子句条件的分区,适用于在处理具有大量分区的表时。
  • 如果SQL查询中包含大量的嵌套left join操作,并且表有大量的动态分区时,这可能会导致在数据解析时消耗大量的内存资源,导致Driver节点的内存不足,并触发频繁的Full GC。

    在这种情况下,可以配置该参数为false即禁用动态分区修剪优化,有助于减少内存使用,避免内存溢出和频繁的Full GC。

    但禁用此优化可能会降低查询性能,禁用后Spark将不会自动修剪掉那些不满足条件的分区。

默认取值:

true

表4 tags参数

参数名称

是否必选

参数类型

说明

key

是

String

参数解释:

标签的键。

约束限制:

无

取值范围:

标签的键的最大长度为128个字符,标签的键可以包含任意语种字母、数字、空格和_ . : +-@ ,但首尾不能含有空格,不能以_sys_开头。

默认取值:

无

value

是

String

参数解释:

标签的值。

约束限制:

无

取值范围:

标签值的最大长度为255个字符,标签的值可以包含任意语种字母、数字、空格和_ . : +-@ 。

默认取值:

无

响应消息

表5 响应参数

参数名称

是否必选

参数类型

说明

is_success

是

Boolean

参数解释:

请求执行是否成功。“true”表示请求执行成功。

取值范围:

无

message

是

String

参数解释:

系统提示信息,执行成功时,信息可能为空。

取值范围:

无

job_id

是

String

参数解释:

此SQL语句将生成并提交一个新作业,返回此作业的ID,可用于获取作业状态和作业结果。

取值范围:

无

job_type

是

String

参数解释:

作业类型。

取值范围:

包含DDL、DCL、IMPORT、EXPORT、QUERY、INSERT。

  • DDL:创建修改删除元数据类型的作业
  • DCL:权限授权与回收类型的作业

    “job_type”为“DCL”时,为同步操作。

  • IMPORT:外部数据入库类型的作业
  • EXPORT:数据导出到外部类型的作业
  • QUERY:运行查询语句类型的作业
  • INSERT:向表追加新数据类型的作业

schema

否

Array of Map

参数解释:

当语句类型为DDL时,返回其结果的列名称及类型。

取值范围:

无

rows

否

Array of objects

参数解释:

当语句类型为DDL,且dli.sql.sqlasync.enabled=false时,直接返回其执行结果。但是最多只能返回1000行。

如果超过1000行,请通过异步方式获取结果。即,提交作业时配置 xxxx = true, 然后从DLI配置的作业桶中获取结果。结果在作业桶上的路径可以通过ShowSqlJobStatus接口返回值中的result_path来获取。结果的全量数据会自动导出到作业桶。

取值范围:

无

job_mode

否

String

参数解释:

作业执行模式:

  • async:异步
  • sync:同步

取值范围:

无

请求示例

提交SQL作业,该作业执行的数据库为db1、队列为default,并为该作业设置标签workspace=space1;jobName=name1。

{
    "currentdb": "db1",
    "sql": "desc table1",
    "queue_name": "default",
    "conf": [
        "dli.sql.shuffle.partitions = 200"
    ],
    "tags": [
            {
              "key": "workspace",
              "value": "space1"
             },
            {
              "key": "jobName",
              "value": "name1"
             }
      ]
}

响应示例

{
  "is_success": true,
  "message": "",
  "job_id": "8ecb0777-9c70-4529-9935-29ea0946039c",
  "job_type": "DDL",
  "job_mode":"sync",
  "schema": [
    {
      "col_name": "string"
    },
    {
      "data_type": "string"
    },
    {
      "comment": "string"
    }
  ],
  "rows": [
    [
      "c1",
      "int",
      null
    ],
    [
      "c2",
      "string",
      null
    ]
  ]
}

状态码

状态码如表6所示。

表6 状态码

状态码

描述

200

提交成功。

400

请求错误。

500

内部服务器错误。

错误码

调用接口出错后,将不会返回上述结果,而是返回错误码和错误信息,更多介绍请参见错误码。