storage: add IterOptions.RangeKeyMaskingBelow

This patch adds an iterator option `RangeKeyMaskingBelow`, which will
cause range keys at or below the given timestamp to mask any point
keys below them.

Release note: None

pkg/storage/engine.go

@@ -341,6 +341,17 @@ type IterOptions struct {
 	// MVCCIterators from them. Range key behavior for EngineIterators is
 	// undefined.
 	KeyTypes IterKeyType
+	// RangeKeyMaskingBelow enables masking (hiding) of point keys by range keys.
+	// Any range key with a timestamp at or below the RangeKeyMaskingBelow
+	// timestamp will mask point keys below it, preventing them from being
+	// surfaced. Consider the following example:
+	//
+	// 4          o---------------o    RangeKeyMaskingBelow=4 emits b3
+	// 3      b3      d3               RangeKeyMaskingBelow=3 emits b3,d3,f2
+	// 2  o---------------o   f2       RangeKeyMaskingBelow=2 emits b3,d3,f2
+	// 1  a1  b1          o-------o    RangeKeyMaskingBelow=1 emits a1,b3,b1,d3,f2
+	//    a   b   c   d   e   f   g
+	RangeKeyMaskingBelow hlc.Timestamp
 }
 
 // IterKeyType configures which types of keys an iterator should surface.

pkg/storage/engine_test.go

@@ -2043,8 +2043,9 @@ func TestEngineRangeKeysUnsupported(t *testing.T) {
 				require.False(t, r.SupportsRangeKeys())
 
 				iter := r.NewMVCCIterator(MVCCKeyAndIntentsIterKind, IterOptions{
-					KeyTypes:   keyType,
-					UpperBound: keys.MaxKey,
+					KeyTypes:             keyType,
+					UpperBound:           keys.MaxKey,
+					RangeKeyMaskingBelow: hlc.Timestamp{WallTime: 1}, // should disable when unsupported
 				})
 				defer iter.Close()
 

pkg/storage/mvcc_history_test.go

@@ -70,7 +70,7 @@ import (
 // put_rangekey   k=<key> end=<key> ts=<int>[,<int>]
 // scan           [t=<name>] [ts=<int>[,<int>]] [resolve [status=<txnstatus>]] k=<key> [end=<key>] [inconsistent] [tombstones] [reverse] [failOnMoreRecent] [localUncertaintyLimit=<int>[,<int>]] [globalUncertaintyLimit=<int>[,<int>]] [max=<max>] [targetbytes=<target>] [avoidExcess] [allowEmpty]
 //
-// iter           [k=<key>] [end=<key>] [kind=key|keyAndIntents] [types=pointsOnly|pointsWithRanges|pointsAndRanges|rangesOnly]
+// iter           [k=<key>] [end=<key>] [kind=key|keyAndIntents] [types=pointsOnly|pointsWithRanges|pointsAndRanges|rangesOnly] [maskBelow=<int>[,<int>]]
 // iter_seek_ge   k=<key> [ts=<int>[,<int>]]
 // iter_seek_lt   k=<key> [ts=<int>[,<int>]]
 // iter_seek_intent_ge k=<key> txn=<name>
@@ -972,6 +972,9 @@ func cmdIterNew(e *evalCtx) error {
 			return errors.Errorf("unknown key type %s", arg)
 		}
 	}
+	if e.hasArg("maskBelow") {
+		opts.RangeKeyMaskingBelow = e.getTsWithName(nil, "maskBelow")
+	}
 
 	var r, closeReader Reader
 	rType := util.ConstantWithMetamorphicTestChoice(

pkg/storage/pebble_iterator.go

@@ -18,6 +18,7 @@ import (
 	"github.com/cockroachdb/cockroach/pkg/keys"
 	"github.com/cockroachdb/cockroach/pkg/roachpb"
 	"github.com/cockroachdb/cockroach/pkg/storage/enginepb"
+	"github.com/cockroachdb/cockroach/pkg/util/hlc"
 	"github.com/cockroachdb/cockroach/pkg/util/protoutil"
 	"github.com/cockroachdb/cockroach/pkg/util/uuid"
 	"github.com/cockroachdb/errors"
@@ -159,6 +160,7 @@ func (p *pebbleIterator) setOptions(opts IterOptions, durability DurabilityRequi
 			opts.UpperBound = []byte{0}
 		}
 		opts.KeyTypes = IterKeyTypePointsOnly
+		opts.RangeKeyMaskingBelow = hlc.Timestamp{}
 	}
 
 	// Generate new Pebble iterator options.
@@ -168,6 +170,10 @@ func (p *pebbleIterator) setOptions(opts IterOptions, durability DurabilityRequi
 	newOptions := pebble.IterOptions{
 		OnlyReadGuaranteedDurable: durability == GuaranteedDurability,
 		KeyTypes:                  opts.KeyTypes,
+		RangeKeyMasking: pebble.RangeKeyMasking{
+			// TODO(erikgrinaker): Consider reusing a buffer if necessary.
+			Suffix: EncodeMVCCTimestampSuffix(opts.RangeKeyMaskingBelow),
+		},
 	}
 
 	newBuf := 1 - p.curBuf
@@ -236,6 +242,7 @@ func (p *pebbleIterator) setOptions(opts IterOptions, durability DurabilityRequi
 		newOptions.KeyTypes != p.options.KeyTypes ||
 		!bytes.Equal(newOptions.UpperBound, p.options.UpperBound) ||
 		!bytes.Equal(newOptions.LowerBound, p.options.LowerBound) ||
+		!bytes.Equal(newOptions.RangeKeyMasking.Suffix, p.options.RangeKeyMasking.Suffix) ||
 		// We can't compare these filters, so if any existing or new filters are set
 		// we consider them changed.
 		newOptions.TableFilter != nil || p.options.TableFilter != nil ||