max_marginal_relevance_search

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

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

Embedded
JS/TS

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

# 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:

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:

# 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
)

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

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

Example Usage

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 }
);

Async

Python async variants

The Embedded library provides an async version of this method prefixed with a:

# amax_marginal_relevance_search — async variant
docs = await store.amax_marginal_relevance_search("query", k=5, lambda_mult=0.5)

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

Introduction

CyborgVectorStore

Types

max_marginal_relevance_search

Parameters

Returns

Example Usage

By Vector Variant

Parameters

Returns

Example Usage

Async

​Parameters

​Returns

​Example Usage

​By Vector Variant

​Parameters

​Returns

​Example Usage

​Async

Parameters

Returns

Example Usage

By Vector Variant

Parameters

Returns

Example Usage

Async