MOD-10798: Support K Ratio argument in FT.HYBRID vector query by nafraf · Pull Request #8227 · RediSearch/RediSearch

nafraf · 2026-01-30T14:24:08Z

Describe the changes in the pull request

Support K Ratio argument in FT.HYBRID vector query, as part of KNN clause.

[KNN <count-tokens>]
   K <topk-k>
   [EF_RUNTIME <ef-value>]
   [YIELD_DISTANCE_AS <distance_field>]
   [SHARD_K_RATIO <shard-k-ratio-value>]

Main objects this PR modified

...

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

Note

Medium Risk
Touches hybrid parsing and distributed command construction, which can affect query correctness/performance in clustered execution. Risk is mitigated by explicit validation and extensive new unit/integration tests.

Overview
Adds support for the new optional SHARD_K_RATIO argument (since 8.6.1) in FT.HYBRID KNN queries, allowing distributed executions to request fewer candidates per shard (while still guaranteeing enough results overall).

The coordinator now computes an effective per-shard K from the ratio and shard count, rewrites the distributed VSIM KNN K value accordingly, and makes shard-count access thread-safe by capturing it in the concurrent command context. Validation and duplicate detection for SHARD_K_RATIO (and improved duplicate handling for YIELD_SCORE_AS) are added, with expanded C++ and new Python tests covering parsing, error cases, and cluster profile behavior.

^{Written by Cursor Bugbot for commit 3436088. This will update automatically on new commits. Configure here.}

codecov · 2026-01-30T23:23:29Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.89%. Comparing base (311afdb) to head (3436088).
⚠️ Report is 48 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #8227      +/-   ##
==========================================
- Coverage   83.00%   82.89%   -0.11%     
==========================================
  Files         389      414      +25     
  Lines       57556    58815    +1259     
  Branches    15708    16873    +1165     
==========================================
+ Hits        47772    48757     +985     
- Misses       9625     9877     +252     
- Partials      159      181      +22

Flag	Coverage Δ
flow	`84.24% <97.05%> (+<0.01%)`	⬆️
unit	`51.07% <80.88%> (+0.65%)`	⬆️

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.

Itzikvaknin

Looks good, left a few comments

Itzikvaknin · 2026-02-04T09:25:59Z

-    if (parseYieldScoreClause(ac, pvd, status) != REDISMODULE_OK) {
-      goto error;
+  // Check for optional YIELD_SCORE_AS detecting duplicate arguments
+  while (!AC_IsAtEnd(ac)) {


Is this while loop required?

It detects duplicate YIELD_SCORE_AS, in this example:

... "SEARCH", "hello", "VSIM", "@vector", "$BLOB", "KNN", "2", "K", "10", "YIELD_SCORE_AS", "dist1", "YIELD_SCORE_AS", "dist2", ...

Without the loop, the error is reported as: "YIELD_SCORE_AS: Unknown argument"
With the loop: "Duplicate YIELD_SCORE_AS argument"

Itzikvaknin

a few minor comments

Itzikvaknin

Minor comments

…naming conventions

sonarqubecloud · 2026-02-16T17:42:52Z

Quality Gate passed

Issues
8 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

nafraf · 2026-02-17T00:19:44Z

/backport

redisearch-backport-pull-request · 2026-02-17T00:20:00Z

Backport failed for 8.4, because it was unable to cherry-pick the commit(s).

Please cherry-pick the changes locally and resolve any conflicts.

git fetch origin 8.4
git worktree add -d .worktree/backport-8227-to-8.4 origin/8.4
cd .worktree/backport-8227-to-8.4
git switch --create backport-8227-to-8.4
git cherry-pick -x d7ac7d333dfa3824f925094ad585c65560294dd4

redisearch-backport-pull-request · 2026-02-17T00:20:02Z

Backport failed for 8.6, because it was unable to cherry-pick the commit(s).

Please cherry-pick the changes locally and resolve any conflicts.

git fetch origin 8.6
git worktree add -d .worktree/backport-8227-to-8.6 origin/8.6
cd .worktree/backport-8227-to-8.6
git switch --create backport-8227-to-8.6
git cherry-pick -x d7ac7d333dfa3824f925094ad585c65560294dd4

(cherry picked from commit d7ac7d3)

…tor query (#8227) (cherry picked from commit d7ac7d3)

…tor query (#8227) (#8399) MOD-10798: Support K Ratio argument in FT.HYBRID vector query (#8227) (cherry picked from commit d7ac7d3)

…tor query (#8400) * [8.4] MOD-14094, MOD-10798: Support K Ratio argument in FT.HYBRID vector query (#8227) (cherry picked from commit d7ac7d3) * Fix "since" field in commands.json Co-authored-by: Omer Shadmi <[email protected]> * Update "since" field for SHARD_K_RATIO in FT.HYBRID command to 8.4.7 --------- Co-authored-by: Omer Shadmi <[email protected]>

github-actions Bot added the size:L label Jan 30, 2026

nafraf marked this pull request as ready for review January 30, 2026 22:56

cursor Bot reviewed Jan 30, 2026

View reviewed changes

Comment thread src/coord/hybrid/dist_hybrid.c Outdated

nafraf marked this pull request as draft January 31, 2026 06:53

github-actions Bot added the size:XL label Jan 31, 2026

nafraf marked this pull request as ready for review January 31, 2026 19:17

nafraf requested a review from oshadmi January 31, 2026 21:02

oshadmi requested a review from Itzikvaknin February 2, 2026 13:03