MetaFieldRanker

Rank documents based on the value of a specific metadata field. You can combine metadata-based ranking with a retriever's relevance score using a configurable weight.

Key Features

• Ranks documents by any numeric or date metadata field.
• Supports ascending and descending sort order.
• Combines metadata ranking with a retriever's score using a configurable weight.
• Handles documents missing the metadata field: drop them, place them at the top, or at the bottom.
• Supports type parsing for string metadata values (float, int, or date).

Configuration

1. Drag the MetaFieldRanker 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 name of the metadata field to rank documents by.
4. Go to the Advanced tab to configure weight, top_k, ranking_mode, sort_order, missing_meta, and meta_value_type.

Connections

MetaFieldRanker accepts a list of documents and optional runtime overrides for top_k, weight, ranking_mode, sort_order, missing_meta, and meta_value_type as inputs. It outputs documents — the list sorted by the specified metadata field.

Typically, you connect MetaFieldRanker after a retriever and before a prompt builder or answer builder.

Usage Example

components:
  MetaFieldRanker:
    type: 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 provided at initialization time is used.
weight	Optional[float]	None	In range [0,1]. 0 disables ranking by a meta field. 0.5 ranking from previous component and based on meta field have the same weight. 1 ranking by a meta field only. If not provided, the weight provided at initialization time is used.
ranking_mode	Optional[Literal['reciprocal_rank_fusion', 'linear_score']]	None	(optional) The mode used to combine the Retriever's and Ranker's scores. Possible values are 'reciprocal_rank_fusion' (default) and 'linear_score'. Use the 'score' mode only with Retrievers or Rankers that return a score in range [0,1]. If not provided, the ranking_mode provided at initialization time is used.
sort_order	Optional[Literal['ascending', 'descending']]	None	Whether to sort the meta field by ascending or descending order. Possible values are descending (default) and ascending. If not provided, the sort_order provided at initialization time is used.
missing_meta	Optional[Literal['drop', 'top', 'bottom']]	None	What to do with documents that are missing the sorting metadata field. Possible values are: - 'drop' will drop the documents entirely. - 'top' will place the documents at the top of the metadata-sorted list (regardless of 'ascending' or 'descending'). - 'bottom' will place the documents at the bottom of metadata-sorted list (regardless of 'ascending' or 'descending'). If not provided, the missing_meta provided at initialization time is used.
meta_value_type	Optional[Literal['float', 'int', 'date']]	None	Parse the meta value into the data type specified before sorting. This will only work if all meta values stored under meta_field in the provided documents are strings. For example, if we specified meta_value_type="date" then for the meta value "date": "2015-02-01" we would parse the string into a datetime object and then sort the documents by date. The available options are: -'float' will parse the meta values into floats. -'int' will parse the meta values into integers. -'date' will parse the meta values into datetime objects. -'None' (default) will do no parsing.

Outputs

Parameter	Type	Default	Description
documents	List[Document]		A dictionary with the following keys: - documents: List of Documents sorted by the specified meta field.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
meta_field	str		The name of the meta field to rank by.
weight	float	1	In range [0,1]. 0 disables ranking by a meta field. 0.5 ranking from previous component and based on meta field have the same weight. 1 ranking by a meta field only.
top_k	Optional[int]	None	The maximum number of Documents to return per query. If not provided, the Ranker returns all documents it receives 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 the 'linear_score' mode 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. Possible values are descending (default) and ascending.
missing_meta	Literal['drop', 'top', 'bottom']	bottom	What to do with documents that are missing the sorting metadata field. Possible values are: - 'drop' will drop the documents entirely. - 'top' will place the documents at the top of the metadata-sorted list (regardless of 'ascending' or 'descending'). - 'bottom' will place the documents at the bottom of metadata-sorted list (regardless of 'ascending' or 'descending').
meta_value_type	Optional[Literal['float', 'int', 'date']]	None	Parse the meta value into the data type specified before sorting. This will only work if all meta values stored under meta_field in the provided documents are strings. For example, if we specified meta_value_type="date" then for the meta value "date": "2015-02-01" we would parse the string into a datetime object and then sort the documents by date. The available options are: - 'float' will parse the meta values into floats. - 'int' will parse the meta values into integers. - 'date' will parse the meta values into datetime objects. - 'None' (default) will do 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 provided at initialization time is used.
weight	Optional[float]	None	In range [0,1]. 0 disables ranking by a meta field. 0.5 ranking from previous component and based on meta field have the same weight. 1 ranking by a meta field only. If not provided, the weight provided at initialization time is used.
ranking_mode	Optional[Literal['reciprocal_rank_fusion', 'linear_score']]	None	(optional) The mode used to combine the Retriever's and Ranker's scores. Possible values are 'reciprocal_rank_fusion' (default) and 'linear_score'. Use the 'score' mode only with Retrievers or Rankers that return a score in range [0,1]. If not provided, the ranking_mode provided at initialization time is used.
sort_order	Optional[Literal['ascending', 'descending']]	None	Whether to sort the meta field by ascending or descending order. Possible values are descending (default) and ascending. If not provided, the sort_order provided at initialization time is used.
missing_meta	Optional[Literal['drop', 'top', 'bottom']]	None	What to do with documents that are missing the sorting metadata field. Possible values are: - 'drop' will drop the documents entirely. - 'top' will place the documents at the top of the metadata-sorted list (regardless of 'ascending' or 'descending'). - 'bottom' will place the documents at the bottom of metadata-sorted list (regardless of 'ascending' or 'descending'). If not provided, the missing_meta provided at initialization time is used.
meta_value_type	Optional[Literal['float', 'int', 'date']]	None	Parse the meta value into the data type specified before sorting. This will only work if all meta values stored under meta_field in the provided documents are strings. For example, if we specified meta_value_type="date" then for the meta value "date": "2015-02-01" we would parse the string into a datetime object and then sort the documents by date. The available options are: -'float' will parse the meta values into floats. -'int' will parse the meta values into integers. -'date' will parse the meta values into datetime objects. -'None' (default) will do no parsing.