IoTDB 常见问题 Q&A 第一期

开始！关于 IoTDB 的 Q&A

我们将定期汇总社区讨论频繁的问题，并展开进行详细回答，通过积累常见问题“小百科”，方便大家使用 IoTDB。

Q1：WAL 堆积导致写入失败

问题及现象

集群报错：

The write is rejected because the wal directory size has reached the threshold 53687091200 bytes. You may need to adjust the flush policy of the storage storageengine or the IoTConsensus synchronization parameter`

原因及方案

• 1.1.0 及之前版本重启可能会导致 WAL 出现堆积，出现该现象时建议升级到当前最新版本 1.3.3。

• 在 1.3.3 版本如果依然出现该问题，可能有以下排查思路：

• 节点状态异常：执行 show cluster 或者 show cluster details 查看各个节点状态是否有 Unknown 或者 ReadOnly 状态。如果有则查看具体日志，针对出现问题的原因进行解决。

• 节点写入负载过大导致副本同步速度不够：如果在日志中发现存在共识组的 searchIndex 和 safeIndex 相差较多，可以尝试调整副本同步流水线并发阈值 data_region_iot_max_pending_batches_num 为 1 来提高同步效率。

• 内存较大 / Region 数较多/ 时间分区较多：可以手动执行 flush 命令将 memtable 刷盘，之后堆积的 WAL 即可被删除。如果未来依然会堆积报错，可以手动调整 iotdb-common.properities 中的 iot_consensus_throttle_threshold_in_byte 从 53687091200（50GB） 至更大值（例如 200GB）后即可暂时规避该问题。

• Pipe 同步任务过多：减少同步任务，或者指定 Pipe 同步类型为文件同步。

Q2：AINode call inference 语句报错

问题及现象

使用 AINode 的 call inference 语句后报错：

Msg: org.apache.iotdb.jdbc.IoTDBSOLException：301: Error ocurred while executing inference:['tuple' object has no attribute 'inference']

解决方法

可以替换 venv 里面的 iotdb 包中的 built_in_model_factory.py 文件的内容来解决，修改后重启即可，命令如下：

sed -i '102s/return model, attributes/return model/' venv/lib/python3.11/site-packages/iotdb/ainode/model/built_in_model_factory.py

Q3：IoTDB 删除数据后文件大小不减反增

现象

IoTDB 删除大量数据后，为什么 data 空间不减反增？

原因

• IoTDB 的存储引擎采用 LSM（Log-Structured Merge）架构。在执行删除操作时，系统会生成 .mod 文件来标记删除的数据。这些删除标记会在后续的合并过程中被处理，合并操作会将标记删除的数据进行物理删除。

• 但如果合并没有触发，或者某个文件长时间没有被合并，那么 .mod 文件中标记删除的数据实际上不会被删除，从而导致空间占用不减反增。

解决方案

• 可以通过检查是否生成 .mod 文件来判断数据是否被删除。使用 settle 工具触发合并任务，实际删除被标记的数据（前提是 tsfile 中有对应的 .mod 文件）。

• 可以通过配置 TTL（数据过期时间）来定期删除数据，确保过期数据被及时清除。

Q4：wal buffer 创建失败，报错 out of memory

现象

Region 目录创建成功后，wal buffer 创建失败，日志参考如下：

原因

数据在写入过程中会先写入 WAL，WAL 在申请堆外空间过程中，空间不足申请失败，导致无法写入 WAL。

解决方案

（1）调大堆外内存

• 1.3.0 以及之后的版本：在 conf/datanode-env.sh 或 conf/datanode-env.bat 中找到 OFF_HEAP_MEMORY 并调大，然后再次启动。

• 1.3.0 之前的版本：在 conf/datanode-env.sh 或 conf/datanode-env.bat 中找到 MAX_DIRECT_MEMORY_SIZE 并调大，然后再次启动。

（2）降低各个模块对 direct memory 的使用量

wal_buffer_size_in_byte=33554432schema_region_ratis_log_appender_buffer_size_max=16777216

1.3.3 版本前，可以在 conf/iotdb-common.properties 中找到以上配置。1.3.3 版本后，可在 conf/iotdb-system.properties.template 中找到以上参数，需要在 iotdb-system.properties 中进行设置。

在当前已有的任意版本中，以上参数修改后都需要重启才能生效。

配置时可根据系统中的 data region 数、schema region 数进行计算：wal_buffer_size_in_byte*data region 数+schema_region_ratis_log_appender_buffer_size_max*schema region 数 < OFF_HEAP_MEMORY*0.8。

其中，保留 20% 堆外内存用于各模块中的临时使用。

需要注意的是，修改以上两个参数可能对性能有一定影响，如果发现调整后存在写入性能下降的情况，建议恢复这两个配置参数并采用调大堆外内存的修复方式。

修改样例：

假设当前配置下分配 OFF_HEAP_MEMORY 为 2G，data region 和 schema region 为 1000 个。此时需要的 direct memory 为 48000 MB，为了让系统能正常运行，可以按比例调整以上两个参数为原来的 2048*0.8/48*100=0.034 倍，此时 wal_buffer_size_in_byte 为 1140850，schema_region_ratis_log_appender_buffer_size_max 为 570425。

（3）调整建模

当以上方式都无法解决时，建议调整建模，降低 db 的数量。

对于无法启动的情况，需要大幅调小上一节中提到的两个配置参数以保证顺利启动，在启动后删除一些不使用的 db，然后将以上两个参数恢复正常大小并重启。