sstable: introduce Attributes bitset field for Reader

This commit introduces the bitset type `Attributes` to track which features are
in use in an sstable. The field is derived from the sstable properties on Reader
creation.

Initially, we include the following attributes:
- AttributeValueBlocks
- AttributeRangeKeySets
- AttributeRangeKeyUnsets
- AttributeRangeKeyDels
- AttributeRangeDels
- AttributeBlobValues

Closes: #4557

Author: xinhaoz

external_iterator.go

@@ -310,7 +310,7 @@ func openExternalTables(
 		if err != nil {
 			return readers, err
 		}
-		if r.Properties.NumValuesInBlobFiles > 0 {
+		if r.Attributes.Has(sstable.AttributeBlobValues) {
 			return readers, errors.Newf("pebble: NewExternalIter does not support blob references")
 		}
 		readers = append(readers, r)

file_cache.go

@@ -759,7 +759,7 @@ func newRangeKeyIter(
 	// file's range key blocks may surface deleted range keys below. This is
 	// done here, rather than deferring to the block-property collector in order
 	// to maintain parity with point keys and the treatment of RANGEDELs.
-	if r.Properties.NumRangeKeyDels == 0 && len(opts.RangeKeyFilters) > 0 {
+	if !r.Attributes.Has(sstable.AttributeRangeKeyDels) && len(opts.RangeKeyFilters) > 0 {
 		ok, _, err := checkAndIntersectFilters(r, opts.RangeKeyFilters, nil, transforms.SyntheticSuffix())
 		if err != nil {
 			return nil, err

internal/problemspans/doc.go

@@ -10,7 +10,7 @@
 // This package is designed for efficiently tracking key ranges that may need
 // special handling.
 //
-// Key Features:
+// Key Attributes:
 //
 //   - **Span Registration:**
 //     Add spans with specified expiration times so that they automatically

sstable/attributes.go

@@ -0,0 +1,62 @@
+// Copyright 2025 The LevelDB-Go and Pebble Authors. All rights reserved. Use
+// of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
+
+package sstable
+
+import "strings"
+
+// Attributes is a bitset containing features in use in an sstable.
+type Attributes uint32
+
+const (
+	AttributeValueBlocks Attributes = 1 << iota
+	AttributeRangeKeySets
+	AttributeRangeKeyUnsets
+	AttributeRangeKeyDels
+	AttributeRangeDels
+	AttributeTwoLevelIndex
+	AttributeBlobValues
+)
+
+// Intersects checks if any bits in attr are set in a.
+func (a Attributes) Intersects(attr Attributes) bool {
+	return a&attr != 0
+}
+
+// Has checks if all bits in attr are set in a.
+func (a Attributes) Has(attr Attributes) bool {
+	return a&attr == attr
+}
+
+// Add sets the bits in attr to a.
+func (a *Attributes) Add(attr Attributes) {
+	*a = *a | attr
+}
+
+// String converts the Attributes fs to a string representation for testing.
+func (a Attributes) String() string {
+	var attributes []string
+	if a.Has(AttributeValueBlocks) {
+		attributes = append(attributes, "ValueBlocks")
+	}
+	if a.Has(AttributeRangeKeySets) {
+		attributes = append(attributes, "RangeKeySets")
+	}
+	if a.Has(AttributeRangeKeyUnsets) {
+		attributes = append(attributes, "RangeKeyUnsets")
+	}
+	if a.Has(AttributeRangeKeyDels) {
+		attributes = append(attributes, "RangeKeyDels")
+	}
+	if a.Has(AttributeRangeDels) {
+		attributes = append(attributes, "RangeDels")
+	}
+	if a.Has(AttributeTwoLevelIndex) {
+		attributes = append(attributes, "TwoLevelIndex")
+	}
+	if a.Has(AttributeBlobValues) {
+		attributes = append(attributes, "BlobValues")
+	}
+	return "[" + strings.Join(attributes, ",") + "]"
+}

sstable/copier.go

@@ -8,7 +8,6 @@ import (
 	"context"
 
 	"github.com/cockroachdb/errors"
-	"github.com/cockroachdb/pebble/internal/base"
 	"github.com/cockroachdb/pebble/internal/bytealloc"
 	"github.com/cockroachdb/pebble/objstorage"
 	"github.com/cockroachdb/pebble/objstorage/objstorageprovider"
@@ -51,7 +50,8 @@ func CopySpan(
 ) (size uint64, _ error) {
 	defer func() { _ = input.Close() }()
 
-	if r.Properties.NumValueBlocks > 0 || r.Properties.NumRangeKeys() > 0 || r.Properties.NumRangeDeletions > 0 {
+	const unsupportedCopyFeatures = AttributeValueBlocks | AttributeRangeKeySets | AttributeRangeKeyUnsets | AttributeRangeKeyDels | AttributeRangeDels
+	if r.Attributes.Intersects(unsupportedCopyFeatures) {
 		return copyWholeFileBecauseOfUnsupportedFeature(ctx, input, output) // Finishes/Aborts output.
 	}
 
@@ -77,11 +77,6 @@ func CopySpan(
 		}
 	}()
 
-	if r.Properties.NumValueBlocks > 0 || r.Properties.NumRangeKeys() > 0 || r.Properties.NumRangeDeletions > 0 {
-		// We just checked for these conditions above.
-		return 0, base.AssertionFailedf("cannot CopySpan sstables with value blocks or range keys")
-	}
-
 	var preallocRH objstorageprovider.PreallocatedReadHandle
 	// ReadBeforeForIndexAndFilter attempts to read the top-level index, filter
 	// and lower-level index blocks with one read.
@@ -224,7 +219,7 @@ func intersectingIndexEntries(
 		if err != nil {
 			return nil, err
 		}
-		if r.Properties.IndexType != twoLevelIndex {
+		if !r.Attributes.Has(AttributeTwoLevelIndex) {
 			entry := indexEntry{bh: bh, sep: top.Separator()}
 			alloc, entry.bh.Props = alloc.Copy(entry.bh.Props)
 			alloc, entry.sep = alloc.Copy(entry.sep)

sstable/reader.go

@@ -65,6 +65,7 @@ type Reader struct {
 
 	Properties  Properties
 	tableFormat TableFormat
+	Attributes  Attributes
 }
 
 type ReadEnv struct {
@@ -130,7 +131,7 @@ func (r *Reader) newPointIter(ctx context.Context, opts IterOptions) (Iterator,
 	// until the final iterator closes.
 	var res Iterator
 	var err error
-	if r.Properties.IndexType == twoLevelIndex {
+	if r.Attributes.Has(AttributeTwoLevelIndex) {
 		if r.tableFormat.BlockColumnar() {
 			res, err = newColumnBlockTwoLevelIterator(
 				ctx, r, opts)
@@ -204,7 +205,7 @@ func (r *Reader) newCompactionIter(
 		BlobContext:          blobContext,
 	}
 
-	if r.Properties.IndexType == twoLevelIndex {
+	if r.Attributes.Has(AttributeTwoLevelIndex) {
 		if !r.tableFormat.BlockColumnar() {
 			i, err := newRowBlockTwoLevelIterator(ctx, r, opts)
 			if err != nil {
@@ -897,6 +898,29 @@ func NewReader(ctx context.Context, f objstorage.Readable, o ReaderOptions) (*Re
 		return nil, r.Close()
 	}
 
+	// Set which attributes are in use based on property values.
+	if r.Properties.NumValueBlocks > 0 || r.Properties.NumValuesInValueBlocks > 0 {
+		r.Attributes.Add(AttributeValueBlocks)
+	}
+	if r.Properties.NumRangeKeySets > 0 {
+		r.Attributes.Add(AttributeRangeKeySets)
+	}
+	if r.Properties.NumRangeKeyUnsets > 0 {
+		r.Attributes.Add(AttributeRangeKeyUnsets)
+	}
+	if r.Properties.NumRangeKeyDels > 0 {
+		r.Attributes.Add(AttributeRangeKeyDels)
+	}
+	if r.Properties.NumRangeDeletions > 0 {
+		r.Attributes.Add(AttributeRangeDels)
+	}
+	if r.Properties.IndexType == twoLevelIndex {
+		r.Attributes.Add(AttributeTwoLevelIndex)
+	}
+	if r.Properties.NumValuesInBlobFiles > 0 {
+		r.Attributes.Add(AttributeBlobValues)
+	}
+
 	if r.Properties.ComparerName == "" || o.Comparer.Name == r.Properties.ComparerName {
 		r.Comparer = o.Comparer
 	} else if comparer, ok := o.Comparers[r.Properties.ComparerName]; ok {

sstable/reader_iter_single_lvl.go

@@ -209,7 +209,7 @@ func newColumnBlockSingleLevelIterator(
 	}
 	i := singleLevelIterColumnBlockPool.Get().(*singleLevelIteratorColumnBlocks)
 	i.init(ctx, r, opts)
-	if r.Properties.NumValueBlocks > 0 {
+	if r.Attributes.Has(AttributeValueBlocks) {
 		i.internalValueConstructor.vbReader = valblk.MakeReader(i, opts.ReaderProvider, r.valueBIH, opts.Env.Block.Stats)
 		i.vbRH = r.blockReader.UsePreallocatedReadHandle(objstorage.NoReadBefore, &i.vbRHPrealloc)
 	}
@@ -244,7 +244,7 @@ func newRowBlockSingleLevelIterator(
 	i := singleLevelIterRowBlockPool.Get().(*singleLevelIteratorRowBlocks)
 	i.init(ctx, r, opts)
 	if r.tableFormat >= TableFormatPebblev3 {
-		if r.Properties.NumValueBlocks > 0 {
+		if r.Attributes.Has(AttributeValueBlocks) {
 			i.internalValueConstructor.vbReader = valblk.MakeReader(i, opts.ReaderProvider, r.valueBIH, opts.Env.Block.Stats)
 			// We can set the GetLazyValuer directly to the vbReader because
 			// rowblk sstables never contain blob value handles.

sstable/reader_iter_two_lvl.go

@@ -166,7 +166,7 @@ func newColumnBlockTwoLevelIterator(
 	i.useFilterBlock = i.secondLevel.useFilterBlock
 	i.secondLevel.useFilterBlock = false
 
-	if r.Properties.NumValueBlocks > 0 {
+	if r.Attributes.Has(AttributeValueBlocks) {
 		// NB: we cannot avoid this ~248 byte allocation, since valueBlockReader
 		// can outlive the singleLevelIterator due to be being embedded in a
 		// LazyValue. This consumes ~2% in microbenchmark CPU profiles, but we
@@ -215,7 +215,7 @@ func newRowBlockTwoLevelIterator(
 	i.secondLevel.useFilterBlock = false
 
 	if r.tableFormat >= TableFormatPebblev3 {
-		if r.Properties.NumValueBlocks > 0 {
+		if r.Attributes.Has(AttributeValueBlocks) {
 			// NB: we cannot avoid this ~248 byte allocation, since valueBlockReader
 			// can outlive the singleLevelIterator due to be being embedded in a
 			// LazyValue. This consumes ~2% in microbenchmark CPU profiles, but we

sstable/reader_test.go

@@ -558,6 +558,18 @@ func TestReaderWithBlockPropertyFilter(t *testing.T) {
 		})
 }
 
+func TestReaderAttributes(t *testing.T) {
+	defer leaktest.AfterTest(t)()
+	opts := WriterOptions{
+		// Use format supporting blob handles.
+		TableFormat:    TableFormatPebblev6,
+		BlockSize:      math.MaxInt32,
+		IndexBlockSize: math.MaxInt32,
+		Comparer:       testkeys.Comparer,
+	}
+	runTestReader(t, opts, "testdata/reader_attributes", nil /* Reader */, false)
+}
+
 func TestInjectedErrors(t *testing.T) {
 	defer leaktest.AfterTest(t)()
 	for _, fixture := range TestFixtures {
@@ -702,11 +714,12 @@ func runTestReader(t *testing.T, o WriterOptions, dir string, r *Reader, printVa
 					r = nil
 				}
 				var cacheSize int
-				var printLayout bool
+				var printLayout, printAttributes bool
 				d.MaybeScanArgs(t, "cache-size", &cacheSize)
 				d.MaybeScanArgs(t, "print-layout", &printLayout)
 				d.MaybeScanArgs(t, "block-size", &o.BlockSize)
 				d.MaybeScanArgs(t, "index-block-size", &o.IndexBlockSize)
+				d.MaybeScanArgs(t, "print-attributes", &printAttributes)
 
 				closeCache()
 				c = cache.New(int64(cacheSize))
@@ -716,10 +729,15 @@ func runTestReader(t *testing.T, o WriterOptions, dir string, r *Reader, printVa
 				if err != nil {
 					return err.Error()
 				}
+				var buf bytes.Buffer
 				if printLayout {
-					return indexLayoutString(t, r)
+					buf.WriteString(indexLayoutString(t, r))
 				}
-				return ""
+				if printAttributes {
+					buf.WriteString("attributes: ")
+					buf.WriteString(r.Attributes.String())
+				}
+				return buf.String()
 
 			case "iter":
 				var globalSeqNum uint64

sstable/suffix_rewriter.go

@@ -87,7 +87,7 @@ func rewriteKeySuffixesInBlocks(
 	switch {
 	case concurrency < 1:
 		return nil, TableFormatUnspecified, errors.New("concurrency must be >= 1")
-	case r.Properties.NumValueBlocks > 0 || r.Properties.NumValuesInValueBlocks > 0:
+	case r.Attributes.Has(AttributeValueBlocks):
 		return nil, TableFormatUnspecified,
 			errors.New("sstable with a single suffix should not have value blocks")
 	case r.Properties.ComparerName != o.Comparer.Name:
@@ -308,7 +308,7 @@ func RewriteKeySuffixesViaWriter(
 	if o.Comparer == nil || o.Comparer.Split == nil {
 		return nil, errors.New("a valid splitter is required to rewrite suffixes")
 	}
-	if r.Properties.NumValuesInBlobFiles > 0 {
+	if r.Attributes.Has(AttributeBlobValues) {
 		return nil, errors.New("cannot rewrite suffixes of sstable with blob values")
 	}