[Enhancement] Skip predicate column vacuuming when TTL is negative or usage is empty (StarRocks#71290)

Signed-off-by: seokyun.ha <seokyun.ha@toss.im>
Signed-off-by: 絵空事スピリット <richard.wang@celerdata.com>
Co-authored-by: 絵空事スピリット <richard.wang@celerdata.com>

Author: 2 people

docs/en/using_starrocks/Cost_based_optimizer.md

@@ -212,7 +212,7 @@ The following table describes the default settings. If you need to modify them,
 | statistic_auto_collect_max_predicate_column_size_on_sample_strategy | INT    | 16       | When the Auto Full Collection task hits the sampled collection policy, if the table has an unusually large number of Predicate Columns and exceeds this configuration item, the task will not switch to full collection of the Predicate Columns, but maintains  to be the sampled collection of all columns. This configuration item controls the maximum value of Predicate Column for this behavior. |
 | statistic_auto_collect_predicate_columns_threshold | INT     | 32       | If the number of columns in the table exceeds this configuration during automatic collection, only the column statistics for the Predicate Column will be collected. |
 | statistic_predicate_columns_persist_interval_sec   | LONG    | 60       | The interval at which FE synchronize and persists statistics of Predicate Column. |
-| statistic_predicate_columns_ttl_hours       | LONG    | 24       | The elimination time of the Predicate Column statistics cached in FE. |
+| statistic_predicate_columns_ttl_hours       | LONG    | 24       | The TTL in hours for Predicate Column entries in FE; vacuum removes older data. A negative value disables vacuum. |
 | enable_predicate_columns_collection         | BOOLEAN | TRUE     | Whether to enable predicate columns collection. If disabled, predicate columns will not be recorded during query optimization. |
 | enable_manual_collect_array_ndv             | BOOLEAN | FALSE        | Whether to enable manual collection for the NDV information of the ARRAY type. |
 | enable_auto_collect_array_ndv               | BOOLEAN | FALSE        | Whether to enable automatic collection for the NDV information of the ARRAY type. |
@@ -250,7 +250,7 @@ Parameter description:
   - `PREDICATE COLUMNS`: Collect statistics from only Predicate Columns. Supported since v3.5.0.
   - `MULTIPLE COLUMNS`: Collects joint statistics from the specified multiple columns. Currently, only manual synchronous collection of multiple columns is supported. The number of columns for manual statistics collection cannot exceed `statistics_max_multi_column_combined_num`, the default value is `10`. Supported since v3.5.0.
 
-- [WITH SYNC | ASYNC MODE]: whether to run the manual collection task in synchronous or asynchronous mode. Synchronous collection is used by default if you do not specify this parameter.
+- `WITH SYNC | ASYNC MODE`: whether to run the manual collection task in synchronous or asynchronous mode. Synchronous collection is used by default if you do not specify this parameter.
 
 - `PROPERTIES`: custom parameters. If `PROPERTIES` is not specified, the default settings in the `fe.conf` file are used. The properties that are actually used can be viewed via the `Properties` column in the output of SHOW ANALYZE STATUS.
 
@@ -318,7 +318,7 @@ Parameter description:
 
 - `col_name`: columns from which to collect statistics. Separate multiple columns with commas (`,`). If this parameter is not specified, the entire table is collected. This parameter is required for histograms.
 
-- [WITH SYNC | ASYNC MODE]: whether to run the manual collection task in synchronous or asynchronous mode. Synchronous collection is used by default if you not specify this parameter.
+- `WITH SYNC | ASYNC MODE`: whether to run the manual collection task in synchronous or asynchronous mode. Synchronous collection is used by default if you not specify this parameter.
 
 - `WITH N BUCKETS`: `N` is the number of buckets for histogram collection. If not specified, the default value in `fe.conf` is used.
 

docs/ja/using_starrocks/Cost_based_optimizer.md

@@ -214,7 +214,7 @@ v3.5.0 以降、StarRocks は自動収集中に、テーブルのデータが前
 | statistic_auto_collect_max_predicate_column_size_on_sample_strategy | INT    | 16       | 自動フル収集タスクがサンプル収集ポリシーに当たったとき、テーブルに異常に多くのPredicate Columnがあり、この設定項目を超えた場合、タスクはPredicate Columnのフル収集に切り替わらず、すべての列のサンプル収集に維持されます。この設定項目は、この動作のためのPredicate Columnの最大値を制御します。 |
 | statistic_auto_collect_predicate_columns_threshold | INT     | 32       | 自動収集中にテーブルの列数がこの設定を超えた場合、Predicate Columnの列統計のみが収集されます。 |
 | statistic_predicate_columns_persist_interval_sec   | LONG    | 60       | FE が Predicate Column の統計情報を同期し、永続化する間隔。 |
-| statistic_predicate_columns_ttl_hours       | LONG    | 24       | FE にキャッシュされた Predicate Column 統計の消去時間。 |
+| statistic_predicate_columns_ttl_hours       | LONG    | 24       | FE にキャッシュされた Predicate Column の TTL（時間）。vacuum が古いデータを削除。負の値で vacuum を無効化。 |
 | enable_predicate_columns_collection         | BOOLEAN | TRUE     | Predicate Column の収集を有効にするかどうか。無効にすると、クエリ最適化中に Predicate Column が記録されません。 |
 | enable_manual_collect_array_ndv             | BOOLEAN | FALSE        | ARRAY タイプの NDV 情報の手動収集を有効にするかどうか。 |
 | enable_auto_collect_array_ndv               | BOOLEAN | FALSE        | ARRAY タイプの NDV 情報の自動収集を有効にするかどうか。 |
@@ -252,7 +252,7 @@ ANALYZE [FULL|SAMPLE] TABLE tbl_name
   - `PREDICATE COLUMNS`：Predicate Column のみから統計情報を収集する。v3.5.0 からサポート。
   - `MULTIPLE COLUMNS`：指定した複数の列から共同の統計情報を収集する。現在のところ、複数列の手動同期収集のみがサポートされている。手動で統計情報を収集する列の数は `statistics_max_multi_column_combined_num` を超えることはできず、デフォルト値は `10` である。v3.5.0 からサポートされている。
 
-- [WITH SYNC | ASYNC MODE]: 手動収集タスクを同期モードまたは非同期モードで実行するかどうか。指定しない場合、デフォルトで同期収集が使用されます。
+- `WITH SYNC | ASYNC MODE`: 手動収集タスクを同期モードまたは非同期モードで実行するかどうか。指定しない場合、デフォルトで同期収集が使用されます。
 
 - `PROPERTIES`: カスタムパラメータ。`PROPERTIES` が指定されていない場合、`fe.conf` ファイルのデフォルト設定が使用されます。実際に使用されるプロパティは、SHOW ANALYZE STATUS の出力の `Properties` 列で確認できます。
 
@@ -320,7 +320,7 @@ ANALYZE TABLE tbl_name UPDATE HISTOGRAM ON col_name [, col_name]
 
 - `col_name`: 統計を収集する列。複数の列をカンマ（`,`）で区切ります。このパラメータが指定されていない場合、テーブル全体が収集されます。ヒストグラムにはこのパラメータが必要です。
 
-- [WITH SYNC | ASYNC MODE]: 手動収集タスクを同期モードまたは非同期モードで実行するかどうか。指定しない場合、デフォルトで同期収集が使用されます。
+- `WITH SYNC | ASYNC MODE`: 手動収集タスクを同期モードまたは非同期モードで実行するかどうか。指定しない場合、デフォルトで同期収集が使用されます。
 
 - `WITH N BUCKETS`: ヒストグラム収集のためのバケット数 `N`。指定しない場合、`fe.conf` のデフォルト値が使用されます。
 

docs/zh/using_starrocks/Cost_based_optimizer.md

@@ -209,7 +209,7 @@ StarRocks 提供灵活的信息采集方式，您可以根据业务场景选择
 | statistic_auto_collect_max_predicate_column_size_on_sample_strategy | INT    | 16       | 自动全量采集任务命中 Sample 策略时，如果表中 Predicate Column 特别多并且超过配置项，则不会转为对 Predicate Column 的全量采集，保持对所有列的抽样采集。当前配置项控制该行为中 Predicate Column 的最大值。 |
 | statistic_auto_collect_predicate_columns_threshold | INT     | 32       | 自动采集时若发现表中的列数超过配置项，则仅会采集 Predicate Column 的列统计信息。 |
 | statistic_predicate_columns_persist_interval_sec   | LONG    | 60       | FE 对 Predicate Column 的同步和持久化间隔周期。 |
-| statistic_predicate_columns_ttl_hours       | LONG    | 24       | Predicate Column 信息在 FE 中缓存淘汰时间。 |
+| statistic_predicate_columns_ttl_hours       | LONG    | 24       | Predicate Column 在 FE 中的 TTL（小时），vacuum 会清理更旧的数据；为负数时关闭 vacuum。 |
 | enable_predicate_columns_collection         | BOOLEAN | TRUE     | 是否启用 Predicate Column 采集。如果禁用，在查询优化期间将不会记录 Predicate Column。 |
 | enable_manual_collect_array_ndv             | BOOLEAN | FALSE        | 是否允许手动采集 ARRAY 类型列的 NDV 信息。 |
 | enable_auto_collect_array_ndv               | BOOLEAN | FALSE        | 是否允许自动采集 ARRAY 类型列的 NDV 信息。 |

fe/fe-core/src/main/java/com/starrocks/common/Config.java

@@ -2359,8 +2359,8 @@ public class Config extends ConfigBase {
     @ConfField(mutable = true, comment = "The interval to persist predicate columns state")
     public static long statistic_predicate_columns_persist_interval_sec = 60L;
 
-    @ConfField(mutable = true, comment = "The TTL of predicate columns, it would not be considered as predicate " +
-            "columns after this period")
+    @ConfField(mutable = true, comment = "The TTL of predicate columns in hours; entries older than this are " +
+            "removed by vacuum. A negative value (e.g. -1) disables predicate column vacuum.")
     public static long statistic_predicate_columns_ttl_hours = 24;
 
     @ConfField(mutable = true, comment = "Enable predicate columns collection. If disabled, predicate columns " +

fe/fe-core/src/main/java/com/starrocks/statistic/columns/PredicateColumnsMgr.java

@@ -174,11 +174,14 @@ public void persist() {
 
     public void vacuum() {
         long ttlHour = Config.statistic_predicate_columns_ttl_hours;
+        if (ttlHour < 0) {
+            return;
+        }
         LocalDateTime ttlTime = TimeUtils.getSystemNow().minusHours(ttlHour);
         Predicate<ColumnUsage> outdated = x -> x.getLastUsed().isBefore(ttlTime);
 
         long before = id2columnUsage.size();
-        if (id2columnUsage.values().removeIf(outdated)) {
+        if (before > 0 && id2columnUsage.values().removeIf(outdated)) {
             long after = id2columnUsage.size();
             LOG.info("removed {} objects from predicate columns because of ttl {}", before - after,
                     Config.statistic_predicate_columns_ttl_hours);

fe/fe-core/src/test/java/com/starrocks/statistic/columns/ColumnUsageTest.java

@@ -287,4 +287,19 @@ public void testColumnUsagePersist() throws MetaNotFoundException {
             Assertions.assertEquals(usage, restored);
         }
     }
-}
+
+    @Test
+    public void testPredicateColumnsVacuumSkipsWhenTtlDisabled() throws Exception {
+        starRocksAssert.query("select * from t0 where v1 > 1").explainQuery();
+        PredicateColumnsMgr mgr = PredicateColumnsMgr.getInstance();
+        TableName t0 = new TableName(connectContext.getDatabase(), "t0");
+        Assertions.assertEquals(1, mgr.queryPredicateColumns(t0).size());
+
+        long beforeValue = Config.statistic_predicate_columns_ttl_hours;
+        Config.statistic_predicate_columns_ttl_hours = -1;
+        mgr.vacuum();
+        Assertions.assertEquals(1, mgr.queryPredicateColumns(t0).size());
+
+        Config.statistic_predicate_columns_ttl_hours = beforeValue;
+    }
+}