What is .from_documents()?
.from_documents() is a class method (factory method) available on all LangChain vector store classes — Chroma, FAISS, Pinecone, Weaviate, Qdrant, and others. It accepts a list of Document objects, an embedding model, and optional backend keyword arguments, then embeds all documents and returns a fully initialized vector store in a single call. Internally it calls .embed_documents() on the text content, generates UUIDs for each chunk, and delegates to the backend's storage layer.
The key advantage over .from_texts() is that Document objects carry a metadata dict alongside their page_content. That metadata survives ingestion and becomes filterable at query time using similarity_search(query, filter={"source": "report.pdf"}) in most backends. This makes .from_documents() the standard choice for RAG pipelines where you need to attribute retrieved chunks back to source files, page numbers, or other structured provenance.
Persistence behavior varies by backend and is not automatic. Chroma.from_documents() stores everything in-memory by default — the data is lost when the process exits unless you pass persist_directory=".chroma_db". FAISS.from_documents() is always in-memory and must be explicitly saved with .save_local(path) and reloaded with FAISS.load_local(path, embeddings). Cloud-native stores like Pinecone and Weaviate persist automatically via their APIs. Always verify persistence semantics for your specific backend before deploying to production.
Use Cases
- • Initialize a RAG retriever from PDF or web-loaded documents
- • Index a document collection with source metadata for filtered retrieval
- • Build a persistent Chroma or FAISS index for production
- • Create vector stores with stable IDs for later update/delete operations
- • One-step ingestion after text splitting in a RAG pipeline
- • Prototype a retrieval chain without writing embedding boilerplate
Key Features
- ✓ Factory method — embeds and stores in one call
- ✓ Preserves Document metadata for filterable retrieval
- ✓ Works with Chroma, FAISS, Pinecone, Weaviate, Qdrant, and more
- ✓ Auto-generates UUIDs unless ids= is provided
- ✓ Calls embed_documents() internally — subject to provider rate limits
- ✓ Returned store is immediately queryable via similarity_search()
When NOT to Use
When your content is raw text strings with no metadata — use from_texts() for simpler syntax. When adding to an existing store — use .add_documents() instead.
Notes
Chroma is in-memory by default — add persist_directory for production
Chroma.from_documents() without persist_directory stores data in RAM. The entire index is lost when the process exits. Always pass persist_directory=".chroma_db" (or your chosen path) in production. On older Chroma versions you also need to call .persist() explicitly; newer versions auto-persist on write.
FAISS requires explicit save/load for persistence
FAISS.from_documents() is always in-memory. Call vs.save_local("./faiss_index") to write the index to disk, and FAISS.load_local("./faiss_index", embeddings, allow_dangerous_deserialization=True) to reload it. The allow_dangerous_deserialization flag is required as of LangChain 0.1.x due to pickle-based serialization.
Use ids= for stable document identity
By default, from_documents() assigns random UUIDs. If you need to update or delete specific documents later (e.g., re-indexing changed files), pass ids=["your-stable-id", ...] with the same length as documents. IDs must be unique within the store.
Large collections hit embedding rate limits
from_documents() calls embed_documents() on the full list in one pass, which the SDK internally batches. For 50K+ documents, prefer a loop: build the store with the first batch using from_documents(), then add subsequent batches with .add_documents() — this lets you add retry logic and progress tracking around each batch.
Method Signature
vector_store = VectorStore.from_documents(documents, embedding, **kwargs)Parameters
| Parameter | Type | Required | Purpose |
|---|---|---|---|
| documents | List[Document] | Yes | List of Document objects with page_content and optional metadata |
| embedding | Embeddings | Yes | Embedding model used to encode document content |
| ids | List[str] | No | Stable string IDs for each document (auto-generated if omitted) |
Return Value
Type:
VectorStore
Description:
Initialized vector store with all documents embedded and indexed
Example Output:
Chroma(collection_name="langchain", ...)Code Examples
Load, split, and index a PDF for RAG
from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings
from langchain_chroma import Chroma
loader = PyPDFLoader('report.pdf')
pages = loader.load() # List[Document] with page metadata
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
chunks = splitter.split_documents(pages)
embeddings = OpenAIEmbeddings(model='text-embedding-3-small')
vector_store = Chroma.from_documents(chunks, embeddings)
results = vector_store.similarity_search('key findings', k=4)
for r in results:
print(r.metadata['page'], r.page_content[:80])Persist to disk and filter by metadata
from langchain_chroma import Chroma
from langchain_openai import OpenAIEmbeddings
from langchain_core.documents import Document
embeddings = OpenAIEmbeddings(model='text-embedding-3-small')
docs = [
Document(page_content='LangChain enables LLM apps.', metadata={'source': 'docs', 'section': 'intro'}),
Document(page_content='LCEL chains Runnables together.', metadata={'source': 'docs', 'section': 'lcel'}),
]
# Persist to disk so data survives process restart
vector_store = Chroma.from_documents(
docs, embeddings, persist_directory='.chroma_db'
)
# Metadata filter at query time
results = vector_store.similarity_search(
'chaining runnables', k=2, filter={'section': 'lcel'}
)
print(results[0].page_content)FAISS with stable IDs and disk persistence
from langchain_community.vectorstores import FAISS
from langchain_openai import OpenAIEmbeddings
from langchain_core.documents import Document
embeddings = OpenAIEmbeddings(model='text-embedding-3-small')
docs = [Document(page_content=f'Document {i}') for i in range(5)]
ids = [f'doc-{i}' for i in range(5)] # stable IDs for future updates
vs = FAISS.from_documents(docs, embeddings, ids=ids)
# Save to disk and reload
vs.save_local('./faiss_index')
vs2 = FAISS.load_local('./faiss_index', embeddings, allow_dangerous_deserialization=True)Common Mistakes
❌ Chroma.from_texts([doc.page_content for doc in docs], embeddings) # silently drops all metadata
✅ Pass Document objects with metadata to from_documents() so metadata is preserved and filterable at query time
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 .from_documents() and the wider framework.
.from_documents() FAQ
What does .from_documents() do in LangChain?
Create and populate a vector store from Document objects in a single call, embedding content and preserving metadata. .from_documents() is a class method (factory method) available on all LangChain vector store classes — Chroma, FAISS, Pinecone, Weaviate, Qdrant, and others. It accepts a list of Document objects, an embedding model, and optional backend keyword arguments, then embeds all documents and returns a fully initialized vector store in a single call. Internally it calls .embed_documents() on the text content, generates UUIDs for each chunk, and delegates to the backend's storage lay…
Which LangChain classes support .from_documents()?
.from_documents() is available on Vector stores (class method). Pin your installed LangChain version and verify the method exists in that release before deploying.
When should I use .from_documents()?
Use .from_documents() when your LangChain chains, agents, or pipelines need the behavior described in this guide.
What does .from_documents() return?
.from_documents() returns a VectorStore. Initialized vector store with all documents embedded and indexed
Does .from_documents() have an async equivalent?
.from_documents() does not have a documented async variant. Avoid .from_documents() When your content is raw text strings with no metadata — use from_texts() for simpler syntax. When adding to an existing store — use .add_documents() instead.
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.