Implementation:Run llama Llama index MetadataReplacementPostProcessor

Overview

The MetadataReplacementPostProcessor module provides a simple node postprocessor that replaces each node's text content with a value from its metadata. This is a lightweight, focused postprocessor commonly used in conjunction with sentence window retrieval strategies. This module is located at llama-index-core/llama_index/core/postprocessor/metadata_replacement.py (33 lines).

Purpose

This postprocessor is designed for retrieval patterns where nodes are indexed at a fine granularity (e.g., individual sentences) but need to be expanded to a broader context (e.g., a surrounding window of sentences) at query time. The broader context is stored in node metadata during indexing, and this postprocessor replaces the node's text with that stored context before the response is synthesized.

A common use case is the sentence window retrieval pattern:

1. Documents are split into individual sentences and indexed as nodes.
2. Each node stores its surrounding sentence window in metadata (e.g., under the key "window").
3. After retrieval, this postprocessor replaces the sentence text with the full window text, giving the LLM more context for response generation.

Key Components

Class: MetadataReplacementPostProcessor

A Pydantic-based postprocessor extending BaseNodePostprocessor.

Fields

Field	Type	Description
target_metadata_key	str	The metadata key whose value will replace the node's text content.

Constructor

def __init__(self, target_metadata_key: str) -> None

Takes a single required parameter specifying which metadata key to use for content replacement.

Methods

Method	Parameters	Return Type	Description
class_name	(none)	str	Returns "MetadataReplacementPostProcessor".
_postprocess_nodes	nodes: List[NodeWithScore], query_bundle: Optional[QueryBundle]	List[NodeWithScore]	Core logic: replaces each node's content with the value from the target metadata key.

Processing Logic

The _postprocess_nodes method performs the following for each node:

1. Looks up self.target_metadata_key in the node's metadata dictionary.
2. If the key exists, the node's content is replaced with the metadata value via node.set_content().
3. If the key does not exist, the node's content falls back to its original text (retrieved with MetadataMode.NONE).
4. The method mutates nodes in-place and returns the same list.

The implementation in a single expression:

n.node.set_content(
    n.node.metadata.get(
        self.target_metadata_key,
        n.node.get_content(metadata_mode=MetadataMode.NONE),
    )
)

Dependencies

Module	Items Imported
llama_index.core.bridge.pydantic	Field
llama_index.core.postprocessor.types	BaseNodePostprocessor
llama_index.core.schema	MetadataMode, NodeWithScore, QueryBundle

Design Notes

• In-place mutation: The postprocessor modifies nodes in place rather than creating copies. This is efficient but means the original node text is lost after processing.
• Graceful fallback: If the target metadata key is missing from a node, the node's content remains unchanged (falls back to the existing text content).
• No query dependency: The query_bundle parameter is accepted but not used, as the replacement is purely metadata-driven.
• Minimal implementation: At 33 lines, this is one of the simplest postprocessors in LlamaIndex, following the single-responsibility principle.