Re: doc: fix pg_stat_autovacuum_scores threshold wording - Mailing list pgsql-hackers

> On Jun 25, 2026, at 11:45, Kyotaro Horiguchi <horikyota.ntt@gmail.com> wrote:
>
> Hello,
>
> At Thu, 25 Jun 2026 10:44:23 +0800, Chao Li <li.evan.chao@gmail.com> wrote in
>> While testing “[d7965d65f] Add rudimentary table prioritization to autovacuum”, I noticed a small doc issue.
>>
>> In monitoring.sgml, it states:
>> ```
>>     <row>
>>      <entry role="catalog_table_entry"><para role="column_definition">
>>       <structfield>vacuum_score</structfield> <type>double precision</type>
>>      </para>
>>      <para>
>>       Vacuum component score.  Scores greater than or equal to
>>       <xref linkend="guc-autovacuum-vacuum-score-weight"/> indicate that
>>       autovacuum would vacuum the table (unless autovacuum is disabled).
>>      </para></entry>
>>     </row>
>> ```
>
> If I understand this correctly, aren't the *_score_weight settings
> used to prioritize candidate tables, rather than to determine whether
> a table needs vacuuming or analyzing in the first place?
>
> Regards,
>
> --
> Kyotaro Horiguchi
> NTT Open Source Software Center

Yes, I agree that the *_score_weight settings are used for prioritizing candidate tables, not for deciding eligibility
directly.

I actually took time to try to understand where the current wording may have come from. For example, for vacuum_score,
thecode does: 
```
    /* Determine if this table needs vacuum, and update the score. */
    scores->vac = (double) vactuples / Max(vacthresh, 1);
    scores->vac *= autovacuum_vacuum_score_weight;
    scores->max = Max(scores->max, scores->vac);
    if (av_enabled && vactuples > vacthresh)
        *dovacuum = true;
```

So, dovacuum is determined by "vactuples > vacthresh", in other words, when  vactuples / vacthresh > 1, dovacuum is
true.Let’s ignore av_enabled here. 

Then, the score is computed roughly as
```
scores->vac =  (vactuples / vacthresh) * autovacuum_vacuum_score_weight
```

So when  (vactuples / vacthresh) > 1, the score > autovacuum_vacuum_score_weight.

I guess that may be how the current wording came from. But it seems a bit indirect to describe it that way, because the
weightitself does not determine if autovacuum would vacuum or analyze the table. 

Rewriting the doc more broadly would be a larger change. This small patch is only meant to avoid the confusion shown by
thetest earlier, where the score is equal to the weight but do_vacuum is false. 

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/