Range scans

Scan a collection

records, err := db.Scan(ctx, "users", zeedb.ScanOptions{
    Start: []byte("1000"),
    End:   []byte("2000"),
    Limit: 100,
})
if err != nil {
    return err
}

Keys are arbitrary byte strings, compared lexicographically. Numeric-looking string keys are not ordered numerically: 10 sorts before 2.

Start is inclusive; End is exclusive. A nil end is unbounded. An explicit empty end produces an empty range. A negative limit or a start greater than an explicit end is invalid.

Consistent results

A scan holds a shared lock while merging matching memtable keys with the ordered SSTable index. It returns the newest visible live record for each key and suppresses tombstones.

All records in one scan reflect a consistent committed database state. Returned byte slices belong to the caller.

Record and byte budgets

Limit: 0 selects MaxScanRecords, which defaults to 1000. A positive limit cannot exceed the configured maximum.

The default MaxScanBytes is 8 MiB under the record accounting model. If the byte budget is exceeded, the operation returns ErrLimit with no partial result. Reduce the record limit and retry. A single record may itself exceed a configured scan byte budget.

Contexts are checked while scanning. Lock waits and OS file reads cannot be interrupted by cancellation.

Pagination

To resume strictly after the last returned key, append a zero byte to that key:

lastKey := records[len(records)-1].Key // only when the page is nonempty
nextStart := append(append([]byte(nil), lastKey...), 0)

Use nextStart as the next inclusive Start. Appending a zero byte is a valid exclusive-successor boundary for arbitrary byte strings. If it exceeds MaxKeyBytes, instead increment the rightmost byte of the original key that is not 0xff and truncate after that byte. If every byte is 0xff, there is no greater valid key. Do not pass an oversized boundary to Scan.

Each page is a separate snapshot. Intervening writes may change later pages; the API does not provide a multi-page persistent snapshot. If your application needs a stable export, coordinate writes externally until a dedicated snapshot/backup API exists.