Thread: Re: Better visualization of default values
On Thu, Feb 6, 2025 at 8:08 AM Marcos Pegoraro <marcos@f10.com.br> wrote:
>
> Reading DOCs sometimes is boring because you want to know only the default value of something. I know what that GUC
is,I know how to change it, I only don't remember what its default value is. Then you have to read that entire
paragraphjust to read that the default value is ...
>
> So, what you think about this.
> It's not complete but you can see if it's useful or not
>
+0.5
IIUC the problem here (if there is one), is just that the default is
sometimes buried within the GUC description.
But just putting the default value adjacent to the GUC name might not
be the best solution because often defaults have special meanings.
e.g. there is no point knowing the default value is -1 unless you know
what that value means. So with your patch, not only is the default
value duplicated, but you are back where you started having to read
all the description text again to learn what it means.
IMO it would be better simply to ensure that defaults are always
described in a consistent place within all GUC descriptions, Then they
are easy to find because you always know where to look for them. In
other words, add nothing new -- just slightly rearrange and/or add
blank lines to the existing text.
Like this:
<guc-name> (type)
<one line terse description>
<default value, and optional special meaning>
<more details, if any>
For example:
CURRENTLY
vacuum_cost_delay (floating point)
The amount of time that the process will sleep when the cost limit has
been exceeded. If this value is specified without units, it is taken
as milliseconds. The default value is 0, which disables the cost-based
vacuum delay feature. Positive values enable cost-based vacuuming.
When using cost-based vacuuming, appropriate values for
vacuum_cost_delay are usually quite small, perhaps less than 1
millisecond. While vacuum_cost_delay can be set to
fractional-millisecond values, such delays may not be measured
accurately on older platforms. On such platforms, increasing VACUUM's
throttled resource consumption above what you get at 1ms will require
changing the other vacuum cost parameters. You should, nonetheless,
keep vacuum_cost_delay as small as your platform will consistently
measure; large delays are not helpful.
SUGGESTION
vacuum_cost_delay (floating point)
The amount of time that the process will sleep when the cost limit has
been exceeded. If this value is specified without units, it is taken
as milliseconds. Positive values enable cost-based vacuuming.
The default value is 0, which disables the cost-based vacuum delay feature.
When using cost-based vacuuming, appropriate values for
vacuum_cost_delay are usually quite small, ... blah blah
~~~
Thoughts?
======
Kind Regards,
Peter Smith.
Fujitsu Australia
I agree that duplicating default values is not fine, I can remove them from the explanation and put it only near definition.
But about adding a new line with its default value, sometimes is fine, sometimes not.
[1] is a good example which would be fine but the next ones cpu_tuple_cost, cpu_index_tuple_cost, cpu_operator_cost and so on wouldn't be good.
And obviously, if you don't know the purpose of that GUC, you'll have to read the entire paragraph to understand it.
Objective here is to those ones who know what it is, but don't remember its default.
regards
Marcos
Em qua., 5 de fev. de 2025 às 20:59, Peter Smith <smithpb2250@gmail.com> escreveu:
On Thu, Feb 6, 2025 at 8:08 AM Marcos Pegoraro <marcos@f10.com.br> wrote:
>
> Reading DOCs sometimes is boring because you want to know only the default value of something. I know what that GUC is, I know how to change it, I only don't remember what its default value is. Then you have to read that entire paragraph just to read that the default value is ...
>
> So, what you think about this.
> It's not complete but you can see if it's useful or not
>
+0.5
IIUC the problem here (if there is one), is just that the default is
sometimes buried within the GUC description.
But just putting the default value adjacent to the GUC name might not
be the best solution because often defaults have special meanings.
e.g. there is no point knowing the default value is -1 unless you know
what that value means. So with your patch, not only is the default
value duplicated, but you are back where you started having to read
all the description text again to learn what it means.
IMO it would be better simply to ensure that defaults are always
described in a consistent place within all GUC descriptions, Then they
are easy to find because you always know where to look for them. In
other words, add nothing new -- just slightly rearrange and/or add
blank lines to the existing text.
Like this:
<guc-name> (type)
<one line terse description>
<default value, and optional special meaning>
<more details, if any>
For example:
CURRENTLY
vacuum_cost_delay (floating point)
The amount of time that the process will sleep when the cost limit has
been exceeded. If this value is specified without units, it is taken
as milliseconds. The default value is 0, which disables the cost-based
vacuum delay feature. Positive values enable cost-based vacuuming.
When using cost-based vacuuming, appropriate values for
vacuum_cost_delay are usually quite small, perhaps less than 1
millisecond. While vacuum_cost_delay can be set to
fractional-millisecond values, such delays may not be measured
accurately on older platforms. On such platforms, increasing VACUUM's
throttled resource consumption above what you get at 1ms will require
changing the other vacuum cost parameters. You should, nonetheless,
keep vacuum_cost_delay as small as your platform will consistently
measure; large delays are not helpful.
SUGGESTION
vacuum_cost_delay (floating point)
The amount of time that the process will sleep when the cost limit has
been exceeded. If this value is specified without units, it is taken
as milliseconds. Positive values enable cost-based vacuuming.
The default value is 0, which disables the cost-based vacuum delay feature.
When using cost-based vacuuming, appropriate values for
vacuum_cost_delay are usually quite small, ... blah blah
~~~
Thoughts?
======
Kind Regards,
Peter Smith.
Fujitsu Australia
On Thu, Feb 6, 2025 at 6:46 AM Marcos Pegoraro <marcos@f10.com.br> wrote:
And obviously, if you don't know the purpose of that GUC, you'll have to read the entire paragraph to understand it.Objective here is to those ones who know what it is, but don't remember its default.
That seems a somewhat arbitrary goal for us to optimize for. I just read through https://www.postgresql.org/docs/current/runtime-config-query.html and while perhaps some of the defaults could be slightly more prominent, none of them took more than a second of brain-cpu-power to find. The only one that threw me off was join_collapse_limit, which really should just state the eight. So for me a -1 for major changes, but a weak +1 to improving some individual items.
Cheers,
Greg
On Thu, Feb 6, 2025 at 4:46 AM Marcos Pegoraro <marcos@f10.com.br> wrote:
Objective here is to those ones who know what it is, but don't remember its default.
My approach would be to add a summary table (or tables) in the first subsection of each major X.Y (section X.Y.1) that lists the name, brief description, type, default value, and notes. Then just leave the full descriptions self-contained as they are. Pure redundancy but basically put the output of a psql meta-command directly into the docs.
Between these other two choices I'd lean toward placing the default only next to the data type.
David J.
Em qui., 6 de fev. de 2025 às 12:32, Greg Sabino Mullane <htamfids@gmail.com> escreveu:
That seems a somewhat arbitrary goal for us to optimize for.
well, my goal was to standardize these values. As examples of non standardization you have ...
Tipically ? Is it 100 or not the default for it ?
"The default value is three connections" or "The default is one thousand files"
Why three and not 3 or why thousand and not 1000 ?
Sometimes "an empty string", sometimes "empty", sometimes ''.
So, if we move all them to the definition of that GUC they would be written the same way, just that.
Sometimes "an empty string", sometimes "empty", sometimes ''.
Sometimes "If this parameter is off (the default)", "Default is off", "Default value is off"
So, if we move all them to the definition of that GUC they would be written the same way, just that.
regards
Marcos
On Thu, Feb 6, 2025 at 10:46 PM Marcos Pegoraro <marcos@f10.com.br> wrote:
>
> I agree that duplicating default values is not fine, I can remove them from the explanation and put it only near
definition.
>
> But about adding a new line with its default value, sometimes is fine, sometimes not.
> [1] is a good example which would be fine but the next ones cpu_tuple_cost, cpu_index_tuple_cost, cpu_operator_cost
andso on wouldn't be good.
>
> And obviously, if you don't know the purpose of that GUC, you'll have to read the entire paragraph to understand it.
> Objective here is to those ones who know what it is, but don't remember its default.
>
If you feel a blank line preceding the default in the description is
sometimes inappropriate then forget that; just ensure the default
information is consistently *last* in the GUC short description
paragraph.
Like this:
<guc-name> (type)
<short description><default value>
<more details, if any>
Then.
- No duplicated info
- Locating the default info is effortless (the $SUBJECT goal) because
they are always found in the same place.
- Many descriptions are using this format already (e.g.
cpu_tuple_cost, cpu_index_tuple_cost, cpu_operator_cost etc) so there
is nothing to do for these.
~~~
+1 to your second goal of wanting to use consistent wording [1]
======
[1] https://www.postgresql.org/message-id/CAB-JLwa1BwESd_OJZftOeaw4dSCg29rd1nhc3gLwYZ1N8yxwrw%40mail.gmail.com
Kind Regards,
Peter Smith.
Fujitsu Australia
> [1] - https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-RANDOM-PAGE-COST
>
> regards
> Marcos
>
> Em qua., 5 de fev. de 2025 às 20:59, Peter Smith <smithpb2250@gmail.com> escreveu:
>>
>> On Thu, Feb 6, 2025 at 8:08 AM Marcos Pegoraro <marcos@f10.com.br> wrote:
>> >
>> > Reading DOCs sometimes is boring because you want to know only the default value of something. I know what that
GUCis, I know how to change it, I only don't remember what its default value is. Then you have to read that entire
paragraphjust to read that the default value is ...
>> >
>> > So, what you think about this.
>> > It's not complete but you can see if it's useful or not
>> >
>>
>> +0.5
>>
>> IIUC the problem here (if there is one), is just that the default is
>> sometimes buried within the GUC description.
>>
>> But just putting the default value adjacent to the GUC name might not
>> be the best solution because often defaults have special meanings.
>> e.g. there is no point knowing the default value is -1 unless you know
>> what that value means. So with your patch, not only is the default
>> value duplicated, but you are back where you started having to read
>> all the description text again to learn what it means.
>>
>> IMO it would be better simply to ensure that defaults are always
>> described in a consistent place within all GUC descriptions, Then they
>> are easy to find because you always know where to look for them. In
>> other words, add nothing new -- just slightly rearrange and/or add
>> blank lines to the existing text.
>>
>> Like this:
>>
>> <guc-name> (type)
>> <one line terse description>
>> <default value, and optional special meaning>
>> <more details, if any>
>>
>> For example:
>>
>> CURRENTLY
>> vacuum_cost_delay (floating point)
>>
>> The amount of time that the process will sleep when the cost limit has
>> been exceeded. If this value is specified without units, it is taken
>> as milliseconds. The default value is 0, which disables the cost-based
>> vacuum delay feature. Positive values enable cost-based vacuuming.
>>
>> When using cost-based vacuuming, appropriate values for
>> vacuum_cost_delay are usually quite small, perhaps less than 1
>> millisecond. While vacuum_cost_delay can be set to
>> fractional-millisecond values, such delays may not be measured
>> accurately on older platforms. On such platforms, increasing VACUUM's
>> throttled resource consumption above what you get at 1ms will require
>> changing the other vacuum cost parameters. You should, nonetheless,
>> keep vacuum_cost_delay as small as your platform will consistently
>> measure; large delays are not helpful.
>>
>> SUGGESTION
>> vacuum_cost_delay (floating point)
>>
>> The amount of time that the process will sleep when the cost limit has
>> been exceeded. If this value is specified without units, it is taken
>> as milliseconds. Positive values enable cost-based vacuuming.
>>
>> The default value is 0, which disables the cost-based vacuum delay feature.
>>
>> When using cost-based vacuuming, appropriate values for
>> vacuum_cost_delay are usually quite small, ... blah blah
>>
>> ~~~
>>
>> Thoughts?
>>
>> ======
>> Kind Regards,
>> Peter Smith.
>> Fujitsu Australia