ES|QL MMR command

The MMR command reduces the result set from a set of input rows by applying a diversification strategy to the return rows.

MMR [query_vector] ON field LIMIT limit [WITH { "lambda": lambda_value }]

field

(required) The name of the field that will use its values for the diversification process. The field must be a dense_vector type.

limit

(required) The maximum number of rows to return after diversification.

query_vector

(optional) The query vector to use as part of the diversification algorithm for comparison. Must have the same number of dimensions as the vector field you are searching against. Must be one of:

• An array of floats
• A hex-encoded byte vector (one byte per dimension; for bit, one byte per 8 dimensions)
• A base64-encoded vector string. Base64 supports float and bfloat16 (big-endian), byte, and bit encodings depending on the target field type.
• A function or expression that returns a dense_vector

lambda_value

(Required if WITH is used) A value between 0.0 and 1.0 that controls how similarity is calculated during diversification. Higher values weight the similarity to the query_vector more heavily, lower values weight the diversity more heavily.

Use the MMR command to return a limited, but diverse, set of row results. This is useful when you want to maximize diversity by preventing similar documents from dominating the top results returned from a search.

The command uses MMR (Maximum Marginal Relevance) diversification to discard results that are too similar to each other. Similarity is determined based on the field parameter and the optionally provided query_vector.

In a cross-cluster query, the inference endpoint used to generate a query vector must exist on the cluster that receives the query.

FROM mmr_text_vector_keyword
| SORT keyword_field
| LIMIT 10
| MMR ON text_vector LIMIT 3
| DROP text_vector, byte_vector, bit_vector

FROM mmr_text_vector_keyword
| SORT keyword_field
| LIMIT 10
| MMR [0.1, 0.2, 0.3] ON text_vector LIMIT 3 WITH { "lambda": 0.1 }
| DROP text_vector, byte_vector, bit_vector

FROM dense_vector_text METADATA _score
| EVAL query_embedding = TEXT_EMBEDDING("be excellent to each other", "test_dense_inference")
| WHERE KNN(text_embedding_field, query_embedding)
| SORT _score DESC
| LIMIT 10
| MMR TEXT_EMBEDDING("be excellent to each other", "test_dense_inference") ON text_embedding_field LIMIT 3 WITH { "lambda": 0.2 }
| KEEP text_field, query_embedding