本文汇总了在使用Lindorm宽表引擎时可能会遇到的常见问题及其解决方案。
问题汇总
连接问题
小版本升级
存储相关（Compaction等）
数据管理
数据查询
监控
HBase相关
批量操作
连接
使用Lindorm-cli连接宽表引擎失败是什么原因？
请根据以下内容逐一排查：
是否为公网连接，如果是，需获取公网IP并将其添加至Lindorm白名单。
是否使用了VPN等代理但未添加至白名单。
服务端口是否可用，您可以使用telnet命令检测Lindorm端口连通性。
如果使用ECS连接Lindorm宽表引擎，请参考Lindorm连接问题与解决方法排查问题。
宽表引擎常见的端口号有哪些？
端口号 | 说明 |
30060 | SQL端口（Avatica协议） |
33060 | SQL端口（MySQL协议） |
30020 | 宽表端口（HBase兼容协议、Java访问方式） |
9042 | CQL端口（Cassandra协议兼容） |
小版本升级
升级宽表小版本有什么影响？需要多久？
升级宽表小版本可能导致单个节点短暂断开连接，每个Server滚动重启，升级期间Region会下线再上线。升级完成后，系统会重新平衡负载。
影响评估：对低负载实例影响较小；对高负载或时延敏感实例可能有一定影响，建议在业务低峰期进行。
耗时估算：每个节点约需5~30分钟，具体时间取决于Region数量及负载。
存储相关（Compaction）
Compaction操作相关
Compaction操作的作用是什么？
清理过期数据（TTL）、清理删除操作的遗留标记（deleteMarker）、归档冷热数据、压缩数据减少空间占用。
Compaction操作的自动触发周期是多久？
系统默认的自动触发周期为20天。在TTL场景下，默认周期为 min(TTL值, 20天)。您可以通过以下两种方式修改自动触发周期：min(ttl,20天)。您可以通过以下方式修改自动触发周期：
通过SQL语句ALTER TABLE修改，例如将自动触发周期修改为2天：
ALTER TABLE <tableName> SET 'COMPACTION_MAJOR_PERIOD'='172800000';。说明COMPACTION_MAJOR_PERIOD单位为毫秒（ms）。通过集群管理系统（Lindorm Insight）的表变更管理，修改Compaction 周期。
Compaction操作是否可以手动触发？
可以，您可以通过SQL语句执行Major Compaction。
实例负载过高、大表、冷热分离表手动触发可能会有风险，请谨慎使用。触发以后需要关注Region的最大文件数，避免Compaction积压导致Region的最大文件数上升进而导致写入反压。Region的最大文件数告警，可参考监控报警最佳实践。
Compaction操作对业务有什么影响？
业务影响：
系统通常会自动分配多个线程执行Compaction操作，不同规格默认使用的线程数量不同，规格越高处理执行效率越高，相反，则可能出现大量任务排队的情况。同时，Compaction操作处理数据时会消耗CPU，CPU资源充足时Compaction操作对业务没有太大的影响，反而有助于提升读性能、释放存储空间、压缩数据等。
负载监控：
您可以通过实例监控查看宽表引擎指标-集群负载中的Compaction队列长度(个)，如果该数值持续增长或始终持平，则说明Compaction队列可能存在大量排队任务。更多介绍可以参考集群负载中的Compaction队列长度(个)说明。
优化建议：
如果CPU利用率小于40%，宽表2.6.5以上版本支持自动根据load调整参数，直接升级小版本即可。如果CPU利用率大于40%，建议您增加宽表引擎节点数量。
如何查看Compaction操作任务的状态？
通过实例监控查看宽表引擎指标-集群负载中的Compaction队列长度(个)。如果该数值在持续减少，或周期性地增加之后开始减少，并不是始终增长或一直持平状态（大于一天持续增加或持平），则为正常状态，反之为不正常状态。
已设置了TTL，但是存储还在持续上涨是什么原因？
您可以通过实例监控查看宽表引擎指标-集群负载中的Compaction队列长度(个)，确认是否存在任务积压情况，如果积压较多就会出现数据清理滞后的现象。如果CPU利用率小于40%，宽表2.6.5以上版本支持自动根据load调整参数，直接升级小版本即可。如果CPU利用率大于40%，建议您增加宽表引擎节点数量。
如果队列无任务则说明Compaction操作正常执行中。如果此时读写（I/O负载）较低，可以手动执行Compaction操作或调整major compaction周期，例如将自动触发周期修改为2天：ALTER TABLE <tableName> SET 'COMPACTION_MAJOR_PERIOD'='172800000';。
COMPACTION_MAJOR_PERIOD单位为毫秒（ms）。
系统周期默认为20天。在TTL场景下，默认周期为min(ttl,20天)。
如何通过设置压缩算法和编码方式来减少存储空间？
您可以将表的压缩算法COMPRESSION设置为ZSTD，编码方式DATA_BLOCK_ENCODING设置为INDEX，并执行major compact以减少存储空间。
如果您是通过SQL方式创建的表，则默认已设置，无需重复设置。
具体如下：
SQL：支持通过Lindorm-cli连接宽表引擎执行SQL语句或通过集群管理系统（Lindorm Insight）执行SQL语句。
-- 修改压缩算法为ZSTD，编码方式为INDEX ALTER TABLE <tablename> SET 'COMPRESSION' = 'ZSTD','DATA_BLOCK_ENCODING' = 'INDEX'; ALTER TABLE <tablename> COMPACT; -- Region较多时请等待一段时间您可以通过实例监控查看宽表引擎指标-集群负载中的Compaction队列长度(个)查看任务进度。
HBase API：建表并插入数据
alter 'ns:tablename', {NAME=>'family', DATA_BLOCK_ENCODING => 'INDEX',COMPRESSION => 'ZSTD'} //Region较多时请等待一段时间 major_compact 'ns:tablename' //Region较多时请等待一段时间您可以通过实例监控查看宽表引擎指标-集群负载中的Compaction队列长度(个)查看任务进度。
磁盘（存储空间）达到容量上限该如何处理？
您可以通过以下方式处理：
通过DROP TABLE直接删除无用的表，立即释放存储空间。
通过TRUNCATE TABLE清空表中数据，立即释放存储空间。
请勿使用DELETE直接删除数据，原因如下：
Lindorm为充分发挥写入性能，删除操作并非是先读取再删除，而是直接写入删除标记以确保这些数据不再被查询到，等到下次触发Compaction操作才会被彻底清理。触发周期请参见Compaction操作的自动触发周期。
为什么磁盘（存储空间）达到容量上限后无法删除数据？
请勿使用DELETE直接删除数据，原因如下：
Lindorm为充分发挥写入性能，删除操作并非是先读取再删除，而是直接写入删除标记（Delete Marker）以确保需删除的数据不再被查询到，等到下次触发Compaction操作这些数据才会被彻底清理。触发周期请参见Compaction操作的自动触发周期。
同时，磁盘达到容量上限后系统将禁止所有数据的写入，包括删除标记。删除标记无法写入将导致需删除的数据无法通过Compaction操作清理，因此该操作无法立即释放空间。
宽表引擎支持变更节点数量、扩缩容磁盘吗？
变更节点数量是引擎级别的操作，扩缩容磁盘为实例级别的操作。
本地盘实例和云盘实例均支持变更宽表引擎节点数量。
本地盘实例不支持扩缩容磁盘，云盘实例支持扩缩容热存储容量和扩缩容冷存储容量。缩容磁盘需要拷贝数据，需要的时间比较久，请耐心等待。
数据管理
常用表属性的单位有哪些需要注意？
major compaction周期：COMPACTION_MAJOR_PERIOD参数用于设置major compaction周期，单位为毫秒（ms），支持在建表时指定Major Compaction周期。时间戳：单位为毫秒（ms），HINT中可能会使用秒（s）作为单位，例如
/*+ _l_ts_(%s) */。数据有效期TTL：单位为秒（s），可以在建表时指定数据有效期。
建表时NUMREGIONS参数应该如何设置？
不指定NUMREGIONS时，默认为1个分区，建议初始将NUMREGIONS设置为Server节点数 * 4个。单个分区中的数据达到8 GB时，分区将会自动分裂，或底层数据读写QPS总和达到1000以上，系统将自动识别热点并判断是否需要分裂分区。
建议您升级小版本至宽表引擎2.4.x以上版本，热点自愈功能将更加完善。
通过ALTER TABLE修改表属性有什么影响？
通过ALTER TABLE修改表属性会使表的所有Region均关闭再开启，基本无影响。如果您的业务对读性能较敏感，例如需达到毫秒级，请在业务低峰期进行操作。
写入的列超过最大写入限制是什么原因？
写入的列超过最大写入限制时会报错：
com.alibaba.lindorm.client.exception.IllegalDataException: Column [xxx] is too big, max length is 2097152 bytes but has 7621168 bytes.
针对VARBINARY类型的列长度无限制，但对于大小是否存在限制请参考配额与限制。
单个Cell默认不能超过2 MB，您同时还需要考虑实例的负载和存储空间大小，负载不大的情况下可以通过SQL语句临时修改非主键列最大写入限制（不推荐）：ALTER TABLE <tablename> SET 'MAX_NONPK_LEN'='4194304';（单位为字节）。
如果需要修改非主键列最大写入限制，建议您参考以下说明升配：
如果节点内存为32 GB，建议MAX_NONPK_LEN最大不超过5 MB。
如果节点内存为64 GB，建议MAX_NONPK_LEN最大不超过10 MB。
删除数据的方式和注意事项有哪些？
目前Lindorm仅支持通过TRUNCATE TABLE清空表中数据或指定完整主键删除部分数据。删除完成后，如果对读RT要求较敏感请手动执行major compact，如果业务对读RT不敏感，您可以等待Compaction周期定期清理。
指定完整主键的删除操作不支持范围删除，需要先查询出完整的主键再通过等值条件进行删除。
如何验证数据是否已进入冷存储？
您可以先指定主键查询全部待验证的数据，再指定相同的主键通过HINT仅查询热数据。对比查询结果，如果查询结果相同则说明数据未进入冷存储。如果查询全部数据和通过HINT仅查询热数据结果不同，且查询全部数据时查不到冷数据，则表示数据已进入冷存储。
您可以提前通过集群管理系统（Lindorm Insight）的概览查看表的冷存储与热存储的大小，与数据归档后冷存储与热存储的大小进行对比。
为什么数据没有进入冷存储？
您可以参考为什么执行compaction操作后，数据还未进入冷存储。
主要原因可能如下：
数据查询
为什么二级索引查询不到为null的数据？
在使用主键重排和多列索引的情况下，第一个非主键列值为NULL时不会构建二级索引，因此仅非主键列中存在具体的值才能在索引表中查询到。
查询结果不符合预期是什么原因？
监控
监控上冷存token指标的含义是什么？
冷存储适用于读取较少的数据归档场景，因此建议尽量少读取冷数据。冷存Token指标是针对冷存储限流的监控，冷存Token数值持续减少表示有部分请求被限流了。
监控配置建议有哪些？
您可以参考监控报警最佳实践进行配置。
表级别监控相关问题
为什么切换表名后，监控数据并没有跟着更新？
切换表名后，仅会同步更新，其他指标（例如系统指标）不会发生变化。
为什么表监控里面找不到对应的表名？
如果在表监控中找不到对应表名，首先尝试延长查询时间范围（例如从1小时扩展到24小时）；如果仍无法找到，表明该表在所选时间段内没有任何读写操作，因此系统未上报监控数据。
HBase相关
SQL表和HBase表的区别是什么？ 如何区分？
SQL表与HBase表的核心区别在于表结构和数据操作方式。SQL表有固定schema（列名和类型预先定义），仅支持SQL操作；HBase表无固定schema（支持动态列），主要通过HBase API操作（也可通过SQL查询）。区分方法如下：
创建方式
HBase表：通过
hbase shell或其他HBase同步工具创建（也称"宽表"）。SQL表：通过SQL命令创建（SQL无法创建Hbase表）。
结构特性
HBase表：无schema，支持动态列。
SQL表：有固定schema，列类型严格定义。
操作限制
HBase表：仅通过HBase API写入（可通过SQL查询，需参考Htype映射文档）。
SQL表：仅通过SQL API读写。
检查方法
执行SQL命令查看IS_HBASE_LIKE属性：SHOW TABLE VARIABLES FROM <数据库名> LIKE 'IS_HBASE_LIKE';true：HBase表false：SQL表
HBase增强版是否支持SQL？
云数据库HBase增强版是由Lindorm宽表引擎（兼容HBase或Cassandra）提供的，使用方式与Lindorm宽表引擎一致，支持SQL使用方式。您可以通过Lindorm-cli连接并使用宽表引擎：
./lindorm-cli -url jdbc:lindorm:table:url=http://ld-bp17j28j2y7pm****-proxy-lindorm-pub.lindorm.rds.aliyuncs.com:30060 -username xxx -password xxx
# 连接以后执行
lindorm:default> show databases;连接前请确保网络畅通，您可以使用telnet命令检测Lindorm端口连通性。同时，您需要将客户端IP加入白名单。
开源HBase客户端用户需要注意什么？
使用开源HBase客户端不支持鉴权，不支持多可用区。连接宽表引擎前，请安装HBase SDK。
批量操作
如何开启批量删除？
可通过以下命令开启和查询批量删除设置。
正常删除通常不会引发性能问题，无需特别处理和关注，大批量删除操作会生成大量deleteMarker，这些标记会显著增加数据扫描负担，从而可能导致查询超时，详见批量删除某个表后导致此表的查询超时。
-- 开关SQL命令
ALTER SYSTEM SET `lindorm.allow.range.delete`=TRUE;
-- 查看开关
SHOW SYSTEM variables LIKE 'lindorm.allow.range.delete';为什么不支持批量更新或报错Update's WHERE clause can only contain PK columns？
默认只支持单行更新，可通过以下命令开启和查询批量更新设置。
如您遇到批量更新表后查询超时的问题，可参考解决方法。
-- 开关SQL命令
ALTER SYSTEM SET `lindorm.allow.batch.update`=TRUE;
-- 查看开关
SHOW SYSTEM variables LIKE 'lindorm.allow.batch.update';批量删除某个表后导致此表的查询超时
删除机制原理
Lindorm 为保障高写入性能，删除操作不会立即物理清除数据，而是写入一个 Delete Marker（删除标记）。该机制对用户透明——被删除的数据在读取时不可见，但底层仍需在读取过程中跳过这些标记和对应的已删除数据。正常删除通常不会引发性能问题，无需特别处理和关注。当删除的数据量较大时，会积累大量 Delete Marker。例如：读取一个范围内的数据，若其中有效数据仅 10 万条，但存在 100 万条已删除数据 + 100万个 Delete Marker，则系统需扫描约 210 万条记录才能过滤出有效结果，导致读取耗时显著增加，甚至超时。查询超时原因
当查询扫描范围包含大量待删除数据时，会产生大量的deleteMarker导致读取时需要跳过大量数据进而导致超时。解决方案
通过Compaction彻底清除过期数据和deleteMarker，Compaction有自动触发周期，也可以手动触发，具体操作可参考Compaction操作相关。
批量更新某个带有二级索引的表后，导致部分查询超时
查询超时原因
Lindorm 的二级索引本质上是一个独立的索引表，其主键格式为 [索引列值] + [主表 RowKey]。当主表记录被更新或删除时，Lindorm 会自动在索引表中：
删除旧索引项（写入 Delete Marker）、插入新索引项（如适用）。
因此，大批量更新索引字段会导致索引表中产生大量 Delete Marker。在执行基于索引的查询时，系统需扫描目标索引值对应的所有 RowKey，并跳过已删除的记录。若有效数据占比极低，扫描和过滤开销将急剧上升，造成查询延迟飙升、吞吐下降。
删除机制原理
Lindorm 为保障高写入性能，删除操作不会立即物理清除数据，而是写入一个 Delete Marker（删除标记）。该机制对用户透明——被删除的数据在读取时不可见，但底层仍需在读取过程中跳过这些标记和对应的已删除数据。正常删除通常不会引发性能问题，无需特别处理和关注。当删除的数据量较大时，会积累大量 Delete Marker。例如：读取一个范围内的数据，若其中有效数据仅 10 万条，但存在 100 万条已删除数据 + 100万个 Delete Marker，则系统需扫描约 210 万条记录才能过滤出有效结果，导致读取耗时显著增加，甚至超时。解决方案
通过Compaction彻底清除过期数据和deleteMarker，Compaction有自动触发周期，也可以手动触发，具体操作可参考Compaction操作相关。