本文匯總了在使用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？
ApsaraDB for 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操作相關。