explain: display number of hints for EXPLAIN

This commit adds a top-level field to the output of `EXPLAIN` and
`EXPLAIN ANALYZE` showing the number of hints applied to the statement,
if nonzero.

Informs #121502

Release note (sql change): EXPLAIN and EXPLAIN ANALYZE will now display
the number of hints from `system.statement_hints` applied to the executed
statement.

Author: DrewKimball

pkg/sql/explain_plan.go

@@ -120,6 +120,10 @@ func (e *explainPlanNode) startExec(params runParams) error {
 			}
 		}
 
+		if len(params.p.stmt.Hints) > 0 {
+			ob.AddStmtHintCount(uint64(len(params.p.stmt.Hints)))
+		}
+
 		if e.options.Flags[tree.ExplainFlagJSON] {
 			// For the JSON flag, we only want to emit the diagram JSON.
 			rows = []string{diagramJSON}

pkg/sql/instrumentation.go

@@ -207,6 +207,10 @@ type instrumentationHelper struct {
 	// stats scanned by this query.
 	nanosSinceStatsForecasted time.Duration
 
+	// stmtHintsCount is the number of hints from system.statement_hints applied
+	// to the statement.
+	stmtHintsCount uint64
+
 	// retryCount is the number of times the transaction was retried.
 	retryCount uint64
 
@@ -429,6 +433,7 @@ func (ih *instrumentationHelper) Setup(
 	ih.implicitTxn = implicitTxn
 	ih.txnPriority = txnPriority
 	ih.txnBufferedWritesEnabled = p.txn.BufferedWritesEnabled()
+	ih.stmtHintsCount = uint64(len(stmt.Hints))
 	ih.retryCount = uint64(retryCount)
 	ih.codec = cfg.Codec
 	ih.origCtx = ctx
@@ -861,6 +866,7 @@ func (ih *instrumentationHelper) emitExplainAnalyzePlanToOutputBuilder(
 	ob.AddDistribution(ih.distribution.String())
 	ob.AddVectorized(ih.vectorized)
 	ob.AddPlanType(ih.generic, ih.optimized)
+	ob.AddStmtHintCount(ih.stmtHintsCount)
 	ob.AddRetryCount("transaction", ih.retryCount)
 	ob.AddRetryTime("transaction", phaseTimes.GetTransactionRetryLatency())
 	ob.AddRetryCount("statement", ih.retryStmtCount)

pkg/sql/opt/exec/execbuilder/testdata/explain

@@ -2573,3 +2573,41 @@ vectorized: true
           table: t_float@t_float_pkey
           spans: /1/0 /2/0 /3/0 /4/0 /5/0 /6/0 /7/0 /8/0 /9/0 /10/0 /11/0 /12/0 /13/0 /14/0 /15/0 /16/0 /17/0 /18/0 /19/0 /20/0 … (20 more)
           parallel
+
+# Verify that the number of applied statement hints is displayed.
+statement ok
+CREATE TABLE t_hints (k INT PRIMARY KEY, v INT, INDEX (v))
+
+statement ok
+SELECT crdb_internal.inject_hint(
+  'SELECT k FROM t_hints WHERE k >= _',
+  'SELECT k FROM t_hints@t_hints_v_idx WHERE k >= _'
+)
+
+statement ok
+SELECT crdb_internal.await_statement_hints_cache()
+
+query T
+EXPLAIN SELECT k FROM t_hints WHERE k >= 100
+----
+distribution: local
+vectorized: true
+statement hints count: 1
+·
+• scan
+  missing stats
+  table: t_hints@t_hints_pkey
+  spans: [/100 - ]
+
+query T
+EXPLAIN (VERBOSE) SELECT k FROM t_hints WHERE k >= 100
+----
+distribution: local
+vectorized: true
+statement hints count: 1
+·
+• scan
+  columns: (k)
+  estimated row count: 333 (missing stats)
+  table: t_hints@t_hints_pkey
+  spans: /100-

pkg/sql/opt/exec/execbuilder/testdata/explain_analyze

@@ -1,7 +1,7 @@
 # LogicTest: local
 
 statement ok
-CREATE TABLE kv (k INT PRIMARY KEY, v INT, FAMILY (k, v))
+CREATE TABLE kv (k INT PRIMARY KEY, v INT, FAMILY (k, v), INDEX (v))
 
 query T
 EXPLAIN ANALYZE (PLAN) SELECT k FROM kv WHERE k >= 2
@@ -176,7 +176,7 @@ quality of service: regular
         │       │               └── • virtual table
         │       │                     sql nodes: <hidden>
         │       │                     regions: <hidden>
-        │       │                     actual row count: 361
+        │       │                     actual row count: 362
         │       │                     execution time: 0µs
         │       │                     table: pg_class@primary
         │       │
@@ -276,3 +276,43 @@ quality of service: regular
           actual row count: 1
           execution time: 0µs
           size: 2 columns, 1 row
+
+# Verify that the number of applied statement hints is displayed.
+statement ok
+SELECT crdb_internal.inject_hint(
+  'SELECT k FROM kv WHERE k >= _',
+  'SELECT k FROM kv@kv_v_idx WHERE k >= _'
+)
+
+statement ok
+SELECT crdb_internal.await_statement_hints_cache()
+
+query T
+EXPLAIN ANALYZE SELECT k FROM kv WHERE k >= 100
+----
+planning time: 10µs
+execution time: 100µs
+distribution: <hidden>
+vectorized: <hidden>
+plan type: custom
+statement hints count: 1
+maximum memory usage: <hidden>
+DistSQL network usage: <hidden>
+regions: <hidden>
+isolation level: serializable
+priority: normal
+quality of service: regular
+·
+• scan
+  sql nodes: <hidden>
+  kv nodes: <hidden>
+  regions: <hidden>
+  actual row count: 0
+  KV time: 0µs
+  KV rows decoded: 0
+  KV bytes read: 0 B
+  KV gRPC calls: 0
+  estimated max memory allocated: 0 B
+  missing stats
+  table: kv@kv_pkey
+  spans: [/100 - ]

pkg/sql/opt/exec/explain/output.go

@@ -316,6 +316,15 @@ func (ob *OutputBuilder) AddPlanType(generic, optimized bool) {
 	}
 }
 
+// AddStmtHintCount adds a top-level field displaying the number of statement
+// hints applied to the query. Cannot be called while inside a node.
+func (ob *OutputBuilder) AddStmtHintCount(hintCount uint64) {
+	if hintCount == 0 {
+		return
+	}
+	ob.AddTopLevelField("statement hints count", string(humanizeutil.Count(hintCount)))
+}
+
 // AddPlanningTime adds a top-level planning time field. Cannot be called
 // while inside a node.
 func (ob *OutputBuilder) AddPlanningTime(delta time.Duration) {