Re: Correct the documentation for work_mem

On Fri, Apr 21, 2023 at 01:15:01PM -0400, Tom Lane wrote:
> Peter Eisentraut <peter(dot)eisentraut(at)enterprisedb(dot)com> writes:
> > On 21.04.23 16:28, Imseih (AWS), Sami wrote:
> >> I suggest a small doc fix:
> >> “Note that for a complex query, several sort or hash operations might be
> >> running simultaneously;”
>
> > Here is a discussion of these terms:
> > https://takuti.me/note/parallel-vs-concurrent/
>
> > I think "concurrently" is the correct word here.
>
> Probably, but it'd do little to remove the confusion Sami is on about,
> especially since the next sentence uses "concurrently" to describe the
> other case. I think we need a more thorough rewording, perhaps like
>
> - Note that for a complex query, several sort or hash operations might be
> - running in parallel; each operation will generally be allowed
> + Note that a complex query may include several sort or hash
> + operations; each such operation will generally be allowed
> to use as much memory as this value specifies before it starts
> to write data into temporary files. Also, several running
> sessions could be doing such operations concurrently.
>
> I also find this wording a bit further down to be poor:
>
> Hash-based operations are generally more sensitive to memory
> availability than equivalent sort-based operations. The
> memory available for hash tables is computed by multiplying
> <varname>work_mem</varname> by
> <varname>hash_mem_multiplier</varname>. This makes it
>
> I think "available" is not le mot juste, and it's also unclear from
> this whether we're speaking of the per-hash-table limit or some
> (nonexistent) overall limit. How about
>
> - memory available for hash tables is computed by multiplying
> + memory limit for a hash table is computed by multiplying

Adjusted patch attached.

--
Bruce Momjian <bruce(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.