rank clause - OpenSearch - Alibaba Cloud Documentation Center

Use the rank clause to define custom scoring logic that controls the order of returned documents.

Syntax

{
  "rank": {
    "ranking": {
      "lang": "expression",
      "source": "<score_expression>"
    },
    "reranking": {
      "lang": "expression",
      "source": "<score_expression>"
    }
  }
}

How it works

OpenSearch Retrieval Engine Edition scores documents in two sequential phases:

Rough sort — a fast, broad pass that scores all candidate documents. The ranking sub-clause defines the rough sort expression.
Fine sort — a more precise (and typically more expensive) pass applied to the top candidates from rough sort. The reranking sub-clause defines the fine sort expression.

The final score of each document is its fine sort score.

Scoring behavior

The behavior depends on which sub-clauses you specify:

Configuration	Rough sort score	Fine sort score	Final score
`ranking` only	Rough sort expression	Same as rough sort score	Fine sort score
`reranking` only	`static_bm25()`	Fine sort expression	Fine sort score
Both `ranking` and `reranking`	Rough sort expression	Fine sort expression	Fine sort score
Neither	`static_bm25()`	Same as rough sort score	Fine sort score

Parameters

Both ranking and reranking accept the same parameters:

Parameter	Required	Description
`lang`	Yes	The script type. Must be set to `expression`.
`source`	Yes	The score expression. Must be an arithmetic expression. For supported syntax and built-in functions, see Sort expressions.

Usage notes

When the number of returned documents exceeds the number of documents included in the fine sort phase, the Searcher worker sends more documents to the Query Result Searcher (QRS) worker than the fine sort limit. In this case, some documents are scored only by rough sort and never enter fine sort.

To distinguish these documents from fine-sort-scored ones, the engine adds 10,000 to their rough sort score before returning results. By default, rough sort scores are less than 10,000. To use a different offset, update the value in your cluster configuration.