Doris Schema Change 常见问题分析

什么是 Schema Change

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

⚠️Schema Change 限制⚠️

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

定位 Schema Change 问题需要的信息

select @@version_comment;

show create table table_name;

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

常见 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.

解决方案

1. 查看相关配置项 memory_limitation_per_thread_for_schema_change_bytes
   （默认为 2GB）。
2. 检查对应 Tablet 的数据大小和 Rowset 分布：

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

3. 调整 memory_limitation_per_thread_for_schema_change_bytes
    为大于最大 Rowset 大小的值。
4. 在 2.0/2.1 版本中，内存限制是自适应的，可以通过日志来看：

   grep "start alter tablet" be.INFO | grep mem_limit
   
   

5. 如果自适应内存仍不足，将 memory_limitation_per_thread_for_schema_change_bytes
    调大，同时将 alter_tablet_worker_count
    设为 1，避免占用过多内存。

问题定位

1. 判断是否正在进行 Schema Change：

• 在 be.WARNING
   日志中找到 -235 对应的 Tablet ID。

2. 使用以下命令查看 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} 
   
   

解决方案

1. 临时增大 max_tablet_version_num
   （默认值为 2000）：

   curl -X POST xxx.xxx.xxx.xxx:8040/api/update_config?max_tablet_version_num=20000
   
   

   同时修改 be.conf
    中的配置，完成后可恢复默认值。 

错误描述

Schema change 一直处于 waiting_txn 状态。

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

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

解决方案

1. 获取冲突事务信息：

• 在 be.INFO
   中查找对应的 txn_id
  。

2. 中止事务：

   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
   
   

错误描述

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

解决方案

1. 在 JAVA_OPTS
    中修改参数，将内存使用情况dump 出来：

   -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=<path>
   
   

2. 使用工具（如 jprofiler）分析内存开销，定位问题。
3. 临时解决方案：
• 如果 FE 能正常重启，直接取消任务。
• 如果不能正常重启，先停止所有 BE，然后重启 FE 并取消任务。

问题描述

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

  history_job_keep_max_second = 7 * 24 * 3600

解决方案

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

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

总结

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