External Table Error Mode¶
文件型外部表暴露三个隐藏列,按行报告源文件行号、错误消息以及加载失败记录的原始文本。查询这些列会把“在第一条坏记录处失败”的加载转变为“将坏记录作为行报告”的加载。
描述¶
默认情况下,扫描 CSV 或 JSONLine 外部表时,遇到第一条无法解析或转换的记录会以错误中止。当查询选择任一错误列时,扫描改为将坏记录作为行报告:正常记录保留其值,坏记录携带其错误状态。这样,一次扫描即可把正常记录写入目标表,把坏记录写入拒绝表。
语法¶
SELECT a, s, __mo_file_line, __mo_error_message, __mo_error_text FROM em_csv;
按名称从 CSV 或 JSONLine 外部表中选择这些隐藏错误列。选择 __mo_error_message 或 __mo_error_text 会为该次扫描启用错误模式。
参数¶
这些隐藏列可像普通列一样被选择:
列 |
类型 |
含义 |
|---|---|---|
|
bigint |
记录在源文件中起始的行号。 |
|
varchar |
该记录的错误消息;记录干净加载时为 |
|
varchar |
失败记录的原始源文本。 |
这些列在 SELECT *、DESC 与 SHOW CREATE TABLE 中隐藏,但可按名称查询。记录的失败是记录本身的属性,与投影无关:在坏记录上选择 __mo_error_message(或 __mo_error_text)都会报告它,无论同时选择了哪些声明列。
使用说明¶
正常与坏记录:正常记录满足
__mo_error_message IS NULL;坏记录满足__mo_error_message IS NOT NULL。用这些谓词分流行。仅
__mo_file_line不够:只选择__mo_file_line属于位置元数据,并非请求容忍错误;扫描仍会在第一条坏记录处失败。必须选择任一错误列才能启用错误模式。Parquet 不受影响:Parquet 以类型化列值解码而非文本,因此没有可报告的行号或记录文本;错误列在那里不生效。
保留名称:这三个列名是保留的,不能在用户表上声明。
示例¶
以下示例创建 CSV 外部表,展示错误列在表结构中保持隐藏,并演示保留名称会被拒绝。该示例不执行扫描,因此 DDL 阶段无需源文件存在:
DROP DATABASE IF EXISTS ext_error_demo;
CREATE DATABASE ext_error_demo;
USE ext_error_demo;
CREATE EXTERNAL TABLE em_csv (a INT, s VARCHAR(20))
INFILE{'filepath'='/tmp/external_table_file/error_mode.csv'}
FIELDS TERMINATED BY ',' LINES TERMINATED BY '\n';
DESC em_csv;
SHOW CREATE TABLE em_csv;
-- Expected-Success: false
CREATE TABLE em_reserved (a INT, __mo_error_message VARCHAR(10));
DROP DATABASE ext_error_demo;
分流正常与坏记录需要读取文件,因此仅作语法模板而非可直接粘贴执行的脚本:
-- report the bad records instead of failing
SELECT a, s, __mo_file_line, __mo_error_message, __mo_error_text FROM em_csv;
-- route good records into a destination table and bad records into a rejects table
INSERT INTO dest (id, name)
SELECT a, s FROM em_csv WHERE __mo_error_message IS NULL;
INSERT INTO rejects (line, msg, txt)
SELECT __mo_file_line, __mo_error_message, __mo_error_text
FROM em_csv WHERE __mo_error_message IS NOT NULL;