sql/hints: add per-node cache for system.statement_hints

This commit adds a per-node cache for the `system.statement_hints` table,
similar to the table stats cache. The cache tracks the set of all statement
fingerprint hashes that have hints in a map kept up-to-date via rangefeed.
This allows queries to quickly determine whether they have hints, minimizing
the overhead for unhinted queries. Hints are kept in a separate
limited-capacity LRU cache. The LRU cache size can be configured by setting
the `sql.hints.statement_hints_cache_size` cluster setting.

Fixes #148160

Release note: None

Author: DrewKimball

.github/CODEOWNERS

@@ -70,6 +70,7 @@
 /pkg/sql/execute.go                    @cockroachdb/sql-queries-prs
 /pkg/sql/executor_statement_metrics.go @cockroachdb/obs-prs
 /pkg/sql/flowinfra/          @cockroachdb/sql-queries-prs
+/pkg/sql/hints/              @cockroachdb/sql-queries-prs
 /pkg/sql/physicalplan/       @cockroachdb/sql-queries-prs
 /pkg/sql/row*                @cockroachdb/sql-queries-prs
 /pkg/sql/control_job*        @cockroachdb/sql-queries-prs @cockroachdb/jobs-prs

build/bazelutil/nogo_config.json

@@ -144,6 +144,7 @@
             "pkg/sql/contention/event_store.go": "flagged by linter, should be evaluated",
             "pkg/sql/distsql_running.go": "flagged by linter, should be evaluated",
             "pkg/sql/flowinfra/flow_registry.go": "flagged by linter, should be evaluated",
+            "pkg/sql/hints/hint_cache.go": "flagged by linter, should be evaluated",
             "pkg/sql/idxusage/local_idx_usage_stats.go": "flagged by linter, should be evaluated",
             "pkg/sql/importer/import_processor.go": "flagged by linter, should be evaluated",
             "pkg/sql/importer/import_processor_planning.go": "flagged by linter, should be evaluated",

pkg/server/BUILD.bazel

@@ -242,6 +242,7 @@ go_library(
         "//pkg/sql/flowinfra",
         "//pkg/sql/gcjob",
         "//pkg/sql/gcjob/gcjobnotifier",
+        "//pkg/sql/hints",
         "//pkg/sql/idxusage",
         "//pkg/sql/importer",
         "//pkg/sql/inspect",

pkg/server/server_sql.go

@@ -83,6 +83,7 @@ import (
 	"github.com/cockroachdb/cockroach/pkg/sql/execinfrapb"
 	"github.com/cockroachdb/cockroach/pkg/sql/flowinfra"
 	"github.com/cockroachdb/cockroach/pkg/sql/gcjob/gcjobnotifier"
+	"github.com/cockroachdb/cockroach/pkg/sql/hints"
 	"github.com/cockroachdb/cockroach/pkg/sql/idxusage"
 	"github.com/cockroachdb/cockroach/pkg/sql/isql"
 	"github.com/cockroachdb/cockroach/pkg/sql/optionalnodeliveness"
@@ -1039,7 +1040,10 @@ func newSQLServer(ctx context.Context, cfg sqlServerArgs) (*SQLServer, error) {
 			cfg.stopper,
 		),
 
-		QueryCache:                 querycache.New(cfg.QueryCacheSize),
+		QueryCache: querycache.New(cfg.QueryCacheSize),
+		StatementHintsCache: hints.NewStatementHintsCache(
+			cfg.clock, cfg.rangeFeedFactory, cfg.stopper, codec, cfg.internalDB, cfg.Settings,
+		),
 		VecIndexManager:            vecIndexManager,
 		RowMetrics:                 &rowMetrics,
 		InternalRowMetrics:         &internalRowMetrics,
@@ -1775,6 +1779,9 @@ func (s *SQLServer) preStart(
 	if err := s.execCfg.TableStatsCache.Start(ctx, s.execCfg.Codec, s.execCfg.RangeFeedFactory); err != nil {
 		return err
 	}
+	if err = s.execCfg.StatementHintsCache.Start(ctx, s.execCfg.SystemTableIDResolver); err != nil {
+		return err
+	}
 
 	scheduledlogging.Start(
 		ctx, stopper, s.execCfg.InternalDB, s.execCfg.Settings,

pkg/sql/BUILD.bazel

@@ -441,6 +441,7 @@ go_library(
         "//pkg/sql/faketreeeval",
         "//pkg/sql/flowinfra",
         "//pkg/sql/gcjob/gcjobnotifier",
+        "//pkg/sql/hints",
         "//pkg/sql/idxrecommendations",
         "//pkg/sql/idxusage",
         "//pkg/sql/inverted",

pkg/sql/catalog/systemschema/system.go

@@ -5433,9 +5433,9 @@ var (
 		},
 	)
 
-	statementHintsComputeExpr = "fnv64(fingerprint)"
-
-	StatementHintsTable = makeSystemTable(
+	statementHintsComputeExpr                = "fnv64(fingerprint)"
+	StatementHintsHashIndexID descpb.IndexID = 2
+	StatementHintsTable                      = makeSystemTable(
 		StatementHintsTableSchema,
 		systemTable(
 			catconstants.StatementHintsTableName,
@@ -5465,7 +5465,7 @@ var (
 			},
 			descpb.IndexDescriptor{
 				Name:                "hash_idx",
-				ID:                  2,
+				ID:                  StatementHintsHashIndexID,
 				Unique:              false,
 				Version:             descpb.StrictIndexColumnIDGuaranteesVersion,
 				KeyColumnNames:      []string{"hash"},

pkg/sql/exec_util.go

@@ -67,6 +67,7 @@ import (
 	"github.com/cockroachdb/cockroach/pkg/sql/execinfra"
 	"github.com/cockroachdb/cockroach/pkg/sql/execinfrapb"
 	"github.com/cockroachdb/cockroach/pkg/sql/gcjob/gcjobnotifier"
+	"github.com/cockroachdb/cockroach/pkg/sql/hints"
 	"github.com/cockroachdb/cockroach/pkg/sql/idxusage"
 	"github.com/cockroachdb/cockroach/pkg/sql/isql"
 	"github.com/cockroachdb/cockroach/pkg/sql/lex"
@@ -1617,19 +1618,20 @@ type ExecutorConfig struct {
 	NodesStatusServer serverpb.OptionalNodesStatusServer
 	// SQLStatusServer gives access to a subset of the Status service and is
 	// available when not running as a system tenant.
-	SQLStatusServer    serverpb.SQLStatusServer
-	TenantStatusServer serverpb.TenantStatusServer
-	MetricsRecorder    limitedMetricsRecorder
-	SessionRegistry    *SessionRegistry
-	ClosedSessionCache *ClosedSessionCache
-	SQLLiveness        sqlliveness.Provider
-	JobRegistry        *jobs.Registry
-	VirtualSchemas     *VirtualSchemaHolder
-	DistSQLPlanner     *DistSQLPlanner
-	TableStatsCache    *stats.TableStatisticsCache
-	StatsRefresher     *stats.Refresher
-	QueryCache         *querycache.C
-	VecIndexManager    *vecindex.Manager
+	SQLStatusServer     serverpb.SQLStatusServer
+	TenantStatusServer  serverpb.TenantStatusServer
+	MetricsRecorder     limitedMetricsRecorder
+	SessionRegistry     *SessionRegistry
+	ClosedSessionCache  *ClosedSessionCache
+	SQLLiveness         sqlliveness.Provider
+	JobRegistry         *jobs.Registry
+	VirtualSchemas      *VirtualSchemaHolder
+	DistSQLPlanner      *DistSQLPlanner
+	TableStatsCache     *stats.TableStatisticsCache
+	StatsRefresher      *stats.Refresher
+	QueryCache          *querycache.C
+	StatementHintsCache *hints.StatementHintsCache
+	VecIndexManager     *vecindex.Manager
 
 	SchemaChangerMetrics *SchemaChangerMetrics
 	FeatureFlagMetrics   *featureflag.DenialMetrics

pkg/sql/hints/BUILD.bazel

@@ -4,11 +4,43 @@ load("@io_bazel_rules_go//go:def.bzl", "go_library")
 
 go_library(
     name = "hints",
-    srcs = ["statement_hint.go"],
+    srcs = [
+        "hint_cache.go",
+        "statement_hint.go",
+    ],
     embed = [":hints_go_proto"],
     importpath = "github.com/cockroachdb/cockroach/pkg/sql/hints",
     visibility = ["//visibility:public"],
-    deps = ["//pkg/util/protoutil"],
+    deps = [
+        "//pkg/keys",
+        "//pkg/kv/kvclient/rangefeed",
+        "//pkg/kv/kvclient/rangefeed/rangefeedbuffer",
+        "//pkg/kv/kvclient/rangefeed/rangefeedcache",
+        "//pkg/kv/kvpb",
+        "//pkg/roachpb",
+        "//pkg/settings",
+        "//pkg/settings/cluster",
+        "//pkg/sql/catalog",
+        "//pkg/sql/catalog/catenumpb",
+        "//pkg/sql/catalog/descpb",
+        "//pkg/sql/catalog/descs",
+        "//pkg/sql/catalog/systemschema",
+        "//pkg/sql/rowenc",
+        "//pkg/sql/sem/tree",
+        "//pkg/sql/sessiondata",
+        "//pkg/sql/types",
+        "//pkg/util/buildutil",
+        "//pkg/util/cache",
+        "//pkg/util/hlc",
+        "//pkg/util/log",
+        "//pkg/util/metamorphic",
+        "//pkg/util/protoutil",
+        "//pkg/util/retry",
+        "//pkg/util/startup",
+        "//pkg/util/stop",
+        "//pkg/util/syncutil",
+        "@com_github_cockroachdb_errors//:errors",
+    ],
 )
 
 go_proto_library(