Skip to content

[MOD-13913] Add debug implementation for NumericRangeTree#8292

Merged
LukeMathWalker merged 1 commit intomasterfrom
numeric-range-tree-1-b-debug-repr
Feb 11, 2026
Merged

[MOD-13913] Add debug implementation for NumericRangeTree#8292
LukeMathWalker merged 1 commit intomasterfrom
numeric-range-tree-1-b-debug-repr

Conversation

@LukeMathWalker
Copy link
Collaborator

@LukeMathWalker LukeMathWalker commented Feb 6, 2026

Describe the changes in the pull request

Rust equivalent of the debug representation for NumericRangeTree provided by debug_commands.c.

Stacked on top #8276.

Main objects this PR modified

  1. ...

Mark if applicable

  • This PR introduces API changes
  • This PR introduces serialization changes

Release Notes

  • This PR requires release notes
  • This PR does not require release notes

If a release note is required (bug fix / new feature / enhancement), describe the user impact of this PR in the title.


Note

Medium Risk
Adds new FT.DEBUG reply generation paths for NumericRangeTree and changes the tree DFS iteration order, which could affect any caller relying on node traversal order; functionality is debug-only but touches core data structure iteration.

Overview
Adds Rust implementations for FT.DEBUG introspection of NumericRangeTree (NUMIDX_SUMMARY, DUMP_NUMIDX, DUMP_NUMIDXTREE), including optional per-range inverted-index headers and computed average memory-efficiency stats.

Updates inverted_index::debug::Summary to format its metrics into Redis replies, exposes numeric_range_tree::debug, and changes the tree iterator to ReversePreOrderDfsIterator (right-first traversal), with new insta-based snapshot integration tests and fixtures to lock the debug output format.

Written by Cursor Bugbot for commit 7a90827. This will update automatically on new commits. Configure here.

@codecov
Copy link

codecov bot commented Feb 6, 2026

Codecov Report

❌ Patch coverage is 98.87640% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.86%. Comparing base (ffb91c4) to head (7a90827).
⚠️ Report is 2 commits behind head on master.

Files with missing lines Patch % Lines
src/redisearch_rs/inverted_index/src/debug.rs 94.11% 0 Missing and 1 partial ⚠️
src/redisearch_rs/numeric_range_tree/src/debug.rs 99.33% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master    #8292      +/-   ##
==========================================
+ Coverage   82.82%   82.86%   +0.04%     
==========================================
  Files         403      405       +2     
  Lines       58449    58621     +172     
  Branches    16578    16750     +172     
==========================================
+ Hits        48410    48576     +166     
+ Misses       9874     9862      -12     
- Partials      165      183      +18     
Flag Coverage Δ
flow 84.07% <ø> (-0.11%) ⬇️
unit 50.93% <98.87%> (+0.13%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-rust branch from 9a7b195 to 4d02a30 Compare February 6, 2026 11:26
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch from 1c84fcd to 9db43f7 Compare February 6, 2026 11:26
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch from 9db43f7 to 1b9cd2f Compare February 6, 2026 11:40
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-rust branch from 4d02a30 to 853f01f Compare February 6, 2026 11:42
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch from 1b9cd2f to 0aef10b Compare February 6, 2026 11:42
@LukeMathWalker LukeMathWalker changed the title [MOD-13913] Add debug implementation for numeric_range_tree [MOD-13913] Add debug implementation for NumericRangeTree Feb 6, 2026
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch from 0aef10b to ad6b3fe Compare February 6, 2026 15:33
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-rust branch from 853f01f to 7e72e18 Compare February 6, 2026 16:07
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch 2 times, most recently from 8bef85f to a099cbf Compare February 6, 2026 16:31
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-rust branch from 7e72e18 to d8ccfc6 Compare February 6, 2026 16:31
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch from a099cbf to 67a358b Compare February 7, 2026 13:23
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-rust branch 2 times, most recently from 118d838 to dbac863 Compare February 7, 2026 13:26
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch from 67a358b to 937e999 Compare February 7, 2026 13:26
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-rust branch from dbac863 to c4fe674 Compare February 8, 2026 09:26
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch 2 times, most recently from 010f7d0 to e7bee69 Compare February 8, 2026 10:02
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-rust branch from c4fe674 to 63087b3 Compare February 8, 2026 10:02
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch 2 times, most recently from f685066 to b473dcb Compare February 9, 2026 12:58
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch from 9f591ad to 8fa02c0 Compare February 9, 2026 14:59
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-rust branch from e09782e to 06f9330 Compare February 9, 2026 14:59
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch from 8fa02c0 to 8042deb Compare February 9, 2026 15:03
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-rust branch from 06f9330 to 601f53a Compare February 9, 2026 15:03
@sonarqubecloud
Copy link

sonarqubecloud bot commented Feb 9, 2026

Base automatically changed from numeric-range-tree-1-rust to master February 9, 2026 17:09
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch 4 times, most recently from 4995446 to 2e87d70 Compare February 11, 2026 11:19
Copy link
Collaborator

@meiravgri meiravgri left a comment

Choose a reason for hiding this comment

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

Few comments

let mut reader = range.reader();
let mut result = RSIndexResult::numeric(0.0);
while reader.next_record(&mut result).unwrap_or(false) {
if result.doc_id != last_doc_id {
Copy link
Collaborator

Choose a reason for hiding this comment

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

why do we skip printing all multi index results?
Is there a test for multi value?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

If my understanding of the existing C code is correct, it does currently avoid to emit the same doc id multiple time.
It goes:

QueryIterator *iter = NewInvIndIterator_NumericQuery(range->entries, sctx, &fieldCtx, NULL, NULL, range->minVal, range->maxVal);
ReplyIteratorResultsIDs(iter, sctx->redisCtx);

which in turn invokes:

InitInvIndIterator(&numIt->base, INV_IDX_NUMERIC_ITERATOR, idx, NewNumericResult(), fieldCtx, sctx, &decoderCtx, NumericCheckAbort);

which in turn uses this helper to decide if it should skip multi-values:

// Returns true if the iterator should skip multi-values from the same document
static inline bool ShouldSkipMulti(const InvIndIterator *it) {
  return IndexReader_HasMulti(it->reader); // The index holds multi-values (if not, no need to check)
}

which basically always evaluates to "skip multivalues in read, just don't bother checking if there are no multivalues".

I guess the reasoning goes as follows: we are only returning the doc ids, without their values, so what's the point of printing the same doc id N times?
I'm happy to change it, but I assume this will be a user-visible change if the debug commands are exposed?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Changed it to include all ids.

}

/// Reply with inverted index header information (adds 1 element to parent).
fn reply_inverted_index_header(parent: &mut ArrayBuilder<'_>, entries: &NumericIndex) {
Copy link
Collaborator

Choose a reason for hiding this comment

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

consider moving to a general inverted index debug file. it essentially implements
debug_commands.c

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Converted this into a method on the Summary itself.

}

/// Reply with debug info for an inverted index.
fn reply_inverted_index_debug(
Copy link
Collaborator

Choose a reason for hiding this comment

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

This function as well can be move to inverted index debug file

Copy link
Collaborator Author

@LukeMathWalker LukeMathWalker Feb 11, 2026

Choose a reason for hiding this comment

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

That was my first instinct too, but this is actually specific to a numeric index since it makes two specific assumptions:

  • All entries are numeric
  • And the index is tracking the number of entries explicitly (i.e. it uses our EntriesTrackingIndex wrapper around the "bare" index)

It is not used for anything else, and in fact, its C counterpart gets deleted in #8306.

Copy link
Collaborator

Choose a reason for hiding this comment

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

so lets rename it

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Changed to reply_numeric_index_debug 👍🏻

@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch from 2e87d70 to 285e614 Compare February 11, 2026 13:43
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch from 285e614 to 81b786b Compare February 11, 2026 14:32
@LukeMathWalker LukeMathWalker force-pushed the numeric-range-tree-1-b-debug-repr branch from 81b786b to ea3d05c Compare February 11, 2026 14:39
Copy link

@cursor cursor bot left a comment

Choose a reason for hiding this comment

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

Cursor Bugbot has reviewed your changes and found 1 potential issue.

let mut reader = range.reader();
let mut result = RSIndexResult::numeric(0.0);
while reader.next_record(&mut result).unwrap_or(false) {
entries_arr.long_long(result.doc_id as i64);
Copy link

Choose a reason for hiding this comment

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

Multi-value doc IDs returned repeatedly

Medium Severity

debug_dump_index emits IDs via range.reader() in reply_range_entries, which returns every numeric entry. Unlike the C DUMP_NUMIDX path, this bypasses iterator logic that skips duplicate IDs for multi-value docs. Multi-valued documents are therefore repeated, producing a different command output shape and inconsistent counts against numDocs.

Additional Locations (1)

Fix in Cursor Fix in Web

meiravgri
meiravgri previously approved these changes Feb 11, 2026
}

/// Reply with debug info for an inverted index.
fn reply_inverted_index_debug(
Copy link
Collaborator

Choose a reason for hiding this comment

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

so lets rename it

@sonarqubecloud
Copy link

@LukeMathWalker LukeMathWalker added this pull request to the merge queue Feb 11, 2026
Merged via the queue into master with commit a10d3ae Feb 11, 2026
50 checks passed
@LukeMathWalker LukeMathWalker deleted the numeric-range-tree-1-b-debug-repr branch February 11, 2026 17:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants