MetaFieldRanker

Rank documents based on the value of a specific metadata field. The ranking can be performed in descending or ascending order, and can be combined with scores from a previous retriever or ranker.

Key Features

• Ranks documents by the value of any numeric, integer, or date metadata field.
• Supports ascending and descending sort order.
• Combines metadata-based ranking with scores from the previous component using reciprocal rank fusion or linear score.
• Configurable handling of documents with missing metadata (drop, place at top, or place at bottom).
• Returns a configurable number of top documents.

Configuration

1. Drag the MetaFieldRanker component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   • Set meta_field to the metadata key to rank by (required).
   • Set weight to control the balance between metadata-based ranking and the previous component's scores.
   • Optionally set top_k to limit the number of returned documents.
4. Go to the Advanced tab to configure ranking_mode, sort_order, missing_meta, and meta_value_type.

Connections

MetaFieldRanker accepts a list of documents through its documents input. It's typically placed after a retriever. It outputs a reranked documents list, which you can send to an LLM or another component.

Source Code

To check this component's source code, open meta_field.py in the Haystack repository.

Usage Examples

Basic Configuration

  MetaFieldRanker:
    type: haystack.components.rankers.meta_field.MetaFieldRanker
    init_parameters: {}

# haystack-pipeline
components:
  MetaFieldRanker:
    type: haystack.components.rankers.meta_field.MetaFieldRanker
    init_parameters:

Parameters

Inputs

Parameter	Type	Default	Description
documents	List[Document]		Documents to be ranked.
top_k	Optional[int]	None	The maximum number of documents to return per query. If not provided, the top_k set during initialization is used.
weight	Optional[float]	None	In range [0,1]. 0 disables ranking by a meta field. 0.5 gives equal weight to the previous component's score and the metadata ranking. 1 uses metadata ranking only. If not provided, the weight set during initialization is used.
ranking_mode	Optional[Literal['reciprocal_rank_fusion', 'linear_score']]	None	The mode used to combine the retriever's and ranker's scores. Possible values are reciprocal_rank_fusion (default) and linear_score. Use linear_score only with retrievers or rankers that return a score in range [0,1]. If not provided, the ranking_mode set during initialization is used.
sort_order	Optional[Literal['ascending', 'descending']]	None	Whether to sort the meta field by ascending or descending order. If not provided, the sort_order set during initialization is used.
missing_meta	Optional[Literal['drop', 'top', 'bottom']]	None	What to do with documents that are missing the sorting metadata field. Possible values: drop drops the documents entirely; top places them at the top; bottom places them at the bottom. If not provided, the missing_meta set during initialization is used.
meta_value_type	Optional[Literal['float', 'int', 'date']]	None	Parse the meta value into the specified data type before sorting. If not provided, the meta_value_type set during initialization is used.

Outputs

Parameter	Type	Default	Description
documents	List[Document]		List of documents sorted by the specified metadata field.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
meta_field	str		The name of the metadata field to rank by.
weight	float	1	In range [0,1]. 0 disables ranking by a meta field. 0.5 gives equal weight to the previous component's score and the metadata ranking. 1 uses metadata ranking only.
top_k	Optional[int]	None	The maximum number of documents to return per query. If not provided, the ranker returns all documents in the new ranking order.
ranking_mode	Literal['reciprocal_rank_fusion', 'linear_score']	reciprocal_rank_fusion	The mode used to combine the retriever's and ranker's scores. Possible values are reciprocal_rank_fusion (default) and linear_score. Use linear_score only with retrievers or rankers that return a score in range [0,1].
sort_order	Literal['ascending', 'descending']	descending	Whether to sort the meta field by ascending or descending order.
missing_meta	Literal['drop', 'top', 'bottom']	bottom	What to do with documents that are missing the sorting metadata field. Possible values: drop drops the documents entirely; top places them at the top of the list (regardless of sort order); bottom places them at the bottom.
meta_value_type	Optional[Literal['float', 'int', 'date']]	None	Parse the meta value into the specified data type before sorting. This only works if all meta values stored under meta_field in the provided documents are strings. Available options: float, int, date (parses into a datetime object), None (no parsing).

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]		Documents to be ranked.
top_k	Optional[int]	None	The maximum number of documents to return per query. If not provided, the top_k set during initialization is used.
weight	Optional[float]	None	In range [0,1]. 0 disables ranking by a meta field. 0.5 gives equal weight. 1 uses metadata ranking only. If not provided, the weight set during initialization is used.
ranking_mode	Optional[Literal['reciprocal_rank_fusion', 'linear_score']]	None	The mode used to combine the retriever's and ranker's scores. If not provided, the ranking_mode set during initialization is used.
sort_order	Optional[Literal['ascending', 'descending']]	None	Whether to sort the meta field by ascending or descending order. If not provided, the sort_order set during initialization is used.
missing_meta	Optional[Literal['drop', 'top', 'bottom']]	None	What to do with documents that are missing the sorting metadata field. If not provided, the missing_meta set during initialization is used.
meta_value_type	Optional[Literal['float', 'int', 'date']]	None	Parse the meta value into the specified data type before sorting. If not provided, the meta_value_type set during initialization is used.