ClickHouse批量插入时能否忽略失败行并返回失败数据？

ClickHouse确实支持跳过批量插入中的失败行，并返回具体的错误行数据，不会直接导致整个批量插入任务失败，通过特定的会话级设置参数即可实现。

核心控制参数 #

ClickHouse提供了三个关键参数来实现该需求：

• input_format_skip_errors_num：允许跳过的绝对错误行数，默认值为0（不跳过任何错误），设置为正数则允许对应数量的错误行。
• input_format_skip_errors_ratio：允许跳过的错误行占总插入行的比例，范围是0到1，比如0.1表示允许最多10%的错误行。
• input_format_report_error_rows：设置为1时，ClickHouse会在返回结果中包含错误行的具体内容及失败原因（默认值为0）。

实际使用示例 #

在执行批量插入语句时，通过SETTINGS子句添加这些参数即可生效，以下是不同格式的插入示例：

CSV格式插入 #

INSERT INTO target_table
FORMAT CSV
SETTINGS
    input_format_skip_errors_num = 5,  -- 最多跳过5条错误行
    input_format_report_error_rows = 1;  -- 返回错误行详情

JSONEachRow格式插入 #

INSERT INTO target_table
FORMAT JSONEachRow
SETTINGS
    input_format_skip_errors_ratio = 0.05,  -- 最多跳过总插入行的5%
    input_format_report_error_rows = 1;

错误返回示例 #

当插入存在错误行时，ClickHouse会完成所有正确行的插入，同时在响应中返回错误详情，类似如下内容：

Row 3: Wrong type for column 'user_age': expected UInt8, got String 'not_a_number'
Row 7: Missing value for required column 'user_email'
Skipped 2 errors.

关键注意事项 #

• 两个错误跳过参数（num和ratio）是或的关系，只要其中一个条件触发（达到允许的错误行数或比例），后续出现的错误会直接终止整个插入任务。
• 虽然该功能可以临时绕过错误行，但建议优先排查插入失败的根本原因：比如数据类型不匹配、违反表约束、字段缺失等，避免依赖错误跳过机制掩盖数据质量问题。
• 这些参数仅适用于基于输入格式的插入操作（如CSV、JSON等），不适用于INSERT ... SELECT这类查询式插入场景。

内容的提问来源于stack exchange，提问作者AlexMorley-Finch