We don't seem to be agreeing on much here... :-( On Tue, 29 Oct 2024 at 13:30, David G. Johnston <david.g.johns...@gmail.com> wrote: > > On Mon, Oct 28, 2024 at 3:54 PM David Rowley <dgrowle...@gmail.com> wrote: >> I'm concerned about the wording "all index-scan related". It's not >> that clear if that would include Bitmap Index Scans or not. > > > That was partially the point of writing "all" there - absent other > information, and seeing how index-only scans were treated, I presumed it was > indeed actually or effectively a switch for all. If it is not it should be > made clear which node types with the word index in them are not affected.
I'm very much against mentioning which things are *not* affected by settings. It doesn't seem like a very sustainable way to write documentation. >> I think >> it's better to explicitly mention index-only-scans to make it clear >> which nodes are affected. > > I hadn't considered Bitmap Index Scans but I would expect if you do not use > index scans then the ability to produce bitmaps from them would be precluded. > > I could see pointing out, in enable_bitmapscan, that enable_bitmapscan is > effectively disabled (for index inputs) when enable_indexscan is set to off. > Then, in enable_indexscan, add a "see also" to enable_bitmapscan with a brief > reason as well. I don't follow this. enable_bitmapscan is completely independent from enable_indexscan. > Is there a listing of all node types produced by PostgreSQL (with the explain > output naming) along with which ones are affected by which enable_* knobs > (possibly multiple for something like Bitmap Index Scan)? No. We purposefully do our best not to document executor nodes. The enable_* GUCs is one place where it's hard to avoid. >> >> + types. The default is <literal>on</literal>. The >> index-only-scan plan types >> + can be independently disabled by setting <xref >> linkend="guc-enable-indexonlyscan"/> >> + to <literal>off</literal>. >> >> I wondered if it's better to reference the enable_indexonlyscan GUC >> here rather than document what enable_indexonlyscan does from the >> enable_indexscan docs. Maybe just a "Also see enable_indexonlyscans." >> could be added? > > > I prefer to briefly explain why we advise the reader to go "see also" here. > >> >> - The default is <literal>on</literal>. >> + The default is <literal>on</literal>. However, this setting >> has no effect if >> + <xref linkend="guc-enable-indexscan"/> is set to >> <literal>off</literal>. >> >> Could we just add "The <xref linkend="guc-enable-indexscan"/> setting >> must also be enabled to have the query planner consider >> index-only-scans"? > > > I'd like to stick with a conjunction there but agree the "must be enabled" > wording is preferrable, avoiding the double-negative. > > "The default is on, but the <xref> setting must also be enabled." > > The 'to have the...' part seems to just be redundant. I think it's confusing to include this as part of the mention of what the default value is. The default value and enable_indexscans being the master switch aren't at all related. David
