fix(hgraph): expose skip_ratio and skip_strategy search parameters by LHT129 · Pull Request #2367 · antgroup/vsag

LHT129 · 2026-06-29T11:34:03Z

Summary

Expose skip_ratio and skip_strategy as configurable search parameters for HGraph index. Previously these were hardcoded defaults (skip_ratio=0.8F) with no way for users to override via the public JSON search parameter API.

Changes

Add skip_ratio and skip_strategy_type fields to HGraphSearchParameters
Parse skip_ratio and skip_strategy from JSON in HGraphSearchParameters::FromJson()
Pass values to InnerSearchParam in both KnnSearch (iterator) and SearchWithRequest paths
Add unit tests for parameter parsing
Update index_parameters.md documentation (zh/en)

Default values

skip_ratio: 0.8F (matches InnerSearchParam default, backward compatible)
skip_strategy_type: DETERMINISTIC_ACCUMULATIVE

Breaking Change: skip_ratio semantics inverted

The skip_ratio parameter semantics have been inverted to match the parameter name.

Before: skip_ratio=0.8 meant visit 80% of invalid points.
After: skip_ratio=0.2 means skip 20% of invalid points (visit 80%).

Default values changed: HGraph 0.8 to 0.2, HNSW 0.9 to 0.1.

If using custom skip_ratio values, change to (1 - old_value) to maintain same behavior.

mergify · 2026-06-29T11:34:42Z

Merge Protections

🟢 All 3 merge protections satisfied — ready to merge.

Show 3 satisfied protections

🟢 Require kind label

label~=^kind/

🟢 Require version label

label~=^version/

🟢 Require linked issue for feature/bug PRs

body~=(?im)(?:^|[\s\-\*])(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s*:?\s+(?:#\d+|[\w.\-]+/[\w.\-]+#\d+|https?://github\.com/[\w.\-]+/[\w.\-]+/issues/\d+)

gemini-code-assist

Code Review

This pull request introduces two new filter-related search parameters for hgraph: skip_ratio and skip_strategy. It includes updates to the English and Chinese documentation, JSON parsing logic, parameter mapping during search, and corresponding unit tests. The review feedback highlights that the documentation for skip_ratio is currently backwards and needs correction. Additionally, it is recommended to add range validation for skip_ratio to ensure it remains within [0.0, 1.0], along with unit tests to verify that out-of-range values are properly rejected.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

Copilot

Pull request overview

Expose HGraph’s previously internal filter-skip controls as user-configurable search parameters, enabling tuning of filtered-search speed/recall trade-offs via JSON search params.

Changes:

Add skip_ratio and skip_strategy_type to HGraphSearchParameters with defaults aligned to existing behavior.
Parse skip_ratio / skip_strategy from JSON and propagate them into InnerSearchParam for both KnnSearch and SearchWithRequest.
Add unit tests and update EN/ZH index-parameter documentation.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/algorithm/hgraph/hgraph_search.cpp	Plumbs new skip parameters into `InnerSearchParam` for HGraph search paths.
src/algorithm/hgraph/hgraph_parameter.h	Adds search-parameter fields and includes skip-strategy type definition.
src/algorithm/hgraph/hgraph_parameter.cpp	Parses new JSON parameters into `HGraphSearchParameters`.
src/algorithm/hgraph/hgraph_parameter_test.cpp	Adds unit tests for new parameter parsing defaults and overrides.
docs/docs/zh/src/resources/index_parameters.md	Documents new HGraph filter-related search parameters (ZH).
docs/docs/en/src/resources/index_parameters.md	Documents new HGraph filter-related search parameters (EN).

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 12 comments.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 7 comments.

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

wxyucs

lgtm

vsag-bot · 2026-07-06T07:20:24Z

/label S-waiting-on-review
/waiting-on reviewer
/request-review @jiaweizone
/request-review @inabao

mergify · 2026-07-06T09:35:21Z

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

Queue this pull request

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Expose skip_ratio and skip_strategy as configurable search parameters for HGraph index. These parameters control the filter skip strategy during graph traversal, allowing users to tune the trade-off between search speed and recall when using filters. Key changes: - Add skip_ratio and skip_strategy_type fields to HGraphSearchParameters - Parse these parameters from JSON in FromJson() - Add validation for skip_ratio range [0.0, 1.0] - Pass parameters to InnerSearchParam in both KnnSearch and SearchWithRequest paths - Invert skip_ratio semantics to match parameter name meaning: skip_ratio now means "what percentage of invalid points to skip" - Remove special case for valid_ratio==1.0 in get_retain_ratio - Add unit tests for parameter parsing and validation - Update documentation (zh/en) with correct default value (0.2) skip_ratio semantics (after inversion): - skip_ratio=0.2 (default): skip 20% of invalid points - retain_ratio = (1 - valid_ratio) * (1 - skip_ratio) - visit_ratio = valid_ratio + retain_ratio The underlying skip mechanism was already supported in BasicSearcher/ ParallelSearcher since v0.17.0, but was never exposed through the public API for HGraph. This change maintains backward compatibility by using the same default value (0.2) that was previously hardcoded. Fixes: antgroup#2368 Signed-off-by: LHT129 <tianlan.lht@antgroup.com> Assisted-by: opencode:qwen3.7-plus

Copilot AI review requested due to automatic review settings June 29, 2026 11:34

LHT129 requested review from inabao, jiaweizone and wxyucs as code owners June 29, 2026 11:34

pull-request-size Bot added the size/M label Jun 29, 2026

LHT129 added kind/feature Brand-new functionality or capabilities 引入全新的功能、新特性或新能力 version/1.0 labels Jun 29, 2026

Copilot started reviewing on behalf of LHT129 June 29, 2026 11:34 View session

mergify Bot added the module/docs label Jun 29, 2026

gemini-code-assist Bot reviewed Jun 29, 2026

View reviewed changes

Comment thread docs/docs/en/src/resources/index_parameters.md Outdated

Comment thread docs/docs/zh/src/resources/index_parameters.md Outdated

Comment thread src/algorithm/hgraph/hgraph_parameter.cpp

Comment thread src/algorithm/hgraph/hgraph_parameter_test.cpp

Copilot AI reviewed Jun 29, 2026

View reviewed changes

Comment thread src/algorithm/hgraph/hgraph_parameter.cpp

Comment thread docs/docs/en/src/resources/index_parameters.md Outdated

Comment thread docs/docs/zh/src/resources/index_parameters.md Outdated

Comment thread src/algorithm/hgraph/hgraph_parameter_test.cpp Outdated

LHT129 added kind/bug Bug fixes, defects, or unexpected behavior 修复程序错误、缺陷或异常行为 and removed kind/feature Brand-new functionality or capabilities 引入全新的功能、新特性或新能力 labels Jun 29, 2026

LHT129 self-assigned this Jun 29, 2026

This was referenced Jun 29, 2026

fix(hgraph): expose skip_ratio and skip_strategy search parameters (v0.18 backport) #2369

Open

fix(hgraph): expose skip_ratio and skip_strategy search parameters (v0.17 backport) #2370

Open

LHT129 force-pushed the lht/hgraph-skip-ratio branch from 1aa08c2 to 1e00909 Compare June 29, 2026 12:48

LHT129 changed the title ~~feat(hgraph): expose skip_ratio and skip_strategy search parameters~~ fix(hgraph): expose skip_ratio and skip_strategy search parameters Jun 29, 2026

LHT129 force-pushed the lht/hgraph-skip-ratio branch from 1e00909 to fab41d0 Compare June 29, 2026 12:50

Copilot AI review requested due to automatic review settings June 30, 2026 02:39

mergify Bot added the module/index label Jun 30, 2026

Copilot started reviewing on behalf of LHT129 June 30, 2026 02:52 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 30, 2026 03:44

pull-request-size Bot added size/L and removed size/M labels Jun 30, 2026

LHT129 force-pushed the lht/hgraph-skip-ratio branch from b5ad01b to 5655bef Compare June 30, 2026 03:44

Copilot started reviewing on behalf of LHT129 June 30, 2026 03:50 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 1, 2026 02:14

Copilot AI reviewed Jul 1, 2026

Copilot started reviewing on behalf of LHT129 July 1, 2026 02:54 View session

LHT129 force-pushed the lht/hgraph-skip-ratio branch from 549d2dc to ef3b07f Compare July 2, 2026 02:49

Copilot AI review requested due to automatic review settings July 2, 2026 02:52

LHT129 force-pushed the lht/hgraph-skip-ratio branch from ef3b07f to ce1d6e5 Compare July 2, 2026 02:52

Copilot started reviewing on behalf of LHT129 July 2, 2026 02:58 View session

Copilot AI reviewed Jul 2, 2026

View reviewed changes

LHT129 force-pushed the lht/hgraph-skip-ratio branch from ce1d6e5 to 2c38390 Compare July 2, 2026 03:06

Copilot AI review requested due to automatic review settings July 2, 2026 03:15

LHT129 force-pushed the lht/hgraph-skip-ratio branch from 2c38390 to e3f881d Compare July 2, 2026 03:15

Copilot AI reviewed Jul 2, 2026

View reviewed changes

Copilot started reviewing on behalf of LHT129 July 2, 2026 03:48 View session

wxyucs approved these changes Jul 2, 2026

View reviewed changes

LHT129 force-pushed the lht/hgraph-skip-ratio branch from e3f881d to b272a8b Compare July 6, 2026 07:20

Copilot AI review requested due to automatic review settings July 7, 2026 02:28

LHT129 force-pushed the lht/hgraph-skip-ratio branch from b272a8b to ba8caa6 Compare July 7, 2026 02:28

Copilot started reviewing on behalf of LHT129 July 7, 2026 02:29 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

Comment thread src/utils/filter_search_skip_strategy.cpp

Comment thread src/index/hnsw_zparameters.h Outdated

Comment thread src/algorithm/hgraph/hgraph_parameter_test.cpp Outdated

LHT129 force-pushed the lht/hgraph-skip-ratio branch from ba8caa6 to 8759f2e Compare July 7, 2026 03:15

Copilot AI review requested due to automatic review settings July 7, 2026 03:16

LHT129 force-pushed the lht/hgraph-skip-ratio branch from 8759f2e to 2456f49 Compare July 7, 2026 03:16

Copilot started reviewing on behalf of LHT129 July 7, 2026 03:24 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

Comment thread docs/docs/en/src/indexes/hgraph.md Outdated

Comment thread docs/docs/zh/src/indexes/hgraph.md Outdated

Comment thread src/impl/inner_search_param.h

LHT129 force-pushed the lht/hgraph-skip-ratio branch from 2456f49 to 92ad37f Compare July 7, 2026 03:53

LHT129 merged commit 25493b1 into antgroup:main Jul 7, 2026
20 checks passed

LHT129 deleted the lht/hgraph-skip-ratio branch July 7, 2026 06:01

Uh oh!

Conversation

LHT129 commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Default values

Breaking Change: skip_ratio semantics inverted

Uh oh!

mergify Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Protections

🟢 Require kind label

🟢 Require version label

🟢 Require linked issue for feature/bug PRs

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

LHT129 commented Jun 29, 2026 •

edited

Loading

mergify Bot commented Jun 29, 2026 •

edited

Loading

vsag-bot commented Jul 6, 2026 •

edited

Loading