> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# max_marginal_relevance_search

Returns documents selected using maximal marginal relevance to balance relevance and diversity.

<Note>Available in Embedded and JS/TS SDK. The Python SDK does not currently support MMR search.</Note>

<Tabs>
  <Tab title="Embedded">
    ```python theme={null}
    max_marginal_relevance_search(
        query: str,
        k: int = 4,
        fetch_k: int = 20,
        lambda_mult: float = 0.5,
        filter: Optional[Dict[str, Any]] = None,
        **kwargs
    ) -> List[Document]
    ```

    ### Parameters

    | Parameter | Type | Description |
    | - | - | - |
    | `query` | `str` | Query text to search for |
    | `k` | `int` | Number of documents to return (default: 4) |
    | `fetch_k` | `int` | Number of documents to fetch before reranking (default: 20) |
    | `lambda_mult` | `float` | Diversity control: 0 = max diversity, 1 = min diversity (default: 0.5) |
    | `filter` | `Optional[Dict[str, Any]]` | *(Optional)* Metadata filters to apply |
    | `**kwargs` | `Any` | Additional keyword arguments (currently unused) |

    ### Returns

    `List[Document]`: List of diverse, relevant Document objects

    ### Example Usage

    ```python theme={null}
    # Search with balanced relevance and diversity
    results = store.max_marginal_relevance_search(
        "Python programming concepts",
        k=5,
        fetch_k=20,
        lambda_mult=0.5  # Balance relevance and diversity
    )

    # Maximum diversity (avoid similar documents)
    diverse_results = store.max_marginal_relevance_search(
        "data structures",
        k=5,
        lambda_mult=0.0  # Maximum diversity
    )

    # Maximum relevance (similar to standard search)
    relevant_results = store.max_marginal_relevance_search(
        "algorithms",
        k=5,
        lambda_mult=1.0  # Maximum relevance
    )
    ```

    ### By Vector Variant

    The Embedded library also provides `max_marginal_relevance_search_by_vector` for searching with a pre-computed embedding vector:

    ```python theme={null}
    max_marginal_relevance_search_by_vector(
        embedding: Union[List[float], np.ndarray],
        k: int = 4,
        fetch_k: int = 20,
        lambda_mult: float = 0.5,
        filter: Optional[Dict[str, Any]] = None,
        **kwargs
    ) -> List[Document]
    ```

    **Parameters:**

    | Parameter | Type | Description |
    | - | - | - |
    | `embedding` | `Union[List[float], np.ndarray]` | Query embedding vector |
    | `k` | `int` | Number of documents to return (default: 4) |
    | `fetch_k` | `int` | Number of documents to fetch before reranking (default: 20) |
    | `lambda_mult` | `float` | Diversity control: 0 = max diversity, 1 = min diversity (default: 0.5) |
    | `filter` | `Optional[Dict[str, Any]]` | *(Optional)* Metadata filters to apply |
    | `**kwargs` | `Any` | Additional keyword arguments (currently unused) |

    **Example:**

    ```python theme={null}
    # Get query embedding
    query_embedding = store.get_embeddings("machine learning algorithms")

    # MMR search with embedding
    results = store.max_marginal_relevance_search_by_vector(
        query_embedding,
        k=5,
        fetch_k=30,
        lambda_mult=0.3  # Favor diversity
    )

    # With metadata filter
    filtered_results = store.max_marginal_relevance_search_by_vector(
        query_embedding,
        k=4,
        filter={"category": "tutorial"},
        lambda_mult=0.7  # Favor relevance
    )
    ```
  </Tab>

  <Tab title="JS/TS">
    ```typescript theme={null}
    maxMarginalRelevanceSearch(
        query: string,
        options: { k?: number; fetchK?: number; lambda?: number; filter?: Record<string, any> }
    ): Promise<Document[]>
    ```

    ### Parameters

    | Parameter | Type | Description |
    | - | - | - |
    | `query` | `string` | Query text to search for |
    | `options.k` | `number` | *(Optional)* Number of documents to return |
    | `options.fetchK` | `number` | *(Optional)* Number of documents to fetch before reranking |
    | `options.lambda` | `number` | *(Optional)* Diversity control: 0 = max diversity, 1 = min diversity |
    | `options.filter` | `Record<string, any>` | *(Optional)* Metadata filters to apply |

    ### Returns

    `Promise<Document[]>`: Array of diverse, relevant Document objects

    <Note>The JS/TS SDK does not have a separate by-vector variant. Use `maxMarginalRelevanceSearch` with a text query.</Note>

    ### Example Usage

    ```typescript theme={null}
    const results = await store.maxMarginalRelevanceSearch(
        "Python programming concepts",
        { k: 5, fetchK: 20, lambda: 0.5 }
    );

    // Maximum diversity
    const diverse = await store.maxMarginalRelevanceSearch(
        "data structures",
        { k: 5, lambda: 0.0 }
    );
    ```
  </Tab>
</Tabs>

### Async

<Accordion title="Python async variants">
  The Embedded library provides an async version of this method prefixed with `a`:

  ```python theme={null}
  # amax_marginal_relevance_search — async variant
  docs = await store.amax_marginal_relevance_search("query", k=5, lambda_mult=0.5)
  ```
</Accordion>

<Note>
  JS/TS methods are natively async — all signatures above already return `Promise<...>`. No separate async variant is needed.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.