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。
- FE 日志目录下的
- 表结构：获取表的当前结构。
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=20000be.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社区的同学～
