What is .split_documents()?
.split_documents() is the standard chunking method when your input is a list of LangChain Document objects (typically produced by a document loader). Unlike .split_text(), which takes a raw string, .split_documents() accepts List[Document] and preserves the metadata from each source document — every chunk produced from a Document inherits that document's metadata dict. This is essential for citation tracking in RAG: you can always trace a chunk back to its source file, page number, or URL.
Internally, .split_documents() calls .split_text() on each document's page_content, then wraps each resulting text chunk in a new Document with the parent's metadata copied in. The configured chunk_size, chunk_overlap, and separators all apply exactly as they do for .split_text(). The chunk_overlap parameter (commonly 100–200 characters) ensures that ideas crossing chunk boundaries are represented in both adjacent chunks, which reduces retrieval gaps for sentence-spanning concepts.
The right splitter class depends on your content type. RecursiveCharacterTextSplitter is the general-purpose default — it splits on paragraph breaks, then sentences, then words, trying to keep chunks semantically coherent. MarkdownHeaderTextSplitter preserves heading structure for markdown files. RecursiveJsonSplitter handles nested JSON. HTMLHeaderTextSplitter groups by HTML headings. For code files, the language-aware RecursiveCharacterTextSplitter.from_language() is the right choice. All of these expose the same .split_documents() interface.
Use Cases
- • Split loaded docs
- • Preserve metadata
- • Chunking pipeline
- • Multi-doc processing
- • RAG preparation
- • Batch splitting
Key Features
- ✓ Document objects
- ✓ Metadata preserved
- ✓ Semantic boundaries
- ✓ Configurable overlap
- ✓ Multiple formats
- ✓ Language support
When NOT to Use
For raw text—use split_text().
Notes
Metadata is shared by reference then copied — mutating a chunk's metadata affects only that chunk
Each chunk gets a shallow copy of the parent document's metadata dict. Modifying chunk.metadata after the fact (e.g., adding a chunk_index key) only affects that chunk, not the parent or siblings. This is intentional — you can safely add per-chunk metadata like {"chunk_id": i} in a post-processing step.
chunk_overlap adds redundancy — calibrate to your retrieval strategy
Overlap of 10–20% of chunk_size is typically a good starting point. Too little overlap and sentences at chunk boundaries are split in half, causing retrieval to miss relevant context. Too much overlap inflates storage costs and can confuse the LLM with near-duplicate passages. For 1000-character chunks, 150–200 character overlap is a common default.
The length_function parameter controls how chunk_size is measured
By default, chunk_size is measured in characters (len). If your embedding model has a token budget (e.g., text-embedding-3-small has an 8191-token limit), you can pass length_function=tiktoken_len to measure in tokens instead. Mixing character-based splitting with token-based embedding models often produces chunks that exceed the embedding model's limit for non-ASCII text.
split_documents() vs split_text() — use the one that matches your input type
If your input is a list of Document objects from a loader, use split_documents(). If your input is a raw Python string (e.g., text scraped manually or from a database), use split_text() which returns List[str]. You then wrap those strings in Document() if needed: Document(page_content=chunk, metadata={"source": "manual"}).
Method Signature
chunks = splitter.split_documents(documents)Parameters
| Parameter | Type | Required | Purpose |
|---|---|---|---|
| documents | List[Document] | Yes | Documents to split |
Return Value
Type:
List[Document]
Description:
Split document chunks
Example Output:
[Document(...), Document(...), ...]Code Examples
Basic split with overlap
from langchain_text_splitters import RecursiveCharacterTextSplitter
splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
chunks = splitter.split_documents(docs)
print(f"{len(chunks)} chunks from {len(docs)} documents")PDF chunking with metadata preserved
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import PyPDFLoader
loader = PyPDFLoader('handbook.pdf')
docs = loader.load()
splitter = RecursiveCharacterTextSplitter(
chunk_size=800,
chunk_overlap=150,
length_function=len
)
chunks = splitter.split_documents(docs)
# Each chunk carries {"source": "handbook.pdf", "page": N}
print(chunks[0].metadata)Language-aware splitting for Python code
from langchain_text_splitters import Language, RecursiveCharacterTextSplitter
splitter = RecursiveCharacterTextSplitter.from_language(
language=Language.PYTHON,
chunk_size=500,
chunk_overlap=50
)
code_chunks = splitter.split_documents(code_docs)Common Mistakes
❌ split_text() with Document objects
✅ Use split_documents() for Document objects
Related LangChain References
Browse the full LangChain API reference index to explore more classes, methods, and decorators, or start with the LangChain introduction tutorial for end-to-end context on building with .split_documents() and the wider framework.
.split_documents() FAQ
What does .split_documents() do in LangChain?
Split Document objects into chunks. .split_documents() is the standard chunking method when your input is a list of LangChain Document objects (typically produced by a document loader). Unlike .split_text(), which takes a raw string, .split_documents() accepts List[Document] and preserves the metadata from each source document — every chunk produced from a Document inherits that document's metadata dict. This is essential for citation tracking in RAG: you can always trace a chunk back to its source file, page n…
Which LangChain classes support .split_documents()?
.split_documents() is available on Text splitters. Pin your installed LangChain version and verify the method exists in that release before deploying.
When should I use .split_documents()?
Use .split_documents() when your LangChain chains, agents, or pipelines need the behavior described in this guide.
What does .split_documents() return?
.split_documents() returns a List[Document]. Split document chunks
Does .split_documents() have an async equivalent?
.split_documents() does not have a documented async variant. Avoid .split_documents() For raw text—use split_text().
Where can I explore more LangChain API reference pages?
Open the LangChain API reference index on DevShelfHub to browse classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.