华为云用户手册

批作业SQL常用配置项说明 本章节为您介绍DLI 批作业SQL语法的常用配置项。 表1 常用配置项 名称 默认值 描述 spark.sql.files.maxRecordsPerFile 0 要写入单个文件的最大记录数。如果该值为零或为负，则没有限制。 spark.sql.shuffle.partitions 200 为连接或聚合过滤数据时使用的默认分区数。 spark.sql.dynamicPartitionOverwrite.enabled false 当前配置设置为“false”时，DLI在覆盖写之前，会删除所有符合条件的分区。例如，分区表中有一个“2021-01”的分区，当使用INSERT OVERWRITE语句向表中写入“2021-02”这个分区的数据时，会把“2021-01”的分区数据也覆盖掉。 当前配置设置为“true”时，DLI不会提前删除分区，而是在运行时覆盖那些有数据写入的分区。 spark.sql.files.maxPartitionBytes 134217728 读取文件时要打包到单个分区中的最大字节数。 spark.sql.badRecordsPath - Bad Records的路径。 spark.sql.legacy.correlated.scalar.query.enabled false 该参数设置为true： 当子查询中数据不重复的情况下，执行关联子查询，不需要对子查询的结果去重。 当子查询中数据重复的情况下，执行关联子查询，会提示异常，必须对子查询的结果做去重处理，比如max(),min()。 该参数设置为false： 不管子查询中数据重复与否，执行关联子查询时，都需要对子查询的结果去重，比如max(),min()，否则提示异常。 spark.sql.keep.distinct.expandThreshold - 参数说明： 对于包含count(distinct)的多维分析（with cube）的查询场景，spark典型的执行计划是将cube使用expand算子来实现，但该操作会导致查询膨胀，为了避免出现查询膨胀，建议执行如下配置： spark.sql.keep.distinct.expandThreshold： 默认值：-1，即使用Spark默认的expand算子。 设置具体数值：即代表定义了查询膨胀的阈值（例如512），超过该阈值count(distinct) 使用distinct聚合算子来执行，不再使用expand算子。 spark.sql.distinct.aggregator.enabled：强制使用distinct聚合算子的开关。配置为true时不再根据spark.sql.keep.distinct.expandThreshold来判断。 适用场景：包含count(distinct)的多维分析（with cube）的查询场景，可能包含多个count(distinct)，且包含cube/roll up 典型场景示例： SELECT a1, a2, count(distinct b), count(distinct c) FROM test_distinct group by a1, a2 with cube spark.sql.distinct.aggregator.enabled false 父主题： Spark SQL语法参考（即将下线）

示例7：创建表并设置多字符的分割符 示例说明：创建了一个名为table5的Hive表。表指定序列化和反序列化类ROW FORMAT SERDE，字段之间的分隔符被设置为/#，并且数据以文本文件格式存储。 只有指定ROW FORMAT SERDE为org.apache.hadoop.hive.contrib.serde2.MultiDelimitSerDe时，字段分隔符才支持设置为多字符。 本例指定字段分割符 field.delim'为“/#”。 ROW FORMAT功能只支持textfile类型的表。 1 2 3 4 5 6 7 8 9 CREATE TABLE IF NOT EXISTs table5 ( col_1 STRING, col_2 INT ) ROW FORMAT SERDE 'org.apache.hadoop.hive.contrib.serde2.MultiDelimitSerDe' WITH SERDEPROPERTIES ( 'field.delim' = '/#' ) STORED AS textfile;

示例1：创建DLI非分区表 示例说明：创建名为table1的DLI非分区表，并用STORED AS关键字指定改表的存储格式为orc格式。 在您的实际使用中，可以将DLI表存储为textfile, avro, orc, sequencefile, rcfile, parquet等类型。 1 2 3 4 5 CREATE TABLE IF NOT EXISTS table1 ( col_1 STRING, col_2 INT ) STORED AS orc;

示例5：创建DLI分区表，自定义表的TBLPROPERTIES参数 示例说明：本例创建名为table3并以col_3为分区依据的DLI分区表。在TBLPROPERTIES中配置dli.multi.version.enable、comment、orc.compress和auto.purge。 dli.multi.version.enable：本例配置为true，即代表开启DLI数据多版本功能，用于表数据的备份与恢复。 comment：表描述信息，TBLPROPERTIES内的描述信息支持后续修改。 orc.compress：指定orc存储的压缩方式，本例定义为ZLIB。 auto.purge：本例配置为true，即删除或者覆盖的数据会不经过回收站，直接被删除。 1 2 3 4 5 6 7 8 9 10 11 12 CREATE TABLE IF NOT EXISTs table3 ( col_1 STRING, col_2 STRING ) PARTITIONED BY (col_3 DATE) STORED AS rcfile TBLPROPERTIES ( dli.multi.version.enable = true, comment = 'Created by dli', orc.compress = 'ZLIB', auto.purge = true );

示例6：创建textfile格式的非分区表，并设置ROW FORMAT 示例说明：本例创建名为table4的textfile类型的非分区表，并设置ROW FORMAT相关格式（ROW FORMAT功能只支持textfile类型的表）。 字段（Fields）是表格中的列，每个字段有一个名称和数据类型，表中字段之间以'/'分隔。 集合项（COLLECTION ITEMS）指的是一组数据中的元素，可以是数组、列表或集合等，table4中集合项以'$'分隔。 映射键（MAP KEYS）是一种键值对的数据结构，用于存储一组相关联的数据，表中Map键以'#'分隔。 行（Rows）表格中的行，每一行包含一组字段值，表中行以'\n'结束（注意，只支持用'\n'作为行分隔符）。 NULL表示缺少值或未知值的特殊值。在表格中，NULL表示该字段没有值或该值未知。如果数据中存在null值，则用字符串“null”表示。 1 2 3 4 5 6 7 8 9 10 11 CREATE TABLE IF NOT EXISTS table4 ( col_1 STRING, col_2 INT ) STORED AS TEXTFILE ROW FORMAT DELIMITED FIELDS TERMINATED BY '/' COLLECTION ITEMS TERMINATED BY '$' MAP KEYS TERMINATED BY '#' LINES TERMINATED BY '\n' NULL DEFINED AS 'NULL';

关键字 IF NOT EXISTS：指定该关键字以避免表已经存在时报错。 COMMENT：字段或表描述。 PARTITIONED BY：指定分区字段。 ROW FORMAT：行数据格式。 STORED AS：指定所存储的文件格式，当前该关键字只支持指定TEXTFILE, AVRO, ORC, SEQUENCEFILE, RCFILE, PARQUET几种格式。创建DLI表时必须指定此关键字。 TBLPROPERTIES：用于为表添加key/value的属性。 在表存储格式为PARQUET时，可以通过指定TBLPROPERTIES(parquet.compression = 'zstd')来指定表压缩格式为zstd。 AS：使用CTAS创建表。 ROW FORMAT SERDE为org.apache.hadoop.hive.contrib.serde2.MultiDelimitSerDe时，字段分隔符才支持设置为多字符。使用方法请参考示例7：创建表并设置多字符的分割符。

参数说明 表1 参数描述 参数 是否必选 描述 db_name 否 Database名称。 由字母、数字和下划线（_）组成。不能是纯数字，且不能以数字和下划线开头。 table_name 是 Database中的表名。 由字母、数字和下划线（_）组成。不能是纯数字，且不能以数字和下划线开头。匹配规则为：^(?!_)(?![0-9]+$)[A-Za-z0-9_$]*$。如果特殊字符需要使用单引号（''）包围起来。 col_name 是 列字段名称。 列字段由字母、数字和下划线（_）组成。不能是纯数字，且至少包含一个字母。 列名为大小写不敏感，即不区分大小写。 col_type 是 列字段的数据类型。数据类型为原生类型。 请参考原生数据类型。 col_comment 否 列字段描述。仅支持字符串常量。 row_format 是 行数据格式。row format功能只支持textfile类型的表。 file_format 是 DLI表数据存储格式：支持textfile, avro, orc, sequencefile, rcfile, parquet。 table_comment 否 表描述。仅支持字符串常量。 key = value 否 设置TBLPROPERTIES具体属性和值。 在表存储格式为PARQUET时，可以通过指定TBLPROPERTIES(parquet.compression = 'zstd')来指定表压缩格式为zstd。 select_statement 否 用于CTAS命令，将源表的select查询结果或某条数据插入到新创建的DLI表中。

示例2：创建DLI分区表 示例说明：创建一个名为student的分区表，该分区表使用院系编号（facultyNo）和班级编号（classNo）进行分区，该student表会同时按照不同的院系编号（facultyNo）和不同的班级编号（classNo）分区。 在实际的使用过程中，您可以选择合适的分区字段并将其添加到PARTITIONED BY关键字后。 1 2 3 4 5 6 7 8 9 CREATE TABLE IF NOT EXISTS student( id int, name STRING ) STORED AS avro PARTITIONED BY ( facultyNo INT, classNo INT );

注意事项 CTAS建表语句不能指定表的属性。 关于分区表的使用说明： 创建分区表时，PARTITONED BY中指定分区列必须是不在表中的列，且需要指定数据类型。分区列支持string, boolean, tinyint, smallint, short, int, bigint, long, decimal, float, double, date, timestamp等hive开源支持的类型。 支持指定多个分区字段，分区字段只需在PARTITIONED BY关键字后指定，不能像普通字段一样在表名后指定，否则将出错。 单表分区数最多允许200000个。 Spark 3.3及以上版本支持使用Hive语法的CTAS语句创建分区表。

语法格式 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 CREATE TABLE [IF NOT EXISTS] [db_name.]table_name [(col_name1 col_type1 [COMMENT col_comment1], ...)] [COMMENT table_comment] [PARTITIONED BY (col_name2 col_type2, [COMMENT col_comment2], ...)] [ROW FORMAT row_format] STORED AS file_format [TBLPROPERTIES (key = value)] [AS select_statement]; row_format: : SERDE serde_cls [WITH SERDEPROPERTIES (key1=val1, key2=val2, ...)] | DELIMITED [FIELDS TERMINATED BY char [ESCAPED BY char]] [COLLECTION ITEMS TERMINATED BY char] [MAP KEYS TERMINATED BY char] [LINES TERMINATED BY char] [NULL DEFINED AS char]

示例5：创建OBS分区表，自定义表的TBLPROPERTIES参数 示例说明：创建名为table3，并以col_3为分区依据的OBS分区表。在TBLPROPERTIES中配置dli.multi.version.enable、comment、orc.compress和auto.purge。 dli.multi.version.enable：本例配置为true，即代表开启DLI数据多版本功能，用于表数据的备份与恢复。 comment：表描述信息，comment描述信息支持后续修改。 orc.compress：指定orc存储的压缩方式，本例定义为ZLIB。 auto.purge：本例配置为true，即删除或者覆盖的数据会不经过回收站，直接被删除。 1 2 3 4 5 6 7 8 9 10 11 12 13 CREATE TABLE IF NOT EXISTs table3 ( col_1 STRING, col_2 STRING ) PARTITIONED BY (col_3 DATE) STORED AS rcfile LOCATION 'obs://bucketName/filePath' TBLPROPERTIES ( dli.multi.version.enable = true, comment = 'Created by dli', orc.compress = 'ZLIB', auto.purge = true );

示例7：创建表并设置多字符的分割符 示例说明：创建了一个名为table5的Hive表。表指定序列化和反序列化类ROW FORMAT SERDE，字段之间的分隔符被设置为/#，并且数据以文本文件格式存储。 只有指定ROW FORMAT SERDE为org.apache.hadoop.hive.contrib.serde2.MultiDelimitSerDe时，字段分隔符才支持设置为多字符。 本例指定字段分割符 field.delim'为“/#”。 ROW FORMAT功能只支持textfile类型的表。 1 2 3 4 5 6 7 8 9 10 CREATE TABLE IF NOT EXISTS table5 ( col_1 STRING, col_2 INT ) ROW FORMAT SERDE 'org.apache.hadoop.hive.contrib.serde2.MultiDelimitSerDe' WITH SERDEPROPERTIES ( 'field.delim' = '/#' ) STORED AS textfile LOCATION 'obs://bucketName/filePath';

示例6：创建textfile格式的非分区表，并设置ROW FORMAT 示例说明：创建名为table4的textfile类型的非分区表，并设置ROW FORMAT（ROW FORMAT功能只支持textfile类型的表）。 FIELDS：字段表格中的列，每个字段有一个名称和数据类型，表中字段之间以'/'分隔。 COLLECTION ITEMS：集合项指的是一组数据中的元素，可以是数组、列表或集合等，表中集合项以'$'分隔。 MAP KEYS：映射键是一种键值对的数据结构，用于存储一组相关联的数据，表中Map键以'#'分隔。 LINES：表格中的行，每一行包含一组字段值，表中行以'\n'结束（注意，只支持用'\n'作为行分隔符）。 NULL：表示缺少值或未知值的特殊值。在表格中，NULL表示该字段没有值或该值未知。如果数据中存在null值，则用字符串“null”表示。 1 2 3 4 5 6 7 8 9 10 11 12 CREATE TABLE IF NOT EXISTS table4 ( col_1 STRING, col_2 INT ) STORED AS textfile LOCATION 'obs://bucketName/filePath' ROW FORMAT DELIMITED FIELDS TERMINATED BY '/' COLLECTION ITEMS TERMINATED BY '$' MAP KEYS TERMINATED BY '#' LINES TERMINATED BY '\n' NULL DEFINED AS 'null';

示例1：创建OBS非分区表 示例说明：创建名为table1的OBS非分区表，并用STORED AS关键字指定改表的存储格式为orc格式。 在您的实际使用中，可以将OBS表存储为textfile, avro, orc, sequencefile, rcfile, parquet等类型。 1 2 3 4 5 6 CREATE TABLE IF NOT EXISTS table1 ( col_1 STRING, col_2 INT ) STORED AS orc LOCATION 'obs://bucketName/filePath';

语法格式 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 CREATE [EXTERNAL] TABLE [IF NOT EXISTS] [db_name.]table_name [(col_name1 col_type1 [COMMENT col_comment1], ...)] [COMMENT table_comment] [PARTITIONED BY (col_name2 col_type2, [COMMENT col_comment2], ...)] [ROW FORMAT row_format] [STORED AS file_format] LOCATION 'obs_path' [TBLPROPERTIES (key = value)] [AS select_statement] row_format: : SERDE serde_cls [WITH SERDEPROPERTIES (key1=val1, key2=val2, ...)] | DELIMITED [FIELDS TERMINATED BY char [ESCAPED BY char]] [COLLECTION ITEMS TERMINATED BY char] [MAP KEYS TERMINATED BY char] [LINES TERMINATED BY char] [NULL DEFINED AS char]

关键字 EXTERNAL：指创建OBS表。 IF NOT EXISTS：指定该关键字以避免表已经存在时报错。 COMMENT：字段或表描述。 PARTITIONED BY：指定分区字段。 ROW FORMAT：行数据格式。 STORED AS：指定所存储的文件格式，当前该关键字只支持指定TEXTFILE, AVRO, ORC, SEQUENCEFILE, RCFILE, PARQUET格式。 LOCATION：指定OBS的路径。创建OBS表时必须指定此关键字。 TBLPROPERTIES：TBLPROPERTIES子句允许用户给表添加key/value的属性。 开启数据多版本功能，用于表数据的备份与恢复。开启多版本功能后，在进行删除或修改表数据时（insert overwrite或者truncate操作），系统会自动备份历史表数据并保留一定时间，后续您可以对保留周期内的数据进行快速恢复，避免因误操作而丢失数据。多版本功能SQL语法请参考开启或关闭数据多版本和多版本备份恢复数据。 创建OBS表时，通过指定TBLPROPERTIES ("dli.multi.version.enable"="true")开启DLI数据多版本功能，具体可以参考示例说明。 表1 TBLPROPERTIES主要参数说明 key值 value说明 dli.multi.version.enable true：开启DLI数据多版本功能。 false：关闭DLI数据多版本功能。 comment 表描述信息。 orc.compress orc存储格式表的一个属性，用来指定orc存储的压缩方式。支持取值为： ZLIB SNAPPY NONE PARQUET auto.purge 当设置为true时，删除或者覆盖的数据会不经过回收站，直接被删除。 AS：使用CTAS创建表。 ROW FORMAT SERDE为org.apache.hadoop.hive.contrib.serde2.MultiDelimitSerDe时，字段分隔符才支持设置为多字符。使用方法参考示例7：创建表并设置多字符的分割符。

参数说明 表2 参数说明 参数 是否必选 描述 db_name 否 Database名称。 由字母、数字和下划线（_）组成。不能是纯数字，且不能以数字和下划线开头。 table_name 是 Database中的表名。 由字母、数字和下划线（_）组成。不能是纯数字，且不能以数字和下划线开头。匹配规则为：^(?!_)(?![0-9]+$)[A-Za-z0-9_$]*$。 特殊字符需要使用单引号（''）包围起来。 表名对大小写不敏感，即不区分大小写。 col_name 是 列字段名称。 列字段由字母、数字和下划线（_）组成。不能是纯数字，且至少包含一个字母。 列名为大小写不敏感，即不区分大小写。 col_type 是 列字段的数据类型。数据类型为原生类型。 请参考原生数据类型。 col_comment 否 列字段描述。仅支持字符串常量。 row_format 是 行数据格式。row_format功能只支持textfile类型的表。 file_format 是 OBS表存储格式，支持TEXTFILE, AVRO, ORC, SEQUENCEFILE, RCFILE, PARQUET table_comment 否 表描述。仅支持字符串常量。 obs_path 是 数据文件所在的OBS存储路径，推荐使用OBS并行文件系统存储。 格式：obs://bucketName/tblPath bucketName即桶名称。 tblPath是目录名称。目录后不需要指定文件名。 当OBS的目录下文件夹与文件同名时，创建OBS表指向的路径会优先指向文件而非文件夹。 key = value 否 设置TBLPROPERTIES具体属性和值。 例如开启DLI数据多版本时，可以设置"dli.multi.version.enable"="true"来开启该功能。 select_statement 否 用于CTAS命令，将源表的select查询结果或某条数据插入到新创建的OBS表中。

示例2：创建OBS分区表 示例说明：创建一个名为student的分区表，该分区表使用院系编号（facultyNo）和班级编号（classNo）进行分区，该student表会同时按照不同的院系编号（facultyNo）和不同的班级编号（classNo）分区。 在实际的使用过程中，您可以选择合适的分区字段并将其添加到PARTITIONED BY关键字后。 1 2 3 4 5 6 7 8 9 10 CREATE TABLE IF NOT EXISTS student( id INT, name STRING ) STORED AS avro LOCATION 'obs://bucketName/filePath' PARTITIONED BY ( facultyNo INT, classNo INT );

注意事项 创建表时会统计大小。 添加数据时不会修改大小。 如需查看表大小可以通过OBS查看。 CTAS建表语句不能指定表的属性。 关于分区表的使用说明： 创建分区表时，PARTITONED BY中指定分区列必须是不在表中的列，且需要指定数据类型。分区列支持string, boolean, tinyint, smallint, short, int, bigint, long, decimal, float, double, date, timestamp等hive开源支持的类型。 支持指定多个分区字段，分区字段只需在PARTITIONED BY关键字后指定，不能像普通字段一样在表名后指定，否则将出错。 单表分区数最多允许200000个。 Spark 3.3及以上版本支持使用Hive语法的CTAS语句创建分区表。

语法格式 将SELECT查询结果插入到表中 1 2 INSERT INTO [TABLE] [db_name.]table_name [PARTITION part_spec] select_statement; 1 2 INSERT OVERWRITE TABLE [db_name.]table_name [PARTITION part_spec] select_statement; part_spec: : (part_col_name1=val1 [, part_col_name2=val2, ...]) 将某条数据插入到表中 1 2 INSERT INTO [TABLE] [db_name.]table_name [PARTITION part_spec] VALUES values_row [, values_row ...]; 1 2 INSERT OVERWRITE TABLE [db_name.]table_name [PARTITION part_spec] VALUES values_row [, values_row ...]; values_row: : (val1 [, val2, ...])

示例 导入数据前已参考创建OBS表或者创建DLI表中的示例描述创建对应的表。 将SELECT查询结果插入到表中 使用DataSource语法创建一个parquet格式的分区表 CREATE TABLE data_source_tab1 (col1 INT, p1 INT, p2 INT) USING PARQUET PARTITIONED BY (p1, p2); 插入查询结果到分区 (p1 = 3, p2 = 4)中 INSERT INTO data_source_tab1 PARTITION (p1 = 3, p2 = 4) SELECT id FROM RANGE(1, 3); 插入新的查询结果到分区 (p1 = 3, p2 = 4) 中 INSERT OVERWRITE TABLE data_source_tab1 PARTITION (p1 = 3, p2 = 4) SELECT id FROM RANGE(3, 5); 将某条数据插入表中 使用Hive语法创建一个parquet格式的分区表 CREATE TABLE hive_serde_tab1 (col1 INT, p1 INT, p2 INT) USING HIVE OPTIONS(fileFormat 'PARQUET') PARTITIONED BY (p1, p2); 插入两条数据到分区 (p1 = 3, p2 = 4)中 INSERT INTO hive_serde_tab1 PARTITION (p1 = 3, p2 = 4) VALUES (1), (2); 插入新的数据到分区 (p1 = 3, p2 = 4) 中 INSERT OVERWRITE TABLE hive_serde_tab1 PARTITION (p1 = 3, p2 = 4) VALUES (3), (4);

关键字 表1 INSERT关键字说明 参数 描述 db_name 需要执行INSERT命令的表所在数据库的名称。 table_name 需要执行INSERT命令的表的名称。 part_spec 指定详细的分区信息。若分区字段为多个字段，需要包含所有的字段，但是可以不包含对应的值，系统会匹配上对应的分区。单表分区数最多允许100000个。 select_statement 源表上的SELECT查询（支持DLI表、OBS表）。 values_row 想要插入到表中的值，列与列之间用逗号分隔。

约束限制 insert overwrite语法不适用于“自读自写”场景，该场景因涉及数据的连续处理和更新，如果使用insert overwrite语法可能存在数据丢失风险。 "自读自写"是指在处理数据时能够读取数据，同时根据读取的数据生成新的数据或对数据进行修改。 使用Hive和Datasource（除Hudi外）表在执行数据修改类命令（例如insert into，load data）时由于数据源不支持事务性，在系统故障或队列资源重启后，可能会导致数据重复或数据不一致等问题。 为了避免这种情况，建议优先选择支持事务性的数据源，如Hudi类型数据源，该类数据源具备ACID（Atomicity、Consistency、Isolation、Durability）能力，有助于确保数据的一致性和准确性。

响应消息 表3 响应参数 参数名称 是否必选 参数类型 说明 is_success 是 Boolean 请求发送是否成功。“true”表示请求发送成功。 message 是 String 系统提示信息，执行成功时，信息可能为空。 job_id 否 String 提交请求成功时，生成并提交一个新的作业，返回作业ID。用户可以使用作业ID来查询作业状态和获取作业结果。 job_mode 否 String 作业执行模式： async：异步 sync：同步

请求消息 表2 请求参数 参数名称 是否必选 参数类型 说明 data_path 是 String 导出结果存储的路径（当前仅支持将数据存储在OBS上）。另外，该路径下的文件夹须不存在，如请求样例中的“path”文件夹。 compress 否 String 导出数据的压缩格式，目前支持gzip，bzip2和deflate压缩方式； 默认值为none，表示不压缩。 data_type 是 String 导出数据的存储格式，目前API支持csv和json格式。 queue_name 否 String 指定执行该任务的队列。若不指定队列，将采用default队列执行操作。 export_mode 否 String 导出模式，目前支持“ErrorIfExists”，“Overwrite”，不指定“export_mode”则默认为“ErrorIfExists”。 “ErrorIfExists”：存在即报错。指定的导出目录必须不存在，如果指定目录已经存在，系统将返回错误信息，无法执行导出操作。 “Overwrite”：覆盖。在指定目录下新建文件，会删除已有文件。 with_column_header 否 Boolean 导出csv和json格式数据时，是否导出列名。 设置为“true”，表示导出列名。 设置为“false”，表示不导出列名。 若为空，默认为“false”。 limit_num 否 Integer 需要导出的数据数量，默认值为“0”，表示全部导出。 encoding_type 否 String 导出数据的编码格式。默认使用utf-8。 支持以下编码格式： utf-8 gb2312 gbk quote_char 否 String 用户自定义引用字符。 默认值: 英文双引号（"） 仅在数据格式为csv格式时支持配置引用字符。 引用字符在导出作业结果时用于标识文本字段的开始和结束，即用于分割字段。 仅支持设置一个字符。 主要用于处理包含空格、特殊字符或与分隔符相同字符的数据。 escape_char 否 String 用户自定义转义字符。 默认值：英文反斜杠（\） 仅在数据格式为csv格式时支持配置转义字符。 在导出结果中如果需要包含特殊字符，如引号本身，可以使用转义字符（反斜杠 \ ）来表示。 仅支持设置一个字符。 常用转义字符的场景： 假设两个引用字符之间的数据内容存在第三个引用字符，则在第三个引用字符前加上转义字符，从而避免字段内容被分割。 假设数据内容中原本就存在转义字符，则在这个原有的转义字符前再加一个转义字符，避免原来的那个字符起到转义作用。

修订记录 表1 修订记录 发布日期 更新特性 2024-05-28 第三十六次发布。 新增 提交SQL作业（推荐）新增配置参数spark.sql.legacy.correlated.scalar.query.enabled。 导出查询结果，请求参数新增quote_char和escape_char。 2024-04-08 第三十五次发布。 新增 提交SQL作业（推荐），新增请求参数engine_type。 查询作业列表，新增graph_editor_enabled、duration等响应参数。 查询作业详情，新增graph_editor_enabled、duration等响应参数。 2024-03-11 第三十四次发布。 创建增强型跨源连接，修改tag中value取值说明。 2024-02-29 第三十三次发布。 生成Flink SQL作业的静态流图新增参数flink_version。 提交SQL作业（推荐），修改dli.sql.sqlasync.enabled默认值为true。 创建增强型跨源连接，新增参数elastic_resource_pools。 2024-01-17 第三十二次发布。 新增以下接口： 数据赋权（用户或项目） 2023-12-12 第三十一次发布。 新增以下接口： 创建路由 删除路由 2023-12-07 第三十次发布。 新增以下接口： 创建跨源认证 获取跨源认证列表 更新跨源认证 删除跨源认证 2023-11-27 第二十九次发布。 下线以下接口： 模板相关API（废弃） 增强型跨源连接相关API（废弃） 跨源认证相关API（废弃） 队列相关API（废弃） 权限相关API（废弃） 资源相关API（废弃） SQL作业相关API（废弃） Spark批处理相关API（废弃） 分组资源相关API（废弃） 委托相关API（废弃） 2023-11-22 第二十八次发布。 队列相关API（推荐），修改API Explorer链接。 SQL作业相关API，修改API Explorer链接。 Flink作业相关API，修改API Explorer链接。 Spark作业相关API，修改API Explorer链接。 Flink作业模板相关API，修改API Explorer链接。 增强型跨源连接相关API，修改API Explorer链接。 全局变量相关API，修改API Explorer链接。 弹性资源池相关API，修改API Explorer链接。 SQL模板相关API，修改API Explorer链接。 2023-11-17 第二十七次发布。 查询批处理作业列表，新增字段result_format、result_path。 2023-11-07 第二十六次发布。 查询批处理作业列表，修改job_id为job-id。 2023-09-07 第二十五次发布。 查询所有作业新增字段cpu_cost和output_byte。 创建弹性资源池，charging_mode修改为可选参数。 查询批处理作业列表、查询批处理作业详情新增参数req_body。 2023-09-05 第二十四次发布。 DLI不再支持边缘作业场景的API调用。IEF相关API（废弃）已移动至历史API章节。 2023-03-15 第二十三次发布。 新增查询增强型跨源连接列表和查询增强型跨源连接章节的响应参数elastic_resource_pools。 2023-2-22 第三十二次正式发布。 文档结构调整，新增分组资源相关API（废弃）。 2022-11-26 第三十一次正式发布。 新增： 弹性资源池扩缩容历史记录 跨源认证相关API（废弃） 创建路由（废弃） 删除路由（废弃） SQL模板相关API 2022-11-15 第三十次正式发布。 查看表的用户权限（废弃），修改privileges参数说明。 2022-8-16 第二十九次正式发布。 新建SQL作业，补充参数flink_version。 更新SQL作业，补充参数flink_version。 2022-8-11 第二十八次正式发布。 创建队列定时扩缩容计划（废弃），修改repeat_day参数为必选。 IEF系统事件上报（废弃），修改请求示例。 创建队列请求参数，新增elastic_resource_pool_name。 2021-1-11 第二十七次正式发布。 废弃“查询作业结果”API，修改为“预览作业结果”。 新增创建数据下载作业接口。 新增生成Flink SQL作业的静态流图接口。 2020-12-2 第二十六次正式发布。 下线Spark作业中，会话和语句相关API。 2020-8-4 第二十五次正式发布。 新增委托相关API。 Flink作业相关API增加以下子章节 9.17 创建IEF消息通道 9.18 边缘Flink作业状态上报 9.19 边缘Flink作业Action回调 9.20 IEF系统事件上报 2020-7-20 第二十四次正式发布。 队列相关API（推荐）增加以下子章节 5.9 创建队列定时扩缩容计划 5.10 查看队列定时扩缩容计划 5.11 批量删除队列定时扩缩容计划 5.12 单个删除队列定时扩缩容计划 5.13 修改队列定时扩缩容计划 2020-5-30 第二十三次正式发布。 队列相关API（推荐）增加以下子章节 5.7 创建指定地址连通性测试请求 5.8 查询指定地址连通性测试详情 2020-5-19 第二十二次正式发布。 修改以下章节 2-API概览 2020-5-12 第二十一次正式发布。 增加以下章节及其子章节 13-全局变量相关API 调整目录。 将“流作业相关API”修改为“Flink作业相关API”。 将“流作业模板相关API”修改为“Flink作业模板相关API”。 2020-2-21 第二十次正式发布。 增加以下章节及其子章节 4.5-重启/扩容/缩容队列 4.6-查询队列详情 5.2.8-获取分区信息列表 9-流作业相关API 10-流作业模板相关API 2020-1-22 第十九次正式发布。 增加以下章节 11-权限策略和授权项 2019-8-16 第十八次正式发布。 增加以下章节及其子章节 4.4-增强型跨源连接相关API 2019-5-15 第十七次正式发布。 删除以下章节及其子章节 5.8-提交基因作业相关API 2018-12-13 第十六次正式发布。 增加以下章节及其子章节 5.9-跨源连接相关API 5.8.11-提交cnvkit作业 5.8.12-查询cnvkit作业 2018-8-28 第十五次正式发布。 增加以下章节及其子章节 5.8-提交基因作业相关API 2018-7-26 第十四次正式发布。 增加以下章节及其子章节 5.10.1-对接CloudTable HBase 2018-5-31 第十三次正式发布。 增加以下章节及其子章节 5.7-提交Spark作业相关API 2018-4-25 第十二次正式发布。 增加以下章节 5.2.13-检查SQL语法 5.4.4-预览表内容 2018-4-19 第十一次正式发布。 服务更名 2018-2-6 第十次正式发布。 增加以下章节及其子章节 5.1.2-创建队列 5.1.3-删除队列 6.3-错误码 修改“5-API说明”各章节参数及示例，补充出错说明 2018-01-22 第九次正式发布。 根据模板修改手册大纲 增加以下章节： 1-使用前必读 调整“5-API说明”中所有子章节的section 修改“公共消息头”为“公共参数” 增加以下内容： 5.2.1-提交SQL作业（推荐） 5.2.7-查看作业结果（推荐） 5.2.11-取消作业（推荐） 5.4.1-查看所有表（推荐） 2017-12-28 第八次正式发布。 修改以下内容： 2-接口简介 4.1-服务使用方法 5-API说明章节下的所有子章节 2017-11-30 第七次正式发布。 修改以下内容： 5.2.3-导入数据 5.2.4-导出数据 5.2.6-查询作业详细信息 5.2.9-导出查询结果 5.5.1-队列赋权 5.5.3-数据赋权 5.5.5-查看表的使用者 2017-11-22 第六次正式发布。 修改以下内容： 3.1-获取请求认证章节下的所有子章节 3.2-获取项目编号 6.1-公共请求参数 5.2.3-导入数据 5.2.4-导出数据 5.2.5-查询作业状态 5.2.6-查询作业详细信息 5.2.10-查询所有作业 5.3.2-查看所有数据库 5.4.2-查看所有表（废弃） 5.4.5-创建表 5.5-权限相关API章节下的所有子章节 2017-11-03 第五次正式发布。 修改以下内容： 4-API 2017-10-28 第四次正式发布。 2017-09-30 第三次正式发布。 2017-09-12 第二次正式发布。 修改以下内容： 全文user_id改为user_name 文档中所有queue_id的地方改为queue_name 删除以下内容： 4.2.1-新增队列 4.2.3-删除队列 2017-08-25 第一次正式发布。

请求示例 提交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 ] ] }

响应消息 表5 响应参数 参数名称 是否必选 参数类型 说明 is_success 是 Boolean 请求发送是否成功。“true”表示请求发送成功。 message 是 String 系统提示信息，执行成功时，信息可能为空。 job_id 是 String 此SQL语句将生成并提交一个新作业，返回此作业的ID，可用于获取作业状态和作业结果。 job_type 是 String 作业类型。 DDL 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：同步

请求消息 表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。 表3 conf参数说明 参数名称 默认值 描述 spark.sql.files.maxRecordsPerFile 0 要写入单个文件的最大记录数。如果该值为零或为负，则没有限制。 spark.sql.autoBroadcastJoinThreshold 209715200 配置执行连接时显示所有工作节点的表的最大字节大小。通过将此值设置为“-1”，可以禁用显示。 说明： 当前仅支持运行命令ANALYZE TABLE COMPUTE statistics noscan的配置单元元存储表，和直接根据数据文件计算统计信息的基于文件的数据源表。 spark.sql.shuffle.partitions 200 为连接或聚合过滤数据时使用的默认分区数。 spark.sql.dynamicPartitionOverwrite.enabled false 当前配置设置为“false”时，DLI在覆盖写之前，会删除所有符合条件的分区。例如，分区表中有一个“2021-01”的分区，当使用INSERT OVERWRITE语句向表中写入“2021-02”这个分区的数据时，会把“2021-01”的分区数据也覆盖掉。 当前配置设置为“true”时，DLI不会提前删除分区，而是在运行时覆盖那些有数据写入的分区。 spark.sql.files.maxPartitionBytes 134217728 读取文件时要打包到单个分区中的最大字节数。 spark.sql.badRecordsPath - Bad Records的路径。 spark.sql.legacy.correlated.scalar.query.enabled false 该参数设置为true： 当子查询中数据不重复的情况下，执行关联子查询，不需要对子查询的结果去重。 当子查询中数据重复的情况下，执行关联子查询，会提示异常，必须对子查询的结果做去重处理，比如max(),min()。 该参数设置为false： 不管子查询中数据重复与否，执行关联子查询时，都需要对子查询的结果去重，比如max(),min()，否则提示异常。 表4 tags参数 参数名称 是否必选 参数类型 说明 key 是 String 标签的键。 说明： 标签的键的最大长度为128个字符，标签的键可以包含任意语种字母、数字、空格和_ . : =+-@ ,但首尾不能含有空格，不能以_sys_开头。 value 是 String 说明： 标签值的最大长度为255个字符，标签的值可以包含任意语种字母、数字、空格和_ . : =+-@ ,但首尾不能含有空格。