---
title: ES|QL MMR command
description: 
url: https://www.elastic.co/elastic/docs-builder/docs/3028/reference/query-languages/esql/commands/mmr
products:
  - Elasticsearch
---

# ES|QL MMR command
<applies-to>
  - Elastic Cloud Serverless: Preview
  - Elastic Stack: Planned
</applies-to>

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

## Syntax

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


## Parameters

<definitions>
  <definition term="field">
    (required) The name of the field that will use its values for the diversification process.
    The field must be a `dense_vector` type.
  </definition>
  <definition term="limit">
    (required) The maximum number of rows to return after diversification.
  </definition>
  <definition term="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`
  </definition>
  <definition term="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.
  </definition>
</definitions>


## Description

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)](https://www.cs.cmu.edu/~jgc/publication/The_Use_MMR_Diversity_Based_LTMIR_1998.pdf) 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`.
<note>
  The ordering of results returned from the input rows is preserved.
</note>

<important>
  You must limit the number of input rows before the `MMR` command.
  For example, you can use the [LIMIT command](https://www.elastic.co/elastic/docs-builder/docs/3028/reference/query-languages/esql/commands/limit) to restrict the input.
</important>


## Examples


### Basic result diversification

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


| keyword_field:keyword | text_body:text |
|-----------------------|----------------|
| test1                 | first text     |
| test3                 | third text     |
| test6                 | sixth text     |


### Result diversification with a query vector

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


| keyword_field:keyword | text_body:text |
|-----------------------|----------------|
| test3                 | third text     |
| test6                 | sixth text     |
| test8                 | eighth text    |


### Result diversification using a text embedding to generate a query vector

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


| text_field:text                                                       | query_embedding:dense_vector |
|-----------------------------------------------------------------------|------------------------------|
| be excellent to each other                                            | [45.0, 55.0, 54.0]           |
| live long and prosper                                                 | [45.0, 55.0, 54.0]           |
| all we have to decide is what to do with the time that is given to us | [45.0, 55.0, 54.0]           |