Quartz 5

Invariant — jDisc Searchers Must Remain Stateless Singletons and Defer Summary Fill

Properties23
doc_idGDN-CLAIM-0002
sluginv-jdisc-searcher-stateless-fill-discipline
titleInvariant — jDisc Searchers Must Remain Stateless Singletons and Defer Summary Fill
roleinvariant
lifecycle_stateactive
maturitygrowing
verificationmachine-checked
confidencehigh
evidence_strengthdirect
dispositionadopt
seductive_wrong_takeawayStoring per-query mutable state on a Searcher instance field or calling execution.fill(result) before top-K hit trimming to inspect document summary fields.
falsificationInspect vespa/container-search/src/main/java/com/yahoo/search/Searcher.java and Execution.java: concurrent worker threads share the same Searcher instance simultaneously, and early execution.fill(result) triggers full docsum RPCs for every unpruned candidate hit.
do_not_import_boundaryDo not import request-scoped bean assumptions into OSGi Component/Searcher subclasses in vespa/container-search or vespa/docproc.
sourcesvespa/container-search, vespa/jdisc_core, vespa/component, documentation/en/searcher-development.html
indexed-byGDN-NOTE-0001, GDN-NOTE-0002
relatedGDN-NOTE-0002, GDN-NOTE-0009, GDN-NOTE-0014, GDN-EVID-0001
supported-byGDN-NOTE-0014, GDN-EVID-0001
created2026-10-27
updated2026-10-27
producersgardener@wave9
owner_loopgardener
tagsinvariant, jdisc, container-search, searcher, concurrency, fill
modified2026-10-27

1 min read

Invariant — jDisc Searchers Must Remain Stateless Singletons and Defer Summary Fill

Every com.yahoo.search.Searcher in container-jdisc is instantiated once per configured search chain generation and invoked concurrently by hundreds of request threads; all per-query mutable state must reside in Query, Result, or Execution.context(), and execution.fill(result, summaryClass) must be deferred until after global top-K windowing (offset + hits).

Why It Holds (Chesterton Fence)

  1. Thread-Safety & Hot Reconfiguration: vespa/container-disc swaps component graphs atomically on config reload while in-flight requests drain on the previous generation. Instance fields mutated during search() cause cross-query data races and memory leaks.
  2. Two-Phase Scatter-Gather Bandwidth: Phase 1 search returns lightweight Hit stubs (relevance score + GlobalId + optional match-features). Calling fill() before trimming forces C++ content nodes to read and transmit compressed document summaries for hits that will be discarded (see jdisc-stateless-searcher-chain-execution).

Seductive Wrong Takeaway (CRIT-001)

  • Misconception: Reading hit.getField("body_text") right after execution.search(query) is free or already populated.
  • Falsification: Hit fields outside match-features are Unfilled after search(); calling fill() early on 1,000 scatter-gather hits amplifies content-node docsum RPC traffic by –.
  • Do-Not-Import Boundary: Use match-features in the rank profile when a container Searcher needs per-hit numeric/tensor signals prior to final fill().

Graph View

Backlinks