LlamaIndex Node Parser

The Node Parser is built as a modular, abstract base class, allowing developers to implement custom parsing logic for any document type. This enables:

• Pluggable strategies: Seamlessly switch between semantic, fixed-length, or hierarchical chunking.
• Custom metadata injection: Attach source file, page number, or author data to each Node.
• Specialized parsers: Create parsers for code (AST-based), scientific papers, or legal contracts by overriding the core get_nodes_from_documents() method. This design ensures the parser is not a black box but an extensible framework component.

Beyond simple character splitting, advanced parsers like the SemanticSplitterNodeParser use embedding models to identify natural semantic boundaries. This process involves:

• Calculating sentence embeddings for the text.
• Identifying breakpoints where the semantic similarity between adjacent sentences drops significantly.
• Creating coherent chunks that group related concepts, preserving context better than arbitrary splits. This results in chunks that are more likely to be self-contained answers to queries, improving retrieval precision.

A critical function is preserving document metadata and relationships during chunking. Each generated Node object contains:

• Inherited metadata: Source document ID, file path, creation date.
• Positional metadata: Character start/end index, page number, section heading.
• Node relationships: References to parent nodes (in hierarchical chunking) or previous/next nodes. This metadata is crucial for source attribution in RAG responses and enables advanced retrieval patterns like parent-child or sentence-window retrieval.

The parser acts as a bridge between raw text splitters and the LlamaIndex data structure. It wraps foundational splitting libraries (like those from LangChain) to produce Nodes. For example:

• SimpleNodeParser can use a RecursiveCharacterTextSplitter with configurable chunk size and overlap.
• It handles the tokenization process, ensuring chunks respect the target LLM's context window limits.
• The splitter's parameters (separators, chunk size, overlap) are exposed and configurable through the parser's interface, providing granular control over the chunking outcome.

For complex documents, parsers like the HierarchicalNodeParser create a multi-level tree structure of Nodes. This involves:

• First-pass chunking: Creating large 'parent' nodes (e.g., entire sections).
• Second-pass chunking: Splitting each parent into smaller 'child' nodes (e.g., paragraphs).
• Storing relationships: Each child node retains a reference to its parent ID. This enables multi-granularity retrieval, where a query can first retrieve a high-level parent for overview, then drill down into specific child nodes for detail.

The parser's output is optimized for downstream vector embedding and index storage. Key optimizations include:

• Controlled chunk size: Prevents creating chunks too large for embedding models or too small to be meaningful.
• Overlap management: Configurable overlap between consecutive chunks mitigates context fragmentation at boundaries.
• Structured JSON output: Nodes are serializable objects, ready for insertion into vector databases (like Pinecone or Weaviate) or LlamaIndex's built-in indices. This ensures the chunking process is not an isolated step but a tuned precursor to efficient similarity search.

The SimpleNodeParser is the default and most commonly used parser. It implements fixed-length chunking using a configurable token or character limit.

• Primary Mechanism: Splits text using a defined chunk_size and optional chunk_overlap.
• Use Case: General-purpose text processing where uniform chunk size is acceptable.
• Key Parameters: chunk_size, chunk_overlap, separator (e.g., " "), and paragraph_separator for better boundary handling.
• Underlying Library: Often uses a RecursiveCharacterTextSplitter from LangChain under the hood, applying a hierarchy of separators (e.g., double newlines, single newlines, spaces) to respect natural breaks while hitting size targets.

The SemanticSplitterNodeParser performs semantic chunking by embedding sentences and grouping them based on similarity to find natural topic boundaries.

• Primary Mechanism: Embeds each sentence in a document, calculates cosine similarity between adjacent sentences, and splits where similarity drops below a threshold.
• Use Case: Creating chunks that are thematically coherent, improving retrieval precision for complex, multi-topic documents.
• Key Parameters: buffer_size, breakpoint_percentile_threshold, and the embed_model used for sentence embeddings.
• Advantage: Produces variable-length chunks that align with the document's intrinsic semantic structure, unlike fixed-size splits.

The SentenceWindowNodeParser is designed for sentence window retrieval, a strategy that retrieves a core sentence and includes its surrounding context.

• Primary Mechanism: Splits a document into individual sentences. Each sentence becomes a 'node' for embedding and retrieval. A configurable window of sentences before and after the core sentence is stored as metadata.
• Use Case: High-precision tasks where the exact answer is contained within a single sentence, but broader context is needed for the LLM to interpret it correctly.
• Key Parameters: window_size (number of sentences on each side) and window_metadata_key.
• Retrieval Flow: The retriever finds the most relevant single-sentence node; the system then passes the full window of surrounding sentences from the node's metadata to the LLM.

The HierarchicalNodeParser creates a parent-child chunk structure, enabling retrieval at multiple levels of granularity.

• Primary Mechanism: Generates a tree of nodes. Large parent nodes (e.g., whole sections) provide broad context. Smaller child nodes (e.g., paragraphs or sentences) within each parent provide fine-grained detail.
• Use Case: Complex Q&A where a query might require a broad overview or a specific detail. Enables two-stage retrieval: retrieve top parent nodes first, then select relevant child nodes from within them.
• Key Parameters: The chunk_sizes dict defines the token sizes for each level (e.g., {2048: 512} for parents of 2048 tokens containing children of 512 tokens).
• Benefit: Balances the recall of broad topics with the precision of specific information.

The CodeSplitter is a specialized parser for source code, implementing Abstract Syntax Tree (AST) chunking.

• Primary Mechanism: Parses code into its Abstract Syntax Tree and uses language-specific syntax nodes (functions, classes, methods) as logical, self-contained chunk boundaries.
• Use Case: Creating a code knowledge base for retrieval-augmented generation (RAG) on codebases, enabling queries about specific functions or classes.
• Key Parameters: language (e.g., python, javascript), max_chars, and chunk_lines.
• Advantage: Preserves the syntactic and semantic integrity of code units far better than splitting by raw characters or tokens, which would break function definitions.

These parsers perform layout-aware chunking for documents with native structural markup.

• Primary Mechanism: The MarkdownNodeParser uses markdown elements (headings #, lists -, code blocks) as natural chunk boundaries. The HTMLNodeParser uses HTML tags (e.g., <p>, <h1>, <div>) and their nesting.
• Use Case: Splitting technical documentation, blogs, or web pages where the existing markup defines semantic sections.
• Key Parameters: Tags/headers to split on and optional size limits for fallback splitting within large elements.
• Benefit: Chunks align perfectly with the document's authored structure, often matching a human's intuitive segmentation of the content.

A Node is the fundamental data object produced by a LlamaIndex Node Parser. It represents a single, indexed unit of data derived from a source document. Each Node contains:

• Text content: The chunked text itself.
• Metadata: Information such as the source document ID, page number, or file path.
• Embeddings: A dense vector representation of the text, generated by an embedding model, which enables semantic search.
• Relationships: Optional pointers to parent, child, or sibling Nodes for hierarchical structures. Nodes are the atomic units stored in a vector index for retrieval.

A Document is the primary input object for a LlamaIndex Node Parser. It is a container for raw, unstructured or semi-structured source data (e.g., a PDF, a webpage, a text file). In LlamaIndex, a Document object typically holds:

• Raw text content.
• Metadata about the source.
• Document ID for tracking. The Node Parser's core function is to ingest one or more Document objects and transform them into a sequence of Node objects suitable for indexing and retrieval.

A Text Splitter is a more generic term for any algorithm or component that segments a long text into smaller pieces. The LlamaIndex Node Parser is a specific implementation of a text splitter that outputs structured Node objects. Key splitting strategies include:

• Recursive Character Text Splitting: Uses a hierarchy of separators (e.g., \n\n, \n, . ).
• Semantic Chunking: Splits based on natural topic boundaries.
• Fixed-size chunking: Creates chunks of a predetermined token or character length. While a basic text splitter returns strings, a Node Parser enriches these chunks into Nodes with metadata and relationships.

Chunking Strategy refers to the specific methodology and rules used to determine where to split a document. It is the algorithmic logic implemented within a Node Parser. The choice of strategy is critical and involves trade-offs between:

• Context Preservation vs. Information Density.
• Retrieval Precision vs. Recall. Common strategies relevant to Node Parsers include Sentence-Aware Splitting, Hierarchical Chunking (producing parent-child Nodes), and Layout-Aware Chunking for PDFs. The strategy defines the chunk_size, chunk_overlap, and separators used.

An Index in LlamaIndex is the persisted data structure built from Nodes. The Node Parser is the first step in constructing an index. After Nodes are created, they are passed to an Index class (e.g., VectorStoreIndex, SummaryIndex) which handles:

• Generating embeddings for each Node.
• Storing Nodes and embeddings in a Vector Database or other storage backend.
• Creating retrieval data structures. The quality of the index is directly dependent on the quality of the Nodes produced by the parser.

An Ingestion Pipeline is a sequential workflow that transforms raw data into queryable Nodes. The Node Parser is a core component within this pipeline. A typical pipeline stages are:

1. Document Loaders: Fetch raw data into Document objects.
2. Node Parser: Split Documents into Nodes.
3. Embedding Models: Generate vector representations for Nodes.
4. Post-processors (optional): Apply metadata enrichment, deduplication, or filtering.
5. Indexing: Store the final Nodes. The pipeline allows for modular, reproducible, and optimized data preparation for RAG systems.