sstable, db: document SeekPrefixGE for sstable and level iters

[RaduBerinde]

This is an attempt to document the current semantics as they are currently implemented.

Also see the discussions in #3845

I hope to be looking at a way to resolve some of these complexities, perhaps by adding more tombstone-related logic in the merging iterator (postponing seeks instead of seeking beyond the prefix just to enact a levelIter positioning suitable for a subsequent try-seek-using-next).

[cockroach-teamcity]

This change is 

[sumeerbhola]

@sumeerbhola reviewed 2 files and all commit messages, and made 4 comments.
Reviewable status: all files reviewed, 3 unresolved discussions (waiting on @jbowens and @RaduBerinde).

---

sstable/reader_iter_single_lvl.go line 874 at r1 (raw file):

// key is greater than or equal to the iterator's current position. When set,
// the iterator may optimize by scanning forward from its current position
// rather than performing a full seek. This optimization is automatically

nit: worth saying that the optimization is disabled by the callee (i.e., it ignores the flag in this case).

---

level_iter.go line 713 at r1 (raw file):

// The prefix argument is passed to each file's iterator for bloom filter
// checking. If a file's bloom filter indicates that prefix is not present, that
// file is skipped. The key argument is used for the actual seek positioning.

consider elaborating:
... is skipped, and the iterator moves to the next file if and only if the next file also can contain the prefix.

---

level_iter.go line 725 at r1 (raw file):

// higher level may cover all keys with prefix P1, requiring the merging
// iterator to seek past the tombstone to a key with prefix P3 > P1. In this
// case, the merging iterator calls SeekPrefixGE(P1, keyWithPrefixP3, flags).

this could clarify that keyWithPrefixP3 is the end key of the RANGEDEL.

[RaduBerinde]

TFTR!

@jbowens let me know if there is anything to add. This still hurts my head haha

@RaduBerinde made 3 comments and resolved 1 discussion.
Reviewable status: 0 of 2 files reviewed, 2 unresolved discussions (waiting on @jbowens and @sumeerbhola).

---

level_iter.go line 713 at r1 (raw file):

Previously, sumeerbhola wrote…

consider elaborating:
... is skipped, and the iterator moves to the next file if and only if the next file also can contain the prefix.

Done.

---

level_iter.go line 725 at r1 (raw file):

Previously, sumeerbhola wrote…

this could clarify that keyWithPrefixP3 is the end key of the RANGEDEL.

Reworded with a more specific example, PTAL

[jbowens]

@jbowens reviewed 1 file and all commit messages, and made 1 comment.
Reviewable status: 1 of 2 files reviewed, 2 unresolved discussions (waiting on @sumeerbhola).

[RaduBerinde]

TFTRs!