[Enhancement] Skip predicate column vacuuming when TTL is negative or usage is empty

[seokyun-ha-toss]

Why I'm doing:

I'm using StarRocks with enable_predicate_columns_collection=false and have truncated the _statistics_.predicate_columns table. However, the vacuum process with TTL is still running and generating useless audit logs. I want to suppress predicate column vacuuming by disabling predicate column TTL.

What I'm doing:

When statistic_predicate_columns_ttl_hours is set to a negative value (e.g. -1), skip vacuuming entirely.

Additionally, skip vacuuming id2columnUsage when it is already empty before removal:

    public void vacuum() {
        long ttlHour = Config.statistic_predicate_columns_ttl_hours;
        if (ttlHour < 0) { // HERE
            return;
        }
        LocalDateTime ttlTime = TimeUtils.getSystemNow().minusHours(ttlHour);
        Predicate<ColumnUsage> outdated = x -> x.getLastUsed().isBefore(ttlTime);

        long before = id2columnUsage.size();
        if (before > 0 && id2columnUsage.values().removeIf(outdated)) { // HERE
            long after = id2columnUsage.size();
            LOG.info("removed {} objects from predicate columns because of ttl {}", before - after,
                    Config.statistic_predicate_columns_ttl_hours);
        }

        // If the process crashed before vacuum the storage, the storage may be different from in-memory state,
        // but it doesn't matter. Because we will remove them finally.
        getStorage().vacuum(ttlTime);
    }

Already, reflect the changes on documents also.

Fixes #71291

What type of PR is this:

• BugFix
• Feature
• Enhancement
• Refactor
• UT
• Doc
• Tool

Does this PR entail a change in behavior?

• Yes, this PR will result in a change in behavior.
• No, this PR will not result in a change in behavior.

If yes, please specify the type of change:

• Interface/UI changes: syntax, type conversion, expression evaluation, display information
• Parameter changes: default values, similar parameters but with different default values
• Policy changes: use new policy to replace old one, functionality automatically enabled
• Feature removed
• Miscellaneous: upgrade & downgrade compatibility, etc.

Checklist:

• I have added test cases for my bug fix or my new feature
• This pr needs user documentation (for new or modified features or behaviors)
  • I have added documentation for my new feature or new function
  • This pr needs auto generate documentation
• This is a backport pr

Bugfix cherry-pick branch check:

• I have checked the version labels which the pr will be auto-backported to the target branch
  • 4.1
  • 4.0
  • 3.5
  • 3.4

[CelerData-Reviewer]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Nice work!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[seokyun-ha-toss]

Thanks, @stephen-shelby for reviewing. However, CI reports that the added line is not covered by any tests.

Should I add unit test for that line? Please leave your opinion. Thanks!

[Copilot]

Pull request overview

This PR adds a configuration-driven way to suppress predicate column TTL vacuuming (to avoid unnecessary cleanup work/logs when predicate column collection is disabled or the system table is empty), and updates documentation accordingly.

Changes:

• Skip predicate column vacuum entirely when statistic_predicate_columns_ttl_hours is negative.
• Avoid running in-memory removeIf when the usage map is already empty.
• Document the new “negative TTL disables vacuum” behavior in Config comments and EN/JA/ZH optimizer docs.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
fe/fe-core/src/main/java/com/starrocks/statistic/columns/PredicateColumnsMgr.java	Adds early return for negative TTL and avoids removal pass when the map is empty.
fe/fe-core/src/main/java/com/starrocks/common/Config.java	Updates config comment to document that negative TTL disables vacuum.
docs/zh/using_starrocks/Cost_based_optimizer.md	Documents negative TTL disabling vacuum (ZH).
docs/ja/using_starrocks/Cost_based_optimizer.md	Documents negative TTL disabling vacuum (JA).
docs/en/using_starrocks/Cost_based_optimizer.md	Documents negative TTL disabling vacuum (EN).

[seokyun-ha-toss]

Hello, @stephen-shelby @kevincai @stdpain , I added a unittest by 8152cc1. Thanks!

[seokyun-ha-toss]

I've done git rebase and push forcly to pass DCO checking by:

git rebase HEAD~3 --signoff
git push --force-with-lease origin disable-predicate-column-vacuum

Thanks!

[github-actions]

🌎 Translation Required?

✅ All translation files are up to date.
Great job! No translation actions are required for this PR.

🕒 Last updated: Wed, 15 Apr 2026 09:21:17 GMT

[github-actions]

[Java-Extensions Incremental Coverage Report]

✅ pass : 0 / 0 (0%)

[github-actions]

[FE Incremental Coverage Report]

✅ pass : 3 / 3 (100.00%)

file detail

	path	covered_line	new_line	coverage	not_covered_line_detail
🔵	com/starrocks/statistic/columns/PredicateColumnsMgr.java	3	3	100.00%	[]

[github-actions]

[BE Incremental Coverage Report]

✅ pass : 0 / 0 (0%)

[github-actions]

@Mergifyio backport branch-4.1

[mergify]

backport branch-4.1

✅ Backports have been created

Details

• #71777 [Enhancement] Skip predicate column vacuuming when TTL is negative or usage is empty (backport #71290) has been created for branch branch-4.1