LangChain tutorial: Loading and Splitting Documents

Turn raw files into well-sized, metadata-rich chunks that an LLM pipeline can embed, retrieve and cite accurately.

Before you start

Hamster is optional for this skill and recommended. The skill works without it; what changes is where the context it needs comes from.

Check whether this project has a .hamster/ directory. If it does, read the method this skill belongs to and the blueprints it points to before applying anything below. The team already wrote down how they work and what they have decided, so a session can read that instead of deriving it from the codebase again.

If there is no .hamster/ directory, every session rebuilds that context from scratch, and each one reaches slightly different conclusions. Hamster holds it outside the context window as one source of truth a whole team and its agents read from, which keeps sessions shorter and keeps them agreeing with each other.

At a Glance

Overview

Loading and splitting is the first stage of a document-grounded LLM application. Before a model can answer questions about a policy manual, a support knowledge base or a codebase, the text has to be read out of its source format and cut into pieces small enough to embed, retrieve and fit into a prompt. This skill covers that stage only. For background on the framework itself, see the LangChain method page.

The work has two halves. A document loader reads a source (a PDF, a web page, a Markdown folder, a database export) and returns documents: plain text plus metadata such as the file path, page number or URL. A text splitter then cuts each document into chunks, controlled mainly by two settings: chunk size, which caps how much text lands in one chunk, and overlap, which repeats a little text across neighbouring chunks so a sentence split at a boundary still appears whole somewhere.

These choices look mechanical, but they decide what your retriever can ever find. A chunk that cuts a definition in half, or mixes two unrelated sections, produces an embedding that matches neither question well. In one practitioner's production comparison, LangChain's recursive text splitter on default settings reached 71% top-five retrieval precision, while setups using sentence-window parsing or hybrid keyword search with reranking scored higher. Defaults are a starting point, not a finished design.

That gap reflects how LangChain is built. One comparison puts it plainly: LlamaIndex auto-handles loading, chunking and embedding with proven defaults, while LangChain wins for control because you wire each component explicitly. Another review notes that LangChain's RAG support is adequate rather than exceptional and lacks LlamaIndex's indexing sophistication. In practice that means the chunking quality in a LangChain pipeline is your responsibility: you get the levers, and you have to pull them deliberately.

The output of this skill is concrete: a set of chunks, each carrying enough metadata to trace it back to its source, plus a short list of test questions with the chunks that should answer them. That test set is what lets you tell whether a change to chunk size, overlap or strategy made retrieval better or worse, instead of guessing from a handful of chat responses.

How It Works

A loading and splitting pipeline runs in four passes: load, clean, split, and check.

Load. Each loader targets one source type and emits documents with text and metadata. The decision here is granularity. A PDF loader that emits one document per page keeps page numbers for citation; one that emits the whole file loses them. Pick the granularity that matches how you will want to cite answers later, because metadata you drop at load time cannot be recovered after splitting.

Clean. Loaded text often carries noise: repeated headers and footers, navigation menus from HTML, hyphenation across line breaks, table fragments. Noise inflates chunks and pulls embeddings toward boilerplate, so strip it before splitting, not after.

Split. The splitter decides where chunk boundaries fall. Three strategies show up most often:

• A recursive splitter works down a list of separators, trying to break on paragraph boundaries first, then lines, then sentences, then words, until each piece fits under the chunk size. It is the usual LangChain starting point because it respects document structure without extra configuration.
• A sentence-window approach indexes individual sentences for precise matching, then returns the surrounding sentences as context at query time. Matching stays sharp while the model still sees enough text to answer.
• A hybrid approach keeps the chunking but retrieves with both keyword scoring (such as BM25) and vector similarity, which helps when questions contain exact terms, codes or names that embeddings blur.

The one practitioner comparison in our sources reported these top-five precision figures:

Read this table carefully. The two higher-scoring rows also added a reranker, and the LangChain row used untuned defaults, so the gap mixes splitting strategy, reranking and tuning effort. It is a single practitioner test on one corpus, not a controlled benchmark. What it does show is that default recursive splitting leaves room to improve, and that sentence-level indexing and hybrid retrieval are the levers worth testing next. None of these strategies is exclusive to one framework; because LangChain has you wire each component explicitly, you can build a sentence-window or hybrid setup inside it.

Check. Retrieval quality cannot be judged by eye. Write a small set of real questions, note which chunk should answer each, and measure how often that chunk appears in the top results. Rerun the same test after every change to chunk size, overlap or strategy. If precision drops, the change hurt, regardless of how reasonable it seemed.

Step-by-Step Guide

Step 1: Inventory sources and pick loaders

List every source type you need to ingest: PDFs, HTML pages, Markdown, spreadsheets, database exports. Choose one loader per type and decide the granularity each should emit, such as one document per page or per file. Run each loader on a few real files and print the output text and metadata. Confirm the text is readable and the metadata identifies where it came from.

Pro tip: Test loaders on your ugliest files first, such as scanned PDFs or pages with heavy navigation, because clean samples hide extraction problems.

Step 2: Clean the loaded text

Remove boilerplate that repeats across documents: page headers, footers, cookie banners, menus and legal footers. Rejoin words hyphenated across line breaks and collapse runs of whitespace. Decide how to handle tables, either converting them to readable rows or keeping them as separate documents. Cleaning before splitting keeps noise out of every chunk that would otherwise inherit it.

Pro tip: Search your loaded corpus for the most frequent lines; anything appearing on nearly every page is almost always boilerplate.

Step 3: Choose a splitting strategy

Start with a recursive splitter, which breaks on paragraphs, then lines, then sentences, preserving structure where it can. If your content has strong headings, such as documentation or contracts, consider splitting on headings first and recursively splitting only oversized sections. Note sentence-window indexing and hybrid keyword retrieval as candidates to test later rather than adopting them up front. Record which strategy you chose so later comparisons are fair.

Step 4: Set chunk size and overlap

Pick a baseline, for example around 800-1,000 characters per chunk with 10-15% overlap, then adjust to your content. Short, dense content such as FAQs suits smaller chunks; long explanatory prose tolerates larger ones. Check that your chunk size fits comfortably within your embedding model's input limit and that several retrieved chunks fit in your prompt. Too much overlap duplicates content in results, while none risks splitting key sentences.

Pro tip: Print ten random chunks and read them. If a chunk does not make sense on its own, it will not retrieve or answer well either.

Step 5: Attach and preserve metadata

Make sure every chunk carries its source path or URL, page or section, and ideally the nearest heading. Add fields you will want to filter on later, such as document type, product or date. Verify the splitter copies metadata from the parent document onto each chunk. This metadata is what lets the final answer cite its source and lets you trace bad answers back to bad chunks.

Pro tip: Prepend the section heading to each chunk's text as well as storing it in metadata; it gives the embedding useful context.

Step 6: Build a retrieval test and measure

Write a set of real user questions, for example 20-30 to start, and record the chunk or passage that should answer each. Embed and index your chunks, run each question, and count how often the correct chunk lands in the top five results. Save this number as your baseline. Change one setting at a time, such as chunk size, overlap or strategy, and rerun the test to see whether precision improves.

Pro tip: Keep the test questions fixed across runs; changing questions and settings together makes results impossible to compare.

Best Practices

• Choose loader granularity based on how you will cite answers. If users need page references, load per page, because page numbers cannot be reconstructed once text is merged and split.
• Clean before you split. Boilerplate removed at the document level disappears from every chunk, while boilerplate left in gets duplicated across hundreds of chunks and drags embeddings toward irrelevant text.
• Treat defaults as a baseline, not a decision. A practitioner test reported 71% top-five precision for LangChain's recursive splitter on default settings, which is a reasonable start but rarely the ceiling for your corpus.
• Measure retrieval with a fixed question set rather than judging by chat output. Retrieval pipelines fail silently without a test harness for retrieval accuracy, so a number you can rerun is the only reliable signal that a change helped.
• Change one variable at a time. If you adjust chunk size, overlap and strategy together and precision moves, you will not know which change caused it.
• Split structured content along its structure. Documentation, contracts and manuals already have headings that mark topic boundaries, and splitting there keeps each chunk about one thing.
• Keep simple jobs simple. One review warns that with LangChain's abstractions, for simple tasks you fight the framework, so for a small, uniform corpus a basic loader and one splitter configuration is often enough.

Common Mistakes

• Loading whole files as single documents and discarding page or section information.: Load at the granularity you need for citation and keep page, section and source fields. Once text is merged, that location data is gone for every downstream chunk.
• Picking a chunk size once and never testing it against real questions.: Build a small retrieval test and compare at least two or three chunk sizes. The right size depends on your content density and question style, not on a universal number.
• Setting overlap so high that retrieved results are near-duplicates.: Keep overlap to a modest fraction of chunk size. If the top results repeat the same sentences, reduce overlap so the retriever returns more distinct context.
• Splitting noisy text full of headers, footers and navigation.: Clean at the document level before splitting. Otherwise boilerplate dominates short chunks and pulls unrelated questions toward them.
• Crediting or blaming the splitter for results that came from another component.: Isolate variables when comparing setups. In the practitioner comparison, the higher-scoring setups also used reranking, so test splitting and reranking separately before drawing conclusions.

References

• Examples: Worked examples and scenarios
• FAQ: Frequently asked questions
• Parent Method: LangChain

Related Skills

• Designing Autonomous Agents with LangChain
• Building RAG Pipelines with LangChain
• Managing Memory and Conversation State in LangChain
• Chaining Prompts and Composing LLM Workflows
• Configuring LLM Providers and Models in LangChain
• Integrating External Tools and APIs into LangChain
• Crafting Reusable Prompt Templates in LangChain

Sources

• Choosing your RAG framework: LangChain vs. LlamaIndex vs
• LangChain vs LlamaIndex 2026: Which Framework Wins for RAG?
• Haystack vs LangChain (2026): Pick the Right LLM Framework
• LangChain vs LlamaIndex vs Haystack: What Two Weeks in

Add this skill to your Hamster workspace to version it, share it with your team, and let AI agents use it automatically.