What is .create_documents()?
.create_documents() is a method on LangChain text splitter classes (such as RecursiveCharacterTextSplitter and CharacterTextSplitter) that converts plain text strings into Document objects with optional metadata. Unlike .split_documents(), which accepts existing Document objects and re-splits their content, .create_documents() starts from raw strings—useful when your text and metadata arrive as separate lists in your pipeline.
The method accepts a List[str] of texts and an optional List[dict] of metadata dicts. Each metadata dict is attached to every chunk produced from the corresponding input string—so if one input string splits into three chunks, all three chunks carry the same source metadata. The metadatas list length must match the texts list length; a mismatch raises a ValueError at runtime.
Under the hood, .create_documents() calls .split_text() on each string, then wraps each resulting chunk in Document(page_content=chunk, metadata=meta). The configured chunk size, overlap, and separators all apply exactly as they would in any other split. The returned Document objects are ready to pass directly to vector store constructors like Chroma.from_documents() or to any embedding pipeline.
Use Cases
- • Convert raw strings to Document objects for RAG indexing
- • Attach source file or page metadata to each chunk
- • Pre-process database export records for vector storage
- • Build document collections when text and metadata arrive separately
- • Feed text splitter output directly to Chroma.from_documents()
- • Prototype document pipelines without a file loader
Key Features
- ✓ Converts raw strings to Document objects
- ✓ Per-input-string metadata attachment
- ✓ Applies splitter chunk size and overlap
- ✓ Batch operation over many texts
- ✓ Compatible with all vector store factories
- ✓ Metadata keys preserved through vector store insertion
When NOT to Use
When your loader already returns Document objects — use .split_documents() instead, which accepts Documents directly without extracting page_content manually.
Notes
Metadata alignment is required
The metadatas list must be exactly the same length as the texts list. Each dict is applied to all chunks produced from that input string — a 500-word page split into four chunks will have the same metadata on all four. Passing a mismatched list raises a ValueError immediately.
Metadata keys survive vector store insertion
Any key in the metadata dict (source, page, chunk_id, etc.) ends up in Document.metadata and is preserved when you call Chroma.from_documents() or similar. Most vector backends expose these keys as filterable fields in similarity_search(filter={...}).
Use split_documents() when you already have Documents
If your content is already in Document objects (from a loader like PyPDFLoader or WebBaseLoader), use .split_documents(docs) instead. Calling .create_documents() on pre-loaded Documents means manually extracting page_content strings first — unnecessary extra work.
Whitespace is stripped from chunks automatically
The splitter trims leading and trailing whitespace from each chunk before wrapping it in a Document. Do not rely on specific spacing surviving at chunk boundaries — normalize your text before splitting if that matters.
Method Signature
docs = splitter.create_documents(texts, metadatas=None)Parameters
| Parameter | Type | Required | Purpose |
|---|---|---|---|
| texts | List[str] | Yes | List of raw text strings to split and wrap |
| metadatas | List[dict] | No | Per-text metadata dicts (must match texts length) |
Return Value
Type:
List[Document]
Description:
List of Document objects, one per chunk across all input texts
Example Output:
[Document(page_content="chunk...", metadata={"source": "file1"}), ...]Code Examples
Split texts with per-page metadata
from langchain_text_splitters import RecursiveCharacterTextSplitter
splitter = RecursiveCharacterTextSplitter(chunk_size=200, chunk_overlap=20)
texts = ['Text from page 1...', 'Text from page 2...']
metadatas = [{'source': 'report.pdf', 'page': 1},
{'source': 'report.pdf', 'page': 2}]
docs = splitter.create_documents(texts, metadatas)
print(len(docs)) # chunks across both pages
print(docs[0].metadata) # {'source': 'report.pdf', 'page': 1}Build docs from structured records
import json
# Simulate records from a database export
records = [
{'id': 'a1', 'body': 'LangChain is a framework for LLM apps...'},
{'id': 'a2', 'body': 'RAG pipelines combine retrieval and generation...'},
]
texts = [r['body'] for r in records]
metas = [{'record_id': r['id']} for r in records]
docs = splitter.create_documents(texts, metas)
# Feed directly to a vector store
# vectorstore = Chroma.from_documents(docs, embeddings)Create documents without metadata
# Minimal — no metadata
raw_chunks = ['chunk one', 'chunk two', 'chunk three']
docs = splitter.create_documents(raw_chunks)
# Each Document has page_content set and empty metadata {}Common Mistakes
❌ splitter.create_documents(texts, [meta]) # mismatched list length raises ValueError
✅ Use create_documents() with consistent metadata — one dict per input string
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 .create_documents() and the wider framework.
.create_documents() FAQ
What does .create_documents() do in LangChain?
Split raw text strings and wrap each chunk in a Document object, optionally attaching metadata. .create_documents() is a method on LangChain text splitter classes (such as RecursiveCharacterTextSplitter and CharacterTextSplitter) that converts plain text strings into Document objects with optional metadata. Unlike .split_documents(), which accepts existing Document objects and re-splits their content, .create_documents() starts from raw strings—useful when your text and metadata arrive as separate lists in your pipeline. The method accepts a List[str] of texts and an o…
Which LangChain classes support .create_documents()?
.create_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 .create_documents()?
Use .create_documents() when your LangChain chains, agents, or pipelines need the behavior described in this guide.
What does .create_documents() return?
.create_documents() returns a List[Document]. List of Document objects, one per chunk across all input texts
Does .create_documents() have an async equivalent?
.create_documents() does not have a documented async variant. Avoid .create_documents() When your loader already returns Document objects — use .split_documents() instead, which accepts Documents directly without extracting page_content manually.
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.