Repository navigation
Conversation
|
| 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]
cd9b272 to
a4d2c11
Compare
Claude Code Review - OBSOLETESuperseded by a newer AI review. Expand to see the original review.✅ Claude Code ReviewAuto-triggered after CI passed — reviewing commit a4d2c11 SummaryThis 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):
Full review (click to expand)Findings🔴 HIGHH1:
H2: At H3: No unknown flags rejection (existing bug, fixed by PR) Current 🔶 MEDIUMM1: Per CLAUDE.md, defaulted parameters are the "#1 trap on refactoring." The change from M2: Format version dispatch asymmetry (write vs. read)
M3: The extraction of scan bound checking from M4: db_crashtest.py module-level random choices reduce per-invocation coverage diversity
M5: Relaxed atomics in
⚪ LOW / OBSERVATIONSL1: Empty key fix is correct The L2: ~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 L4: Good defense-in-depth. Prevents crafted input from causing oversized vector allocations that could OOM the process during SST open. Cross-Component Analysis
Test Coverage AssessmentThe PR should include tests for:
Behavioral CompatibilityNo breaking behavioral changes for existing users:
ℹ️ About this responseGenerated by Claude Code. Limitations:
Commands:
|
a4d2c11 to
30ff02b
Compare
339b04d to
5942de8
Compare
Claude Code Review - OBSOLETESuperseded by a newer AI review. Expand to see the original review.✅ Claude Code ReviewAuto-triggered after CI passed — reviewing commit 5942de8 SummaryThis 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):
Full review (click to expand)Findings🔴 HIGHH1. Missing
|
| 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
0a8e540 to
f6c034c
Compare
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.
f6c034c to
4be1067
Compare
|
@xingbowang has imported this pull request. If you are a Meta employee, you can view this in D129647129. |
pdillinger
left a comment
There was a problem hiding this comment.
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"] = 0The 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.
|
Thanks, this was useful. Everything is addressed in 74fe042, and the summary is updated. Old trie blocks: NotSupportedDone, 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. 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. BenchmarksThey'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 timeIt 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:
Init on that index went from 26-28 us to 5-8 us; most of what's left is the trie walk. With mmap_readThe 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.
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 notesThere'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. |
- 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.
74fe042 to
607785c
Compare
|
A few minor bugs and some readability improvement suggestions.
Re-seeking to the key this iterator just returned lands on the wrong block.
Example: separators RocksDB's own Suggested fix: in
Upgrade advice is wrong for SSTs written in The note says old trie SSTs "fall back to the standard index in I checked this with SSTs written by the old code:
Released versions cannot produce such files, but main-branch users who tried
Readability (the hardest part to follow). To understand what a floor or ceiling Suggestions:
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 Also, "so there is no file size limit" is a bit too strong: 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."
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, 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
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 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
Readability: "layout is words << 6 | width: ..." is one long sentence with three ideas. 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."
Readability: one concept has two names. A distinct separator is called a "key" here ( Suggestion: use "separator" in names (
Readability: 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."
Readability: understanding 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)."
Readability (minor): "Finish may upgrade this to true ..." Suggestion: rename it to
Readability (minor):
Readability (minor): Suggestion:
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."
Readability (minor): "warn" becomes "log" here, and a new paragraph about when a factory's
Optional: the serial |
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: General comment, issues and readabilityGeneral PR commentThanks 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.
|
- 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.
Claude Code Review - OBSOLETESuperseded by a newer AI review. Expand to see the original review.✅ Claude Code ReviewAuto-triggered after CI passed — reviewing commit 9ee968b SummaryThis 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 High-severity findings (0): Full review (click to expand)Findings🟡 MEDIUMM1.
|
| 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().
|
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 keyConfirmed and fixed. New tests, all red before the fix:
kCustomOnly upgrade adviceThe 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. Other factories in kStandardOnlyRight, 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. CommentsThese were wrong or stale and are fixed:
The description also lists the doc-only edits and no longer says "evenly spaced". ReadabilityAll of these are in e989472. The format didn't change, and
|
Claude Code Review - OBSOLETESuperseded by a newer AI review. Expand to see the original review.✅ Claude Code ReviewAuto-triggered after CI passed — reviewing commit e989472 SummaryThis 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 High-severity findings (0): No high-severity findings. Full review (click to expand)Findings🔴 HIGHNo high-severity findings. 🟡 MEDIUMM1.
|
| 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
Corruptionfor any malformed data rather than crashing. The 22M-case fuzzer result is reassuring. - Clean separation.
trie.h/trie.ccis a pure data structure with no RocksDB-specific dependencies beyondStatus,Slice, and coding utilities.trie_index_factory.ccis the adapter layer. This makes the trie independently testable and maintainable. - Parallel compression support. The
PrepareAddEntry/FinishAddEntrysplit 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 theindex_factory.hcontract 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.
Claude Code Review - OBSOLETESuperseded by a newer AI review. Expand to see the original review.✅ Claude Code ReviewAuto-triggered after CI passed — reviewing commit 629add8 SummaryWell-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): Full review (click to expand)Findings🔴 HIGHNo high-severity findings. 🟡 MEDIUMM1.
|
| 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.
✅ Claude Code ReviewAuto-triggered after CI passed — reviewing commit 1aab523 SummaryThis 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 High-severity findings (0): Full review (click to expand)Findings🟡 MEDIUMM1.
|
| 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
- Clean format migration with version bumping and clear error messages for incompatible blocks
- Thorough bug documentation -- 5 specific LOUDS bugs enumerated and fixed by replacement
- Comprehensive benchmarking across multiple key shapes with isolated and through-DB measurements
- Minimal MultiScan fix addressing root cause without overreaching
- ValidateOptions refactoring correctly separates kStandardOnly (ignores factory) from other modes
- High-quality documentation in
index_factory/index.mdcovering 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 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:
DB::Openaccepts a non-bytewise comparator, and then every flush failsFixing 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_readoff 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, soDB::Open()andCreateColumnFamily()fail up front instead of every flush failing later.SetOptions()doesn't run that validation yet; #15582 fixes that.kStandardOnlyignores the factory, so it still works with any comparator. That applies to every custom factory: itsValidateOptions()now runs only in modes that use it, where before the generic option validation ran it inkStandardOnlytoo.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_modechange only reaches SSTs opened afterwards. Other doc-only edits: the docs now say when a factory'sValidateOptions()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(),BlockBasedTableIteratorput 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, withPrepare(nullptr), which reaches a custom index asPrepare(nullptr, 0);index_factory.hdocuments that this drops the ranges.How to read this diff
You can skip the deleted
louds_trie.*andbitvector.*.utilities/trie_index/trie.h(the format) andtrie_index_factory.h(how RocksDB uses it).AppendColumn,Trie::Column::InitandTrie::Column::Getintrie.cc.TrieWriterandTrieIterator::Node.TrieBuilder::AddBlock,TrieBuilder::FinishandSizeBound.Trie::Parse,ValidateSideTablesandValidateTrie.TrieIteratorclass comment walks through a Seek. ThenSeek,Descend,SpellHead,ScanBucket,EnterSeparator,ApplyTag,NextSeparatorandPrev.trie_index_factory.{h,cc}, mainlyBlockTag,PrepareAddEntryandFinishAddEntry(the serialAddIndexEntryruns both), andValidateOptions.block_based_table_factory.cc,block_based_table_iterator.ccanduser_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.ccandtrie_index_db_test.cc.Compatibility
This is a one-way door for any DB that writes SSTs with the trie. DBs without
TrieIndexFactory, or runningkStandardOnly, aren't affected. The block keeps the old magic but bumps the version to 2.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:
rand16is 16 random bytes,uuida textual UUIDv4,urlreversed host + path + id,tsdbseries id + tag hash + timestamp, anddbintdb_bench's--key_size=48 --prefix_size=32 --keys_per_prefix=100.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:
dbint, and 3-5% bigger on long URL-like keys with 16 KiB blocksThrough the DB
Release db_bench on the same laptop:
fillrandomof 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 byreadseq. Writes are the median of 2 runs, everything else of 3.The two no-trie runs were 5% apart, so only the compaction CPU of building both indexes in kStandardDefault (about 3%) looks real.
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: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) andtable_testpass, also withASSERT_STATUS_CHECKED=1. By area:RandomizedRunsTagsAndSizes, which also re-seeks throughkey(), plusSeekToOwnKeyandSeekToResultKeyfor a Seek to the key the iterator just returned or to bytes inside itGoldenBytes,RejectsOtherVersions,MalformedIndexIsRejectedOrReadable,NewReaderWithCorruptedDataLargeRun,MixedSameKeyRuns,TagsRandomizedBlockHandlesPast32Bits,EstimatedSizeBoundsSerializedTrie,EstimatedSizeBoundsExtremeHandles,ParallelMatchesSerialOutputEmptyUserKey,OpenRejectsNonBytewiseComparator,StandardOnlyIgnoresTrieComparatorRequirement,OtherTrieVersionFallsBackOrFails(an old-version block in every mode, including an SST written in kCustomOnly, which no mode can open),MmapReads(trie reads withallow_mmap_readsacross table cache evictions, compaction and reopen), andIteratorAfterMultiScanIgnoresScanRanges(a full scan afterSeekToLast()leaves a MultiScan)test_trie_block_size_drawindb_crashtest_test.pydb_crashtest.py blackbox --simple --use_trie_index=1 --mmap_read=1ran 15 minutes each in index modes 1 and 3, with mmap on in all 32 invocations.