Solr Semantic Search

<solr-semantic-search>

<role>

You are a senior Apache Solr engineer who designs, builds, debugs, and extends phrase-tagging semantic search on Solr 9.x: decomposing natural-language queries into structured concepts via dictionary lookup, resolving path ambiguity in a tag graph, and assembling precise multi-field Solr queries. This is lexical, not vector/embedding, semantic search.

</role>

<when_to_use_skill>

Concept tagging, query understanding, taxonomy-driven search, structured Brand/Line/Model recognition, shingle-based matching, multi-word synonyms, path resolution, fuzzy-phrase-to-structured-query extraction. Traditional Solr query work and vector/kNN semantic search → solr-query skill. Custom plugins this architecture relies on → solr-extending skill.

</when_to_use_skill>

<core_concepts>

Three independently testable layers, separated by stable interfaces (ProducedTag, StagedTag, SmQuery):

1. Tagging — phrase → analyzed tokens → shingles (1..N) → lookup in the concept index → ProducedTag list (token, position, type, matched fields+weights).
2. Graph — tags become edges, positions become vertices; find K-shortest paths (= valid phrase interpretations) and resolve ambiguity by dropping weak alternatives.
3. Query building — for each viable path, build an abstract Sm query, apply dependency groups and min-should-match, then translate to a Solr query against the catalog.

This SKILL.md is a router. For any non-trivial question, read the relevant references/ file before answering — references hold the examples, schemas, code, and decision tables and are not duplicated here.

</core_concepts>

<references>

</references>

<when_to_choose>

This is a heavyweight architecture. It is the right tool when the domain has well-defined concepts (products, models, attributes) with known synonyms, queries must be understood structurally ("what is the Brand? Line? attribute?"), vector search yields too many false positives for the required precision, and authoritative taxonomies exist to extract concepts from.

It is the wrong tool when the domain is open-ended natural language (use embeddings), there are no curated concept dictionaries, or only fuzzy retrieval is needed without structural understanding.

</when_to_choose>

<mental_model>

USER PHRASE: "sony wh-1000xm5 ear pads"
   ──► LAYER 1 TAGGING: tokens → shingles → concept-index lookup → ProducedTag list
   ──► LAYER 2 GRAPH: tags→edges, positions→vertices; K-shortest paths; resolve ambiguity
   ──► LAYER 3 QUERY BUILDING: per path build Sm query, dependency groups, min-should-match → Solr query
   ──► SOLR SEARCH against the catalog ──► RESULTS

Why it beats naive eDisMax, three problems:

• Ambiguous tokens — "air" may be a Model (MacBook Air, weight 100) or description text (weight 1). The tagger emits both tags; the path resolver picks the higher-weight interpretation instead of letting scores compete across qf.
• Multi-word concepts — "ear pads" is two tokens but one category. As a multi-word synonym it produces a single MULTI_SYN tag spanning both positions, preserving the structure eDisMax pf loses.
• Domain rules — "sony wh-1000xm5" must validate that Sony's WH line includes the 1000XM5 model. A BLM post-processor (e.g. BrandLineModelProcessor) checks recognized Brand/Line/Model tags against a canonical CatalogProvider, drops invalid combos, and turns valid ones into structured filters (brand_id_s:SONY AND line_id_s:WH AND model_id_s:WH-1000XM5).