Skip to content

docs(search): correct the 15.8 rank fusion page against the implementation - #474

Merged
marevol merged 1 commit into
masterfrom
docs-15.8-rank-fusion-accuracy
Aug 9, 2026
Merged

docs(search): correct the 15.8 rank fusion page against the implementation#474
marevol merged 1 commit into
masterfrom
docs-15.8-rank-fusion-accuracy

Conversation

@marevol

@marevol marevol commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Reviewed 15.8/config/rank-fusion.rst against the implementation (RankFusionProcessor, SemanticChunkSearcher, FessConfigImpl, SystemHelper, fess_rankfusion.xml, fess_config.properties) and corrected it, then propagated the result to all seven languages.

The page's own reference table already documented the window_size lower bound correctly, but the troubleshooting section then told readers to set a value that violates it — so the most actionable instruction on the page silently did nothing. That is the main fix here.

Corrections

Documented Implementation
rank.fusion.window_size "reduce it", with rank.fusion.window_size=100 as the example init() raises the value to paging.search.page.max.size * 2 (200 by default) and logs a WARN. Since 200 is also window_size's own default, the default configuration cannot lower it at all. The page now shows paging.search.page.max.size and rank.fusion.window_size set together, and states the page-size trade-off.
rank.fusion.threads availableProcessors × 1.5 + 1 availableProcessors() * 3 / 2 + 1, integer arithmetic (5 cores gives 8, not 8.5), sizing a fixed thread pool.
content_chunker.search.enabled shown as if it belonged in fess_config.properties resolved through getSystemProperty, so it comes from conf/system.properties or -Dfess.system.<key>. Writing it in fess_config.properties has no effect, and it is only evaluated at startup.
rank.fusion.searchers "a JVM option, not fess_config.properties" read with a raw System.getProperty, so the -Dfess.config. / -Dfess.system. prefixed forms do not work either. The fess.in.sh snippet now uses the FESS_JAVA_OPTS form instead of a bare -D line, and the page notes that the "System Property" field under System > General can set it too, since SystemHelper promotes arbitrary keys from it via System.setProperty.

Additions

These all exist in the code but were undocumented:

  • Verifying fusion results — the searcher and rf_score fields, that both are added at search time and never stored in the index, and that seeing them in /api/v2/search requires query.additional.api.response.fields=rf_score,searcher plus a restart. Without this there was no documented way to tell whether hybrid search was actually running, which is what the troubleshooting section needs first.
  • Impact on hit counts — fusion adds the documents only the non-main searchers found to the reported total, and skips that correction when the count is a lower bound. This means enabling hybrid search changes the displayed hit count.
  • Behavior when a searcher fails — a failing searcher degrades to an empty result with a WARN and fusion continues, except for InvalidQueryException and ResultOffsetExceededException, and except on deep pages, where the fallback path calls the main searcher without exception handling. There is no per-searcher timeout.
  • When settings take effect — all four rank.fusion.* settings require a restart, because FessConfigImpl memoizes fess_config.properties values for the lifetime of the JVM. Being read per request is not the same as being reloadable.
  • RRF is fixed: no algorithm switch and no per-searcher weighting, so rank.fusion.rank_constant is the only ranking knob.
  • Troubleshooting now starts from the searcher field and the semantic-skip conditions (cross-referencing search-semantic), and the deep-page boundary is stated concretely as "from the 101st result onward".

Verification

  • All 7 languages parse cleanly under docutils, with identical section trees and directive counts.
  • The ASCII search-flow diagram is byte-identical to the previous revision in every language.
  • Untouched paragraphs were preserved verbatim, so each translation's diff maps hunk-for-hunk onto the Japanese one.
  • Checked against the other 15.8 pages: search-semantic.rst (all languages) and properties.rst do not contradict any of the corrected statements.

…ation

Verified ja/15.8/config/rank-fusion.rst against RankFusionProcessor,
SemanticChunkSearcher, FessConfigImpl, SystemHelper, fess_rankfusion.xml and
fess_config.properties, then propagated the result to the other six languages.

Corrections:

- The troubleshooting sections recommended lowering rank.fusion.window_size
  to 100. init() clamps the value to paging.search.page.max.size * 2, which
  is 200 by default -- the same as window_size's own default. The suggested
  value was therefore silently raised back to 200. The page now states that
  paging.search.page.max.size has to be lowered first, and shows both keys
  together.
- rank.fusion.threads is computed as availableProcessors * 3 / 2 + 1 with
  integer arithmetic, not "cores x 1.5 + 1"; it sizes a fixed thread pool.
- content_chunker.search.enabled is a system property (conf/system.properties
  or -Dfess.system.<key>), not a fess_config.properties key, and it is only
  evaluated at startup.
- rank.fusion.searchers is read with a raw System.getProperty, so the
  -Dfess.config. / -Dfess.system. prefixed forms do not work. The fess.in.sh
  snippet now uses the FESS_JAVA_OPTS form. It can also be set from the
  "System Property" field under System > General, which promotes arbitrary
  keys via System.setProperty.

Added:

- Verifying fusion results: the searcher and rf_score fields, that both are
  runtime-only and absent from the index, and that seeing them in
  /api/v2/search requires query.additional.api.response.fields.
- Impact on hit counts: fusion adds the documents only the non-main searchers
  found to the reported total, and skips that correction when the count is a
  lower bound.
- Behavior when a searcher fails: a failing searcher degrades to an empty
  result with a WARN and fusion continues, except for InvalidQueryException
  and ResultOffsetExceededException, and except on deep pages, where the
  fallback path has no exception handling. There is no per-searcher timeout.
- All four rank.fusion.* settings require a restart, because FessConfigImpl
  memoizes fess_config.properties values for the lifetime of the JVM.
- RRF is fixed, with no algorithm switch and no per-searcher weighting.
- Troubleshooting now starts from the searcher field and the semantic-skip
  conditions.
@marevol
marevol merged commit 719946a into master Aug 9, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant