Apache Spark SQL Hive Row Format 语法详解：SERDE 与 DELIMITED 的完整使用指南

大数据数据分析批处理流处理机器学习图计算【免费下载链接】sparkApache Spark - A unified analytics engine for large-scale data processing项目地址https://gitcode.com/gh_mirrors/sp/spark点击查看免费下载本文档是 Apache Spark 官方 SQL 语法参考系列的一部分对应仓库文档 docs/sql-ref-syntax-hive-format.md。Hive Row Format 用于在CREATE TABLE与TRANSFORM含MAP/REDUCE等子句中指定 SerDe 类或文本分隔符是打通 Spark 与 Hive 生态数据读写格式的关键语法。读完本文你将掌握ROW FORMAT SERDE与ROW FORMAT DELIMITED两种定义方式、全部子句参数字段/集合/Map/行分隔符、NULL 表示、转义字符的语义与默认行为并理解 Spark 解析器与 Hive 底层 SerDe 属性之间的映射规则。一、概述DescriptionSpark 在CREATE TABLE和TRANSFORM子句中支持Hive row format用于指定 SerDe 类或文本分隔符。CREATE TABLE与TRANSFORM的row_format有两种定义方式SERDE子句指定一个自定义的 SerDe 类fully-qualified class nameDELIMITED子句为原生 SerDenative SerDe指定分隔符delimiter、转义字符escape character、空值字符null character等。从语法解析的实现看这两种方式最终都会被解析成同一份SerdeInfo数据结构定义于 statements.scala它统一承载storedAs、formatClasses、serde类名与serdeProperties键值对。ANTLR 文法 SqlBaseParser.g4 中的rowFormat规则完整对应了本文档的两种语法形态。二、语法Syntaxrow_format: SERDE serde_class [ WITH SERDEPROPERTIES (k1v1, k2v2, ... ) ] | DELIMITED [ FIELDS TERMINATED BY fields_terminated_char [ ESCAPED BY escaped_char ] ] [ COLLECTION ITEMS TERMINATED BY collection_items_terminated_char ] [ MAP KEYS TERMINATED BY map_key_terminated_char ] [ LINES TERMINATED BY row_terminated_char ] [ NULL DEFINED AS null_char ]两种形态互斥只能二选一。DELIMITED形态下除了FIELDS TERMINATED BY是可选项其余各子句均为可选可按需自由组合。2.1 row_format 可出现的语法位置row_format不仅仅出现在建表语句中。从 ANTLR 文法可以看出Spark 在以下语法位置都允许嵌入row_formatCREATE TABLE / CREATE TABLE LIKE建表时可指定行格式例如CREATE TABLE ... LIKE source (rowFormat | createFileFormat | locationSpec | TBLPROPERTIES ...)*见 SqlBaseParser.g4CREATE TABLE ... 含分区、分桶、SKEWED 等完整建表子句列表rowFormat与createFileFormat、locationSpec、bucketSpec等并列出现在建表选项列表中见 SqlBaseParser.g4INSERT OVERWRITE (LOCAL) DIRECTORY向目录写出数据时可指定rowFormat与createFileFormat见 SqlBaseParser.g4TRANSFORM / MAP / REDUCE 子句SELECT TRANSFORM(...) ... USING script的输入行格式inRowFormat与输出行格式outRowFormat见 SqlBaseParser.g4。2.2 解析器如何构建 SerdeInfo在 AstBuilder.scala 中visitRowFormat根据语法树节点类型分发RowFormatSerdeContext→visitRowFormatSerde把SERDE serde_name解析为SerdeInfo(serde Some(name), serdeProperties ...)WITH SERDEPROPERTIES中的键值对直接进入serdeProperties映射RowFormatDelimitedContext→visitRowFormatDelimited把 DELIMITED 形态中的每个分隔符映射为对应名称的 SerDe 属性详见下文第四节。三、参数说明Parameters参数语义说明SERDE serde_class指定自定义 SerDe 的完整限定类名fully-qualified class name必须给出可被类加载器加载的完整类路径例如 Hive 生态常见的org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe、JsonSerDe等SERDEPROPERTIES一组用于标记 SerDe 定义的键值对key-value pairs透传给 SerDe 的初始化属性例如(field.delim\t, serialization.format\t)FIELDS TERMINATED BY定义列分隔符column separator指定字段之间的分隔字符COLLECTION ITEMS TERMINATED BY定义集合元素分隔符collection item separator用于 Array、Struct 等集合类型内部元素的切分MAP KEYS TERMINATED BY定义 Map 键分隔符map key separator用于 Map 类型中键与值之间的切分LINES TERMINATED BY定义行分隔符row separatorSpark 仅接受\n其他字符会被拒绝见下文NULL DEFINED AS定义 NULL 的特定表示值指定文本文件中表示空值的字符序列ESCAPED BY转义机制escape mechanism指定转义字符用于转义分隔符或特殊字符注意SERDEPROPERTIES的键值对写法是kv1但在实际 SQL 中通常写作带引号的字符串键值对例如WITH SERDEPROPERTIES (field.delim \t)这在CREATE TABLE与TRANSFORM语法中均被支持。四、DELIMITED 子句与底层 SerDe 属性的映射源码级DELIMITED 形态的每个子句并不会被存成独立字段而是被转换成 Hive SerDe 的serdeProperties。visitRowFormatDelimited见 AstBuilder.scala逐项完成映射SQL 子句生成的 serdeProperties 键说明FIELDS TERMINATED BYfield.delim与serialization.format同时写入两个键供不同 SerDe 解析使用ESCAPED BYescape.delim转义字符COLLECTION ITEMS TERMINATED BYcolelction.delim注意拼写为colelction少一个 l源码注释明确说明这是继承自 Hive 的拼写错误必须沿用MAP KEYS TERMINATED BYmapkey.delimMap 键值分隔符LINES TERMINATED BYline.delim行分隔符NULL DEFINED AS——源码中entry(null, ...)尚未实现注释标注TODO we need proper support for the NULL format即当前 DELIMITED 形态对 NULL 自定义值的支持仍属 TODO 状态两个值得关注的实现细节LINES TERMINATED BY 只接受\n当LINES TERMINATED BY的值不是\n时解析器直接抛出QueryParsingErrors.unsupportedRowFormatLinesTerminatedByError见 AstBuilder.scala。这意味着在 Spark 中行分隔符实际上是固定为换行符的无法像 Hive 那样自由指定行分隔符。映射即 SerDe 属性DELIMITED 形态最终生成的也是一个SerdeInfo(serdeProperties entries.toMap)只是不指定serde类交由原生默认SerDe 读取这些属性。五、ROW FORMAT 与 STORED AS 的兼容性规则ROW FORMAT不能与任意文件格式随意组合。解析器在validateRowFormatFileFormat见 AstBuilder.scala中强制校验以下组合除此之外都会抛出 ParseExceptionROW FORMAT SERDE ... STORED AS [SEQUENCEFILE | RCFILE | TEXTFILE]—— 允许ROW FORMAT DELIMITED ... STORED AS TEXTFILE—— 允许ROW FORMAT ... STORED AS INPUTFORMAT ... OUTPUTFORMAT ...—— 允许显式指定 InputFormat/OutputFormat其他组合例如ROW FORMAT SERDE搭配PARQUET/ORC/AVRO等自带 SerDe 的格式或ROW FORMAT DELIMITED搭配非 TEXTFILE 格式—— 不允许。对应测试用例位于 DDLParserSuite.scala例如ROW FORMAT SERDE customSerde WITH SERDEPROPERTIES (propvalue)搭配STORED AS otherFormat会报错ROW FORMAT SERDE is incompatible with format otherformat, which also specifies a serdeROW FORMAT DELIMITED FIELDS TERMINATED BY ,搭配非 TEXTFILE 格式会报错ROW FORMAT DELIMITED is only compatible with textfile, not otherformat。六、实战示例6.1 CREATE TABLE 中使用 ROW FORMAT SERDE指定自定义 SerDe 类并透传 SerDe 属性CREATE TABLE hive_serde_table ( name STRING, age INT ) ROW FORMAT SERDE org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe WITH SERDEPROPERTIES ( field.delim \t, serialization.format \t );6.2 CREATE TABLE 中使用 ROW FORMAT DELIMITED使用原生 SerDe 并指定完整的分隔符组合CREATE TABLE hive_delimited_table ( id INT, name STRING, tags ARRAYSTRING, attributes MAPSTRING, STRING ) ROW FORMAT DELIMITED FIELDS TERMINATED BY , ESCAPED BY \\ COLLECTION ITEMS TERMINATED BY # MAP KEYS TERMINATED BY : LINES TERMINATED BY \n NULL DEFINED AS \\N;上例中字段用逗号切分数组元素用#切分Map 键值对用:切分转义字符为反斜杠NULL 在文本中以\N表示。注意LINES TERMINATED BY在 Spark 中只能取\n。6.3 CREATE TABLE LIKE 中继承行格式CREATE TABLE LIKE子句允许在复制表结构的同时显式覆盖行格式CREATE TABLE new_table LIKE source_table ROW FORMAT SERDE customSerde WITH SERDEPROPERTIES (prop value);6.4 TRANSFORM 子句中使用 ROW FORMATSELECT TRANSFORMMAP/REDUCE为其别名可以分别为脚本的输入与输出指定行格式SELECT TRANSFORM (id, name) ROW FORMAT DELIMITED FIELDS TERMINATED BY , USING /usr/bin/awk -F, \{print $1, toupper($2)}\ AS (id INT, name STRING) ROW FORMAT DELIMITED FIELDS TERMINATED BY ,;6.5 INSERT OVERWRITE DIRECTORY 中使用 ROW FORMAT向目录导出文本时指定分隔符INSERT OVERWRITE LOCAL DIRECTORY /tmp/export ROW FORMAT DELIMITED FIELDS TERMINATED BY \t SELECT name, age FROM people;七、注意事项与限制结合源码行分隔符受限LINES TERMINATED BY仅接受\n设置其他字符会在解析阶段直接报错源码见 AstBuilder.scala。colelction.delim拼写是历史遗留COLLECTION ITEMS TERMINATED BY映射到的属性键为colelction.delimHive 拼写错误使用SERDEPROPERTIES直接手写属性时必须保持该拼写才能生效。NULL 自定义支持未完成NULL DEFINED AS在 DELIMITED 形态下尚未映射到任何 SerDe 属性源码中有对应 TODO 注释实际效果需要结合所用 SerDe 的自身属性如 LazySimpleSerDe 的serialization.null.format来实现。SERDE 与自带 SerDe 的文件格式不兼容PARQUET、ORC 等格式自带序列化方案不能与ROW FORMAT SERDE混用否则建表报错。SERDEPROPERTIES 是透传机制Spark 本身不解释属性值的业务含义只负责将其原样绑定到表/目录的 SerDe 上具体解析由对应 SerDe 类完成。八、相关资源本文档原文docs/sql-ref-syntax-hive-format.md语法文法定义SqlBaseParser.g4解析实现AstBuilder.scalaSerdeInfo 数据结构statements.scala兼容性与错误提示测试DDLParserSuite.scala赞分享大数据数据分析批处理流处理机器学习图计算【免费下载链接】sparkApache Spark - A unified analytics engine for large-scale data processing项目地址https://gitcode.com/gh_mirrors/sp/spark点击查看免费下载相关推荐Apache Spark SQL 的 LOAD DATA 语句向 Hive Serde 表装载数据文件的完整指南Apache Spark SQL 的 LOAD DATA 语句向 Hive Serde 表装载数据文件的完整指南 LOAD DATA 是 Apache Spa大数据数据分析批处理流处理机器学习图计算Apache Spark SQL 语法精解SHOW TABLES 命令的完整使用指南Apache Spark SQL 语法精解SHOW TABLES 命令的完整使用指南 导读 SHOW TABLES 是 Apache Spark SQL 中最大数据数据分析批处理流处理机器学习图计算Apache Spark SQL 集成 Hive UDF / UDAF / UDTF 完整指南Apache Spark SQL 集成 Hive UDF / UDAF / UDTF 完整指南 导读 本文以 Apache Spark 官方 SQL 参考文档大数据数据分析批处理流处理机器学习图计算创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考