Domain Guide — Querying, YQL, and Grouping

Vespa queries enter through the /search/ HTTP endpoint in container-jdisc (vespa/container-search),
where a chain of stateless Java Searcher components parses YQL, resolves query profiles, and
dispatches scatter-gather requests to content-nodes.

YQL (Vespa Query Language) Execution Path

1. Parsing and Query Tree Construction (vespa/container-search):
   • YQL statements (select * from sources * where ...) are parsed into a typed QueryTree
     supporting boolean operators (AND, OR, NOT), userInput(@q), weakAnd, wand,
     nearestNeighbor(field, query_vector), and rank(...).
   • Query parameters (input.query(q_vec), ranking.profile, hits, offset) are bound via
     typed Query Profiles.
2. Scatter-Gather Dispatch:
   • The container’s dispatcher selects a content group and broadcasts the serialized query over
     FNET/RPC to proton nodes (vespa/searchcore).
   • Phase 1 returns top-K docsums/scores; Phase 2 fetches full document summaries for the winning
     global hits.
3. Distributed Grouping (vespa/searchcore/src/vespa/searchcore/grouping/):
   • Multi-level all(group(...) each(output(...))) expressions aggregate attributes across content
     nodes in parallel and merge intermediate buckets in vespa/container-search.

Client Tooling

• Python query construction and evaluation: pyvespa/vespa/querybuilder/ (see work-areas).
• Agent query authoring patterns: skills/query-builder/SKILL.md (see search-ranking and ai-rag).