Elasticsearch Search Relevance

Improve full-text search results on content and catalog indices. Diagnose the mapping and current query, choose the right relevance lever (query rules for deterministic pinning vs multi_match and field boosts for organic ranking), apply the change, and verify top hits before reporting success.

Environment Configuration

This skill executes Elasticsearch operations through the elastic CLI. If the elastic CLI is not installed, tell the user what it is needed for. Do not guess credentials, call the HTTP API directly, or attempt other workarounds.

This skill references operations in HTTP-shorthand form (e.g., GET /, GET /_cat/indices, GET /{index}/_mapping, GET /{index}/_settings/index.mode, POST /_query). The Operations table at the end of this document maps each shorthand to the equivalent elastic CLI command — always use the CLI rather than calling the HTTP API directly.

Scope

This skill covers Query DSL relevance on indices with text (and optional keyword) fields — product catalogs, documentation, knowledge bases. It uses POST /{index}/_search for evaluation and query-rules APIs for pinned or excluded documents.

Out of scope:

• ES|QL search (POST /_query) — use the elasticsearch-esql skill.
• Semantic / vector / hybrid retrieval — different field types and retrievers.
• Sorting by price, date, or popularity instead of fixing text relevance unless the user explicitly wants non-relevance ordering.

Relevance levers

User intent	Lever	APIs
Always show document X first for query Q	Query rules — pinned rule + rule query in search	PUT /_query_rules/{ruleset_id}, POST /{index}/_search
Hide specific documents for query Q	Query rules — exclude rule + rule query	Same
Better ranking for open-ended text queries	multi_match across mapped text fields with field boosts	POST /{index}/_search
Tokens not matching user language	Operator, minimum_should_match, or synonym analyzers	POST /{index}/_search, optionally POST /{index}/_analyze

Decision rule: If the user names a document that must rank first for a specific query, use query rules. If results are generally weak for a phrase, tune the organic query from the mapping. Do not simulate pinning with extreme boosts, function_score, or sort clauses.

Process

1. Inspect the mapping and current query. Call GET / to confirm connectivity. When the index is unknown, narrow candidates with GET /_cat/indices, then call GET /{index}/_mapping.

   From the mapping, list every text field (e.g., title, description) and every keyword field used for filters (brand, category). Note which fields are short (precision) vs long (recall). Read the user's current search body if provided — identify which fields it queries and whether it already uses rule, multi_match, or single-field match.

   Decision: Is the problem deterministic promotion (one doc must win for one query) or organic ranking (several docs should score better)? Data needed: index name, mapping properties, current query JSON, example query strings, and target document ID(s) when pinning.

2. Choose the relevance lever. Apply the decision from step 1:

   • Pinning / promotion → Create a query-rules ruleset with a rule of type pinned (never exclude for promotion). Set criteria so the rule fires only for the intended query text — e.g., contains or exact on a metadata key such as query_string with value "sale". Set actions to pin the correct document via ids (e.g., ["SKU123"]) or docs (e.g., [{"_index":"catalog","_id":"SKU123"}]). Use docs when _id may not be unique across indices. Read Query Rules Reference for full structure.

   • Organic ranking → Replace single-field match on a long field with multi_match across the mapped text fields. Boost short fields (typically title^2 with description unboosted). Consider operator, minimum_should_match, or synonym-aware analyzers when multi-word recall is still poor — but do not sort by price, date, or keyword fields to fake better text relevance, and do not query .keyword sub-fields with term for analyzed user phrases. Read Multi-Match Tuning.

   Decision: Pick exactly one primary lever per request. Data needed: chosen fields and boosts, ruleset ID and rule ID names, criteria metadata keys, and pinned document identifiers.

3. Apply the change. Execute the APIs for the chosen lever:

   Query rules path

   • Create or replace the ruleset with PUT /_query_rules/{ruleset_id} (or add one rule with PUT /_query_rules/{ruleset_id}/_rule/{rule_id}).
   • Confirm structure with GET /_query_rules/{ruleset_id}.
   • Validate criteria with POST /_query_rules/{ruleset_id}/_test using the same match_criteria you will pass at search time.
   • Wire the search: POST /{index}/_search must use a rule query whose ruleset_id references the ruleset and whose match_criteria supplies values for every criteria metadata key (e.g., "query_string": "sale"). Place the normal relevance clause inside organic. Creating the ruleset alone does not pin anything — the pin applies only when search includes the rule query.

   Organic tuning path

   • Build a candidate multi_match (or equivalent bool/should) query from the mapping.
   • Optionally inspect analysis with POST /{index}/_analyze on sample query text when tokenization explains misses.

   Decision: Stop after one coherent change set; avoid stacking unrelated edits before testing.

4. Test and compare top hits. Before and after each candidate, call POST /{index}/_search with the same size (≥ 10), the user's query string, and "track_scores": true. For pinning, the search body must include the rule query from step 3.

   Compare for each run:

   • Top _id values and order
   • _score where relevant
   • Key _source fields (title, description, product id)

   For pinning, confirm the target document (e.g., SKU123) is first when match_criteria matches the query and that organic matches still appear below. For organic tuning, confirm titles and intent-aligned documents rise without relying on sort or keyword exact-match hacks.

   Decision: Ship the candidate that wins on evidence; if none improve results, report what was tried and propose the next lever (e.g., synonyms or additional fields). Data needed: side-by-side top-hit lists from baseline and candidate queries.

Examples

Pin SKU123 for query "sale" on catalog

Wrong: Boost SKU123, sort by _id, or create a ruleset without a rule search query.

Right:

1. PUT /_query_rules/catalog-sale-pin with a pinned rule, criteria matching query text "sale", actions pinning SKU123.
2. POST /catalog/_search with:

{
  "query": {
    "rule": {
      "ruleset_id": "catalog-sale-pin",
      "match_criteria": { "query_string": "sale" },
      "organic": {
        "multi_match": {
          "query": "sale",
          "fields": ["title^2", "description"]
        }
      }
    }
  },
  "size": 10
}

Verify SKU123 is hit #1 and remaining hits are organic matches below the pin.

Improve "running shoes" when only description is searched

Mapping provides title and description as text, plus brand and category as keyword.

Wrong: Keep match on description only; sort by price; term query on title.keyword.

Right:

1. Baseline: POST /catalog/_search with the user's current match on description; record top hits.
2. Candidate: POST /catalog/_search with:

{
  "query": {
    "multi_match": {
      "query": "running shoes",
      "fields": ["title^2", "description"],
      "type": "best_fields",
      "operator": "or",
      "minimum_should_match": "75%"
    }
  },
  "size": 10
}

1. Compare top hits — documents with "running shoes" in title should rank above description-only matches. If recall is still thin, consider synonym expansion in a follow-up iteration (not sort-by-price).

Guidelines

• Ground every field name in the mapping — never invent name, content, or body without checking GET /{index}/_mapping.
• Query rules for pins, boosts for ranking — merchandising belongs in query rules; field boosts belong in organic queries.
• Match criteria wiring is mandatory — metadata keys in rule criteria must appear in the search rule.match_criteria object with the runtime values (typically the user's query string).
• Test before claiming success — run baseline and candidate searches; cite top-hit changes.
• Keyword fields filter; text fields search — use keyword fields in filter context, not as the primary full-text target for natural language.
• Always deliver the concrete artifact — even when you cannot connect to a cluster to verify, produce the full ruleset JSON (for pinning) or the candidate query body (for organic tuning), then explain how to verify once the connection is available. Never stop at a high-level outline.

References

• Query Rules Reference — criteria types, pinned actions, ruleset JSON, rule query wiring, test API
• Multi-Match Tuning — field boosts, operators, testing discipline, anti-patterns

Operations

HTTP API (shorthand)	elastic CLI command
GET /	elastic es info
GET /_cat/indices	elastic es cat indices --index '<pattern>'
GET /{index}/_mapping	elastic es indices get-mapping --index '<index>'
PUT /_query_rules/{ruleset_id}	elastic es query-rules put-ruleset --ruleset-id '<id>' --rules '<json>'
PUT /_query_rules/{ruleset_id}/_rule/{rule_id}	elastic es query-rules put-rule --ruleset-id '<id>' --rule-id '<id>' --type pinned --criteria '<json>' --actions '<json>'
GET /_query_rules/{ruleset_id}	elastic es query-rules get-ruleset --ruleset-id '<id>'
POST /_query_rules/{ruleset_id}/_test	elastic es query-rules test --ruleset-id '<id>' --match-criteria '<json>'
POST /{index}/_search	elastic es search --index '<index>' --query '<json>'
POST /{index}/_analyze	elastic es indices analyze --index '<index>' --field '<field>' --text '<text>'