/elasticsearch-search-relevance

name: elasticsearch-search-relevance
description: >
  Improve Elasticsearch search relevance for content and catalog indices: pin or promote
  results with query rules (correct rule type, criteria, and rule-query wiring) and
  tune organic ranking with multi_match, field boosts, and analysis grounded in the
  index mapping. Use when search results rank poorly, a specific document must appear
  first for a query, or the user asks to tune full-text matching — not for ES|QL analytics,
  index ingest, or cluster health.
metadata:
  author: elastic
  version: 0.1.0
  universal: true
compatibility: Elasticsearch 8.10 or later (query rules), self-managed, Elastic Cloud
  Hosted, or Elastic Cloud Serverless. Requires the `elastic` CLI ≥ 0.2 with `stack
  es` support.

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.

<!-- begin-partial: preamble -->

Environment Configuration

This skill executes Elasticsearch operations through the `elastic` CLI. If the [`elastic` CLI](https://github.com/elastic/cli#configuration) 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](#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.

<!-- end-partial: preamble -->

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](references/query-rules-reference.md) 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](references/multi-match-tuning.md).

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