Overall, I think we need to do something here. There's no
documentation about what Disabled Nodes means so we either need to
make it easier to understand without documenting it or add something
to the documents about it. If Laurenz, who has a huge amount of
PostgreSQL experience didn't catch it, then what hope is there for the
average user?
I think you are right, most users will perceive this parameter as the
number of rejected paths, and not in any other way.
To be honest, I don't have much experience writing documentation, but I
think we should add a little more information to doc/src/sgml/perform.sgml.
It contains a description about "explain queries", so the description of
"Disabled nodes" is available there.
I prepared a patch that includes the information we can add.
--
Regards,
Alena Rybakina
Postgres Professional
From 3670f14326bf3ac97242042e63046f7658d13709 Mon Sep 17 00:00:00 2001
From: Alena Rybakina <a.rybak...@postgrespro.ru>
Date: Thu, 3 Oct 2024 20:31:25 +0300
Subject: [PATCH] Documentation about Disabled nodes. We need to describe this,
as this parameter can be perceived ambiguously.
---
doc/src/sgml/perform.sgml | 36 ++++++++++++++++++++++++++++++++++++
1 file changed, 36 insertions(+)
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index ff689b65245..9f7339f3388 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -130,6 +130,42 @@ EXPLAIN SELECT * FROM tenk1;
</itemizedlist>
</para>
+ <para>
+ The parameter <literal>Disabled nodes</literal> appears if one of the
+ <xref linkend="runtime-config-query-enable"/> was disable. It tracks how many plan
+ nodes below and including this node are disabled.
+ </para>
+
+ <para>
+ Here is an example, just to show what the output looks like:
+
+<screen>
+SET enable_seqscan = off;
+SET
+SET enable_nestloop = off;
+SET
+EXPLAIN SELECT * FROM tenk1 t1 join tenk1 t2 on t1.unique1 > t2.unique2;
+ QUERY PLAN
+----------------------------------------------------------------------------
+ Nested Loop (cost=0.00..1500915.00 rows=33333333 width=488)
+ Disabled Nodes: 3
+ Join Filter: (t1.unique1 > t2.unique2)
+ -> Seq Scan on tenk1 t1 (cost=0.00..445.00 rows=10000 width=244)
+ Disabled Nodes: 1
+ -> Materialize (cost=0.00..495.00 rows=10000 width=244)
+ Disabled Nodes: 1
+ -> Seq Scan on tenk1 t2 (cost=0.00..445.00 rows=10000 width=244)
+ Disabled Nodes: 1
+</screen>
+ </para>
+
+ <para>
+ The number of <literal>Disabled nodes</literal> is equal to 3 in nested-loop join node
+ beacuse it is disable itself and it contains two disabled sequential scan nodes. Every
+ sequential scan nodes is disable and has one <literal>Disabled nodes</literal> in the
+ query plan.
+ </para>
+
<para>
The costs are measured in arbitrary units determined by the planner's
cost parameters (see <xref linkend="runtime-config-query-constants"/>).
--
2.34.1
