elasticsearch-search-relevance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Elasticsearch Search Relevance

Elasticsearch 搜索相关性

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.

提升内容和目录索引的全文搜索结果。诊断映射和当前查询，选择合适的相关性调节手段（确定性固定结果使用查询规则，自然排序优化使用multi_match和字段权重），应用更改并验证顶部结果后再报告成功。

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.

本技能通过

elastic

CLI执行Elasticsearch操作。如果未安装

elastic

CLI，请告知用户其用途。请勿猜测凭证、直接调用HTTP API或尝试其他变通方法。

本技能以HTTP简写形式引用操作（例如

GET /

、

GET /_cat/indices

、

GET /{index}/_mapping

、

GET /{index}/_settings/index.mode

、

POST /_query

）。本文档末尾的操作表格将每个简写映射为等效的

elastic

CLI命令——请始终使用CLI而非直接调用HTTP API。

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.

本技能涵盖带有

text

（可选

keyword

）字段的索引上的Query DSL相关性优化——适用于产品目录、文档、知识库。使用

POST /{index}/_search

进行评估，使用查询规则API处理固定或排除的文档。

不适用场景：

ES|QL搜索（
```
POST /_query
```
）——请使用
```
elasticsearch-esql
```
技能。
语义/向量/混合检索——涉及不同的字段类型和检索器。
按价格、日期或人气排序（而非修复文本相关性），除非用户明确要求非相关性排序。

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`

用户意图	调节手段	API
针对查询Q始终将文档X置于首位	查询规则—— `pinned` 规则 + 搜索中的 `rule` 查询	`PUT /_query_rules/{ruleset_id}` 、 `POST /{index}/_search`
针对查询Q隐藏特定文档	查询规则—— `exclude` 规则 + `rule` 查询	同上
优化开放式文本查询的排名	在映射的 `text` 字段上使用带字段权重的 `multi_match`	`POST /{index}/_search`
分词与用户语言不匹配	运算符、 `minimum_should_match` 或同义词分析器	`POST /{index}/_search` ，可选 `POST /{index}/_analyze`

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.

检查映射和当前查询。调用
```
GET /
```
确认连接性。当索引未知时，使用
```
GET /_cat/indices
```
缩小候选范围，然后调用
```
GET /{index}/_mapping
```
。
从映射中列出所有
```
text
```
字段（例如
```
title
```
、
```
description
```
）以及所有用于过滤的
```
keyword
```
字段（
```
brand
```
、
```
category
```
）。注意哪些字段是短字段（精准），哪些是长字段（召回）。如果提供了用户当前的搜索体，读取并识别其查询的字段，以及是否已使用
```
rule
```
、
```
multi_match
```
或单字段
```
match
```
。
决策：问题是确定性提升（单个文档需在单个查询中获胜）还是自然排名优化（多个文档应获得更高评分）？所需数据：索引名称、映射属性、当前查询JSON、示例查询字符串，以及固定时的目标文档ID。
选择相关性调节手段。应用步骤1的决策：
- 固定/提升 → 创建带有
```
pinned
```
  类型规则的查询规则集（提升时绝不要使用
```
exclude
```
  ）。设置
```
criteria
```
  使规则仅针对预期查询文本触发——例如，对元数据键
```
query_string
```
  使用
```
contains
```
  或
```
exact
```
  匹配，值为
```
"sale"
```
  。设置
```
actions
```
  通过
```
ids
```
  （例如
```
["SKU123"]
```
  ）或
```
docs
```
  （例如
```
[{"_index":"catalog","_id":"SKU123"}]
```
  ）固定正确的文档。当
```
_id
```
  在多个索引中可能不唯一时使用
```
docs
```
  。查阅查询规则参考获取完整结构。
- 自然排名优化 → 将长字段上的单字段
```
match
```
  替换为在映射的
```
text
```
  字段上的
```
multi_match
```
  。为短字段设置权重（通常
```
title^2
```
  ，
```
description
```
  不设置权重）。当多词召回效果仍不佳时，考虑使用
```
operator
```
  、
```
minimum_should_match
```
  或支持同义词的分析器——但不要通过按价格、日期或关键字字段排序来伪造更好的文本相关性，也不要对经过分析的用户短语使用
```
term
```
  查询
```
.keyword
```
  子字段。查阅Multi-Match调优。
决策：每个请求仅选择一种主要调节手段。所需数据：选定的字段和权重、规则集ID和规则ID名称、条件元数据键，以及固定文档的标识符。
应用更改。为所选调节手段执行API：

查询规则路径
- 使用
```
PUT /_query_rules/{ruleset_id}
```
  创建或替换规则集（或使用
```
PUT /_query_rules/{ruleset_id}/_rule/{rule_id}
```
  添加单个规则）。
- 使用
```
GET /_query_rules/{ruleset_id}
```
  确认结构。
- 使用
```
POST /_query_rules/{ruleset_id}/_test
```
  验证条件，传入搜索时将使用的相同
```
match_criteria
```
  。
- 关联搜索：
```
POST /{index}/_search
```
  必须使用
```
rule
```
  查询，其
```
ruleset_id
```
  引用规则集，
```
match_criteria
```
  为每个条件
```
metadata
```
  键提供值（例如
```
"query_string": "sale"
```
  ）。将正常相关性子句放在
```
organic
```
  内部。仅创建规则集不会固定任何内容——只有当搜索包含
```
rule
```
  查询时，固定效果才会生效。
自然调优路径
- 根据映射构建候选
```
multi_match
```
  （或等效的bool/should）查询。
- 当分词导致匹配失败时，可对示例查询文本调用
```
POST /{index}/_analyze
```
  检查分析结果。
决策：完成一套连贯的更改后停止；测试前避免堆叠无关编辑。
测试并对比顶部结果。在每个候选方案前后，使用相同的
```
size
```
（≥10）、用户的查询字符串和
```
"track_scores": true
```
调用
```
POST /{index}/_search
```
。对于固定操作，搜索体必须包含步骤3中的
```
rule
```
查询。
每次运行对比以下内容：
- 顶部
```
_id
```
  值及其顺序
- 相关的
```
_score
```
- 关键
```
_source
```
  字段（
```
title
```
  、
```
description
```
  、产品ID）
对于固定操作，确认当
```
match_criteria
```
匹配查询时，目标文档（例如
```
SKU123
```
）位于首位，自然匹配结果仍显示在下方。对于自然调优，确认标题和符合意图的文档排名提升，且不依赖排序或关键字精确匹配的技巧。
决策：采用经证据验证有效的候选方案；如果没有方案提升结果，报告已尝试的内容并提出下一种调节手段（例如同义词或额外字段）。所需数据：基线查询和候选查询的并排顶部结果列表。

Examples

示例

Pin SKU123 for query "sale" on

catalog

在

catalog

索引中针对查询"sale"固定SKU123

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.

错误做法：对

SKU123

设置权重、按

_id

排序，或创建规则集但不添加

rule

搜索查询。

正确做法：

调用
```
PUT /_query_rules/catalog-sale-pin
```
，创建
```
pinned
```
规则，条件匹配查询文本
```
"sale"
```
，操作固定
```
SKU123
```
。
调用
```
POST /catalog/_search
```
，请求体如下：

json

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

验证

SKU123

是第一个结果，其余结果是固定下方的自然匹配项。

Improve "running shoes" when only

description

is searched

仅搜索

description

时优化"running shoes"的结果

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

映射中

title

和

description

为

text

字段，

brand

和

category

为

keyword

字段。

错误做法：仅保留

description

上的

match

查询；按价格排序；对

title.keyword

使用

term

查询。

正确做法：

基线：使用用户当前的
```
description
```
上的
```
match
```
查询调用
```
POST /catalog/_search
```
；记录顶部结果。
候选方案：调用
```
POST /catalog/_search
```
，请求体如下：

json

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

对比顶部结果——
```
title
```
中包含"running shoes"的文档应排名仅
```
description
```
包含该短语的文档之前。如果召回率仍低，可在后续迭代中考虑同义词扩展（而非按价格排序）。

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.

所有字段名称均基于映射——未经
```
GET /{index}/_mapping
```
检查，切勿自行创建
```
name
```
、
```
content
```
或
```
body
```
字段。
固定结果用查询规则，排名优化用权重——商品推广属于查询规则的范畴；字段权重属于自然查询的范畴。
条件关联是必需的——规则条件中的
```
metadata
```
键必须出现在搜索的
```
rule.match_criteria
```
对象中，并带有运行时值（通常为用户的查询字符串）。
成功前必须测试——运行基线和候选查询；引用顶部结果的变化。
关键字字段用于过滤；文本字段用于搜索——在
```
filter
```
上下文中使用
```
keyword
```
字段，而非作为自然语言的主要全文搜索目标。
始终提供具体的工件——即使无法连接到集群进行验证，也要生成完整的规则集JSON（用于固定）或候选查询体（用于自然调优），然后说明连接可用后如何验证。切勿仅停留在高层概述。

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

查询规则参考——条件类型、
```
pinned
```
操作、规则集JSON、
```
rule
```
查询关联、测试API
Multi-Match调优——字段权重、运算符、测试规范、反模式

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

HTTP API（简写）	`elastic` CLI命令
`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

Original

Translation

Elasticsearch Search Relevance

Elasticsearch 搜索相关性

Environment Configuration

环境配置

Scope

适用范围

Relevance levers

相关性调节手段

Process

流程

Examples

示例

Pin SKU123 for query "sale" on
`catalog`

在
`catalog`
索引中针对查询"sale"固定SKU123

Improve "running shoes" when only
`description`
is searched

仅搜索
`description`
时优化"running shoes"的结果

Guidelines

指南

References

参考

Operations

操作

elasticsearch-search-relevance

Original

Translation

Elasticsearch Search Relevance

Elasticsearch 搜索相关性

Environment Configuration

环境配置

Scope

适用范围

Relevance levers

相关性调节手段

Process

流程

Examples

示例

Pin SKU123 for query "sale" on catalog

在catalog索引中针对查询"sale"固定SKU123

Improve "running shoes" when only description is searched

仅搜索description时优化"running shoes"的结果

Guidelines

指南

References

参考

Operations

操作

Pin SKU123 for query "sale" on
`catalog`

在
`catalog`
索引中针对查询"sale"固定SKU123

Improve "running shoes" when only
`description`
is searched

仅搜索
`description`
时优化"running shoes"的结果