MetaFieldGroupingRanker

Reorder documents by grouping them based on metadata keys. This helps organize retrieved documents before passing them to an LLM, improving context coherence and generation quality.

Key Features

• Groups documents by a primary metadata key (group_by).
• Optionally subgroups documents within each group using a secondary key (subgroup_by).
• Optionally sorts documents within groups by a metadata key (sort_docs_by).
• Outputs a flat, ordered list of documents sorted by group and subgroup values.
• Places documents without a group value at the end of the list.

Configuration

1. Drag the MetaFieldGroupingRanker component onto the canvas from the Component Library.
2. Click the component to open the configuration panel.
3. On the General tab:
   1. Enter the metadata key to group documents by.
4. Go to the Advanced tab to configure the optional subgroup key and document sort key.

Connections

MetaFieldGroupingRanker accepts a list of documents as input. It outputs documents — a flat list reordered by the specified group and subgroup metadata values.

Typically, you place MetaFieldGroupingRanker after a retriever or ranker and before an answer builder or generator. It's commonly used after OpenSearchHybridRetriever to organize results by source document before generating an answer.

Usage Example

components:
  MetaFieldGroupingRanker:
    type: components.rankers.meta_field_grouping_ranker.MetaFieldGroupingRanker
    init_parameters:

Parameters

Inputs

Parameter	Type	Default	Description
documents	List[Document]		The list of documents to group.

Outputs

Parameter	Type	Default	Description
documents	List[Document]		A dictionary with the following keys: - documents: The list of documents ordered by the group_by and subgroup_by metadata values.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
group_by	str		The metadata key to aggregate the documents by.
subgroup_by	Optional[str]	None	The metadata key to aggregate the documents within a group that was created by the group_by key.
sort_docs_by	Optional[str]	None	Determines which metadata key is used to sort the documents. If not provided, the documents within the groups or subgroups are not sorted and are kept in the same order as they were inserted in the subgroups.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
documents	List[Document]		The list of documents to group.