StarRocks作为一款高性能分布式分析型数据库，在实时数仓、日志分析、用户画像等场景中被广泛应用。数据写入过程中，INSERT操作是最常见的数据导入方式之一。然而，在开启严格模式（strict mode）后，部分数据可能会出现被过滤、写入失败或者导入任务异常等问题。
严格模式主要用于保证数据质量，当源数据不符合目标表字段定义、类型转换规则或者约束条件时，StarRocks会拒绝异常数据，而不是自动进行宽松转换。因此，了解INSERT数据过滤的原因以及正确排查方法，对于保障数据稳定写入具有重要意义。
StarRocks严格模式简介
StarRocks的数据导入机制支持严格模式控制。严格模式开启后，系统会对导入数据进行更加严格的数据校验，包括：
字段类型是否匹配；
数据格式是否符合要求；
字段长度是否超出限制；
NULL值是否满足字段定义；
日期、时间等特殊类型是否能够正常转换。
如果某条数据无法通过校验，StarRocks不会强制写入，而是将其视为错误数据进行过滤。
例如，目标表定义如下：
CREATE TABLE user_info (
id INT,
username VARCHAR(20),
age INT
)
DUPLICATE KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 3;执行：
INSERT INTO user_info VALUES
(1, 'Tom', 'abc');由于age字段定义为INT类型，而插入的数据为字符串abc，在严格模式下该记录会被过滤。
INSERT数据被过滤的常见原因
1. 字段类型转换失败
这是最常见的数据过滤原因。
StarRocks支持部分隐式类型转换，例如数字字符串转换为数字，但无法保证所有格式都可以转换。
常见异常包括：
字符串无法转换为数字；
日期格式错误；
小数写入整数导致精度异常；
空字符串转换失败。
例如：
INSERT INTO orders VALUES
(1001, '2026-13-40');如果目标字段为DATE类型，由于日期格式非法，数据会被过滤。
排查方式：
查看导入任务详情：
SHOW LOAD;或者查询具体任务：
SHOW LOAD WHERE LABEL = 'your_label';重点关注：
ErrorURL；
error message；
filtered rows。
这些信息可以快速定位失败原因。
2. NULL值导致写入失败
如果目标字段定义为NOT NULL，而INSERT数据包含NULL，则严格模式下会直接过滤。
例如：
CREATE TABLE product (
id INT NOT NULL,
name VARCHAR(50)
);执行：
INSERT INTO product VALUES(NULL,'phone');会出现数据无法写入的问题。
解决方案：
方式一：插入前处理NULL数据。
INSERT INTO product
SELECT
IFNULL(id,0),
name
FROM source_table;方式二：根据业务需求调整字段允许NULL：
ALTER TABLE product MODIFY COLUMN id INT NULL;3. VARCHAR字段长度超限
StarRocks不会无限制存储字符串。
例如：
CREATE TABLE employee (
id INT,
name VARCHAR(10)
);插入：
INSERT INTO employee VALUES
(1,'this_is_long_username');字符串长度超过10个字符时，在严格模式下可能被过滤。
解决方法：
扩大字段长度：
ALTER TABLE employee
MODIFY COLUMN name VARCHAR(100);或者在写入前截断：
INSERT INTO employee
SELECT
id,
SUBSTRING(name,1,10)
FROM temp_employee;4. 日期时间格式异常
日期字段是INSERT过滤问题中的高频区域。
常见错误：
错误：
2026/08/24目标格式：
2026-08-24或者：
2026-08-24 25:61:00时间范围非法。
建议在写入前统一格式：
SELECT
STR_TO_DATE(create_time,'%Y-%m-%d')
FROM source_table;对于ETL流程，应尽量在数据进入StarRocks之前完成格式标准化。
如何查看INSERT过滤原因
查看INSERT执行结果
执行INSERT后，可以关注返回信息，例如：
Query OK, 9500 rows affected, 500 rows filtered其中：
affected rows表示成功写入数量；
filtered rows表示被过滤数量。
如果过滤数量大，需要进一步分析。
查询导入任务日志
对于INSERT INTO SELECT或者批量导入任务，可以通过：
SHOW LOAD;查看任务状态。
重点字段：
| 字段 | 说明 |
|---|---|
| State | 任务状态 |
| LoadRows | 读取数据量 |
| LoadedRows | 成功写入量 |
| FilteredRows | 过滤数据量 |
| ErrorMsg | 错误原因 |
通过FilteredRows可以判断是否存在大量异常数据。
使用错误数据文件定位问题
StarRocks通常会生成错误数据地址，可以通过ErrorURL查看具体失败记录。
错误文件通常包含：
原始数据内容；
错误字段；
错误原因。
例如：
Invalid INT value: abc表示整数字段出现非法字符串。
根据错误记录修改源数据，可以避免后续重复失败。
严格模式下INSERT问题解决方案
方法一：修正源数据
这是最推荐的方式。
例如：
原始数据：
id,name,age
1,Tom,abc修改为：
id,name,age
1,Tom,18保证进入数据库的数据符合模型要求。
方法二：关闭严格模式
如果业务允许部分异常数据自动转换，可以关闭严格模式。
例如：
SET enable_insert_strict = false;关闭后，StarRocks可能会尝试完成部分类型转换。
但是需要注意：
数据质量可能下降；
异常数据可能被转换为默认值；
问题数据不容易被发现。
生产环境通常不建议长期关闭严格模式。
方法三：INSERT前增加数据清洗逻辑
通过SQL提前过滤异常数据。
例如：
INSERT INTO target_table
SELECT *
FROM source_table
WHERE age REGEXP '^[0-9]+$';只允许合法数字进入目标表。
对于复杂业务，可以建立数据清洗层：
ODS → 清洗层 → StarRocks明细表。
方法四：合理设计表结构
表结构设计不合理，也会增加数据过滤概率。
建议：
VARCHAR长度根据业务最大值设计；
可为空字段不要设置NOT NULL；
时间字段统一格式；
数值字段避免混用字符串。
良好的数据模型能够减少大量导入异常。
StarRocks INSERT严格模式最佳实践
1. 导入前进行数据质量检查
在正式写入前，可以执行：
SELECT COUNT(*)
FROM source_table