Rerank processor

Introduced 2.12

The rerank search response processor intercepts and reranks search results. The processor orders documents in the search results based on their new scores.

OpenSearch supports the following rerank types.

TypeDescriptionEarliest available version
ml_opensearchApplies an OpenSearch-provided cross-encoder model.2.12
by_fieldApplies reranking based on a user-provided field.2.18

Request body fields

The following table lists all available request fields.

FieldData typeRequired/OptionalDescription
<rerank_type>ObjectRequiredThe rerank type for document reranking. Valid values are ml-opensearch and by_field.
contextObjectRequired for the ml_opensearch rerank type. Optional and does not affect the results for the by_field rerank type.Provides the rerank processor with information necessary for reranking at query time.
tagStringOptionalThe processor’s identifier.
descriptionStringOptionalA description of the processor.
ignore_failureBooleanOptionalIf true, OpenSearch ignores any failure of this processor and continues to run the remaining processors in the search pipeline. Default is false.

The ml_opensearch rerank type

Introduced 2.12

To rerank results using a cross-encoder model, specify the ml_opensearch rerank type.

Prerequisite

Before using the ml_opensearch rerank type, you must configure a cross-encoder model. For information about using an OpenSearch-provided model, see Cross-encoder models. For information about using a custom model, see Custom local models.

The ml_opensearch rerank type supports the following fields. All fields are required.

FieldData typeDescription
ml_opensearch.model_idStringThe model ID of the cross-encoder model for reranking. For more information, see Using ML models.
context.document_fieldsArrayAn array of document fields that specifies the fields from which to retrieve context for the cross-encoder model.

Example

The following example demonstrates using a search pipeline with a rerank processor implemented using the ml_opensearch rerank type. For a complete example, see Reranking using a cross-encoder model.

Creating a search pipeline

The following request creates a search pipeline with a rerank response processor:

  1. PUT /_search/pipeline/rerank_pipeline
  2. {
  3.   "response_processors": [
  4.     {
  5.       "rerank": {
  6.         "ml_opensearch": {
  7.           "model_id": "gnDIbI0BfUsSoeNT_jAw"
  8.         },
  9.         "context": {
  10.           "document_fields": [ "title", "text_representation"]
  11.         }
  12.       }
  13.     }
  14.   ]
  15. }

copy

Using a search pipeline

Combine an OpenSearch query with an ext object that contains the query context for the large language model (LLM). Provide the query_text that will be used to rerank the results:

  1. POST /_search?search_pipeline=rerank_pipeline
  2. {
  3.   "query": {
  4.     "match": {
  5.       "text_representation": "Where is Albuquerque?"
  6.     }
  7.   },
  8.   "ext": {
  9.     "rerank": {
  10.       "query_context": {
  11.         "query_text": "Where is Albuquerque?"
  12.       }
  13.     }
  14.   }
  15. }

copy

Instead of specifying query_text, you can provide a full path to the field containing text to use for reranking. For example, if you specify a subfield query in the text_representation object, specify its path in the query_text_path parameter:

  1. POST /_search?search_pipeline=rerank_pipeline
  2. {
  3.   "query": {
  4.     "match": {
  5.       "text_representation": {
  6.         "query": "Where is Albuquerque?"
  7.       }
  8.     }
  9.   },
  10.   "ext": {
  11.     "rerank": {
  12.       "query_context": {
  13.         "query_text_path": "query.match.text_representation.query"
  14.       }
  15.     }
  16.   }
  17. }

copy

The query_context object contains the following fields. You must provide either query_text or query_text_path but cannot provide both simultaneously.

Field nameRequired/OptionalDescription
query_textExactly one of query_text or query_text_path is required.The natural language text of the question that you want to use to rerank the search results.
query_text_pathExactly one of query_text or query_text_path is required.The full JSON path to the text of the question that you want to use to rerank the search results. The maximum number of characters allowed in the path is 1000.

The by_field rerank type

Introduced 2.18

To rerank results by a document field, specify the by_field rerank type.

The by_field object supports the following fields.

FieldData typeRequired/OptionalDescription
target_fieldStringRequiredSpecifies the field name or a dot path to the field containing the score to use for reranking.
remove_target_fieldBooleanOptionalIf true, the response does not include the target_field used to perform reranking. Default is false.
keep_previous_scoreBooleanOptionalIf true, the response includes a previous_score field, which contains the score calculated before reranking and can be useful when debugging. Default is false.

Example

The following example demonstrates using a search pipeline with a rerank processor implemented using the by_field rerank type. For a complete example, see Reranking by a document field.

Creating a search pipeline

The following request creates a search pipeline with a by_field rerank type response processor that ranks the documents by the reviews.stars field and specifies to return the original document score:

  1. PUT /_search/pipeline/rerank_byfield_pipeline
  2. {
  3.   "response_processors": [
  4.     {
  5.       "rerank": {
  6.         "by_field": {
  7.           "target_field": "reviews.stars",
  8.           "keep_previous_score" : true
  9.         }
  10.       }
  11.     }
  12.   ]
  13. }

copy

Using the search pipeline

To apply the search pipeline to a query, provide the search pipeline name in the query parameter:

  1. POST /book-index/_search?search_pipeline=rerank_byfield_pipeline
  2. {
  3.   "query": {
  4.      "match_all": {}
  5.   }
  6. }

copy

Next steps