当前位置：首页 > news >正文

Doris Schema Change 常见问题分析

news 来源：原创 2025/5/21 11:15:39

在这里插入图片描述

1. 什么是 Schema Change

Schema Change 是在数据库中修改表结构的一种操作，例如添加列、删除列、更改列类型等。

⚠️Schema Change 限制⚠️

一张表在同一时间只能有一个 Schema Change 作业在运行。
分区列和分桶列不能修改。
如果聚合表中有 REPLACE 方式聚合的 Value 列，则不允许删除 Key 列。
Unique 表不允许删除 Key 列。
在新增聚合类型为 SUM 或者 REPLACE 的 Value 列时，该列的默认值对历史数据没有含义。
因为历史数据已经失去明细信息，所以默认值的取值并不能实际反映聚合后的取值。
当修改列类型时，除 Type 以外的字段都需要按原列上的信息补全。
注意，除新的列类型外，如聚合方式，Nullable 属性，以及默认值都要按照原信息补全。
不支持修改聚合类型、Nullable 属性和默认值。

2. 定位 Schema Change 问题需要的信息

版本信息：最好精确到 commit 号。

select @@version_comment;

日志文件：
- FE 日志目录下的 fe.log 和 fe.audit.log，以获取最近的 Schema Change 语句。
- BE 日志目录下的 be.INFO。
表结构：获取表的当前结构。

show create table table_name;

内存状态：如果是 FE OOM 问题，需要 dump FE 内存进行分析。

a. 获取FE进行的pidz
b. dump文件获取：执行jmap -dump:format=b,file=heapdump.phrof pidz

3. 常见 Schema Change 问题及解决方案

3.1 BE 内存不足导致 Schema Change 失败

错误描述

errCode = 2, detailMessage = rollup tasks failed on same tablet reach threshold [[ALTER], signature: 3404761, backendId: 294163, tablet id: 3404761], reason=task type: ALTER, status_code: MEM_LIMIT_EXCEEDED, status_message: [(xx.xx.xx.xx)[MEM_LIMIT_EXCEEDED]PreCatch error code:11, [E11] Allocator mem tracker check failed, [MEM_LIMIT_EXCEEDED]failed alloc size 64.00 KB, memory tracker limit exceeded, tracker label:EngineAlterTabletTask#baseTabletId=3375343:newTabletId=3404761, type:schema_change, limit 2.00 GB, peak used 2.00 GB, current used 2.00 GB. backend xx.xx.xx.xx process memory used 12.22 GB. can modify `memory_limitation_per_thread_for_schema_change_bytes` in be.conf to change limit, details see be.INFO.

解决方案

查看相关配置项 memory_limitation_per_thread_for_schema_change_bytes（默认为 2GB）。

检查对应 Tablet 的数据大小和 Rowset 分布：

curl http://xx.xx.xx.xx:8040/api/compaction/show?tablet_id=${tablet_id}

调整 memory_limitation_per_thread_for_schema_change_bytes 为大于最大 Rowset 大小的值。
在 2.0/2.1 版本中，内存限制是自适应的，可以通过日志来看：
```
grep "start alter tablet" be.INFO | grep mem_limit
```
如果自适应内存仍不足，将 memory_limitation_per_thread_for_schema_change_bytes 调大，同时将 alter_tablet_worker_count 设为 1，避免占用过多内存。

3.2 Schema Change 耗时过长导致 -235 错误

问题定位

判断是否正在进行 Schema Change：
- 在 be.WARNING 日志中找到 -235 对应的 Tablet ID。

使用以下命令查看 Tablet 状态：

curl -X POST -H "Content-Type: application/json" -d '{"stmt":  "show tablet ${tablet_id}"}' http://xx.xx.xx.xx:8030/api/show/db

如果表名前缀为 _doris_shadow_，说明是新建的 Tablet。结果示例：

[["default_cluster:avi","base_blocks","month_202405","__doris_shadow_base_blocks","10839","471528","476493","891940","true","7","0","SHOW PROC '/dbs/10839/471528/partitions/476493/891940/892915';"]],"meta":[{"name":"DbName","type":"VARCHAR"},{"name":"TableName","type":"VARCHAR"},{"name":"PartitionName","type":"VARCHAR"},{"name":"IndexName","type":"VARCHAR"},{"name":"DbId","type":"VARCHAR"},{"name":"TableId","type":"VARCHAR"},{"name":"PartitionId","type":"VARCHAR"},{"name":"IndexId","type":"VARCHAR"},{"name":"IsSync","type":"VARCHAR"},{"name":"Order","type":"VARCHAR"},{"name":"QueryHits","type":"VARCHAR"},{"name":"DetailCmd","type":"VARCHAR"}],"type":"result_set"},"count":0}

解决方案

临时增大 max_tablet_version_num（默认值为 2000）：
```
curl -X POST xxx.xxx.xxx.xxx:8040/api/update_config?max_tablet_version_num=20000
```
同时修改 be.conf 中的配置，完成后可恢复默认值。

3.3 Schema Change 长时间处于等待水位线状态

错误描述

Schema change 一直处于 waiting_txn 状态。

//执行下面命令查看状态
show alter table column

Schema change 会等待双写节点前所有的事务完成才开始数据的转换. 因为有未决事务, 所以一直等待。由于stream load 是 2PC的，在发起第一阶段的时候挂了，就会需要等待 stream load 超时之后才能让 schema change 开始执行。

解决方案

获取冲突事务信息：
- 在 be.INFO 中查找对应的 txn_id。

中止事务：

curl -X PUT --location-trusted -u user:passwd  -H "txn_id:xxx" -H "txn_operation:abort"  http://fe_host:http_port/api/{db}/{table}/_stream_load_2pc

3.4 Schema Change 导致 FE OOM

错误描述

执行 schema change 的时候，FE 内存快速上涨并且OOM

解决方案

在 JAVA_OPTS 中修改参数，将内存使用情况dump 出来：
```
-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=<path>
```
使用工具（如 jprofiler）分析内存开销，定位问题。
临时解决方案：
- 如果 FE 能正常重启，直接取消任务。
- 如果不能正常重启，先停止所有 BE，然后重启 FE 并取消任务。

3.5 Schema Change 任务过多

问题描述

Schema change job 默认会保持 7 天。Schema Change 任务的历史记录占用大量内存。

  history_job_keep_max_second = 7 * 24 * 3600

解决方案

调整历史记录保留时间，在启动时临时调小该值，完成任务后恢复。

注：如果提前预知到自己需要执行大量schema change，可以先把history_job_keep_max_second 调小，在执行完之后再恢复。

4. 总结

Schema Change 是 Doris 中非常关键的功能，其复杂性也带来了许多潜在问题。通过精准定位问题根因，并结合上述方法进行优化，可解决大部分问题。如果有任何疑问或者问题，可以随时联系我或者Doris社区的同学～

1. 什么是 Schema Change

2. 定位 Schema Change 问题需要的信息

3. 常见 Schema Change 问题及解决方案

3.1 BE 内存不足导致 Schema Change 失败

错误描述

解决方案

3.2 Schema Change 耗时过长导致 -235 错误

问题定位

解决方案

3.3 Schema Change 长时间处于等待水位线状态

错误描述

解决方案

3.4 Schema Change 导致 FE OOM

错误描述

解决方案

3.5 Schema Change 任务过多

问题描述

解决方案

4. 总结

相关文章：