OpenWikirun-llama/llama_index

Node Parsers

Purpose and Scope

Node parsers are the LlamaIndex loading-layer abstraction that turns higher-level documents into smaller node objects for indexing, retrieval, and response generation. A document usually represents an original source item such as a file, page, database record, or loaded web artifact. A node represents an indexable chunk of that source with inherited text, metadata, and formatting behavior. The main reader problem is deciding where chunking belongs in an application: run a parser directly while prototyping, put one in a repeatable ingestion pipeline, or configure parsing as part of index construction. Sources: docs/api_reference/api_reference/node_parsers/index.md

Chunking is a retrieval design decision, not just a preprocessing detail. It controls how much evidence each search result contains, how precise similarity matching can be, how much context is passed to a language model, and how faithfully answers can cite source material. Large chunks preserve surrounding meaning but can dilute matches and waste context budget. Small chunks make matching sharper, but may require overlap, metadata, or hierarchy so that an answer has enough surrounding information. LlamaIndex treats parsing as a reusable transformation so this decision can be applied consistently before storage, indexing, and querying.

The node parser API reference is organized as a family rather than a single generic splitter. The top-level reference points at the common node parser interface, while specialized pages expose parser classes for code, HTML, JSON, LangChain interoperability, and hierarchical node structures. That layout matters because different source formats have different natural boundaries. Source code is often meaningful around imports, classes, functions, and comments. HTML carries headings and markup structure. JSON carries nested fields and records. Hierarchical parsing preserves multiple levels of the same source, allowing retrieval to be precise while final synthesis can recover broader context. Sources: docs/api_reference/api_reference/node_parsers/code.md, docs/api_reference/api_reference/node_parsers/html.md, docs/api_reference/api_reference/node_parsers/json.md, docs/api_reference/api_reference/node_parsers/hierarchical.md, docs/api_reference/api_reference/node_parsers/langchain.md

Relevant Source Files

  • docs/api_reference/api_reference/node_parsers/index.md — Defines the top-level Node Parsers API reference entry by documenting llama_index.core.node_parser.interface.
  • docs/api_reference/api_reference/node_parsers/code.md — Exposes CodeSplitter in the node parser API reference family.
  • docs/api_reference/api_reference/node_parsers/hierarchical.md — Exposes HierarchicalNodeParser and helper functions for selecting root, leaf, child, and deeper nodes.
  • docs/api_reference/api_reference/node_parsers/html.md — Exposes HTMLNodeParser for HTML-aware parsing.
  • docs/api_reference/api_reference/node_parsers/json.md — Exposes JSONNodeParser for JSON-aware parsing.
  • docs/api_reference/api_reference/node_parsers/langchain.md — Exposes LangchainNodeParser for adapting LangChain splitters into the LlamaIndex node parser surface.

Core API Surface

The top-level reference page identifies the common contract at llama_index.core.node_parser.interface. In practical application code, that contract is visible through the operation of accepting a collection of documents and returning a collection of nodes. The official usage pattern calls this operation with get_nodes_from_documents(...), which makes parsing explicit and inspectable. This is the most direct way to confirm how many chunks were created, whether metadata was inherited, and whether the resulting text boundaries make sense before any vector store or index is involved. Sources: docs/api_reference/api_reference/node_parsers/index.md

The specialized parser pages define the public names to search for in examples, imports, and generated API reference. CodeSplitter is the code-oriented parser entry point. HTMLNodeParser is the HTML-oriented parser entry point. JSONNodeParser is the JSON-oriented parser entry point. LangchainNodeParser is the bridge for teams that already depend on LangChain text splitters but want downstream LlamaIndex indexing and retrieval behavior. These names form the stable vocabulary for parser selection even when the concrete constructor parameters are checked in the generated reference or implementation docs. Sources: docs/api_reference/api_reference/node_parsers/code.md, docs/api_reference/api_reference/node_parsers/html.md, docs/api_reference/api_reference/node_parsers/json.md, docs/api_reference/api_reference/node_parsers/langchain.md

Hierarchical parsing has a broader public surface because it is not only about producing chunks. The reference exposes HierarchicalNodeParser alongside get_leaf_nodes, get_root_nodes, get_child_nodes, and get_deeper_nodes. That grouping indicates a two-part workflow. First, parsing creates nodes with relationships across levels of granularity. Then application code chooses which level to embed, retrieve, display, expand, or send into response synthesis. Leaf nodes can support precise retrieval, while root or parent nodes can restore enough context to answer questions that span a larger section. Sources: docs/api_reference/api_reference/node_parsers/hierarchical.md

Execution Flow and Usage Patterns

Use standalone parsing when you are learning a corpus, designing tests, or tuning chunk boundaries before committing to an ingestion architecture. The official getting-started flow creates a document, initializes a sentence-based splitter, and asks the parser to produce nodes. This is intentionally simple: it lets developers inspect node text, inherited metadata, and chunk counts without also debugging embeddings, persistence, or retrieval. A good first task is to run the parser on a few representative files, examine the shortest and longest chunks, and verify that headings, citations, and important entities remain attached to useful context.

from llama_index.core import Document
from llama_index.core.node_parser import SentenceSplitter
 
node_parser = SentenceSplitter(chunk_size=1024, chunk_overlap=20)
 
nodes = node_parser.get_nodes_from_documents(
    [Document(text="long text")], show_progress=False
)

Use transformation-based parsing when chunking is one phase in a repeatable data-preparation workflow. An ingestion pipeline can combine loading, parsing, metadata extraction, embedding, and storage preparation. Putting the parser in the transformation list makes chunking explicit, reviewable, and repeatable across local development, scheduled refreshes, and production ingestion. It also makes the parser easier to swap when the corpus changes. For example, a prototype might begin with token-based splitting for predictable context sizes, then move to a format-aware parser after evaluation reveals that structural boundaries are more important than uniform chunk length.

from llama_index.core import SimpleDirectoryReader
from llama_index.core.ingestion import IngestionPipeline
from llama_index.core.node_parser import TokenTextSplitter
 
documents = SimpleDirectoryReader("./data").load_data()
pipeline = IngestionPipeline(transformations=[TokenTextSplitter()])
nodes = pipeline.run(documents=documents)

Use index-level configuration when parsing is part of the index policy. The official examples show both global settings and a per-index transformation list used during construction from documents. A global splitter is convenient for notebooks and small applications where one corpus-wide policy is adequate. A per-index parser is safer when different indexes need different boundaries, such as a documentation index, a source-code index, and a structured data index living in the same application. This separation avoids accidentally applying a prose splitter to code or a JSON-aware parser to ordinary narrative text.

from llama_index.core import SimpleDirectoryReader, VectorStoreIndex, Settings
from llama_index.core.node_parser import SentenceSplitter
 
documents = SimpleDirectoryReader("./data").load_data()
Settings.text_splitter = SentenceSplitter(chunk_size=1024, chunk_overlap=20)
 
index = VectorStoreIndex.from_documents(
    documents,
    transformations=[SentenceSplitter(chunk_size=1024, chunk_overlap=20)],
)

Parser Families and Selection Guidance

Choose a general sentence or token splitter when the corpus is mostly prose and fixed-size chunks with predictable overlap are enough. This is a common starting point for extracted PDFs, markdown guides, support knowledge bases, and long-form articles. Sentence-aware chunking tends to preserve readability, while token-aware chunking can make model context budgeting easier. The important review step is not only whether chunks are the right average size, but whether a retrieved chunk can stand alone as useful evidence. If a chunk regularly needs the previous paragraph to be understandable, increase overlap or consider hierarchy.

Choose CodeSplitter when the corpus contains source files, notebooks, generated code, or example snippets where arbitrary paragraph boundaries would break meaning. Code retrieval often depends on keeping nearby imports, function signatures, class definitions, comments, and implementation bodies together. A code-aware parser keeps code chunking inside the same LlamaIndex node parsing surface as other data preparation steps, instead of requiring a separate preprocessing system. This is especially useful when a single application indexes both prose documentation and repository source, because each corpus can still produce ordinary nodes for downstream retrieval. Sources: docs/api_reference/api_reference/node_parsers/code.md

Choose HTMLNodeParser or JSONNodeParser when the input format already carries useful structure. HTML pages may include headings, nested sections, lists, tables, navigation, and other markup that should influence how chunks are formed. JSON documents may represent objects, arrays, records, and field names that give text its meaning. Format-aware parsing can preserve those relationships better than a plain length-based split. The result is often easier to debug because retrieved nodes align with visible source structure rather than starting and ending at arbitrary character or token offsets. Sources: docs/api_reference/api_reference/node_parsers/html.md, docs/api_reference/api_reference/node_parsers/json.md

Choose LangchainNodeParser when a project already has validated LangChain splitting logic or needs a LangChain splitter for a specific data type. The adapter keeps the rest of the application on the LlamaIndex node contract, so indexes, retrievers, response synthesizers, and evaluators can work with normal nodes. This is useful during migrations, hybrid stacks, and staged rewrites. Instead of changing chunking and retrieval at the same time, teams can preserve a known splitter decision while moving the downstream indexing or query pipeline into LlamaIndex. Sources: docs/api_reference/api_reference/node_parsers/langchain.md

Hierarchical Parsing and Retrieval Design

Hierarchical parsing is best understood as a strategy for separating retrieval granularity from answer context. A common RAG failure mode occurs when a highly relevant small chunk is retrieved, but the language model lacks the surrounding section needed to answer accurately. Hierarchical nodes allow applications to embed or search at one level and then expand to related nodes before synthesis. The public helper functions reveal the intended traversal vocabulary: select leaves for fine-grained matching, roots for broad context, immediate children for expansion, and deeper descendants when the application needs more detail. Sources: docs/api_reference/api_reference/node_parsers/hierarchical.md

When designing a hierarchical workflow, decide which node level is stored in the primary retriever, which level is displayed to users as source evidence, and which level is sent to the language model. Those choices do not have to be identical. For example, a retriever may use small leaf nodes because they match questions precisely, while the final answer may include parent text so definitions and caveats remain available. Conversely, a summarization workflow may operate from root nodes first and only drill down into children when the user asks for specific details.

The helper names also help define edge-case behavior. If retrieved results are too narrow, move from leaves to parents or deeper related nodes before synthesis. If results are too broad, retrieve leaves first and expand only when confidence or answer completeness requires it. If citations are confusing, inspect whether the displayed node is the same level as the searched node. Hierarchy gives more flexibility, but it also adds responsibility: the application must make explicit which level is being embedded, filtered, reranked, summarized, and shown as provenance. Sources: docs/api_reference/api_reference/node_parsers/hierarchical.md

Implementation Checklist and Next Steps

Treat parser configuration as part of evaluation, not as a one-time setup value. Before shipping, inspect chunk counts, average chunk length, overlap behavior, metadata contents, and a sample of retrieved nodes for the most important question types. If answers miss necessary context, try larger chunks, overlap, or hierarchical expansion. If retrieval returns broad but weakly relevant passages, try smaller chunks or a format-aware parser. If source structure matters, prefer the API family member that matches the format. If an existing LangChain splitter is already trusted, adapt it rather than changing two systems at once. Sources: docs/api_reference/api_reference/node_parsers/code.md, docs/api_reference/api_reference/node_parsers/html.md, docs/api_reference/api_reference/node_parsers/json.md, docs/api_reference/api_reference/node_parsers/langchain.md

Metadata inheritance is another important design constraint. The official node parser guidance states that when documents are broken into nodes, document attributes such as metadata, text templates, and metadata templates are inherited by child nodes. That means upstream readers and metadata extractors should run before parsing when their output should be attached to every chunk. It also means overly broad or noisy document metadata can be duplicated many times. Good metadata improves filtering, observability, citations, and debugging, while noisy metadata can make retrieved nodes harder to interpret.

After selecting a parser, connect this page to the rest of the data path. Read Documents and Nodes to understand the objects being produced, then Ingestion Pipelines to place parsing inside repeatable transformations, and then Vector Store Indexing or Retrievers to see how parsed nodes are searched. For multi-level context recovery, keep the hierarchical helper functions in view while designing retrieval and synthesis. For format-specific corpora, start from the API reference member matching the source format before tuning general chunk sizes.

Ask a question...