Thread

Commits

doc: Fix pg_stat_autovacuum_scores descriptions.
- ba7a65c5c5aa 19 (unreleased) landed
- 644026560624 master landed

doc: fix pg_stat_autovacuum_scores threshold wording

Chao Li <li.evan.chao@gmail.com> — 2026-06-25T02:44:23Z

Hi,

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>
```

This indicates that when vacuum_score >= autovacuum_vacuum_score_weight, autovacuum would vacuum the table.

However, the related code uses >, not >=:
```
        /* 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;
```

Also, see the following test:
```
evantest=# create table t (id int) with (
evantest(# autovacuum_vacuum_threshold = 1,
evantest(# autovacuum_vacuum_scale_factor = 0,
evantest(# autovacuum_analyze_threshold = 1000000);
CREATE TABLE
evantest=# insert into t values(1);
INSERT 0 1
evantest=# delete from t;
DELETE 1
evantest=# select pg_stat_force_next_flush();
 pg_stat_force_next_flush
--------------------------

(1 row)
evantest=# select vacuum_score, do_vacuum from pg_stat_autovacuum_scores s where s.relid='t'::regclass;
 vacuum_score | do_vacuum
--------------+-----------
            1 | f
(1 row)
```
Here vacuum_score is 1, and autovacuum_vacuum_score_weight is the default 1.0 defined in postgres.conf. From the user's view they are equal, but do_vacuum is false.

The same boundary applies to the other component scores as well: the code uses strict comparisons to decide whether autovacuum would vacuum or analyze the table.

So I think we should fix the docs by changing "greater than or equal to" to "greater than". See the attached small patch.

BTW, I also noticed that the release note about this feature has a typo. I will report that to Bruce in the release note thread.

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

Re: doc: fix pg_stat_autovacuum_scores threshold wording

Kyotaro Horiguchi <horikyota.ntt@gmail.com> — 2026-06-25T03:45:19Z

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

Re: doc: fix pg_stat_autovacuum_scores threshold wording

Chao Li <li.evan.chao@gmail.com> — 2026-06-25T06:03:00Z


> 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, the code 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 weight itself 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 the test 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/

Re: doc: fix pg_stat_autovacuum_scores threshold wording

Sami Imseih <samimseih@gmail.com> — 2026-06-25T15:48:07Z

> I guess that may be how the current wording came from. But it seems a bit indirect to describe it that way, because the weight itself 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 the test earlier, where the score is equal to the weight but do_vacuum is false.

Hi,

Thanks for reporting. I took a look and agree with your doc changes.
do_vacuum/do_analyze will not be true for cases where the
individual component scores are less than or equal to the weight.

The patch LGTM

--
Sami Imseih
Amazon Web Services (AWS)

Re: doc: fix pg_stat_autovacuum_scores threshold wording

Nathan Bossart <nathandbossart@gmail.com> — 2026-06-26T18:26:20Z

On Thu, Jun 25, 2026 at 10:48:07AM -0500, Sami Imseih wrote:
>> I guess that may be how the current wording came from. But it seems a
>> bit indirect to describe it that way, because the weight itself does not
>> determine if autovacuum would vacuum or analyze the table.

My goal was to explain how to interpret the value as simply as possible.
It's true that the code doesn't use this value for deciding eligibility,
but the documentation doesn't say that it does.  Rather, it gives users a
frame of reference for what a given value means.

> Thanks for reporting. I took a look and agree with your doc changes.
> do_vacuum/do_analyze will not be true for cases where the
> individual component scores are less than or equal to the weight.

+1, I'll take care of it.

-- 
nathan

Re: doc: fix pg_stat_autovacuum_scores threshold wording

Nathan Bossart <nathandbossart@gmail.com> — 2026-07-01T15:49:49Z
```
Committed.

-- 
nathan
```

Re: doc: fix pg_stat_autovacuum_scores threshold wording

Chao Li <li.evan.chao@gmail.com> — 2026-07-01T23:51:03Z


> On Jul 1, 2026, at 23:49, Nathan Bossart <nathandbossart@gmail.com> wrote:
> 
> Committed.
> 
> -- 
> nathan

Thanks for pushing.

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