Sequence: Builder to avoid intermediate EF representation (#19552)

We knowing `count` in-advance. Means:
- or directly write to rebased EF
- or directly write to SimpleSeq

```
  ┌────────┬──────────────────────┬───────────────────────┐
  │        │       Builder        │         Merge         │
  ├────────┼──────────────────────┼───────────────────────┤
  │ time   │ 5.5µs → 1.8µs (−67%) │ 16.7µs → 9.0µs (−46%) │
  ├────────┼──────────────────────┼───────────────────────┤
  │ memory │ 1896B → 696B (−63%)  │ 3117B → 1175B (−63%)  │
  ├────────┼──────────────────────┼───────────────────────┤
  │ allocs │ 9 → 6 (−33%)         │ 10 → 7 (−30%)         │
  └────────┴──────────────────────┴───────────────────────┘
```

Author: AskAlexSharov

db/recsplit/multiencseq/sequence_builder.go

@@ -29,8 +29,10 @@ const SIMPLE_SEQUENCE_MAX_THRESHOLD = 16
 //
 // This is the "writer" counterpart of SequenceReader.
 type SequenceBuilder struct {
-	baseNum uint64
-	ef      *eliasfano32.EliasFano
+	baseNum    uint64
+	smallBuf   [SIMPLE_SEQUENCE_MAX_THRESHOLD]uint32 // rebased values for simple encoding (count <= 16)
+	smallCount uint8
+	rebasedEf  *eliasfano32.EliasFano // direct rebased EF for large sequences (count > 16)
 }
 
 // Creates a new builder. The builder is not meant to be reused. The construction
@@ -47,67 +49,48 @@ type SequenceBuilder struct {
 // count: this is the number of elements in the sequence, used in case of elias fano
 // maxOffset: this is maximum value in the sequence, used in case of elias fano
 func NewBuilder(baseNum, count, maxOffset uint64) *SequenceBuilder {
-	return &SequenceBuilder{
-		baseNum: baseNum,
-		ef:      eliasfano32.NewEliasFano(count, maxOffset),
+	if count > SIMPLE_SEQUENCE_MAX_THRESHOLD {
+		// For large sequences, target rebased EF directly. AddOffset subtracts baseNum
+		// on the fly, so AppendBytes can serialize without a second pass.
+		return &SequenceBuilder{
+			baseNum:   baseNum,
+			rebasedEf: eliasfano32.NewEliasFano(count, maxOffset-baseNum),
+		}
 	}
+	return &SequenceBuilder{baseNum: baseNum}
 }
 
 func (b *SequenceBuilder) AddOffset(offset uint64) {
-	// TODO: write offset already subtracting baseNum now that PlainEF is gone
-	b.ef.AddOffset(offset)
+	if b.rebasedEf != nil {
+		b.rebasedEf.AddOffset(offset - b.baseNum)
+		return
+	}
+	b.smallBuf[b.smallCount] = uint32(offset - b.baseNum)
+	b.smallCount++
 }
 
 func (b *SequenceBuilder) Build() {
-	b.ef.Build()
+	if b.rebasedEf != nil {
+		b.rebasedEf.Build()
+	}
 }
 
 func (b *SequenceBuilder) AppendBytes(buf []byte) []byte {
-	if b.ef.Count() <= SIMPLE_SEQUENCE_MAX_THRESHOLD {
-		return b.simpleEncoding(buf)
+	if b.rebasedEf != nil {
+		buf = append(buf, byte(RebasedEliasFano))
+		return b.rebasedEf.AppendBytes(buf)
 	}
-
-	return b.rebasedEliasFano(buf)
+	return b.simpleEncoding(buf)
 }
 
 func (b *SequenceBuilder) simpleEncoding(buf []byte) []byte {
 	// Simple encoding type + size: [0x80, 0x8F]
-	count := b.ef.Count()
-	enc := byte(count-1) & byte(0b00001111)
-	enc |= byte(SimpleEncoding)
+	enc := (b.smallCount-1)&0x0F | byte(SimpleEncoding)
 	buf = append(buf, enc)
 
-	// Encode elems
-	var bn [4]byte
-	for it := b.ef.Iterator(); it.HasNext(); {
-		n, err := it.Next()
-		if err != nil {
-			// TODO: err
-			panic(err)
-		}
-		n -= b.baseNum
-
-		binary.BigEndian.PutUint32(bn[:], uint32(n))
-		buf = append(buf, bn[:]...)
+	for _, v := range b.smallBuf[:b.smallCount] {
+		buf = binary.BigEndian.AppendUint32(buf, v)
 	}
 
 	return buf
 }
-
-func (b *SequenceBuilder) rebasedEliasFano(buf []byte) []byte {
-	// Reserved encoding type 0x90 == rebased elias fano
-	buf = append(buf, byte(RebasedEliasFano))
-
-	// Rebased ef
-	rbef := eliasfano32.NewEliasFano(b.ef.Count(), b.ef.Max()-b.baseNum)
-	for it := b.ef.Iterator(); it.HasNext(); {
-		n, err := it.Next()
-		if err != nil {
-			panic(err)
-		}
-
-		rbef.AddOffset(n - b.baseNum)
-	}
-	rbef.Build()
-	return rbef.AppendBytes(buf)
-}

db/recsplit/multiencseq/sequence_builder_test.go

@@ -101,3 +101,77 @@ func TestMultiEncodingSeqBuilder(t *testing.T) {
 		}
 	})
 }
+
+func BenchmarkBuilder(b *testing.B) {
+	const baseNum = 1_000_000
+	const n = 500
+
+	vals := make([]uint64, n)
+	for i := range vals {
+		vals[i] = baseNum + uint64(i)*2
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		sb := NewBuilder(baseNum, n, vals[n-1])
+		for _, v := range vals {
+			sb.AddOffset(v)
+		}
+		sb.Build()
+		_ = sb.AppendBytes(nil)
+	}
+}
+
+// TestBuilderRoundTrip verifies that serialized output can be read back correctly via
+// SequenceReader for both encoding paths, including the direct-rebased-EF path (count > 16).
+func TestBuilderRoundTrip(t *testing.T) {
+	check := func(t *testing.T, baseNum uint64, vals []uint64) {
+		t.Helper()
+		raw := buildTestSeq(baseNum, vals...)
+		s := ReadMultiEncSeq(baseNum, raw)
+		require.Equal(t, uint64(len(vals)), s.Count())
+		require.Equal(t, vals[0], s.Min())
+		require.Equal(t, vals[len(vals)-1], s.Max())
+		for i, want := range vals {
+			require.Equal(t, want, s.Get(uint64(i)), "index %d", i)
+		}
+		var it SequenceIterator
+		it.Reset(s, 0)
+		for i := 0; it.HasNext(); i++ {
+			v, err := it.Next()
+			require.NoError(t, err)
+			require.Equal(t, vals[i], v, "iterator index %d", i)
+		}
+	}
+
+	t.Run("boundary: 16 elements uses simple encoding", func(t *testing.T) {
+		vals := make([]uint64, 16)
+		for i := range vals {
+			vals[i] = 5000 + uint64(i)*3
+		}
+		raw := buildTestSeq(5000, vals...)
+		require.Equal(t, byte(SimpleEncoding)|15, raw[0])
+		check(t, 5000, vals)
+	})
+
+	t.Run("boundary: 17 elements uses rebased EF", func(t *testing.T) {
+		vals := make([]uint64, 17)
+		for i := range vals {
+			vals[i] = 5000 + uint64(i)*3
+		}
+		raw := buildTestSeq(5000, vals...)
+		require.Equal(t, byte(RebasedEliasFano), raw[0])
+		check(t, 5000, vals)
+	})
+
+	t.Run("large sequence with high baseNum", func(t *testing.T) {
+		const baseNum = 1_000_000_000
+		vals := make([]uint64, 100)
+		for i := range vals {
+			vals[i] = baseNum + uint64(i)*7
+		}
+		raw := buildTestSeq(baseNum, vals...)
+		require.Equal(t, byte(RebasedEliasFano), raw[0])
+		check(t, baseNum, vals)
+	})
+}

db/recsplit/multiencseq/sequence_reader.go

@@ -195,7 +195,7 @@ func (s *SequenceReader) ReverseIterator(v int) stream.U64 {
 }
 
 // Merge merges the other sequence into this one, returning a built SequenceBuilder
-// with outBaseNum. Both sequences must be pre-sorted.
+// with outBaseNum. Both sequences must be pre-sorted with s.Max() <= other.Min().
 // Call AppendBytes on the result to serialize.
 func (s *SequenceReader) Merge(other *SequenceReader, outBaseNum uint64, it1, it2 *SequenceIterator) (*SequenceBuilder, error) {
 	it1.Reset(s, 0)

db/recsplit/multiencseq/sequence_reader_test.go

@@ -9,6 +9,15 @@ import (
 	"github.com/erigontech/erigon/db/recsplit/simpleseq"
 )
 
+func buildTestSeq(baseNum uint64, vals ...uint64) []byte {
+	b := NewBuilder(baseNum, uint64(len(vals)), vals[len(vals)-1])
+	for _, v := range vals {
+		b.AddOffset(v)
+	}
+	b.Build()
+	return b.AppendBytes(nil)
+}
+
 func TestMultiEncSeq(t *testing.T) {
 
 	t.Run("plain elias fano", func(t *testing.T) {
@@ -112,6 +121,174 @@ func TestMultiEncSeq(t *testing.T) {
 	})
 }
 
+func TestMerge(t *testing.T) {
+	t.Run("small sequences (simple encoding path)", func(t *testing.T) {
+		// 3 + 3 = 6 elements: stays within SIMPLE_SEQUENCE_MAX_THRESHOLD
+		s1 := ReadMultiEncSeq(1000, buildTestSeq(1000, 1001, 1003, 1005))
+		s2 := ReadMultiEncSeq(1000, buildTestSeq(1000, 1007, 1009, 1011))
+
+		var it1, it2 SequenceIterator
+		merged, err := s1.Merge(s2, 1000, &it1, &it2)
+		require.NoError(t, err)
+
+		out := merged.AppendBytes(nil)
+		result := ReadMultiEncSeq(1000, out)
+		require.Equal(t, uint64(6), result.Count())
+		require.Equal(t, uint64(1001), result.Min())
+		require.Equal(t, uint64(1011), result.Max())
+		for i, want := range []uint64{1001, 1003, 1005, 1007, 1009, 1011} {
+			require.Equal(t, want, result.Get(uint64(i)))
+		}
+	})
+
+	t.Run("large sequences (rebased EF fast path)", func(t *testing.T) {
+		// 10 + 10 = 20 elements: exceeds SIMPLE_SEQUENCE_MAX_THRESHOLD
+		vals1 := make([]uint64, 10)
+		vals2 := make([]uint64, 10)
+		for i := range vals1 {
+			vals1[i] = 1000 + uint64(i)*2
+			vals2[i] = 1020 + uint64(i)*2
+		}
+		s1 := ReadMultiEncSeq(1000, buildTestSeq(1000, vals1...))
+		s2 := ReadMultiEncSeq(1000, buildTestSeq(1000, vals2...))
+
+		var it1, it2 SequenceIterator
+		merged, err := s1.Merge(s2, 1000, &it1, &it2)
+		require.NoError(t, err)
+
+		out := merged.AppendBytes(nil)
+		require.Equal(t, byte(RebasedEliasFano), out[0], "expected rebased EF encoding")
+
+		result := ReadMultiEncSeq(1000, out)
+		require.Equal(t, uint64(20), result.Count())
+		require.Equal(t, uint64(1000), result.Min())
+		require.Equal(t, uint64(1038), result.Max())
+		for i := uint64(0); i < 20; i++ {
+			require.Equal(t, 1000+i*2, result.Get(i))
+		}
+	})
+}
+
+func TestMergeEncodingBoundary(t *testing.T) {
+	merge := func(baseNum uint64, raw1, raw2 []byte) []byte {
+		s1 := ReadMultiEncSeq(baseNum, raw1)
+		s2 := ReadMultiEncSeq(baseNum, raw2)
+		var it1, it2 SequenceIterator
+		merged, err := s1.Merge(s2, baseNum, &it1, &it2)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return merged.AppendBytes(nil)
+	}
+
+	// 8+8=16: must stay simple encoding
+	raw16 := merge(1000,
+		buildTestSeq(1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008),
+		buildTestSeq(1000, 1009, 1010, 1011, 1012, 1013, 1014, 1015, 1016),
+	)
+	require.Equal(t, byte(SimpleEncoding)|15, raw16[0], "8+8=16 must use simple encoding")
+
+	// 8+9=17: must flip to rebased EF
+	raw17 := merge(1000,
+		buildTestSeq(1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008),
+		buildTestSeq(1000, 1009, 1010, 1011, 1012, 1013, 1014, 1015, 1016, 1017),
+	)
+	require.Equal(t, byte(RebasedEliasFano), raw17[0], "8+9=17 must use rebased EF")
+}
+
+func TestMergeSeek(t *testing.T) {
+	// merge two large sequences so output uses rebased EF
+	vals1 := make([]uint64, 10)
+	vals2 := make([]uint64, 10)
+	for i := range vals1 {
+		vals1[i] = 1000 + uint64(i)*2 // 1000,1002,...,1018
+		vals2[i] = 1020 + uint64(i)*2 // 1020,1022,...,1038
+	}
+	s1 := ReadMultiEncSeq(1000, buildTestSeq(1000, vals1...))
+	s2 := ReadMultiEncSeq(1000, buildTestSeq(1000, vals2...))
+	var it1, it2 SequenceIterator
+	merged, err := s1.Merge(s2, 1000, &it1, &it2)
+	require.NoError(t, err)
+	result := ReadMultiEncSeq(1000, merged.AppendBytes(nil))
+
+	// Seek to existing value
+	n, ok := result.Seek(1010)
+	require.True(t, ok)
+	require.Equal(t, uint64(1010), n)
+
+	// Seek to gap — returns next
+	n, ok = result.Seek(1011)
+	require.True(t, ok)
+	require.Equal(t, uint64(1012), n)
+
+	// Seek past end
+	_, ok = result.Seek(1039)
+	require.False(t, ok)
+
+	// Has
+	require.True(t, result.Has(1020))
+	require.False(t, result.Has(1021))
+}
+
+func TestBuilderFreeFunctions(t *testing.T) {
+	const baseNum = uint64(5000)
+	vals := []uint64{5003, 5007, 5015}
+	b := NewBuilder(baseNum, uint64(len(vals)), vals[len(vals)-1])
+	for _, v := range vals {
+		b.AddOffset(v)
+	}
+	b.Build()
+	raw := b.AppendBytes(nil)
+
+	require.Equal(t, uint64(3), Count(baseNum, raw))
+
+	n, ok := Seek(baseNum, raw, 5006)
+	require.True(t, ok)
+	require.Equal(t, uint64(5007), n)
+
+	n, ok = Seek(baseNum, raw, 5007)
+	require.True(t, ok)
+	require.Equal(t, uint64(5007), n)
+
+	_, ok = Seek(baseNum, raw, 5016)
+	require.False(t, ok)
+}
+
+func BenchmarkMerge(b *testing.B) {
+	const baseNum = 1_000_000
+	const n = 500 // elements per sequence
+
+	raw1 := func() []byte {
+		sb := NewBuilder(baseNum, n, baseNum+n*2-2)
+		for i := uint64(0); i < n; i++ {
+			sb.AddOffset(baseNum + i*2)
+		}
+		sb.Build()
+		return sb.AppendBytes(nil)
+	}()
+	raw2 := func() []byte {
+		sb := NewBuilder(baseNum, n, baseNum+n*2+n*2-2)
+		for i := uint64(0); i < n; i++ {
+			sb.AddOffset(baseNum + n*2 + i*2)
+		}
+		sb.Build()
+		return sb.AppendBytes(nil)
+	}()
+
+	var s1, s2 SequenceReader
+	var it1, it2 SequenceIterator
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		s1.Reset(baseNum, raw1)
+		s2.Reset(baseNum, raw2)
+		merged, err := s1.Merge(&s2, baseNum, &it1, &it2)
+		if err != nil {
+			b.Fatal(err)
+		}
+		_ = merged.AppendBytes(nil)
+	}
+}
+
 func requireSequenceChecks(t *testing.T, s *SequenceReader) {
 	t.Helper()