sql/opt: implement canary full statistics rollout with configurable window

This commit implements the core logic for canary statistics rollout,
allowing gradual deployment of newly collected full statistics.
Previously, all queries would immediately use the most recent full
statistics, which could cause performance regressions if the new full
statistics were inaccurate.

The implementation adds a `CanaryWindowSize` field in table descriptors
and catalog interfaces to define the canary period, along with logic in
the statistics builder to skip "canary" statistics (the latest stats
within the canary window) when not using the canary path. The cluster
setting `sql.stats.canary_fraction` controls what percentage of queries
use canary statistics.

Release note (sql change): implement canary full statistics rollout core logic, which
is configurable via the table-level storage paramter
(`canary_window`) and the cluster setting
`sql.stats.canary_fraction`.

Author: ZhouXing19

pkg/sql/catalog/descriptor.go

@@ -7,6 +7,7 @@ package catalog
 
 import (
 	"context"
+	"time"
 
 	"github.com/cockroachdb/cockroach/pkg/clusterversion"
 	"github.com/cockroachdb/cockroach/pkg/jobs/jobspb"
@@ -878,6 +879,9 @@ type TableDescriptor interface {
 	// security for the table and false if it is no force. When forced is
 	// set the table's RLS policies are enforced even on the table owner.
 	IsRowLevelSecurityForced() bool
+	// GetCanaryWindowSize returns the canary statistics rollout duration.
+	// See TableDescriptor.CanaryWindowSize for details.
+	GetCanaryWindowSize() time.Duration
 }
 
 // MutableTableDescriptor is both a MutableDescriptor and a TableDescriptor.

pkg/sql/catalog/tabledesc/table_desc.go

@@ -7,6 +7,8 @@
 package tabledesc
 
 import (
+	"time"
+
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog"
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog/catenumpb"
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog/catpb"
@@ -740,3 +742,8 @@ func (desc *wrapper) IsRowLevelSecurityEnabled() bool {
 func (desc *wrapper) IsRowLevelSecurityForced() bool {
 	return desc.RowLevelSecurityForced
 }
+
+// GetCanaryWindowSize implements the TableDescriptor interface.
+func (desc *wrapper) GetCanaryWindowSize() time.Duration {
+	return desc.CanaryWindowSize
+}

pkg/sql/opt/cat/table.go

@@ -205,6 +205,9 @@ type Table interface {
 
 	// Policies returns all the policies defined for this table.
 	Policies() *Policies
+
+	// CanaryWindowSize returns the canary window size for the table.
+	CanaryWindowSize() time.Duration
 }
 
 // CheckConstraint represents a check constraint on a table. Check constraints

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

@@ -10,6 +10,7 @@ import (
 	"context"
 	b64 "encoding/base64"
 	"encoding/binary"
+	"time"
 
 	"github.com/cockroachdb/cockroach/pkg/geo/geopb"
 	"github.com/cockroachdb/cockroach/pkg/roachpb"
@@ -682,6 +683,9 @@ func (u *unknownTable) IsRowLevelSecurityEnabled() bool { return false }
 // IsRowLevelSecurityForced is part of the cat.Table interface
 func (u *unknownTable) IsRowLevelSecurityForced() bool { return false }
 
+// CanaryWindowSize is part of the cat.Table interface
+func (u *unknownTable) CanaryWindowSize() time.Duration { return 0 }
+
 // Policies is part of the cat.Table interface.
 func (u *unknownTable) Policies() *cat.Policies { return nil }
 

pkg/sql/opt/memo/statistics_builder.go

@@ -9,6 +9,7 @@ import (
 	"context"
 	"math"
 	"reflect"
+	"time"
 
 	"github.com/cockroachdb/cockroach/pkg/geo/geoindex"
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog/colinfo"
@@ -23,6 +24,7 @@ import (
 	"github.com/cockroachdb/cockroach/pkg/sql/stats"
 	"github.com/cockroachdb/cockroach/pkg/sql/types"
 	"github.com/cockroachdb/cockroach/pkg/util/buildutil"
+	"github.com/cockroachdb/cockroach/pkg/util/hlc"
 	"github.com/cockroachdb/cockroach/pkg/util/json"
 	"github.com/cockroachdb/cockroach/pkg/util/log"
 	"github.com/cockroachdb/errors"
@@ -659,6 +661,7 @@ func (sb *statisticsBuilder) makeTableStatistics(tabID opt.TableID) *props.Stati
 	}
 
 	tab := sb.md.Table(tabID)
+	tabMeta := sb.md.TableMeta(tabID)
 	// Create a mapping from table column ordinals to inverted index column
 	// ordinals. This allows us to do a fast lookup while iterating over all
 	// stats from a statistic's column to any associated inverted columns.
@@ -680,13 +683,41 @@ func (sb *statisticsBuilder) makeTableStatistics(tabID opt.TableID) *props.Stati
 	// Make now and annotate the metadata table with it for next time.
 	stats = &props.Statistics{}
 
+	useCanary := sb.mem.Metadata().UseCanaryStats()
+	var skippedStatsCreationTimestamp time.Time
+	canaryWindowSize := tabMeta.CanaryWindowSize
 	// Find the most recent full statistic. (Stats are ordered with most recent first.)
 	var first int
-	for first < tab.StatisticCount() &&
-		(tab.Statistic(first).IsPartial() ||
-			tab.Statistic(first).IsMerged() && !sb.evalCtx.SessionData().OptimizerUseMergedPartialStatistics ||
-			tab.Statistic(first).IsForecast() && !sb.evalCtx.SessionData().OptimizerUseForecasts) {
-		first++
+	sd := sb.evalCtx.SessionData()
+	for first < tab.StatisticCount() {
+		stat := tab.Statistic(first)
+		if stat.IsPartial() ||
+			stat.IsMerged() && !sd.OptimizerUseMergedPartialStatistics ||
+			stat.IsForecast() && !sd.OptimizerUseForecasts {
+			first++
+			continue
+		} else if canaryWindowSize > 0 && !useCanary && first < tab.StatisticCount()-1 {
+			// The following, we are getting full statistics for the stable stats,
+			// in contrast to the canary stats. The canary stats is skipped.
+			// If there remains only one full statistics, don't skip.
+			createdAtTS := hlc.Timestamp{WallTime: stat.CreatedAt().UnixNano()}
+			if stat.CreatedAt() == skippedStatsCreationTimestamp && !skippedStatsCreationTimestamp.IsZero() {
+				// We've already seen this canary stat, so skip it.
+				first++
+				continue
+			}
+			// Found a canary stats (defined as creation time within the canary window size). Register the
+			// creation timestamp and move on the next older one.
+			if createdAtTS.AddDuration(canaryWindowSize).After(hlc.Timestamp{WallTime: time.Now().UnixNano()}) {
+				// If there is already a canary stats skipped, we don't skip again.
+				if skippedStatsCreationTimestamp.IsZero() {
+					skippedStatsCreationTimestamp = stat.CreatedAt()
+					first++
+					continue
+				}
+			}
+		}
+		break
 	}
 
 	if first >= tab.StatisticCount() {

pkg/sql/opt/metadata.go

@@ -73,7 +73,7 @@ var canaryFraction = settings.RegisterFloatSetting(
 func canaryRollDice(evalCtx *eval.Context) bool {
 	threshold := canaryFraction.Get(&evalCtx.Settings.SV)
 
-	// If the fraction is 0, never use canary stats.
+	// If the fraction is 0, never use canary stats. (should we even allow?)
 	if threshold == 0 {
 		return false
 	}
@@ -824,7 +824,7 @@ func (md *Metadata) AddTable(tab cat.Table, alias *tree.TableName) TableID {
 	if md.tables == nil {
 		md.tables = make([]TableMeta, 0, 4)
 	}
-	md.tables = append(md.tables, TableMeta{MetaID: tabID, Table: tab, Alias: *alias})
+	md.tables = append(md.tables, TableMeta{MetaID: tabID, Table: tab, Alias: *alias, CanaryWindowSize: tab.CanaryWindowSize()})
 
 	colCount := tab.ColumnCount()
 	if md.cols == nil {
@@ -945,6 +945,7 @@ func (md *Metadata) DuplicateTable(
 		partialIndexPredicates:        partialIndexPredicates,
 		indexPartitionLocalities:      tabMeta.indexPartitionLocalities,
 		checkConstraintsStats:         checkConstraintsStats,
+		CanaryWindowSize:              tabMeta.CanaryWindowSize,
 	}
 	newTabMeta.indexVisibility.cached = tabMeta.indexVisibility.cached
 	newTabMeta.indexVisibility.notVisible = tabMeta.indexVisibility.notVisible
@@ -1331,3 +1332,9 @@ func (md *Metadata) checkRLSDependencies(
 	// check already accounts for changes in the table descriptor version.
 	return true, nil
 }
+
+// UseCanaryStats returns true if the metadata is configured to use canary
+// statistics for the current query planning.
+func (md *Metadata) UseCanaryStats() bool {
+	return md.useCanaryStats
+}

pkg/sql/opt/table_meta.go

@@ -8,6 +8,7 @@ package opt
 import (
 	"context"
 	"math/rand"
+	"time"
 
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog/catpb"
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog/descpb"
@@ -214,6 +215,11 @@ type TableMeta struct {
 		cached     *intsets.Fast
 		notVisible *intsets.Fast
 	}
+
+	// CanaryWindowSize determines the time duration for which a newly collected
+	// stats is in a "canary" state before it is promoted to a stable state.
+	// See TableDescriptor.CanaryWindowSize for details.
+	CanaryWindowSize time.Duration
 }
 
 // IsIndexNotVisible returns true if the given index is not visible, and false
@@ -293,6 +299,7 @@ func (tm *TableMeta) copyFrom(from *TableMeta, copyScalarFn func(Expr) Expr) {
 		Alias:                        from.Alias,
 		IgnoreForeignKeys:            from.IgnoreForeignKeys,
 		IgnoreUniqueWithoutIndexKeys: from.IgnoreUniqueWithoutIndexKeys,
+		CanaryWindowSize:             from.CanaryWindowSize,
 		// Annotations are not copied.
 	}
 

pkg/sql/opt/testutils/testcat/test_catalog.go

@@ -922,6 +922,8 @@ type Table struct {
 	rlsForced    bool
 	policies     cat.Policies
 	nextPolicyID descpb.PolicyID
+
+	canaryWindowSize time.Duration
 }
 
 var _ cat.Table = &Table{}
@@ -1232,6 +1234,9 @@ func (tt *Table) IsRowLevelSecurityEnabled() bool { return tt.rlsEnabled }
 // IsRowLevelSecurityForced is part of the cat.Table interface.
 func (tt *Table) IsRowLevelSecurityForced() bool { return tt.rlsForced }
 
+// CanaryWindowSize is part of the cat.Table interface.
+func (tt *Table) CanaryWindowSize() time.Duration { return tt.canaryWindowSize }
+
 // Policies is part of the cat.Table interface.
 func (tt *Table) Policies() *cat.Policies {
 	return &tt.policies

pkg/sql/opt_catalog.go

@@ -941,6 +941,9 @@ type optTable struct {
 	rlsForced  bool
 	policies   cat.Policies
 
+	// Canary statistics rollout duration.
+	canaryWindow time.Duration
+
 	// colMap is a mapping from unique ColumnID to column ordinal within the
 	// table. This is a common lookup that needs to be fast.
 	colMap catalog.TableColMap
@@ -1224,6 +1227,9 @@ func newOptTable(
 	ot.rlsForced = desc.IsRowLevelSecurityForced()
 	ot.policies = getOptPolicies(desc.GetPolicies())
 
+	// Store canary stats rollout duration.
+	ot.canaryWindow = desc.GetCanaryWindowSize()
+
 	// Synthesize any check constraints for user defined types.
 	var synthesizedChecks []optCheckConstraint
 	if ot.rlsEnabled {
@@ -1630,6 +1636,11 @@ func (ot *optTable) IsRowLevelSecurityEnabled() bool { return ot.rlsEnabled }
 // IsRowLevelSecurityForced is part of the cat.Table interface.
 func (ot *optTable) IsRowLevelSecurityForced() bool { return ot.rlsForced }
 
+// CanaryWindowSize is part of the cat.Table interface.
+func (ot *optTable) CanaryWindowSize() time.Duration {
+	return ot.canaryWindow
+}
+
 // Policies is part of the cat.Table interface.
 func (ot *optTable) Policies() *cat.Policies {
 	if !ot.rlsEnabled {
@@ -2777,6 +2788,12 @@ func (ot *optVirtualTable) IsRowLevelSecurityEnabled() bool { return false }
 // IsRowLevelSecurityForced is part of the cat.Table interface.
 func (ot *optVirtualTable) IsRowLevelSecurityForced() bool { return false }
 
+// CanaryWindowSize is part of the cat.Table interface.
+// TODO: think about the actual number.
+func (ot *optVirtualTable) CanaryWindowSize() time.Duration {
+	return 0
+}
+
 // Policies is part of the cat.Table interface.
 func (ot *optVirtualTable) Policies() *cat.Policies { return nil }