Skip to content

Replace the trie index format - #15534

Open
zaidoon1 wants to merge 6 commits into
meta:mainfrom
zaidoon1:zaidoon/udi-12-trie-index-v2
Open

zaidoon1 wants to merge 6 commits into
meta:mainfrom
zaidoon1:zaidoon/udi-12-trie-index-v2

Conversation

@zaidoon1

@zaidoon1 zaidoon1 commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

This replaces the on-disk format of the experimental trie index (TrieIndexFactory). The LOUDS format is deleted outright, with no format option or migration path. As far as I know nobody uses it.

Why not keep LOUDS

The point of the trie was an index smaller than the standard one, and LOUDS never got there. On every key shape I tried it was 1.3x to 2.7x bigger than the standard index even at restart interval 1, and Get was up to 2x slower. Most of the bytes go to per-edge child position tables, which also get copied to the heap when the SST opens, and to a seqno table that's written whether it's needed or not.

It also has bugs:

  • an empty user key as a block separator gets dropped, so the flush fails with Corruption and writes stop (in kStandardDefault the trie is silently skipped instead)
  • a data block offset or size past 4 GiB fails the flush or compaction with NotSupported, in every mode
  • DB::Open accepts a non-bytewise comparator, and then every flush fails
  • a block with bad counts but a valid checksum can throw or read out of bounds
  • arrays are stored in host byte order, so big-endian is broken

Fixing those would still leave an index that loses to the standard one, so I replaced the format.

The new format

It's the block-tree layout Lucene and tantivy use. The prefix shared by all separators is stored once. Separators are grouped 8 to a bucket and front coded, and a path-compressed trie over each bucket's first separator sends a Seek to one bucket. Block offsets are stored as a column: each group of 64 is a straight line plus a small correction per offset. Block sizes aren't stored when the gap after every block is the same, which is normally just the block trailer; then a size is the next offset minus this one minus the gap. Two small side tables cover user keys that span several blocks and blocks that need a seqno tag. Everything is little-endian, 64-bit and read in place; the spec is at the top of utilities/trie_index/trie.h.

Opening an index validates the header, the section and column layouts, the side tables and the trie. It doesn't decode every block offset or bucket position. Instead the iterator checks a block's derived size when it lands on the block, keeps bucket reads inside the bucket data, and bounds-checks every entry it decodes, returning Corruption for anything out of bounds. Like the other index blocks, the trie relies on the block checksum for anything subtler.

#14409 turned mmap_read off in the crash test and db_stress because of LOUDS's zero-copy pointers. The new reader also reads its block in place, but the block always outlives it: an mmap'd block points into the table reader's own mapping, and the block cache only stores heap copies. So the exclusion is gone.

TrieIndexFactory::ValidateOptions() rejects non-bytewise comparators, so DB::Open() and CreateColumnFamily() fail up front instead of every flush failing later. SetOptions() doesn't run that validation yet; #15582 fixes that. kStandardOnly ignores the factory, so it still works with any comparator. That applies to every custom factory: its ValidateOptions() now runs only in modes that use it, where before the generic option validation ran it in kStandardOnly too.

The docs also said rolling back from kCustomDefault takes effect immediately. It doesn't: index routing is fixed when a table reader opens, so the docs now say an index_mode change only reaches SSTs opened afterwards. Other doc-only edits: the docs now say when a factory's ValidateOptions() runs, that an SST written in kCustomOnly can't fall back even in kStandardDefault, that the kStandardDefault fallback is logged rather than warned (a missing block logs at WARN, an unreadable one at ERROR), and that a table reader keeps its custom index block pinned in the block cache. That code is unchanged.

One fix is outside the trie and the bug is on main too. When an iterator left a MultiScan, for example with SeekToLast(), BlockBasedTableIterator put the custom index iterator back with the scan ranges still set, so the trie kept stopping at the old limit and a plain scan returned too few keys. Prepare() now drops the index iterator's ranges as soon as it has collected the block handles, with Prepare(nullptr), which reaches a custom index as Prepare(nullptr, 0); index_factory.h documents that this drops the ranges.

How to read this diff

You can skip the deleted louds_trie.* and bitvector.*.

  1. Overview: the comments at the top of utilities/trie_index/trie.h (the format) and trie_index_factory.h (how RocksDB uses it).
  2. Columns: "Column" in the trie.h overview, then AppendColumn, Trie::Column::Init and Trie::Column::Get in trie.cc.
  3. Trie nodes and buckets: "Trie node" and "Bucket data" in the overview, then TrieWriter and TrieIterator::Node.
  4. Builder: TrieBuilder::AddBlock, TrieBuilder::Finish and SizeBound.
  5. Validation: Trie::Parse, ValidateSideTables and ValidateTrie.
  6. Iterator: the TrieIterator class comment walks through a Seek. Then Seek, Descend, SpellHead, ScanBucket, EnterSeparator, ApplyTag, NextSeparator and Prev.
  7. RocksDB adapter: trie_index_factory.{h,cc}, mainly BlockTag, PrepareAddEntry and FinishAddEntry (the serial AddIndexEntry runs both), and ValidateOptions.
  8. Options, docs and tests: block_based_table_factory.cc, block_based_table_iterator.cc and user_defined_index_wrapper.h (the MultiScan fix), include/rocksdb/index_factory.h, include/rocksdb/table.h, docs/components/index_factory/index.md, the release note, trie_index_test.cc and trie_index_db_test.cc.

Compatibility

This is a one-way door for any DB that writes SSTs with the trie. DBs without TrieIndexFactory, or running kStandardOnly, aren't affected. The block keeps the old magic but bumps the version to 2.

  • Upgrading: an old trie block fails with NotSupported, and the message says what to do. In kStandardDefault the SST falls back to the standard index; the other modes fail to open it. Run kStandardDefault and compact before switching. SSTs that 11.14 writes in kCustomOnly have no standard index, so no mode can open them after the upgrade; rewrite them in another mode first.
  • Downgrading: older releases reject the new blocks with Corruption. 11.14 falls back to the standard index in kStandardDefault; 11.13 and earlier can't open the new SSTs in any mode while the factory is configured. Remove the factory first.

The release note covers this.

Numbers

Isolated index

Release db_bench on an Apple Silicon laptop, single thread. 3M keys per shape, 100-byte values, no compression, 4 KiB blocks, format_version 8, 10-bit bloom, everything in the block cache. Each variant is written with SstFileWriter from the same sorted keys and ingested, so the data blocks are identical and only the index differs. Medians of 3 rounds in random order; anything under about 3% is noise.

Shapes: rand16 is 16 random bytes, uuid a textual UUIDv4, url reversed host + path + id, tsdb series id + tag hash + timestamp, and dbint db_bench's --key_size=48 --prefix_size=32 --keys_per_prefix=100.

rand16 uuid url tsdb dbint
index B/block, restart 1 15.0 17.6 28.7 25.8 44.1
index B/block, restart 16 5.4 6.2 9.8 6.5 16.0
index B/block, trie 4.4 5.3 9.1 5.5 17.0
Get us/op, restart 1 1.412 1.637 1.752 1.494 1.619
Get us/op, restart 16 1.493 1.685 1.834 1.472 1.641
Get us/op, trie 1.346 1.612 1.704 1.422 1.607
Seek+10 us/op, restart 1 2.704 2.752 3.212 2.639 2.780
Seek+10 us/op, restart 16 2.654 2.802 3.343 2.660 2.777
Seek+10 us/op, trie 2.449 2.686 3.241 2.502 2.689
reverse Seek+10 us/op, restart 1 3.611 3.877 4.695 3.551 3.924
reverse Seek+10 us/op, restart 16 3.680 3.945 4.914 3.646 3.905
reverse Seek+10 us/op, trie 3.539 3.892 4.766 3.584 3.856
build CPU s, restart 1 0.245 0.574 0.609 0.236 0.263
build CPU s, restart 16 0.242 0.580 0.614 0.234 0.259
build CPU s, trie 0.244 0.585 0.615 0.237 0.259

So it's about the size of restart 16 with lookups as fast as restart 1 or better, and reverse seeks and build time are a wash. Where it doesn't win:

  • the trie block isn't compressed, so with compression on, files were up to 0.6% bigger than restart 16
  • it's 6% bigger than restart 16 on dbint, and 3-5% bigger on long URL-like keys with 16 KiB blocks
  • full scans are 0-3% slower than restart 1
  • opening a table still costs more with the trie than without it (see below)

Through the DB

Release db_bench on the same laptop: fillrandom of 20M keys with 16-byte keys, 100-byte values, LZ4, 4 KiB blocks, 16 MiB target files and 10-bit bloom, then reads on the resulting DB (56 SSTs over L0-L2) with an 8 GiB block cache warmed by readseq. Writes are the median of 2 runs, everything else of 3.

write no trie kStandardDefault kCustomOnly
fillrandom us/op 2.422 2.508 2.429
flush s 4.6 4.7 4.6
compaction s 14.9 15.3 15.0
compaction CPU s 13.9 14.3 14.0
SST MiB 934 952 933

The two no-trie runs were 5% apart, so only the compaction CPU of building both indexes in kStandardDefault (about 3%) looks real.

read, us/op standard index (mode 1) trie (mode 2)
readrandom 1.604 1.557
seekrandom, 10 nexts 7.205 6.709
reverse seekrandom, 10 nexts 10.289 9.612

Table open: Trie::Init() used to decode every block offset and the whole bucket table, which was about two thirds of its time. Those checks moved into the iterator, and Init on a 14.8K-block index went from 26-28 us to 5-8 us; most of what's left is the trie walk. With --open_files=20, which leaves room for 10 table readers, most Gets reopen a table:

readrandom, open_files=20, us/op no trie mode 1 mode 2
this PR 88.5 96.7 94.9
before the open-time change 108.5 108.6

So under table cache churn the trie adds about 7 us per Get, down from about 20 us. DB::Open() of the 56-SST DB took 25-27 ms in every variant; at that size, loading tables on 16 threads is lost in the noise.

Testing

  • trie_index_test (98 tests), trie_index_db_test (280) and table_test pass, also with ASSERT_STATUS_CHECKED=1. By area:
    • Seek, Next and Prev against a model: RandomizedRunsTagsAndSizes, which also re-seeks through key(), plus SeekToOwnKey and SeekToResultKey for a Seek to the key the iterator just returned or to bytes inside it
    • format and corruption: GoldenBytes, RejectsOtherVersions, MalformedIndexIsRejectedOrReadable, NewReaderWithCorruptedData
    • runs and tags: LargeRun, MixedSameKeyRuns, TagsRandomized
    • large handles and the size estimate: BlockHandlesPast32Bits, EstimatedSizeBoundsSerializedTrie, EstimatedSizeBoundsExtremeHandles, ParallelMatchesSerialOutput
    • through the DB: EmptyUserKey, OpenRejectsNonBytewiseComparator, StandardOnlyIgnoresTrieComparatorRequirement, OtherTrieVersionFallsBackOrFails (an old-version block in every mode, including an SST written in kCustomOnly, which no mode can open), MmapReads (trie reads with allow_mmap_reads across table cache evictions, compaction and reopen), and IteratorAfterMultiScanIgnoresScanRanges (a full scan after SeekToLast() leaves a MultiScan)
    • the crash test's block size choice: test_trie_block_size_draw in db_crashtest_test.py
  • A corruption fuzzer under ASAN/UBSAN (byte flips, planted 32/64-bit values, truncation) ran 22M cases clean, 7.2M of which opened.
  • db_crashtest.py blackbox --simple --use_trie_index=1 --mmap_read=1 ran 15 minutes each in index modes 1 and 3, with mmap on in all 32 invocations.

@meta-cla meta-cla Bot added the CLA Signed label Oct 31, 2026
@github-actions

github-actions Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

⚠️ clang-tidy: 9 warning(s) on changed lines

Completed in 9970.6s.

Summary by check

Check Count
cppcoreguidelines-avoid-non-const-global-variables 1
cppcoreguidelines-pro-type-member-init 1
performance-inefficient-string-concatenation 4
performance-inefficient-vector-operation 3
Total 9

Details

db/c.cc (1 warning(s))
db/c.cc:918:3: warning: constructor does not initialize these fields: state_, destructor_, compare_, name_, compare_ts_, compare_without_ts_ [cppcoreguidelines-pro-type-member-init]
db/db_impl/db_impl_secondary.cc (2 warning(s))
db/db_impl/db_impl_secondary.cc:2136:65: warning: string concatenation results in allocation of unnecessary temporary strings; consider using 'operator+=' or 'string::append()' instead [performance-inefficient-string-concatenation]
db/db_impl/db_impl_secondary.cc:2137:77: warning: string concatenation results in allocation of unnecessary temporary strings; consider using 'operator+=' or 'string::append()' instead [performance-inefficient-string-concatenation]
db_stress_tool/db_stress_structured_key_value.cc (1 warning(s))
db_stress_tool/db_stress_structured_key_value.cc:19:27: warning: variable 'structured_kv_ctx' is non-const and globally accessible, consider making it const [cppcoreguidelines-avoid-non-const-global-variables]
db_stress_tool/db_stress_structured_key_value_test.cc (1 warning(s))
db_stress_tool/db_stress_structured_key_value_test.cc:49:5: warning: 'push_back' is called inside a loop; consider pre-allocating the container capacity before the loop [performance-inefficient-vector-operation]
utilities/backup/backup_engine.cc (2 warning(s))
utilities/backup/backup_engine.cc:1843:7: warning: string concatenation results in allocation of unnecessary temporary strings; consider using 'operator+=' or 'string::append()' instead [performance-inefficient-string-concatenation]
utilities/backup/backup_engine.cc:1852:7: warning: string concatenation results in allocation of unnecessary temporary strings; consider using 'operator+=' or 'string::append()' instead [performance-inefficient-string-concatenation]
utilities/trie_index/trie_index_test.cc (2 warning(s))
utilities/trie_index/trie_index_test.cc:296:5: warning: 'push_back' is called inside a loop; consider pre-allocating the container capacity before the loop [performance-inefficient-vector-operation]
utilities/trie_index/trie_index_test.cc:321:5: warning: 'push_back' is called inside a loop; consider pre-allocating the container capacity before the loop [performance-inefficient-vector-operation]

@zaidoon1
zaidoon1 force-pushed the zaidoon/udi-12-trie-index-v2 branch 2 times, most recently from cd9b272 to a4d2c11 Compare October 31, 2026 17:47
@github-actions

github-actions Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

Claude Code Review - OBSOLETE

Superseded by a newer AI review. Expand to see the original review.

✅ Claude Code Review

Auto-triggered after CI passed — reviewing commit a4d2c11


Summary

This PR adds trie index format 2 (path-compressed trie over front-coded buckets with frame-of-reference columns) and fixes several correctness bugs in format 1 (empty user key handling, malformed block validation, memory accounting). The changes are well-structured and the bug fixes are sound. I identified 3 HIGH and 5 MEDIUM findings, none of which are blockers -- the HIGHs are existing bugs that this PR correctly fixes.

High-severity findings (3):

  • H1: ApproximateAuxMemoryUsage() underreports heap memory by omitting overflow_base_, aligned_copy_, and chain vectors -- correctly fixed by this PR
  • H2: overflow_base_ prefix sum uses uint32_t running_sum which could silently wrap on crafted input -- correctly fixed by this PR (changed to uint64_t with early overflow check)
  • H3: InitFromData() does not reject unknown flags, allowing silent misinterpretation of future format extensions -- correctly fixed by this PR
Full review (click to expand)

Findings

🔴 HIGH

H1: ApproximateAuxMemoryUsage() underreports memory (existing bug, fixed by PR)

louds_trie.h:280-283 currently only counts s_child_start_pos_ and s_child_end_pos_. The PR correctly adds overflow_base_, aligned_copy_, and chain-related vectors (s_chain_suffix_offsets_, s_chain_lens_, s_chain_end_child_idx_). This fix is important because ApproximateMemoryUsage() feeds into block cache accounting via TrieIndexReader::ApproximateMemoryUsage() at trie_index_factory.cc:683.

H2: overflow_base_ prefix sum overflow (existing bug, fixed by PR)

At louds_trie.cc:1486, the current uint32_t running_sum could silently wrap to 0 if total overflow blocks exceed UINT32_MAX. While unlikely with legitimate data (kMaxReasonableKeys caps at 2^30), a malformed trie with large block_counts could trigger this. The PR changes to uint64_t running_sum with early overflow checking during accumulation -- correct fix.

H3: No unknown flags rejection (existing bug, fixed by PR)

Current InitFromData() at louds_trie.cc:1088 reads the flags field but does not reject unknown bits. A trie written by a future version with new flag bits would be silently read with incorrect interpretation. The PR adds if (flags & ~kKnownFlags) rejection -- correct forward-compatibility measure.

🔶 MEDIUM

M1: TrieIndexBuilder constructor signature change adds defaulted parameter

Per CLAUDE.md, defaulted parameters are the "#1 trap on refactoring." The change from explicit TrieIndexBuilder(const Comparator*) to TrieIndexBuilder(const Comparator*, int format_version = 1) means existing callers silently get format 1, but a future caller who forgets the parameter gets unexpected behavior. Consider making format_version explicit (no default) since the factory always knows the version.

M2: Format version dispatch asymmetry (write vs. read)

TrieIndexFactory takes format_version to control writing, but NewReader dispatches on the version in the serialized header. This is architecturally correct (any reader handles any version), but the factory's format_version member is ignored during reads. This should be documented to prevent confusion -- the factory's format_version is write-only configuration.

M3: TrieScanBounds extraction must preserve exact CheckBounds semantics

The extraction of scan bound checking from TrieIndexIterator::CheckBounds into a shared TrieScanBounds helper must preserve the exact reference_key semantics: for Seek, reference_key = seek target; for Next, reference_key = previous separator. The conservative bound check (comparing reference_key, not current separator, against limit) is subtle and must not be altered. Verify that TrieV2IndexIterator passes the same reference_key as TrieIndexIterator in each call site.

M4: db_crashtest.py module-level random choices reduce per-invocation coverage diversity

_USE_TRIE_INDEX and _INDEX_MODE are drawn once at module level, fixing them for the entire test run. This is documented as intentional, but it means a single crash test invocation exercises only one configuration. The trie_index_format_version and read_index randomized per invocation partially compensate.

M5: Relaxed atomics in TrackHandle are correct but deserve a comment

max_block_step_, max_block_size_, and irregular_block_gaps_ use std::memory_order_relaxed for cross-thread size estimation during parallel compression. This is correct because: (1) these are approximate estimates, (2) they're read-only after the parallel phase completes (serialized Finish() runs single-threaded). A brief comment noting the ordering rationale would help future readers.

⚪ LOW / OBSERVATIONS

L1: Empty key fix is correct

The cutoff_level_=1 when max_depth_==0 ensures the root becomes a dense node, which is required for prefix key emission. The level > 0 guard on skip-pure-leaf prevents the root from being incorrectly skipped. The DescendToRightmostLeaf fix handles the case where root has a prefix key but no labels by checking d_is_prefix_key_ before attempting label traversal. Test coverage for empty keys should include: (a) single empty key, (b) empty key + non-empty keys, (c) seek to empty key, (d) reverse iteration from first non-empty key to empty key.

L2: ValidateStructure() performance is documented and acceptable

~200us per SST open is well within tolerance. The validation runs once per SST open for format 1 indexes and catches structural corruption that would otherwise cause silent wrong results or crashes during read operations.

L3: Format 2 portability improvement

Format 2 uses DecodeFixed32/64 (little-endian reads) instead of format 1's host-byte-order memcpy. This makes format 2 portable to big-endian architectures (e.g., s390x). Format 1's host-byte-order limitation is pre-existing and documented.

L4: num_chains bounded by num_internal in InitFromData

Good defense-in-depth. Prevents crafted input from causing oversized vector allocations that could OOM the process during SST open.

Cross-Component Analysis

  • DB Mutex impact: None. Trie code executes during SST build (table builder, no mutex) and SST open (table reader, no mutex). No path through DBImpl::mutex_ is affected.
  • Alternative execution contexts: WritePreparedTxnDB, ReadOnly DB, and SecondaryDB all use the standard table reader path. The trie index integrates through IndexFactory SPI, so these contexts are transparent.
  • Block cache interaction: ApproximateMemoryUsage() fix (H1) directly affects cache charge accounting. The fix correctly includes all heap allocations.

Test Coverage Assessment

The PR should include tests for:

  1. Empty key round-trip (build trie with empty key, verify Seek/Next/Prev)
  2. ValidateStructure() with crafted malformed tries (corrupt node counts, invalid child positions)
  3. ValidateDerivedData() with corrupted rank LUT / select hints
  4. Format 2 round-trip (build with format 2, read back, verify correctness)
  5. Format version cross-compatibility (write format 1, read with format 2 factory; write format 2, read with format 1 factory)
  6. ApproximateAuxMemoryUsage() includes all vectors
  7. TrieScanBounds semantic equivalence with inline CheckBounds

Behavioral Compatibility

No breaking behavioral changes for existing users:

  • Format 1 remains the default
  • Existing SST files continue to be read correctly
  • The use_udi_as_primary_index -> index_mode change affects only db_stress tooling, not the production API
  • Format 2 is opt-in via format_version=2 on the factory

ℹ️ About this response

Generated by Claude Code.
Review methodology: claude_md/ci_review_prompt.md

Limitations:

  • Claude may miss context from files not in the diff
  • Large PRs may be truncated
  • Always apply human judgment to AI suggestions

Commands:

  • /claude-review [context] — Request a code review
  • /claude-query <question> — Ask about the PR or codebase

@zaidoon1
zaidoon1 force-pushed the zaidoon/udi-12-trie-index-v2 branch from a4d2c11 to 30ff02b Compare November 2, 2026 21:05
@zaidoon1 zaidoon1 changed the title Add trie index format 2 and fix format 1 bugs Replace the trie index format Nov 2, 2026
@zaidoon1
zaidoon1 force-pushed the zaidoon/udi-12-trie-index-v2 branch 2 times, most recently from 339b04d to 5942de8 Compare November 4, 2026 02:22
@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Claude Code Review - OBSOLETE

Superseded by a newer AI review. Expand to see the original review.

✅ Claude Code Review

Auto-triggered after CI passed — reviewing commit 5942de8


Summary

This is a well-structured replacement of the experimental LOUDS trie index with a new block-tree format. The changes are comprehensive: build system updates, public API documentation, validation flow improvements, crash test coverage, and release notes. The approach of keeping the same magic but bumping the version field to detect incompatible formats is sound.

High-severity findings (1):

  • [trie_index_factory.h] The TrieIndexFactory class visible in the current codebase lacks a ValidateOptions() override, yet BlockBasedTableFactory::ValidateOptions() now calls factory->ValidateOptions(). If the new trie_index_factory.h (in the truncated part of the diff) does not add this override, the comparator check at DB::Open time will silently pass (base Configurable::ValidateOptions() returns OK), and the error would only surface at NewBuilder() / first flush time.
Full review (click to expand)

Findings

🔴 HIGH

H1. Missing ValidateOptions() override on TrieIndexFactory — trie_index_factory.h
  • Issue: The diff adds a new validation pathway where BlockBasedTableFactory::ValidateOptions() calls factory->ValidateOptions(db_opts, cf_opts) in non-kStandardOnly modes (block_based_table_factory.cc:833-843). However, the current TrieIndexFactory class (trie_index_factory.h:334-350) has no ValidateOptions() override. The base class Configurable::ValidateOptions() returns Status::OK() by default. Without an override that checks for BytewiseComparator, DB::Open would succeed with a non-bytewise comparator, and the error would only be caught at NewBuilder() time (first flush), which is the exact behavior the PR claims to fix.
  • Root cause: The truncated diff likely adds this override in the new version of trie_index_factory.h, but since it's not visible in the provided diff, this is flagged for explicit verification.
  • Suggested fix: Ensure the new trie_index_factory.h includes:
    Status ValidateOptions(const DBOptions& db_opts,
                           const ColumnFamilyOptions& cf_opts) const override;
    with an implementation that rejects cf_opts.comparator != BytewiseComparator().

🟡 MEDIUM

M1. SetValidateFunc bypass may surprise future maintainers — block_based_table_factory.cc:421-432
  • Issue: The PR adds a SetValidateFunc that unconditionally returns OK for user_defined_index_factory, bypassing the automatic per-option Configurable::ValidateOptions() call that OptionTypeInfo::Validate() would normally make (options_helper.cc:1782-1784). This is correct for the stated goal (kStandardOnly should not validate the factory), but the pattern is subtle: a reader seeing AsCustomSharedPtr<IndexFactory> might expect standard Configurable validation to apply.
  • Root cause: The Configurable validation framework doesn't have a notion of "validate only in certain modes" — it validates unconditionally. The workaround is to disable automatic validation and do it explicitly in BlockBasedTableFactory::ValidateOptions().
  • Suggested fix: The code comment in the diff ("BlockBasedTableFactory::ValidateOptions() validates the factory only in the index modes that use it") is necessary and sufficient. Consider adding a similar note at the ValidateOptions() call site to cross-reference back.
M2. has_unsupported_handle_ still enforces 32-bit limit — trie_index_factory.cc:142,164,364
  • Issue: The PR description says the new format "supports data blocks past 4 GiB in an SST," and the release note says so too. However, trie_index_factory.cc still checks handle.offset > UINT32_MAX || handle.size > UINT32_MAX (lines 142-143 and 364-365) and returns NotSupported in Finish() (line 164-167). The header comment in trie_index_factory.h (lines 33-38) also documents the 32-bit limit. If the new format supports 64-bit offsets, these checks and comments need updating.
  • Root cause: The truncated diff may include updates to trie_index_factory.cc that remove these checks (the diff modifies this file), but since those changes aren't visible, this is flagged.
  • Suggested fix: Verify the new trie_index_factory.cc either removes the has_unsupported_handle_ check entirely (if the new format supports 64-bit) or documents why it's retained despite the format supporting it.
M3. Documentation says "64-bit offsets and sizes" but code may still enforce 32-bit — docs/components/index_factory/index.md
  • Issue: The docs change removes the "32-bit integer" warning and the text about UINT32_MAX limitations. The PR description says "64-bit offsets and sizes." But if has_unsupported_handle_ still enforces 32-bit in the builder (M2), the documentation is inaccurate.
  • Suggested fix: Align documentation with actual code behavior. Either remove the limit or document it.
M4. Release note for udi_validation_and_cache_statistics.md removes 32-bit text — unreleased_history/behavior_changes/udi_validation_and_cache_statistics.md
  • Issue: The release note edit removes the paragraph about NotSupported for offsets/sizes exceeding UINT32_MAX. If this limit is actually lifted, the removal is correct. If not (see M2), the release note should retain a version of this text.
  • Suggested fix: Verify consistency with actual code.

🟢 LOW / NIT

L1. index_factory.h example string change — include/rocksdb/index_factory.h:363
  • Issue: The comment changes the example from "trie" to "trie_index". This is correct — the registered name is TrieIndexFactory::kClassName() which returns "trie_index". Good fix.
L2. Documentation terminology change "warn" → "log" — docs/components/index_factory/index.md
  • Issue: The mode table changes "warn, fall back to standard" to "log, fall back to standard" for kStandardDefault missing/unusable custom block. This is a precision improvement — the behavior is a log message, not a warning-level alert. Appropriate change.
L3. Crash test block_size may be overridden — tools/db_crashtest.py
  • Issue: The new block_size = random.choice([1024, 4096, 16384]) for use_trie_index=1 (inserted around line 1652) can be overridden later at line 2203 (block_size = 1024 for the auto_readahead_size case). This is not a bug — the readahead case just always uses 1024, which is already in the trie's list — but it means the trie won't always get its random block size diversity.
  • Suggested fix: No action needed; the override happens rarely (1/4 probability with specific conditions).
L4. db_bench_tool.cc description simplification — tools/db_bench_tool.cc:773
  • Issue: The use_trie_index flag description is simplified from mentioning "LOUDS-encoded succinct trie" to just "trie from separator keys." Appropriate since the LOUDS format is removed.

Cross-Component Analysis

Context Affected? Assessment
WritePreparedTxnDB No Trie index operates at block-level, not key-level visibility
ReadOnly DB No Reader-only, no builder involvement
CompactionService Potentially If remote compaction builds SSTs with trie, the new format must be serializable
User-defined timestamps No Explicitly rejected by existing check + new ValidateOptions
MemPurge No Trie index is for SST files only
BlobDB No Trie indexes data blocks, not blob files
FIFO / Universal compaction No Index format is independent of compaction style
Prefix seek No Trie operates on full keys, prefix is handled by data iterator
SetOptions Indirectly index_mode change through SetOptions only affects newly opened SSTs — now documented

DB Mutex Analysis

The changed code paths (ValidateOptions, factory registration, crash test parameters) do not execute while DBImpl::mutex_ is held. ValidateOptions runs during DB::Open before the mutex is typically contested. No DB mutex impact.

Positive Observations

  • Well-structured compatibility story: Version field bump with same magic, clear upgrade/downgrade paths documented in release notes.
  • Crash test block_size diversification: Good insight that 16 KiB blocks produce too few separators for meaningful trie testing.
  • SetValidateFunc pattern: Clean separation of per-option validation (bypassed) vs. explicit mode-aware validation in ValidateOptions. This correctly handles kStandardOnly ignoring the factory.
  • Documentation update for SetOptions routing: The clarification that "index routing is fixed when a table reader opens" is an important correction of prior documentation that implied immediate effect.
  • Release notes: Appropriately detailed for a behavior change with compatibility impact, without being overly verbose.

ℹ️ About this response

Generated by Claude Code.
Review methodology: claude_md/ci_review_prompt.md

Limitations:

  • Claude may miss context from files not in the diff
  • Large PRs may be truncated
  • Always apply human judgment to AI suggestions

Commands:

  • /claude-review [context] — Request a code review
  • /claude-query <question> — Ask about the PR or codebase

@zaidoon1
zaidoon1 force-pushed the zaidoon/udi-12-trie-index-v2 branch 2 times, most recently from 0a8e540 to f6c034c Compare November 4, 2026 05:54
The LOUDS trie index was larger than the standard index on every key
shape tried, and up to 2x slower on Get. Replace it with a block-tree
layout: a shared prefix, front-coded buckets of 8 separators, a
path-compressed trie over the bucket heads, and frame-of-reference
offset columns.

The old format has no known users, so it is removed rather than kept
readable. Its blocks fail the version check, and earlier releases
reject the new blocks the same way.

The new builder stores the empty user key and 64-bit block handles.
Opening an index checks everything but the separators inside buckets,
whose bounds are checked as they are decoded, and bounds the key length
an iterator reserves. DB::Open now rejects a non-bytewise comparator
except in kStandardOnly, which ignores the factory:
BlockBasedTableFactory calls the factory's ValidateOptions() only in
the modes that use it.

Also correct the rollback text in table.h and the IndexFactory doc: an
index_mode change through SetOptions() only reaches SSTs opened
afterwards. When the trie is on and no block size is given, the crash
test now draws smaller block sizes, so its SSTs have enough separators
to reach multi-bucket tries and user keys that span blocks.
@zaidoon1
zaidoon1 force-pushed the zaidoon/udi-12-trie-index-v2 branch from f6c034c to 4be1067 Compare November 4, 2026 08:08
@meta-codesync

meta-codesync Bot commented Nov 4, 2026

Copy link
Copy Markdown

@xingbowang has imported this pull request. If you are a Meta employee, you can view this in D129647129.

@pdillinger pdillinger left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Old trie blocks: NotSupported rather than Corruption

utilities/trie_index/trie.cc, Trie::Parse():

  if (DecodeFixed32(p + kVersionPos) != kVersion) {
    return Corrupt("unsupported format version");
  }

A version-1 block isn't corrupt; it's a valid block in a format this release no longer reads. The status matters for anyone upgrading in a mode that requires the trie. That includes users who never set index_mode: GetEffectiveIndexMode() maps the legacy use_udi_as_primary_index to kCustomDefault and fail_if_no_udi_on_open to kStandardRequired. In those modes the table open fails, and with max_open_files=-1 so does DB::Open(), with a status that operators and automation can reasonably read as data corruption (e.g. restore from backup) rather than "change an option and compact".

Suggest returning NotSupported for a recognized magic with an unrecognized version, with a message that says what to do, e.g.:

  const uint32_t version = DecodeFixed32(p + kVersionPos);
  if (version != kVersion) {
    return Status::NotSupported(
        "Trie index: format version " + std::to_string(version) +
        " is not readable by this release; open with "
        "index_mode=kStandardDefault and compact to rewrite the trie");
  }

kStandardDefault behavior is unchanged: the fallback in BlockBasedTable::Open() already treats IsNotSupported() like IsCorruption(). And the advice is always actionable: as far as I can tell, no released version writes trie SSTs without a full standard index (stub-only writing came with #14963, which isn't in a release branch), so every old SST is readable through kStandardDefault.

TrieTest.RejectsOtherVersions could then assert the status code, and a DB-level test could cover an old-version block falling back in kStandardDefault and failing with NotSupported in kCustomDefault. The summary's "each version rejects the other's blocks with Corruption" would need updating for the new-reads-old direction.


Write, read, and table open benchmarks through the DB

The numbers in the summary isolate the index nicely (identical data blocks via SstFileWriter + ingest, everything cached), but they don't show the end-to-end cost on the normal write and read paths, or the cost of opening a table reader. I'd like to see db_bench runs along these lines:

Write: fillrandom (or fillseq + overwrite) with normal flush and compaction, comparing

  • --use_trie_index=0 (baseline)
  • --use_trie_index=1 --index_mode=1 (kStandardDefault: both indexes built, the rollout mode)
  • --use_trie_index=1 --index_mode=3 (kCustomOnly: trie only)

reporting throughput and flush/compaction time or CPU.

Read: on the resulting multi-level DB (--use_existing_db=1), readrandom, seekrandom with --seek_nexts, and a reverse scan (readreverse or seekrandom --reverse_iterator=1), comparing --index_mode=1 vs --index_mode=2 (kCustomDefault).

Table open: every table reader open reads the trie block, and Trie::Init() validates it in full: every block offset is decoded and checked, along with the bucket table, the side tables, and a walk of the whole trie. That is linear in the number of blocks in the SST, and unlike the standard index with cache_index_and_filter_blocks=true, the custom index is loaded eagerly at open. By the summary's own numbers it adds roughly 20-30 us per 64 MiB SST over restart 16. That cost is paid by DB::Open() with max_open_files=-1, on every table cache miss with a bounded max_open_files, and for each new flush or compaction output. Please include DB open time on a DB with many SSTs, and readrandom with a small --open_files so table readers are reopened. If it shows up, the per-block offset check looks like the main candidate: as far as I can tell it exists only so that derived block sizes cannot wrap, which could instead be checked where value() derives the size.


tools/db_crashtest.py: is the mmap_read=0 exclusion still needed?

finalize_and_sanitize() still forces mmap_read=0 with the trie:

        # Trie UDI uses zero-copy pointers into block data, which is
        # incompatible with mmap_read.
        dest_params["mmap_read"] = 0

The new format is read in place with unaligned loads, at any alignment. What is the remaining incompatibility with mmap_read? If it no longer applies, the exclusion can go and the crash test regains mmap_read coverage with the trie; if it does, the comment should say why.

@zaidoon1

zaidoon1 commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Thanks, this was useful. Everything is addressed in 74fe042, and the summary is updated.

Old trie blocks: NotSupported

Done, with your message. The version is now checked right after the magic and before the header size, so a block whose format has a shorter header still gets NotSupported. RejectsOtherVersions asserts the code. TrieIndexDBTest.OtherTrieVersionFallsBackOrFails writes SSTs whose trie block says version 1: kStandardDefault reads them through the standard index and counts the load failure, while kStandardRequired and kCustomDefault fail DB::Open() with NotSupported.

One correction to the reasoning: 11.14.fb was cut today (3f56cbf) and it contains #14963. So 11.14.0 will be able to write version-1 tries into kCustomOnly SSTs, which have only the stub standard index. After this PR, nothing can read those files. The release note now tells users to rewrite them in another mode before upgrading. If you'd rather 11.14.0 not ship that state, picking this PR into 11.14.fb before the tag would avoid it.

Benchmarks

They're in the summary under "Through the DB". In short: on a 56-SST LZ4 DB, Get through the trie was 3% faster than through the standard index, and Seek with 10 nexts was 7% faster in both directions. fillrandom throughput was within noise in all three modes. Building both indexes in kStandardDefault cost about 3% more compaction CPU, and kCustomOnly matched the baseline without the trie.

Open time

It showed up, and the offset check was the main cost, as you guessed. On a 14.8K-block index it took about 14-18 us of Init's 25-28 us, and the bucket table loop took another 2-4 us. Both are gone from Init:

  • The iterator now reads the block handle when it lands on a block, and returns Corruption if a derived size would wrap. value() became a plain return, so there are no extra column reads.
  • A bucket position is clamped to the bucket data, where every entry is already bounds-checked.

Init on that index went from 26-28 us to 5-8 us; most of what's left is the trie walk. With --open_files=20 (10 table readers for 56 SSTs), the trie's cost per readrandom Get, over not loading it at all, dropped from about 20 us to about 7 us. Opening that DB took 25-27 ms in every variant, so the difference doesn't show at that size.

mmap_read

The exclusion no longer applies, so it's gone from db_crashtest.py and db_stress. The trie keeps pointers into its block, but the block outlives the reader. An mmap'd block is copied to the heap before it goes into the block cache. Otherwise it stays uncached and points into the table reader's own mapping.

TrieIndexDBTest.MmapReads reads through the trie with allow_mmap_reads across table cache evictions, compaction and reopen, with the index cached and uncached, in all three modes. The crash test with --mmap_read=1 ran clean for 15 minutes each in modes 1 and 3.

I also couldn't reproduce a crash on main with the exclusion removed: 10 minutes per mode, about half of it with mmap on. So I can't say what the original failure was.

Release notes

There's now a single new note, in behavior_changes. It covers the format, the upgrade path including the kCustomOnly case, the empty-key fix and the comparator check.

@zaidoon1
zaidoon1 requested a review from pdillinger November 6, 2026 02:47
- A trie block of another version now fails with NotSupported and a
  hint to compact in kStandardDefault, instead of Corruption. The
  version is checked before the header size.
- Init() no longer decodes every block offset or bucket position. The
  iterator reads a block's handle when it lands on it and returns
  Corruption if a derived size would wrap; bucket positions are clamped
  to the bucket data, where every entry is bounds-checked. Init on a
  14.8K-block index goes from 26-28 us to 5-8 us.
- db_crashtest.py and db_stress no longer turn mmap_read off with the
  trie; trie reads are tested with allow_mmap_reads.
- The edits to existing release notes are reverted, and the trie
  changes get a single new note.
@zaidoon1
zaidoon1 force-pushed the zaidoon/udi-12-trie-index-v2 branch from 74fe042 to 607785c Compare November 8, 2026 09:09
@xingbowang

Copy link
Copy Markdown
Contributor

A few minor bugs and some readability improvement suggestions.

  1. utilities/trie_index/trie.cc:1193 (bug)

Re-seeking to the key this iterator just returned lands on the wrong block.

TrieIndexIterator::SetResult() sets result->key = iter_.key(), which points into key_. Here SpellHead() calls key_.resize(prefix_len) and then appends the bucket head. If the seek target is that same result.key, these writes change the target while ScanBucket() still reads it. Then ScanBucket()'s rule "the current separator is always below target" no longer holds.

Example: separators apq, b, bb, c, d, date in one bucket. SeekAndGetResult("bb", &r, ...) works. Then SeekAndGetResult(r.key, &r, ...) returns b (the previous block) instead of bb, with status OK. In a test that re-seeks every separator this way, every re-seek gave a wrong key. The old implementation copied the key into a separate buffer after the seek, so the same test passes there.

RocksDB's own IndexFactoryIteratorWrapper seeks with its own key copy, so normal reads are not affected. But IndexFactoryIterator is a public API, and "re-seek to the current key" is a natural thing for a caller to do.

Suggested fix: in TrieIterator::Seek(), copy the target into a separate member buffer when it points into key_. Or copy it in TrieIndexIterator::SeekAndGetResult(). Regression test: for each block, Seek(sep_i), then Seek(it.key(), tag) and SeekAndGetResult(result.key, ...), and check that the key and handle are unchanged.

  1. unreleased_history/behavior_changes/trie_index_format.md:1 (wrong upgrade advice)

Upgrade advice is wrong for SSTs written in kCustomOnly.

The note says old trie SSTs "fall back to the standard index in kStandardDefault". The PR description says the same. That holds only for SSTs that also have a full standard index. An SST written in kCustomOnly has a stub standard index (standard_index_is_stub), so requires_custom_reader is true and custom_index_required is true even in kStandardDefault (see BlockBasedTable::Open). The version-2 reader rejects the old trie block with Corruption, and there is no fallback.

I checked this with SSTs written by the old code:

SST written in Opened in kStandardDefault
kCustomDefault opens through the standard index
kCustomOnly Corruption: Trie index: unsupported format version

Released versions cannot produce such files, but main-branch users who tried kCustomOnly can. Suggested wording: "SSTs written in kCustomOnly have no standard index and cannot be opened in any mode. Before upgrading, switch to kCustomDefault or kStandardDefault and compact, so every SST has a full standard index."

  1. utilities/trie_index/trie.cc:1073 (Descend) and trie.h:285 (Candidate)

Readability (the hardest part to follow). To understand what a floor or ceiling Candidate holds and how it becomes a key, I had to read 9 places: Spell/Candidate, the Descend declaration, the node format comment, Node::Parse, the Descend body, SpellHead, Seek, NextKey and Prev. depth means slightly different things with and without has_label. Descend is a 117-line loop with the sparse and bitmap child searches inline, so the floor/ceiling logic is hard to see.

Suggestions:

  • Move the sparse/bitmap "find rank, label below, label above" code into a Node method, for example FindChild(c, &rank, &present, &below, &above). Then Descend shows only the floor/ceiling logic.
  • Give Candidate one comment with an example: "A Candidate names a bucket head without storing it. For kTerminal, depth already includes the path of node, and the head is the first depth bytes of the target. For kSmallest and kLargest, the head is the first depth bytes of the target, then label if has_label is true, then the path of node and the nodes below it. kSmallest follows the first child until it reaches a terminal node; kLargest follows the last child until it reaches a leaf. Example: target "abx", and a node reached by "ab" has children 'c' and 'z'. The ceiling is {depth=2, has_label=true, label='z', spell=kSmallest} at child 'z'."
  1. utilities/trie_index/trie.h:25

Readability: "Block sizes are derived from consecutive offsets when the gaps between blocks are uniform." The comment does not say what fills the gap or why it is usually the same, so size_gap (line 46) looks arbitrary. "Frame-of-reference column" is used here but explained only at line 70.

Also, "so there is no file size limit" is a bit too strong: AppendColumn still returns NotSupported when a group's residual range needs more than 56 bits. "No 32-bit limit" would be accurate.

Suggested text: "Block offsets are stored in a column (see "Column" below). In a block-based table each data block is followed by its block trailer, so the distance from the end of one block to the start of the next is normally the same for every block. When it is, the index stores that distance once as size_gap and derives each size from the next offset. When it is not, for example because of block alignment padding, the sizes are stored in their own column."

  1. utilities/trie_index/trie.h:269

Readability: tags. "A block without a tag sorts after every tag of its key." Tag 0 means "no tag", but 0 is also a real packed tag (sequence 0, type 0). The reader has to work out alone why that is safe. Tags are explained in pieces across about 8 places (here, AddBlock, BlockTag, IndexEntryContext, SeekContext, ApplyTag).

Suggestion: one tag paragraph in the overview at the top of this file, and point the other places to it: "A tag is the packed sequence number and value type of an internal key. In internal key order, a larger tag sorts first. Most blocks are found by user key alone and store tag 0. A real tag of 0 is also the smallest tag, so treating 0 as "no tag" gives the same order. A block stores the real tag of its last key only when that user key continues into the next block, when its separator equals the previous block's separator, or when it is the last block (see BlockTag in trie_index_factory.cc)." In ApplyTag (trie.cc:1268): "The run's first block has no tag, so it sorts after every target tag of this key and is the answer."

  1. utilities/trie_index/trie.h:63

Readability: "Run table ... extra_blocks_through". The word "run" is never defined; line 28 says "Blocks that share a separator" without calling that a run. The key formula (block = key_index + extra blocks of earlier runs) is in no comment; it is only in EnterKey's code.

Suggestion: "A run is two or more consecutive blocks that share one separator, which happens when one user key spans several blocks. Each distinct separator has an index (0 to num_keys - 1). The first block of separator k is k + (extra blocks of all runs before k), where a run of n blocks has n - 1 extra blocks." Consider renaming extra_blocks_through to cumulative_extra_blocks.

  1. utilities/trie_index/trie.h:73

Readability: "layout is words << 6 | width: ..." is one long sentence with three ideas. words is a word index but is not called one, and the reason for the 56-bit limit is only in trie.cc.

Suggested text: "layout = (start_word << 6) | width. width is the number of bits per residual in this group, at most 56, so one unaligned 8-byte load and a shift of up to 7 bits read any residual. start_word is where this group's residuals begin, counted in 8-byte words from the start of the residual area. It equals the total size of the residuals of all earlier groups. A group of n values uses ceil(n * width / 64) words."

  1. utilities/trie_index/trie.h:41

Readability: one concept has two names. A distinct separator is called a "key" here (num_keys) and in the iterator (key_index_, EnterKey, NextKey, RunKey). But "key" also means the seek target (Seek(key, ...)) and the user key. While reading ApplyTag and Prev I often had to check which one was meant.

Suggestion: use "separator" in names (num_separators, separator_index_, EnterSeparator, NextSeparator). Or define the word once at the top of the file: "In this file, "key" means a distinct separator, and "key index" is its position among the distinct separators. The seek argument is called the target."

  1. utilities/trie_index/trie.cc:1467

Readability: scratch_.push_back('\0') is not explained, and it is not clear why NextKey goes through the trie when the bucket table could give the next bucket directly.

Suggested comment: "A bucket stores only the separators after its head. The head is spelled from the trie. key + '\0' is the smallest string greater than the current key, so the ceiling for it is the next bucket's head."

  1. utilities/trie_index/trie_index_factory.h:122

Readability: understanding EstimatedSize() and which thread owns which field took me about 11 places. The members are ordered for padding, so the comments point forward ("described below") and back ("above"). estimate_ is a SizeStats whose block fields are unused, while separate atomics hold them, so one concept lives in two places.

Suggestion: group members by owner thread, even if it costs a few bytes of padding, with one comment in front: "Threads. In a parallel build, PrepareAddEntry() and EstimatedSize() run on the emit thread, and FinishAddEntry() runs on the BG writer thread. In a serial build, everything runs on one thread. Emit thread only: estimate_ and previous_prepared_separator_. Writer thread only: trie_builder_, previous_handle_, block_gap_. Written by the writer and read by EstimatedSize(): max_block_step_, max_block_size_, irregular_block_gaps_ (relaxed atomics, because a slightly stale value only changes the estimate)."

  1. utilities/trie_index/trie_index_factory.h:169

Readability (minor): "Finish may upgrade this to true ..." FinishAddEntry never writes same_user_key_initial; it ORs it with SharesPreviousSeparator(). The _initial suffix is also vague.

Suggestion: rename it to same_user_key and write: "True if last_key_in_current_block and first_key_in_next_block have the same user key. FinishAddEntry() also gives the block a tag when its separator equals the previous block's separator; only the writer thread can check that."

  1. utilities/trie_index/trie.cc:57

Readability (minor): kMinBitmapChildren = 32 has no reason. Suggested comment: "A sparse node stores a count byte and one label byte per child, and a bitmap takes kBitmapBytes (32 bytes). From 32 children on, the bitmap is smaller." Similarly, a short reason for kGroupBits = 6 (groups of 64 values) at line 27 would help.

  1. utilities/trie_index/trie.cc:603

Readability (minor): 2 * 8 has no name or comment. Also, num_buckets (line 587) is computed from num_blocks, not from distinct separators, and the comment does not say that this is a deliberate overestimate.

Suggestion: 2 * sizeof(uint64_t) // the two side table counts, and at line 587: "Blocks are an upper bound on distinct separators, so this overcounts buckets."

  1. table/block_based/block_based_table_factory.cc:425

Readability (minor): a validate func that always returns OK is surprising, and the comment does not say what it replaces.

Suggested text: "Without this, Configurable validation would call the factory's ValidateOptions() in every index mode. kStandardOnly ignores the factory, so BlockBasedTableFactory::ValidateOptions() calls it instead, and only in the other modes."

  1. docs/components/index_factory/index.md:43

Readability (minor): "warn" becomes "log" here, and a new paragraph about when a factory's ValidateOptions() runs is added, but the PR description does not mention these doc edits. A reader cannot tell whether the log level changed in code or only in the docs. One line in the description would help: "The docs also describe when a factory's ValidateOptions() runs, and say the kStandardDefault fallback is logged; the code is unchanged."

  1. utilities/trie_index/trie_index_factory.cc:78 (optional)

Optional: the serial AddIndexEntry() repeats the separator, same-user-key and tag logic of PrepareAddEntry() + FinishAddEntry(). Building AddIndexEntry() from those two (prepare into a reused member entry, finish, then swap the separator into separator_scratch) would remove about 30 to 40 lines and keep serial and parallel output the same by construction.

@xingbowang

Copy link
Copy Markdown
Contributor

GitHub review comments for meta/rocksdb PR 15534 ("Replace the trie index format")

Paths are relative to the RocksDB repo root. Line numbers are from the reviewed version of the PR. Post the general comment on the PR, and each numbered comment inline on the file and line in its heading.

  • Part 1: the general PR comment, the two issues, and readability comments.
  • Part 2: code comment and documentation suggestions.

Part 1: General comment, issues and readability

General PR comment

Thanks for this rewrite. The new format is much easier to follow than LOUDS, and the tests are thorough. I left inline comments: two are real issues (one wrong-block bug in a public API, one wrong upgrade note), and the rest are readability and documentation suggestions. None of the readability items change behavior.

Notes on the PR description:

1. **Reading guide and test plan.** With about 12k changed lines, a reader has no starting point and no list of what the tests check. Suggested "How to read this diff":
   1. Overview: the comment at the top of `utilities/trie_index/trie.h`. You do not need to read the deleted `louds_trie.*` and `bitvector.*`.
   2. Columns: the "Column" part of the overview, then `AppendColumn`, `Trie::Column::Init` and `Trie::Column::Get` in `trie.cc`.
   3. Trie nodes and buckets: the "Trie node" and "Bucket data" parts of the overview, then `TrieWriter` and `TrieIterator::Node`.
   4. Builder: `TrieBuilder` in `trie.h`, then `TrieBuilder::AddBlock`, `TrieBuilder::Finish` and `SizeBound`.
   5. Validation: `Trie::Parse`, `ValidateSideTables` and `ValidateTrie`.
   6. Iterator: `TrieIterator` in `trie.h`, then `Seek`, `Descend`, `SpellHead`, `ScanBucket`, `EnterKey`, `ApplyTag`, `NextKey` and `Prev`.
   7. RocksDB adapter: `utilities/trie_index/trie_index_factory.{h,cc}` (`BlockTag`, the serial and parallel paths, `ValidateOptions`).
   8. Options, docs and tests: `table/block_based/block_based_table_factory.cc`, `include/rocksdb/index_factory.h`, `include/rocksdb/table.h`, `docs/components/index_factory/index.md`, the release notes, `trie_index_test.cc` and `trie_index_db_test.cc`.

   A short test plan grouped by area would also help: format and corruption (`MalformedIndexIsRejectedOrReadable`, `NewReaderWithCorruptedData`), runs and tags (`LargeRun`, `MixedSameKeyRuns`, `TagsRandomized`), large handles (`BlockHandlesPast32Bits`, `EstimatedSizeBoundsExtremeHandles`), empty key and comparator checks (`EmptyUserKey`, `OpenRejectsNonBytewiseComparator`, `StandardOnlyIgnoresTrieComparatorRequirement`), and the crash-test block size choice (`test_trie_block_size_draw`).

2. **"sizes come from consecutive offsets when blocks are evenly spaced".** "Evenly spaced" reads as "all blocks have the same size", which is rarely true. The code needs every gap between the end of one block and the start of the next to be the same, which is normally just the block trailer. "Frame-of-reference column" is also not explained. Suggested text: "Block offsets are stored as a column. A column stores each group of 64 values as a straight line (base + slope * i) plus a small per-value correction. The size of a block is not stored when every block is followed by a gap of the same length, which is normally the block trailer. Then size = next offset - offset - gap. Otherwise the sizes are stored in a second column."

3. **Behavior change for other factories.** With the no-op validate func in `block_based_table_factory.cc`, no custom factory's `ValidateOptions()` runs in `kStandardOnly` any more. Before, the generic option validation ran it in every mode. The description only mentions the trie's comparator check. One sentence would cover it: "A custom factory's `ValidateOptions()` now runs only in index modes that use the factory."

4. **Upgrade text.** The "Compatibility" section has the same problem as the release note (see my inline comment there): SSTs written in `kCustomOnly` do not fall back in `kStandardDefault`.

A. utilities/trie_index/trie.cc:1193 (bug)

**Re-seeking to the key this iterator just returned lands on the wrong block.**

`TrieIndexIterator::SetResult()` sets `result->key = iter_.key()`, which points into `key_`. Here `SpellHead()` calls `key_.resize(prefix_len)` and then appends the bucket head. If the seek target is that same `result.key`, these writes change the target while `ScanBucket()` still reads it. Then `ScanBucket()`'s rule "the current separator is always below target" no longer holds.

Example: separators `apq`, `b`, `bb`, `c`, `d`, `date` in one bucket. `SeekAndGetResult("bb", &r, ...)` works. Then `SeekAndGetResult(r.key, &r, ...)` returns `b` (the previous block) instead of `bb`, with status OK. In a test that re-seeks every separator this way, every re-seek gave a wrong key. The old implementation copied the key into a separate buffer after the seek, so the same test passes there.

RocksDB's own `IndexFactoryIteratorWrapper` seeks with its own key copy, so normal reads are not affected. But `IndexFactoryIterator` is a public API, and "re-seek to the current key" is a natural thing for a caller to do.

Suggested fix: in `TrieIterator::Seek()`, copy the target into a separate member buffer when it points into `key_`. Or copy it in `TrieIndexIterator::SeekAndGetResult()`. Regression test: for each block, `Seek(sep_i)`, then `Seek(it.key(), tag)` and `SeekAndGetResult(result.key, ...)`, and check that the key and handle are unchanged.

B. unreleased_history/behavior_changes/trie_index_format.md:1 (wrong upgrade advice)

**Upgrade advice is wrong for SSTs written in `kCustomOnly`.**

The note says old trie SSTs "fall back to the standard index in `kStandardDefault`". The PR description says the same. That holds only for SSTs that also have a full standard index. An SST written in `kCustomOnly` has a stub standard index (`standard_index_is_stub`), so `requires_custom_reader` is true and `custom_index_required` is true even in `kStandardDefault` (see `BlockBasedTable::Open`). The version-2 reader rejects the old trie block with Corruption, and there is no fallback.

I checked this with SSTs written by the old code:

| SST written in | Opened in `kStandardDefault` |
|---|---|
| `kCustomDefault` | opens through the standard index |
| `kCustomOnly` | `Corruption: Trie index: unsupported format version` |

Released versions cannot produce such files, but main-branch users who tried `kCustomOnly` can. Suggested wording: "SSTs written in `kCustomOnly` have no standard index and cannot be opened in any mode. Before upgrading, switch to `kCustomDefault` or `kStandardDefault` and compact, so every SST has a full standard index."

C. utilities/trie_index/trie.h:73

Readability: "layout is words << 6 | width: ..." is one long sentence with three ideas. `words` is a word index but is not called one, and the reason for the 56-bit limit is only in trie.cc.

Suggested text: "layout = (start_word << 6) | width. width is the number of bits per residual in this group, at most 56, so one unaligned 8-byte load and a shift of up to 7 bits read any residual. start_word is where this group's residuals begin, counted in 8-byte words from the start of the residual area. It equals the total size of the residuals of all earlier groups. A group of n values uses ceil(n * width / 64) words."

D. utilities/trie_index/trie.h:41

Readability: one concept has two names. A distinct separator is called a "key" here (`num_keys`) and in the iterator (`key_index_`, `EnterKey`, `NextKey`, `RunKey`). But "key" also means the seek target (`Seek(key, ...)`) and the user key. While reading `ApplyTag` and `Prev` I often had to check which one was meant.

Suggestion: use "separator" in names (`num_separators`, `separator_index_`, `EnterSeparator`, `NextSeparator`). Or define the word once at the top of the file: "In this file, "key" means a distinct separator, and "key index" is its position among the distinct separators. The seek argument is called the target."

E. table/block_based/block_based_table_factory.cc:425

Readability (minor): a validate func that always returns OK is surprising, and the comment does not say what it replaces.

Suggested text: "Without this, Configurable validation would call the factory's ValidateOptions() in every index mode. kStandardOnly ignores the factory, so BlockBasedTableFactory::ValidateOptions() calls it instead, and only in the other modes."

F. utilities/trie_index/trie_index_factory.cc:78 (optional)

Optional: the serial `AddIndexEntry()` repeats the separator, same-user-key and tag logic of `PrepareAddEntry()` + `FinishAddEntry()`. Building `AddIndexEntry()` from those two (prepare into a reused member entry, finish, then swap the separator into `separator_scratch`) would remove about 30 to 40 lines and keep serial and parallel output the same by construction.

Part 2: Code comment and documentation suggestions

Each suggested text below passed a writing-rules review (0 violations) and a fact check against the code.

1. utilities/trie_index/trie_index_factory.h:10 (feature overview; replaces lines 10-29 and keeps the usage example)

The code has no overview of the whole feature. `trie.h` documents the byte layout well, but nothing explains who calls the trie, the write and read paths, the index modes, tags, or why the design is this way. This header is the first file a reader opens, so I suggest an overview here (it also fixes line 29: reads with `read_index = kBuiltin` do not use the trie). Suggested text:

```
//  Trie index: a User Defined Index (UDI) for block-based tables.
//
//  Background
//  An SST index maps each data block to its block handle (offset and size),
//  so a read loads only the block that can hold its key. An IndexFactory
//  (rocksdb/index_factory.h) builds a custom index next to the standard
//  index, or in its place. TrieIndexFactory is the IndexFactory registered as
//  "trie_index".
//
//  Terms
//  - Separator: a user key that is at least every user key in its block and
//    at most the first user key of the next block.
//  - Tag: the packed sequence number and value type of a block's last key.
//    Tag 0 means that the block can be found by user key alone. Only a block
//    that shares a user key with a neighbor block, or the last block, can
//    get a real tag. BlockTag() in trie_index_factory.cc has the exact rule.
//
//  Write path (one TrieIndexBuilder per SST file)
//  1. The table builder calls NewBuilder() in every index_mode except
//     kStandardOnly.
//  2. At each data block boundary it calls AddIndexEntry() with the block's
//     last user key, the next block's first user key (null for the last
//     block), the block handle and the last key's tag. With parallel
//     compression it calls PrepareAddEntry() and FinishAddEntry() instead.
//  3. FindShortestSeparator() computes the separator from the block's last
//     user key and the next block's first user key. The last block uses its
//     last user key unchanged. AddIndexEntry() explains why.
//  4. Finish() serializes the index with TrieBuilder (layout in trie.h). The
//     table builder writes it uncompressed as the meta block
//     "rocksdb.user_defined_index.trie_index".
//  5. EstimatedSize() returns an upper bound of the final index size once
//     every data block has been written (with parallel compression, blocks
//     are written after they are prepared). The table builder adds it to its
//     estimate of the SST tail, the blocks written after the data blocks.
//     Compaction can use that estimate to decide when to cut an output file.
//
//  Read path
//  1. When an SST is opened, NewReader() validates the block with
//     Trie::Init(). Reads then use the block in place, without a copy.
//  2. A Seek passes the target's user key and tag. TrieIterator returns the
//     first block whose separator and tag are at or after (user key, tag).
//     Blocks are ordered by separator ascending, then by tag descending.
//     Tag 0 sorts after every other tag of the same separator.
//  3. The table reader turns the separator into an internal key with
//     sequence number 0 (see user_defined_index_wrapper.h).
//
//  Index mode
//  index_mode (rocksdb/table.h) decides if the trie is built and if reads use
//  it by default. ReadOptions::read_index overrides that choice per read. For
//  example, in kStandardDefault the trie is built, but a read uses it only in
//  these cases:
//  - The read asks for it with read_index = kPreferCustom.
//  - The read keeps read_index = kDefault but sets the legacy option
//    ReadOptions::table_index_factory to a TrieIndexFactory.
//  - The SST was written in kCustomOnly and has no usable standard index.
//
//  Why this design
//  - The prefix that all separators share is stored once.
//  - Distinct separators are grouped 8 to a bucket (kTrieBucketSize). Only
//    the first separator of a bucket, the bucket head, goes into the trie.
//    The other separators, up to 7, are front coded: each one is stored as
//    how many bytes to drop from the end of the previous one, plus the bytes
//    to add. So the trie stays small, and a Seek decodes at most 7
//    separators after it walks the trie. Larger buckets put fewer heads in
//    the trie but make a Seek decode more. kTrieBucketSize explains the
//    choice of 8.
//  - A block offset is stored as a point on a straight line plus a small
//    correction. Each group of 64 blocks has its own line, so a reader finds
//    the group of a block with a shift.
//  - The gap after a block is the number of bytes between its end and the
//    start of the next block. When blocks are written back to back, the gap
//    is the block trailer (BlockBasedTable::kBlockTrailerSize, 5 bytes).
//    When every gap is the same, block sizes are not stored: a size is the
//    next offset minus this offset minus the gap.
//  - Tags are kept in a side table, so a block without a tag costs nothing.
//
//  Requirements: the comparator must be BytewiseComparator, because the trie
//  orders keys byte by byte. User-defined timestamps are not supported.
```

Note: `kTrieBucketSize` (trie_index_factory.cc:21) says 8 "was the best tradeoff on the key sets measured", but the PR has no bucket-size data. Please either add the numbers or say "8 balances index size against Seek cost".

2. utilities/trie_index/trie.cc:158 (AppendColumn)

The one-line comment does not say how a group's line is chosen, or when the column fails. Suggested text:

```
// Appends values as a column (layout in trie.h). The bucket table, the block
// offsets and the block sizes are columns.
//
// Each group of up to 64 values gets its own straight line: value j of the
// group is close to base + slope * j. The column stores the line and, for
// each value, how far the value is above the line (its residual). Bucket
// positions and block offsets never decrease. When buckets and blocks have
// similar sizes, positions and offsets grow at a steady rate, and sizes stay
// close to each other. A line then fits each group well, so the residuals
// stay small.
//
// Below, n is the number of values in the group, and v[j] is value j of the
// group, counting from 0:
// - The slope is (v[n - 1] - v[0]) / (n - 1), rounded down, when all of
//   these hold: n is at least 2, the group never decreases, v[n - 1] is
//   below kMaxLinearValue (2^62), and the slope fits 32 bits. base is then
//   the minimum of v[j] - slope * j, so no residual is negative. base can be
//   below 0. Get() still returns the exact value, because uint64_t
//   arithmetic wraps around.
// - Otherwise slope is 0 and base is the smallest value.
// The residual width is the bit length of the largest residual.
//
// AppendColumn() fails with NotSupported when a group needs more than
// kMaxColumnWidth (56) bits. It also fails when a group's residuals would
// start at 8-byte word kMaxResidualWords (2^26) or later. The layout field
// has 32 bits, and kWidthBits (6) of them hold the width, so 26 bits are
// left for the start word.
```

3. utilities/trie_index/trie.cc:26

Why groups of 64? Suggested text in place of `// Columns.`:

```
// Columns. A group holds 64 values, so Get() finds a value's group with a
// shift. The group header (kGroupHeaderSize, 16 bytes) costs 2 bits per
// value, because 64 values share it.
```

4. utilities/trie_index/trie.cc:226 (TrieWriter)

The two-line comment does not explain how nodes are formed, why children come first, or how the pointer width is chosen. Suggested text:

```
// TrieBuilder::Finish() uses this to write the trie that a Seek walks to find
// its bucket. The trie is path-compressed and covers sorted, distinct heads:
// the bucket heads without the shared prefix. A head's bucket id is its index
// in heads.
//
// Each node covers the heads that share their first `depth` bytes. Its path
// is the common prefix of the first and the last of those heads, after the
// `depth` bytes. The node is terminal, and stores the head's bucket id, when
// the first head ends there. The other heads are split by their next byte
// (the label), and each label gets a child node one byte deeper.
//
// Nodes are written children first, so the root comes last and every child
// pointer is a positive distance back from its parent. The writer knows all
// child positions when it writes a parent, so each node uses the smallest
// pointer width, 1 to 4 bytes, that fits its farthest child. The writer
// keeps its own stack instead of recursing, so deep tries cannot exhaust
// the thread's stack.
```

5. utilities/trie_index/trie.cc:57

Why 32 children? Suggested text:

```
// Nodes with at least this many children use a bitmap instead of a label
// list. At 32 children the 32-byte bitmap is smaller than the 33-byte list
// (count byte and labels), and finding a child is a popcount, not a scan.
```

6. utilities/trie_index/trie.h:66 (insert after the run table spec)

"Run" is never defined, and the rule that maps a separator to its first block appears only in the code of `EnterKey()`. A worked example would help:

```
//      A run is two or more blocks in a row that share one separator. For
//      example, if blocks 0 to 6 have the separators a, b, b, b, c, d, d,
//      the distinct separators get the key indexes a=0, b=1, c=2 and d=3,
//      and the entries are {1, 2} and {3, 3}. The first block of key index
//      k is k plus extra_blocks_through of the last run whose key_index is
//      below k, or just k when there is no such run. So c starts at block
//      2 + 2 = 4, and d starts at block 3 + 2 = 5. The run of d has 1 extra
//      block (its extra_blocks_through 3 minus the previous run's 2), so d
//      covers blocks 5 and 6.
```

7. utilities/trie_index/trie.h:196 (Trie class comment)

"Init() validates everything except the separators inside buckets" is not complete: Init does not check that the tags of one separator descend, which `ApplyTag()` relies on. It also helps to say what Init proves about the trie. Suggested text:

```
// Read-only view of a serialized trie index. Init() validates the header,
// the section offsets, and the contents of every section except the bucket
// data, which holds the separators inside buckets. It also does not check
// that the tags of one separator descend. The iterator bounds-checks each
// separator as it decodes it. The index has no checksum of its own. So a
// separator whose bytes are wrong but in bounds decodes to a wrong key.
//
// Init() proves that the trie is a tree that spells the bucket heads in
// order, so the iterator parses trie nodes without bounds checks. Where the
// iterator knows which bucket a walk must reach (the next or the previous
// bucket, the first or the last), it checks that the walk gets there,
// because bucket entries are not validated.
```

8. utilities/trie_index/trie.cc:945 (above Trie::ValidateTrie)

`ValidateTrie` has no comment, and why it rejects cycles and shared subtrees is not obvious. Suggested text:

```
// Walks the trie from the root in pre-order and checks what the iterator
// relies on, because Node::Parse(), Descend() and SpellHead() do not check
// again:
// - Every node and its fields lie inside the trie section, and the bytes on
//   the way to a node never make a head longer than max_key_len allows.
// - Every child pointer is nonzero and at most the parent's position, so a
//   child lies strictly before its parent. Every walk down the trie then
//   moves backward and ends, so the trie has no cycles.
// - Terminal nodes come in pre-order with bucket ids 0, 1, 2, ... Labels
//   ascend, so pre-order spells the heads in ascending order, and each
//   bucket head is below the head of the next bucket.
// - Every leaf is terminal, so every subtree holds a bucket id. A subtree
//   reached from two parents would repeat its bucket ids and fail the check
//   above, so the nodes form a tree.
// - To bound the work on a corrupt trie, the walk fails if it visits more
//   than trie_size / 2 nodes. A valid trie has no more, because each node
//   takes at least 2 bytes (header and path length).
```

9. utilities/trie_index/trie.h:260 (TrieIterator class comment)

Each private method has a short contract, but no comment gives the whole Seek flow. To follow it I had to read about 13 places. The current comment also lists only one cause of Corruption: the trie leading to an unexpected bucket is another. Suggested class comment:

```
// Iterates the blocks of a Trie in order. Positioning methods return
// Corruption, and leave the iterator invalid, when a separator they decode
// is out of bounds or the trie leads to an unexpected bucket.
//
// Position: key_ holds the current separator, with the shared prefix.
// key_index_ is its index among the distinct separators, and bucket_ is its
// bucket. block_ is the current block in [run_begin_, run_end_), the blocks
// that share this separator.
//
// Seek(key, tag) works in five steps. Below, "target" is the key argument.
// 1. Compare target with the shared prefix. If target's first bytes are
//    larger, every separator is smaller, and the iterator becomes invalid.
//    If they are smaller, or equal but target is shorter than the prefix,
//    every separator is larger, and Seek moves to the first block.
// 2. Descend() walks the trie with the rest of target. It returns the floor
//    (the largest bucket head below target) and the ceiling (the smallest
//    head at or above target).
// 3. If the ceiling equals target, enter the ceiling's bucket at its head
//    and go to step 5. If there is no floor, every head is larger than
//    target, and Seek moves to the first block.
// 4. SpellHead() writes the floor's head into key_. ScanBucket() then
//    decodes the floor's bucket up to the first separator at or after
//    target. If every separator there is smaller, the answer is the head of
//    the next bucket, which is the ceiling. If there is no next bucket, the
//    iterator becomes invalid.
// 5. EnterKey() finds the separator's blocks in the run table. If the
//    separator equals target, ApplyTag() skips its blocks whose tag is
//    greater than the tag argument. If it skips them all, it moves to the
//    next separator.
//
// Next() moves to the next block that shares the separator. If there is
// none, NextKey() moves to the next separator. Prev() moves to the previous
// block that shares the separator. If there is none, it finds the bucket
// head of the previous separator with Descend() and decodes forward from
// it, because front coding only decodes forward.
```

10. utilities/trie_index/trie.cc:1400 (inside TrieIterator::Seek)

The prefix comparison has no comment. Suggested text:

```
  // Every separator starts with the shared prefix. If target's first bytes
  // are larger than the prefix, every separator is below target. If they
  // are smaller, or equal but target is shorter than the prefix, every
  // separator is above target.
```

11. utilities/trie_index/trie.cc:1073 (above TrieIterator::Descend)

`Descend` is a 117-line loop with only a one-sentence description. The floor and ceiling rules are the hardest part of the iterator to follow. Suggested text:

```
// Walks down from the root along target. At each node it compares the
// node's path with target, then looks for target's next byte among the
// node's labels:
// - The child with the largest label below that byte gives a floor
//   candidate: the largest head under that child. The child with the
//   smallest label above it gives a ceiling candidate: the smallest head
//   under that child.
// - A terminal node whose head is a prefix of target, and shorter than
//   target, is a floor candidate. A terminal node whose head equals target
//   is the ceiling.
// A candidate found deeper replaces an earlier one: it shares more bytes
// with target, so it lies closer to target.
//
// The walk stops when target leaves the trie. When target leaves inside a
// node's path, or ends at a node that is not terminal, every head below
// that node is on one side of target. The smallest of them becomes the
// ceiling when target is smaller. The largest becomes the floor when target
// is larger.
//
// A sparse node scans its labels in order. A bitmap node counts the set
// bits below the byte (its rank) to find the child pointer.
```

Optional: moving the sparse and bitmap child search into a `Node` method would shorten `Descend` and make the floor/ceiling logic easier to see.

12. utilities/trie_index/trie.h:329 (NextKey)

The `key + '\0'` step in `NextKey` (trie.cc:1467) is not explained. Suggested comment on the declaration:

```
  // Moves to the first block of the next separator, or makes the iterator
  // invalid after the last one. Inside a bucket it decodes the next
  // separator. At the end of a bucket it needs the next bucket's head, but
  // the trie has no map from bucket id to node. So it calls Descend() with
  // the current separator (without the shared prefix) plus one 0 byte. That
  // string is the smallest string greater than the current separator, so
  // its ceiling is the next bucket's head.
```

13. utilities/trie_index/trie.h:274 (Prev)

The public `Prev()` has no comment, and its cost is not obvious. Suggested text:

```
  // Moves to the previous block. Moving to the previous separator costs one
  // Descend() and up to bucket_size - 1 decodes, because front coding only
  // decodes forward from a bucket head.
```

14. utilities/trie_index/trie.cc:578 (SizeBound)

The upper-bound argument is spread over short inline comments, and some terms (the 17 bytes, `2 * 8`, the clamp) have no reason. Suggested single block above the function, in place of the inline comments:

```
// Bounds the size Finish() produces, term by term. It counts buckets from
// blocks, not from distinct separators, which only overcounts.
// - Header and shared prefix: kTrieHeaderSize + max_key_len bytes.
// - Trie paths and labels: a trie over sorted strings holds one path or
//   label byte per distinct prefix of the strings. The heads are a subset of
//   the separators, so these bytes are at most suffix_bytes, which counts
//   the distinct prefixes of all separators.
// - Other trie bytes: the trie has one terminal node per bucket, and every
//   node that is not terminal has at least 2 children. So it has fewer than
//   2 * num_buckets nodes. Each node costs at most 17 more bytes: header 1,
//   path length 6 (the 255 marker and a 5-byte varint32), bucket id 4, child
//   count 1, the pointer to it 4, and 1 for its share of a bitmap (32 bytes
//   over at least 32 children).
// - Bucket table and bucket data: entry_bytes counts an entry for every
//   separator, and the bucket data holds entries only for the separators
//   after each head. So entry_bytes bounds the bucket data. Every position
//   in the bucket table is at most the size of the bucket data, so
//   entry_bytes bounds each position too.
// - Offsets: a step is the distance from one block offset to the next. The
//   offset column has one extra value after the last block (the sentinel).
//   A step between blocks is at most max_block_step. The step to the
//   sentinel is at most max_block_size + max_block_step (a size plus a gap).
//   So no step is larger than max_block_step + max_block_size. A group of 64
//   offsets spans at most 64 steps, so its range is at most 64 times that
//   sum.
// - Sizes, stored only when irregular_gaps is set: at most max_block_size.
// - Side tables: two 8-byte counts, at most one 16-byte run entry per
//   duplicate, and at most one 16-byte tag entry per tagged block.
// A group's residuals never exceed the range of its values (the largest
// value minus the smallest), because a fitted slope is at most
// range / (n - 1), where n is the number of values in the group. Finish()
// fails when a residual needs more than kMaxColumnWidth (56) bits, so 56
// bits per value always suffice. The code therefore clamps max_block_step
// and max_block_size to 2^56 each. This keeps the products from wrapping,
// and the result still bounds every index that Finish() accepts.
```

15. utilities/trie_index/trie.h:35 (also trie.cc:22)

`kMagic = 0x54524945` is written little-endian, so the bytes in the file read "EIRT", not "TRIE" (the GoldenBytes test shows `45495254`). Someone looking for "TRIE" in a hex dump will not find it. Suggested text:

```
//      u32 magic        0x54524945, stored as the bytes "EIRT"
```

and in trie.cc, on its own line so it fits 80 columns:

```
// Stored little-endian, so the bytes in the file read "EIRT".
constexpr uint32_t kMagic = 0x54524945;
```

If you want the bytes to read "TRIE", the constant must be 0x45495254. That changes the format and the golden bytes, so it is your call.

16. utilities/trie_index/trie.h:25

"so there is no file size limit" is a bit too strong: `AppendColumn` still returns NotSupported for extreme layouts. Suggested bullet:

```
//  - Block offsets are stored as 64-bit values in a column (see "Column"
//    below). Finish() rejects only extreme offset layouts, for example when
//    the offsets of one column group of 64 blocks span 2^56 bytes or more.
//    Block sizes are derived from consecutive offsets when the gaps between
//    blocks are uniform.
```

17. utilities/trie_index/trie.h:165

"whether the gaps between blocks differ" is not the whole rule: the flag is also set when blocks overlap or a block end does not fit 64 bits. Suggested text:

```
    // max_block_step is the largest distance between consecutive block
    // offsets, and max_block_size is the largest block size. The gap after a
    // block is the number of bytes from its end to the start of the next
    // block. irregular_gaps is true when Finish() must store block sizes.
    // This happens in these cases:
    // - The gaps between blocks differ.
    // - Two blocks overlap.
    // - The end of a block does not fit 64 bits.
    // - The offset where a next block would start does not fit 64 bits.
```

18. utilities/trie_index/trie_index_factory.h:122

Same point as in trie.h, and "Finish()" here reads as this class's Finish(). Suggested text:

```
  // True when TrieBuilder::Finish() must store block sizes (see
  // SizeStats::irregular_gaps in trie.h). It is one of the block statistics
  // described below, and is kept here to avoid padding.
```

19. utilities/trie_index/trie.h:277 (key())

If the code keeps the aliasing described in my comment on `SpellHead`, this comment should warn about it:

```
  // The current block's separator. It points into the iterator's own
  // buffer. It is valid until the next positioning call, and must be copied
  // before it is passed to Seek() of this iterator.
```

20. utilities/trie_index/trie.h:85

A node's path is only its own compressed edge. The head is spelled by all the paths and labels from the root. Suggested text:

```
//    Terminal nodes: bucket id (id_width bytes). The paths and labels from
//      the root to this node spell that bucket's head, without the shared
//      prefix.
```

21. utilities/trie_index/trie.h:286 (Candidate::depth)

For a `kTerminal` candidate, `depth` already includes the node's path (`Descend` uses `label_depth`), so the current comment is wrong for that case. Suggested text:

```
    // Number of target bytes (after the shared prefix) that the head shares
    // with target before node's path. For kTerminal it includes node's
    // path, so these bytes are the whole head.
```

22. utilities/trie_index/trie_index_factory.h:169

"Finish may upgrade this to true": `FinishAddEntry` never writes this field. It ORs `SharesPreviousSeparator()` into the `BlockTag()` argument. Suggested text:

```
    // True if last_key and first_key_in_next_block have the same user key,
    // computed from the inputs alone. FinishAddEntry() also tags the block
    // when its separator equals the previous block's, which only the BG
    // writer thread can check (see BlockTag()).
```

23. utilities/trie_index/trie_index_factory.h:164

The list of `last_key_tag` users misses the case where the block's last user key continues into the next block. Suggested text:

```
    // Real tag of last_key_in_current_block. BlockTag() uses it for the
    // last block, and when this block's last user key continues into the
    // next block or its separator equals the previous block's.
```

24. utilities/trie_index/trie_index_factory.h:209

`user_defined_index.h` is now only an alias header, and it holds no such contract. The sentence before already states the rule, so I suggest dropping the pointer:

```
  // Checks whether the current block may hold keys in the current scan.
  // reference_key is the key to compare against the limit: for Seek this is
  // the seek target, for Next this is the previous separator key. Separators
  // are upper bounds on block contents, not first-in-block keys, so the
  // current separator cannot be compared against the limit directly.
```

25. utilities/trie_index/trie_index_factory.h:90 (also lines 96-103 and 158-161)

One thread has three names here: "write thread", "BG worker thread" and "BG writer thread" (the last is the name in index_factory.h). Lines 92-93 also suggest that `FinishAddEntry` calls can run at the same time; they cannot. The lock-free part is `EstimatedSize()` against `FinishAddEntry()`. Suggested text for 90-93:

```
  // Returns an estimate of the current serialized index size. With parallel
  // compression, it may run on the emit thread (the thread that adds keys
  // and prepares entries) while FinishAddEntry() runs on the BG writer
  // thread (the thread that writes blocks in order). Separator statistics
  // are written only on the emit thread, and block statistics are relaxed
  // atomics, so no lock is needed.
```

For 96-103:

```
  // --- Parallel compression protocol ---
  //
  // With parallel compression, AddIndexEntry() is split in two steps:
  // 1. PrepareAddEntry() runs on the emit thread and computes the
  //    separator.
  // 2. FinishAddEntry() runs on the BG writer thread. It gets the block
  //    handle, which is known only after the block is written, and adds the
  //    block to trie_builder_.
  // The table builder calls FinishAddEntry() serially and in block order,
  // so trie_builder_ needs no lock.
```

For 158-161:

```
  // One prepared entry of the parallel compression protocol.
  // PrepareAddEntry() fills it on the emit thread, and FinishAddEntry()
  // uses it on the BG writer thread. The block handle is not known in
  // PrepareAddEntry(), so FinishAddEntry() receives it as an argument.
```

Optional: grouping these members by owner thread (emit thread, BG writer thread, shared relaxed atomics), even at the cost of a few bytes of padding, would remove the "described below" / "above" pointers between fields.

26. utilities/trie_index/trie_index_factory.h:69

This does not say what the last block gets. Suggested text:

```
  // Called at each data block boundary. Computes a short separator between
  // last_key_in_current_block and first_key_in_next_block, adds it to the
  // trie with the block's handle, and returns it. For the last block,
  // first_key_in_next_block is null and the separator is
  // last_key_in_current_block itself.
```

27. utilities/trie_index/trie_index_factory.h:142

The comment says the estimate can fall short, but index_factory.h says `EstimatedSize()` must be an upper bound. It should say why the final estimate is still safe. Suggested text for 142-147:

```
  // These fields, with irregular_block_gaps_ above, hold statistics of the
  // block handles added so far. The thread that adds handles writes them
  // (the BG writer thread in a parallel build). EstimatedSize() reads them
  // on the emit thread. They bound the widths of the offset and size
  // columns. A block that is still being compressed is assumed to be no
  // larger than the largest block so far, so the estimate can be too small
  // until its handle arrives. The table builder takes its final estimate
  // after the last FinishAddEntry() (in BlockBasedTableBuilder::Finish()),
  // so that estimate is an upper bound, as index_factory.h requires.
```

28. utilities/trie_index/trie_index_factory.cc:36 (BlockTag)

The comment and the parameter name `shares_previous_separator` miss a case. Callers pass `same_user_key || SharesPreviousSeparator(...)`, so a block whose last user key continues into the next block gets its tag even when its separator differs from the previous block's. Suggested text, with the parameter renamed:

```
// A block's tag is 0 when the block can be found by user key alone.
// Otherwise it is the real tag of the block's last key. A block needs its
// real tag in two cases:
// - Its separator is a user key that also appears in a neighbor block. This
//   happens when its last user key continues into the next block, or when
//   its separator equals the previous block's. The tags then tell the blocks
//   of that user key apart.
// - It is the last block. Its separator is the last user key itself, and the
//   tag lets a Seek for that user key with a smaller sequence number move
//   past it, as the standard index does with its full internal key.
// A separator between different user keys needs no tag: the standard index
// with index_key_is_user_key also compares user keys only there.
uint64_t BlockTag(bool shares_user_key_with_neighbor, bool has_next_block,
                  uint64_t last_key_tag) {
  return shares_user_key_with_neighbor || !has_next_block ? last_key_tag : 0;
}
```

29. utilities/trie_index/trie_index_factory.cc:87

"the separator is then that user key for both blocks": only this block's separator is that user key. The next block's separator comes from its own last key and can be larger. Suggested text:

```
  // True when last_key and first_key_in_next_block are the same user key.
  // This block's separator is then that user key, and the next block holds
  // it too, so this block needs its real tag.
```

30. utilities/trie_index/trie_index_factory.cc:247

There is no buffer or `back()` any more; `FinishAddEntry` compares with `trie_builder_.LastSeparator()`. Suggested text:

```
    // This checks, from the inputs alone, whether the block's last user key
    // continues into the next block. The half of the check that needs the
    // previous block's separator runs in FinishAddEntry(), where
    // trie_builder_ holds every earlier block.
```

31. utilities/trie_index/trie_index_factory.cc:84

"use a short successor of the last key" contradicts the code and the comment 16 lines below: the last block uses the last key unchanged. Suggested text for lines 80-85:

```
  // Compute a short separator between the two user keys using the
  // comparator. FindShortestSeparator takes `*start` as both input and output:
  //   input:  *start == last_key_in_current_block
  //   output: *start modified to shortest string in [start, limit)
  // If first_key_in_next_block is nullptr, this is the last block: the
  // separator is the last key itself (see below).
```

32. utilities/trie_index/trie_index_factory.cc:102

"lines 278-286" is already stale (`GetSeparatorWithSeq` starts at line 270). Suggested text without line numbers:

```
    // Last block: use the last key itself as the separator, NOT a shortened
    // successor. The standard ShortenedIndexBuilder does the same (see
    // GetSeparatorWithSeq() in table/block_based/index_builder.h). It calls
    // FindShortInternalKeySuccessor only when shortening_mode is
    // kShortenSeparatorsAndSuccessor. The default is kShortenSeparators, and
    // then the last block's separator is simply last_key_in_current_block.
```

33. docs/components/index_factory/index.md:43

The `kStandardDefault` row says a missing custom block falls back to the standard index. That is not true for SSTs written in `kCustomOnly` (see my comment on the release note). Suggested note under the table:

```
An SST written in `kCustomOnly` has only a stub standard index. It needs a
working custom index in every mode, so a missing or unusable custom block is a
hard error, even in `kStandardDefault`.
```

Also, this line changes "warn" to "log", and the PR adds a paragraph about when a factory's `ValidateOptions()` runs. The PR description does not mention these doc edits. One line would help: "The docs also describe when a factory's ValidateOptions() runs, and say the kStandardDefault fallback is logged; the code is unchanged."

- Seek() to the iterator's own key(), or to bytes inside it, could land
  on the wrong block: spelling the new separator overwrote the target.
  Seek() now copies a target that points into its key, and
  SeekAndGetResult() runs the bound check before the seek, which read
  the target afterwards too.
- The release note and docs say that an SST written in kCustomOnly with
  an old trie block cannot be opened in any mode, and the note says a
  custom factory's ValidateOptions() no longer runs in kStandardOnly.
  OtherTrieVersionFallsBackOrFails covers the kCustomOnly case.
- Fix comments that were wrong or stale: the magic's byte order,
  Candidate::depth, how a terminal node's head is spelled, when sizes
  are stored, thread names, why the final EstimatedSize() is an upper
  bound, which blocks get tags, and pointers to moved code.
  same_user_key_initial is renamed same_user_key.
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Claude Code Review - OBSOLETE

Superseded by a newer AI review. Expand to see the original review.

✅ Claude Code Review

Auto-triggered after CI passed — reviewing commit 9ee968b


Summary

This PR replaces the LOUDS-based trie index format with a new block-tree format, removes the mmap_read incompatibility, delegates factory validation conditionally, and updates crash testing. The visible portions of the diff are well-structured. The diff was truncated (22 files changed, 4015 insertions, 8320 deletions -- the new trie.h/trie.cc core implementation is not visible), so this review covers only the visible changes.

High-severity findings (0):
No high-severity findings.

Full review (click to expand)

Findings

🟡 MEDIUM

M1. SetValidateFunc bypass is global, not trie-specific -- block_based_table_factory.cc:424
  • Issue: The SetValidateFunc on the user_defined_index_factory OptionTypeInfo returns Status::OK() unconditionally. This suppresses the generic Configurable::ValidateOptions path for all IndexFactory implementations, not just the trie. If a future (or third-party) IndexFactory registers inner Configurable options that need recursive validation, the generic path would no longer run. The explicit call in BlockBasedTableFactory::ValidateOptions calls factory->ValidateOptions(db_opts, cf_opts), which does recurse into registered options via Configurable::ValidateOptions (options/configurable.cc:71-86), so the semantics are equivalent today. But the coupling between the bypass and the explicit call is implicit -- someone modifying one could forget the other.
  • Root cause: The OptionTypeInfo validation bypass is a blanket override at the type-info level, while the conditional call is at the factory level. They must stay in sync.
  • Suggested fix: Add a comment at the SetValidateFunc site explicitly referencing the explicit call in ValidateOptions() and stating the invariant: "Validation is handled conditionally by BlockBasedTableFactory::ValidateOptions() below, which skips kStandardOnly. Any change to the explicit call must be reflected here." The existing comment is close but doesn't name the invariant precisely.
M2. Release note says "supports data blocks past 4 GiB" but factory still has 32-bit handle check -- trie_index_factory.cc:142-143
  • Issue: The release note at unreleased_history/behavior_changes/trie_index_format.md says the new format "supports data blocks past 4 GiB." However, the factory header doc (trie_index_factory.h:33-38) still says "The trie format stores data-block offsets and sizes as 32-bit integers" and the builder code at trie_index_factory.cc:142-143 still checks handle.offset > UINT32_MAX || handle.size > UINT32_MAX. The diff was truncated so the factory file changes may not be visible. If the 32-bit limit is not removed in the full diff, the release note is misleading.
  • Root cause: Possibly the full diff changes the factory code (not visible in the truncated diff), or the release note is inaccurate.
  • Suggested fix: Verify the full diff. If 32-bit handles remain, update the release note to remove or qualify the "past 4 GiB" claim.
M3. ValidateOptions gap at SetOptions() time -- include/rocksdb/index_factory.h:355
  • Issue: The new doc comment on IndexFactory correctly documents that factory ValidateOptions() runs at DB::Open() and CreateColumnFamily() but NOT at SetOptions() or SstFileWriter. A user could dynamically switch to kCustomDefault via SetOptions() with a comparator the factory rejects, and the rejection won't happen until the first table build. This is properly documented and Validate table factory options in SetOptions() #15582 tracks the fix, so no action needed in this PR.
  • Root cause: Intentional documented limitation.
  • Suggested fix: None -- properly tracked.

🟢 LOW / NIT

L1. index_factory.h:362 comment fix is correct
  • The fix from "trie" to "trie_index" correctly matches kClassName() at trie_index_factory.h:339.
L2. db_crashtest.py block_size lambda follows established patterns
  • The lambda is correctly resolved by finalize_and_sanitize at line 1494. The getattr(args, "block_size", None) check correctly detects explicit CLI arguments. The auto_readahead_size shrink can still override to 1024, which is fine.
L3. db_crashtest_test.py mmap assertion update is consistent
  • self.assertEqual(1, finalized["mmap_read"]) correctly reflects removal of the mmap restriction.
L4. table.h rollback doc correction is accurate
  • Index routing is fixed at BlockBasedTable::Open() time and stored in Rep; SetOptions() changes only affect subsequently opened SSTs.
L5. Build system consistency maintained
  • BUCK, CMakeLists.txt, and src.mk all consistently replace bitvector.cc + louds_trie.cc with trie.cc.
L6. mmap restriction removal is architecturally sound
  • The UDI block is loaded into the block cache (heap copy) or read via the table reader's mmap mapping, both of which outlive the iterator. Crash-tested with --mmap_read=1.
L7. Trie block_size randomization conditions are correct
  • index_mode != 0 correctly excludes kStandardOnly (which never builds the trie). Smaller blocks exercise more trie nodes.

Cross-Component Analysis

Context Affected? Assessment
SetOptions() YES Documented gap; #15582 tracks fix
SstFileWriter YES Documented; fails at first table build
kStandardOnly NO Correctly excluded from factory validation
mmap_read YES Architecturally sound; crash-tested
Third-party IndexFactory YES Semantically equivalent today; see M1
WritePreparedTxnDB NO Index layer, not visibility layer

Positive Observations

  • The SetValidateFunc + explicit conditional call pattern cleanly implements mode-dependent validation without framework changes.
  • Crash test block_size randomization is well-designed: smaller blocks exercise more trie structure.
  • Documentation updates are thorough and accurate, including the SetOptions() rollback timing correction.
  • Release note is appropriately concise.
  • Build system consistency across Make/CMake/BUCK is maintained.
  • The PR description is exceptionally thorough with detailed benchmarks, compatibility analysis, and bug enumeration.

ℹ️ About this response

Generated by Claude Code.
Review methodology: claude_md/ci_review_prompt.md

Limitations:

  • Claude may miss context from files not in the diff
  • Large PRs may be truncated
  • Always apply human judgment to AI suggestions

Commands:

  • /claude-review [context] — Request a code review
  • /claude-query <question> — Ask about the PR or codebase

- One name for a distinct separator: num_separators, separator_index_,
  EnterSeparator(), NextSeparator(), RunSeparator(), max_separator_len
  and cumulative_extra_blocks. Seek()'s argument is target. The format
  is unchanged; GoldenBytes still passes.
- Descend()'s sparse and bitmap child search moved into
  Node::FindLabel(). A Seek microbenchmark over three key shapes stays
  within 3% of before, both ways.
- The serial AddIndexEntry() runs PrepareAddEntry() and
  FinishAddEntry() on a member entry, so serial and parallel builds
  share one path. The serial size estimate is now the parallel one,
  which charges a possible tag before the tag is known.
- TrieIndexBuilder's members are grouped by the thread that writes
  them.
- New comments: an overview in trie_index_factory.h, the column
  layout and AppendColumn(), groups of 64, TrieWriter,
  kMinBitmapChildren, a run table example, what Init() proves about
  the trie, ValidateTrie(), the Seek walkthrough, Descend(),
  NextSeparator(), Prev() and SizeBound().
@zaidoon1

Copy link
Copy Markdown
Contributor Author

Thanks for the careful read. Your line numbers are from the first commit, so the second one had already covered part of the kCustomOnly point. The fixes are in 9ee968b, the readability changes are in e989472, and the description is updated.

Re-seeking to the returned key

Confirmed and fixed. TrieIterator::Seek() now copies a target that points into its own key, and TrieIndexIterator::SeekAndGetResult() runs the bound check before the seek, since it also read the target after the seek. That second part matters when the target is bytes inside result.key: with a scan limit of "c", a seek to the "b" inside "xb" lands on "bz", and the old order compared "z" with the limit.

New tests, all red before the fix:

  • TrieTest.SeekToOwnKey: your example, every slice of every separator, bucket sizes 1, 2 and 8, with and without a shared prefix
  • TrieIndexFactoryTest.SeekToResultKey: the same through IndexFactoryIterator, comparing key, handle and bound check with a seek to a copy
  • the randomized walk in RandomizedRunsTagsAndSizes now also re-seeks through key()

kCustomOnly upgrade advice

The second commit already told users to rewrite kCustomOnly SSTs before upgrading. The note and the description now say outright that no mode can open them, and your note is under the modes table in the docs. OtherTrieVersionFallsBackOrFails now also writes an old-version SST in kCustomOnly: it fails with NotSupported in kStandardDefault and kCustomOnly, and with InvalidArgument in kStandardOnly.

Other factories in kStandardOnly

Right, that's a behavior change for every custom factory, not just the trie. It's in the release note and the description now, and the comment on the no-op validate func says what it replaces.

Comments

These were wrong or stale and are fixed:

  • the magic: the comments now say the bytes are "EIRT". I kept the constant because it's version 1's, so an old block passes the magic check and gets NotSupported from the version check
  • Candidate::depth for kTerminal, and which bytes spell a terminal node's head
  • "no file size limit" is now "no 32-bit limit", and the full rule for when sizes are stored is written out
  • Init() doesn't check that the tags of one separator descend, and the trie leading to the wrong bucket is a second Corruption cause
  • one name for the BG writer thread, and the concurrency comment now says EstimatedSize() races FinishAddEntry(), not FinishAddEntry() calls each other
  • why the final EstimatedSize() is still an upper bound
  • last_key_tag, same_user_key_initial (now same_user_key) and the BlockTag() parameter, which all missed the block whose last user key continues into the next block
  • the last-block "short successor" comment, the stale line numbers, back(), and the pointer to user_defined_index.h
  • the file header now says kBuiltin reads don't use the trie in kCustomDefault or kCustomOnly
  • kTrieBucketSize: I don't have data that 8 is best. In my Seek tests on long URL-like keys, 4 and 16 were within noise of 8, and 16 was 1-6% smaller, so the comment now just says 8 balances the two

The description also lists the doc-only edits and no longer says "evenly spaced".

Readability

All of these are in e989472. The format didn't change, and GoldenBytes still passes.

  • One name for a distinct separator: num_separators, separator_index_, EnterSeparator, NextSeparator and RunSeparator. The Seek argument is target. The header fields are now max_separator_len and cumulative_extra_blocks, but only in comments and names; the bytes are the same.
  • The sparse and bitmap child search moved out of Descend() into Node::FindLabel(). Seek is a hot path, so I timed 1M Seeks over 200K separators on three key shapes before and after: within 3% both ways across 8 alternating runs, which is noise on this machine.
  • AddIndexEntry() is now PrepareAddEntry() and then FinishAddEntry() on a member entry, so serial and parallel builds run the same code. One side effect: the serial size estimate is now the parallel one, which charges a possible tag before the tag is known. That only adds to an upper bound, and the EstimatedSize tests pass both ways.
  • The builder's members are grouped by the thread that writes them.
  • Your comment blocks, checked against the code and sometimes shortened: AppendColumn, groups of 64, TrieWriter, kMinBitmapChildren, the column layout, the run table (with a worked example), what Init() proves about the trie, ValidateTrie, the Seek walkthrough on TrieIterator, the prefix comparison, Descend, NextSeparator, Prev and SizeBound.
  • trie_index_factory.h now opens with what a separator and a tag are and how the builder, reader and iterator fit together. I left out the read path and timestamp parts of your text, because I couldn't point to the code behind them in this PR.
  • The description has a reading guide and a test plan grouped by area.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Claude Code Review - OBSOLETE

Superseded by a newer AI review. Expand to see the original review.

✅ Claude Code Review

Auto-triggered after CI passed — reviewing commit e989472


Summary

This is a well-designed replacement of the experimental LOUDS trie index with a compact block-tree format. The new format is smaller, faster, fixes several bugs in the old format, removes byte-order dependency, and lifts the 4 GiB limit. The code is thoroughly tested and benchmarked. The implementation is clean, with solid validation in Trie::Init() / ValidateTrie() and careful corruption handling throughout the iterator.

High-severity findings (0):

No high-severity findings.

Full review (click to expand)

Findings

🔴 HIGH

No high-severity findings.

🟡 MEDIUM

M1. CommonPrefix reads 8 bytes at a time from potentially short buffers — trie.cc:154
  • Issue: CommonPrefix() reads 8 bytes via DecodeFixed64(a + i) when i + 8 <= n. When called from ScanBucket() with suffix pointing into bucket_data_, the suffix data is part of a contiguous index block, so the read is within the allocation. Similarly, Descend() reads from target which is a full Slice, and from node.path within the trie section. Because these are all within a single contiguous block cache allocation or mmap region, the out-of-bounds read does not cause a crash or security issue — but it does read bytes beyond the logical boundary.
  • Root cause: Performance optimization for prefix comparison uses 8-byte loads without regard for the logical bounds of the specific sub-buffer.
  • Suggested fix: This is safe in practice because the entire index is a single contiguous allocation, and kColumnPadding provides trailing slack. However, it could trigger ASAN or MSAN reports if the index block happens to end exactly at a page boundary. Consider adding a brief comment documenting why this is safe (the index block is contiguous).
M2. Column::Get() does not validate i < count — trie.cc:706
  • Issue: Column::Get(i) trusts its caller to provide i < count. An out-of-range i reads from arbitrary memory relative to the groups and residuals pointers.
  • Root cause: Performance choice — adding an assert or bounds check would slow the hot path.
  • Suggested fix: Add assert(i < count) for debug-build coverage. The callers (EnterBlock, EnterBucket) are already gated by iterator validity and Trie::Parse() validation, so this is defense-in-depth.
M3. SetValidateFunc bypasses generic Configurable validation for the index factory — block_based_table_factory.cc:424
  • Issue: The SetValidateFunc lambda always returns Status::OK(), which means any IndexFactory::ValidateOptions() override is ONLY called through BlockBasedTableFactory::ValidateOptions(). If a code path constructs a BlockBasedTableOptions and validates it through the generic Configurable::ValidateOptions() without going through BlockBasedTableFactory::ValidateOptions(), the factory's constraints are silently skipped.
  • Root cause: Intentional design — BlockBasedTableFactory::ValidateOptions() gates the call on !kStandardOnly. But the coupling between the two is implicit and fragile.
  • Suggested fix: Add a comment at the SetValidateFunc site noting that BlockBasedTableFactory::ValidateOptions() is the sole validation entry point, and document this invariant. The current doc comment and code comment already explain the intent, but a cross-reference would help future maintainers.
M4. Potential Prev() cost with large bucket sizes — trie.cc TrieIterator::Prev
  • Issue: Prev() calls Descend() and then AdvanceTo(), which decodes forward from the bucket head to the target separator. With a large bucket_size, this could decode up to bucket_size - 1 separators. The current bucket size is 8, so this is 7 decodes maximum.
  • Root cause: Front-coded buckets only decode forward. This is a fundamental design trade-off, well documented in the iterator class comment.
  • Suggested fix: No fix needed at current bucket size. The class comment already documents this cost. If bucket sizes grow, consider a backward-decode optimization or per-bucket skip list.

🟢 LOW / NIT

L1. Missing assert on bucket_size > 0 precondition in TrieBuilder::SizeBound — trie.cc
  • Issue: SizeBound() has an assert(bucket_size > 0) but no runtime check. If called with bucket_size == 0, the division in (n + bucket_size - 1) / bucket_size would cause undefined behavior (division by zero).
  • Suggested fix: The only caller is EstimatedSize() which uses kTrieBucketSize = 8, so this is unreachable. The assert is sufficient.
L2. Trie::Parse() checks num_blocks_ / 4 > data.size() — trie.cc:912
  • Issue: This overflow guard ("every block takes at least a quarter byte of the offset column") is a heuristic. With extreme values of num_blocks_ that are just below the threshold, the subsequent column parsing could still fail safely (AppendColumn validates all group layouts).
  • Suggested fix: No change needed — the column validation is the real check, this is an early-exit optimization.
L3. EnterBucket clamps bucket positions with std::min — trie.cc:1310
  • Issue: When bucket_table_.Get(bucket) returns a corrupt position, clamping it to bucket_data_size_ prevents out-of-bounds access. DecodeNext() then checks bounds within the clamped region. This is correct but means a corrupt bucket table produces a Corruption error rather than crashing.
  • Suggested fix: This is good defensive coding. No change needed.
L4. Release note is a single long line — unreleased_history/behavior_changes/trie_index_format.md
  • Issue: The release note is 383 characters on one line. CLAUDE.md says "Release note should be kept short at high level for external user consumption."
  • Suggested fix: The content is good — it covers the upgrade/downgrade path and the behavioral changes. The length is acceptable for a format change, but consider a line break or two for readability in the markdown source.
L5. TrieIndexFactory::ValidateOptions() calls IndexFactory::ValidateOptions(db_opts, cf_opts) — trie_index_factory.cc
  • Issue: After checking for BytewiseComparator, the factory chains to IndexFactory::ValidateOptions(), which today is a no-op. This is correct forward-looking practice.
  • Suggested fix: None needed.

Cross-Component Analysis

Context Does code execute? Assumptions hold? Action needed?
WritePreparedTxnDB YES (uses same SST builder) YES (trie operates at separator/block level, not visibility) None
ReadOnly DB YES (reader only) YES None
User-defined timestamps NO (factory rejects non-BytewiseComparator, and UDT uses timestamp-aware comparators) N/A None
Concurrent writers YES (parallel compression) YES (PrepareAddEntry/FinishAddEntry split with relaxed atomics is correct) None
FIFO / Universal compaction YES YES (trie is comparator-level, not compaction-strategy-level) None
Column family drop YES YES (index lifetime tied to table reader) None
mmap reads YES (explicitly tested in MmapReads test) YES (block data outlives iterator) None
Big-endian YES YES (all integers are little-endian via Encode/DecodeFixed, explicit in format spec) None

DB Mutex: The changed code does not execute under DBImpl::mutex_. The trie index builder runs during flush/compaction (outside mutex), and the reader/iterator runs during reads (outside mutex). ValidateOptions() runs during DB::Open() and CreateColumnFamily(), which may hold the mutex, but it performs no I/O and returns immediately.

Behavioral Compatibility: The PR correctly documents the one-way-door nature of this change. Old trie blocks fail with NotSupported (not Corruption), which is the right status for a version mismatch. The kStandardDefault fallback works because those SSTs always carry a full standard index. The kStandardOnly mode is unaffected. The ValidateOptions change for kStandardOnly is a correct relaxation — the factory is ignored in that mode, so its constraints should not block DB::Open().

Positive Observations

  • Thorough validation. Trie::Init() → Parse() → ValidateSideTables() → ValidateTrie() validates the header, section layout, column structures, side tables, and the trie's tree structure before accepting an index. ValidateTrie() proves bucket ids are sequential, labels ascend, and child pointers are well-formed, making the iterator's unchecked trie walks safe.
  • Little-endian format. The old LOUDS format stored arrays in host byte order, breaking big-endian. The new format uses EncodeFixed*/DecodeFixed* throughout, which handle endianness correctly.
  • Column encoding. The linear frame-of-reference encoding for block offsets is an elegant design — most SSTs have nearly uniform block sizes, so the residuals are very small and the offset column is compact.
  • Corruption resilience. The iterator bounds-checks bucket entries, offset differences, and trie traversals, returning Corruption for any malformed data rather than crashing. The 22M-case fuzzer result is reassuring.
  • Clean separation. trie.h / trie.cc is a pure data structure with no RocksDB-specific dependencies beyond Status, Slice, and coding utilities. trie_index_factory.cc is the adapter layer. This makes the trie independently testable and maintainable.
  • Parallel compression support. The PrepareAddEntry / FinishAddEntry split with relaxed atomics for block statistics is correct and does not need locking.
  • Good test coverage. 98 trie-level tests and 277 DB-level tests, including golden-bytes format verification, corruption fuzzing, version fallback, mmap reads, empty user keys, and non-bytewise comparator rejection.
  • Accurate size estimation. SizeBound() provides a sound upper bound, and the estimate converges to the actual size as blocks are added, meeting the index_factory.h contract that the last estimate (after all blocks) is an upper bound.

ℹ️ About this response

Generated by Claude Code.
Review methodology: claude_md/ci_review_prompt.md

Limitations:

  • Claude may miss context from files not in the diff
  • Large PRs may be truncated
  • Always apply human judgment to AI suggestions

Commands:

  • /claude-review [context] — Request a code review
  • /claude-query <question> — Ask about the PR or codebase

- An iterator reading through a custom index kept the MultiScan ranges
  in the index iterator after SeekToLast(), SeekForPrev() or Prev()
  left the MultiScan. The trie then reported later blocks out of bound,
  so a plain scan returned too few keys, and it still pointed at the
  caller's scan keys. BlockBasedTableIterator::ResetMultiScan() now
  calls Prepare(nullptr) on the index iterator when Prepare() had passed
  it ranges, the wrapper forwards that as Prepare(nullptr, 0), and
  TrieIndexIterator drops its bounds. index_factory.h documents that
  num_opts == 0 discards the ranges. The bug predates this PR.
- TrieIterator::Seek() returns SeekToFirst() for an empty target before
  the shared prefix memcmp, so a null data() never reaches it.
- assert(i < count) in Trie::Column::Get().
- reserve() in EstimatedSizeBoundsExtremeHandles, for clang-tidy.
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Claude Code Review - OBSOLETE

Superseded by a newer AI review. Expand to see the original review.

✅ Claude Code Review

Auto-triggered after CI passed — reviewing commit 629add8


Summary

Well-structured PR that replaces the LOUDS trie index with a new block-tree format and fixes a real MultiScan bug. The visible changes (non-truncated diff) are correct and well-designed. The MultiScan fix is clean, the ValidateOptions architecture is sound, and the build system updates are consistent.

High-severity findings (0):
No high-severity findings.

Full review (click to expand)

Findings

🔴 HIGH

No high-severity findings.

🟡 MEDIUM

M1. SimpleExternalTableIterator::Prepare() stores raw pointer — Prepare(nullptr, 0) is safe but fragile — test_util/simple_external_table_factory.cc:150
  • Issue: SimpleExternalTableIterator::Prepare() stores the raw scan_options pointer. When called with Prepare(nullptr, 0), it correctly sets scan_options_ = nullptr. However, this implementation does no bounds-checking on the stored pointer against num_options_. If a future code path calls Prepare(nullptr, 0) and then accesses scan_options_[scan_index_] without checking scan_options_ != nullptr, it would dereference null. The PR's new contract says "May be null when num_opts is 0", but the enforcement is on the caller side.
  • Root cause: No validation in the Prepare() implementation that scan_options != nullptr || num_options == 0.
  • Suggested fix: This is a pre-existing fragility in test code, not introduced by this PR. The PR's documentation improvement helps. Low risk in practice since all callers pass 0 with nullptr.
M2. index_iter_has_scan_ranges_ is set unconditionally even if Prepare() fails downstream — block_based_table_iterator.cc:1098
  • Issue: The PR adds index_iter_has_scan_ranges_ = true immediately after index_iter_->Prepare(multiscan_opts). If the downstream CollectBlockHandles() fails (setting multi_scan_status_ to non-OK), the method returns early. Later when ResetMultiScan() runs, it will call index_iter_->Prepare(nullptr) even though the scan ranges may not have been fully established. This is harmless (Prepare(nullptr) is a no-op or clears state), but the tracking bool is imprecise.
  • Root cause: The bool tracks "Prepare was called" rather than "scan ranges are actively in use."
  • Suggested fix: Acceptable as-is. The Prepare(nullptr) call is idempotent and cheap. The alternative (tracking more precisely) adds complexity for no functional benefit.

🟢 LOW / NIT

L1. Missing else branch documentation in IndexFactoryIteratorWrapper::Prepare() — user_defined_index_wrapper.h:113
  • Issue: The new else branch that calls udi_iter_->Prepare(nullptr, 0) has no comment explaining why this is needed.
  • Suggested fix: Add a brief comment: // Discard scan ranges when the table iterator leaves a MultiScan.
L2. table_test.cc Prepare() relaxes the "called only once" assertion — table_test.cc:10466
  • Issue: The test's TestIndexFactoryIterator::Prepare() previously had EXPECT_EQ(scan_opts_, nullptr) to assert Prepare is called only once. The PR adds an early return for num_opts == 0, which skips this assertion. This means the test no longer verifies the "called at most once with non-zero opts" contract as strictly.
  • Suggested fix: Consider adding EXPECT_NE(num_opts, 0) after the early return guard, or restructuring to separate the discard path from the setup path.
L3. Release note is a single long line — unreleased_history/behavior_changes/trie_index_format.md
  • Issue: The release note is a single very long line. Dense but thorough.
  • Suggested fix: Consider splitting into 2-3 sentences for readability.
L4. db_bench help text drops useful detail — tools/db_bench_tool.cc:778
  • Issue: The old help text mentioned "providing space reduction compared to the standard index." The new text is sparser.
  • Suggested fix: Consider: "Builds a compact trie from separator keys. Requires BytewiseComparator."

Cross-Component Analysis

Context Affected? Analysis
Standard index (no custom factory) Partially ResetMultiScan()'s Prepare(nullptr) hits the no-op default in InternalIteratorBase. Safe.
WritePreparedTxnDB No MultiScan is read-path only.
ReadOnly DB Minimal Fix applies equally.
CompactionIterator No Doesn't use MultiScan.
SetOptions() Documented Doesn't run ValidateOptions(). Factory fails at first table build. Intentional.
kCustomOnly old-format SSTs Breaking Cannot be opened. Documented. Acceptable for experimental feature.

Assumption stress-test: index_iter_->Prepare(nullptr) safety

  • IndexBlockIter → no-op default ✅
  • IndexFactoryIteratorWrapper → PR adds else branch ✅
  • MultiScanIndexIterator → no-op default ✅

Assumption stress-test: SetValidateFunc returning OK

  • Suppresses generic Customizable validation for the factory sub-object.
  • Manual validation runs for all modes except kStandardOnly (where factory is ignored).
  • Safe for current design. Well-commented.

Assumption stress-test: mmap_read safety

  • Block lifetime follows standard RocksDB ref-counting: active iterator → table reader ref → mmap alive.
  • New format reads in place without auxiliary heap allocations that could outlive the block.
  • Old format had zero-copy pointers that broke this contract. New format avoids it.

Positive Observations

  • Clean MultiScan fix with minimal, safe state tracking.
  • ValidateOptions architecture is well-documented and consistent with existing patterns.
  • Contract documentation for Prepare(nullptr, 0) makes implicit semantics explicit. Already followed by external_table.cc.
  • Crash test improvements with block_size variation and mmap_read un-restriction.
  • Build system consistency across BUCK, CMake, and Make/src.mk.
  • Excellent PR description — thorough benchmarks, compatibility analysis, and reading guide.

ℹ️ About this response

Generated by Claude Code.
Review methodology: claude_md/ci_review_prompt.md

Limitations:

  • Claude may miss context from files not in the diff
  • Large PRs may be truncated
  • Always apply human judgment to AI suggestions

Commands:

  • /claude-review [context] — Request a code review
  • /claude-query <question> — Ask about the PR or codebase

- BlockBasedTableIterator::Prepare() now calls Prepare(nullptr) on the
  index iterator as soon as CollectBlockHandles() returns, instead of
  tracking a flag and clearing the ranges in ResetMultiScan(). The index
  iterator needs them only for that walk, so this also covers a
  Prepare() that fails, and index_iter_has_scan_ranges_ is gone.
- The index factory docs say that a table reader keeps its custom index
  block pinned in the block cache for its whole life.
@github-actions

Copy link
Copy Markdown

✅ Claude Code Review

Auto-triggered after CI passed — reviewing commit 1aab523


Summary

This is a well-executed replacement of the LOUDS trie index format with a new block-tree layout. The core format change (deleted ~8400 lines, added ~4300 lines) is accompanied by a solid MultiScan bug fix, a thoughtful ValidateOptions refactoring, and comprehensive documentation updates. The diff is truncated so the new trie.h/trie.cc could not be fully reviewed, but the visible changes are high quality.

High-severity findings (0):
No high-severity findings.

Full review (click to expand)

Findings

🟡 MEDIUM

M1. simple_external_table_factory.cc Prepare() may not handle the new Prepare(nullptr, 0) contract -- test_util/simple_external_table_factory.cc:150
  • Issue: The Prepare(nullptr, 0) reset contract is added to IndexFactoryIterator::Prepare(), and IndexFactoryIteratorWrapper now calls udi_iter_->Prepare(nullptr, 0) when scan_opts is null. However, SimpleExternalTableIterator::Prepare() at simple_external_table_factory.cc:150 stores a raw pointer (scan_options_ = scan_options) without checking for null. While ExternalTableIterator is a separate interface from IndexFactoryIterator, the doc change in index_factory.h establishes a new contract pattern. The ExternalTableIterator::Prepare interface at external_table.h:172 does not document the nullptr/0 reset semantics. This is not currently a bug (the two interfaces are independent), but the contract divergence is worth noting for consistency.
  • Suggested fix: Consider adding the nullptr/0 reset semantics to ExternalTableIterator::Prepare() doc for consistency, or add a note that the two interfaces have different contracts.
M2. TrieIndexFactory lacks ValidateOptions override in visible code -- utilities/trie_index/trie_index_factory.h
  • Issue: BlockBasedTableFactory::ValidateOptions() now calls user_defined_index_factory->ValidateOptions(db_opts, cf_opts) for non-kStandardOnly modes. The PR description says "The built-in trie rejects comparators other than BytewiseComparator in both places." However, the visible trie_index_factory.h and .cc show no ValidateOptions override. The base Configurable::ValidateOptions returns OK (no registered options). The ValidateOptions override must be in the truncated portion of the diff.
  • Root cause: Diff truncation prevents verification.
  • Suggested fix: Verify that TrieIndexFactory::ValidateOptions exists in the full diff and checks cf_opts.comparator != BytewiseComparator(). Without it, the comparator check only happens at NewBuilder() time, not at DB::Open().
M3. SetValidateFunc suppresses all generic validation for user_defined_index_factory -- block_based_table_factory.cc:427
  • Issue: The diff adds .SetValidateFunc(...) returning Status::OK() unconditionally. This means the generic Configurable::ValidateOptions traversal will never validate the factory's own registered options. The intent is correct and well-commented: BlockBasedTableFactory::ValidateOptions() takes over. But if someone later adds registered options to an IndexFactory subclass, those options would silently skip the generic validation path.
  • Suggested fix: The comment adequately documents intent. Consider noting that factory subclasses with registered options should validate them in their own ValidateOptions() override.
M4. DB mutex analysis: not affected
  • Issue: None of the changed code paths execute under DBImpl::mutex_. The BlockBasedTableFactory::ValidateOptions() runs during DB::Open() and CreateColumnFamily() before the DB is fully operational. The Prepare(nullptr) call runs during table iteration, not under the DB mutex. No regression.

🟢 LOW / NIT

L1. Release note is a single ~600-character line -- unreleased_history/behavior_changes/trie_index_format.md
  • Issue: Consider breaking into 2-3 sentences for readability in HISTORY.md.
L2. db_crashtest.py block_size lambda is well-tested -- tools/db_crashtest.py:2297
  • Issue: The test_trie_block_size_draw test at db_crashtest_test.py validates the lambda draws from {1024, 4096, 16384} over 60 iterations, checks that explicit --block_size wins, and that kStandardOnly keeps the default. Good coverage.

Cross-Component Analysis

Context Affected? Assessment
WritePreparedTxnDB No Trie operates at index block level, below transaction visibility
ReadOnly DB No Trie reader is read-only by design
User-defined timestamps Correctly guarded ValidateOptions rejects UDT with custom index in non-kStandardOnly
allow_mmap_reads Now supported New format reads in-place; block outlives reader
Concurrent writers Not affected Builder operates on single thread or ordered parallel protocol
FIFO / Universal compaction Not affected Compaction style doesn't change index format
Snapshots Correctly handled Seqno side-table handles same-user-key block selection

MultiScan Bug Fix Analysis

Root cause: ResetMultiScan() restores the original index_iter_, but the custom IndexFactoryIterator inside retains stale scan ranges from the previous Prepare(). Subsequent full scans are incorrectly bounded.

Fix: Prepare(nullptr) after CollectBlockHandles() clears the ranges. The placement after collection (regardless of success/failure) is correct -- ranges are only needed during the index walk. The IndexFactoryIteratorWrapper translates Prepare(nullptr) to udi_iter_->Prepare(nullptr, 0).

Positive Observations

  1. Clean format migration with version bumping and clear error messages for incompatible blocks
  2. Thorough bug documentation -- 5 specific LOUDS bugs enumerated and fixed by replacement
  3. Comprehensive benchmarking across multiple key shapes with isolated and through-DB measurements
  4. Minimal MultiScan fix addressing root cause without overreaching
  5. ValidateOptions refactoring correctly separates kStandardOnly (ignores factory) from other modes
  6. High-quality documentation in index_factory/index.md covering nuances like kCustomOnly unreadability, SetOptions() routing lag, and cache pinning behavior

ℹ️ About this response

Generated by Claude Code.
Review methodology: claude_md/ci_review_prompt.md

Limitations:

  • Claude may miss context from files not in the diff
  • Large PRs may be truncated
  • Always apply human judgment to AI suggestions

Commands:

  • /claude-review [context] — Request a code review
  • /claude-query <question> — Ask about the PR or codebase

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants