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

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.
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.
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.
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:

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

json

{
  "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

text

, plus

brand

and

category

keyword

Wrong: Keep

match

description

only; sort by price;

term

query on

title.keyword

Right:

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

json

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

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>'`

elasticsearch-search-relevance

NPX Install

Tags

SKILL.md Content