What is .add_documents()?
.add_documents() is the standard method for incrementally adding Document objects to an existing LangChain vector store. Where from_documents() creates a new store from scratch, add_documents() targets an already-initialized store, embeds the new documents using the store's configured embedding function, and inserts the resulting vectors. It returns a list of string IDs — one per document — that can be used later for deletion or retrieval by ID.
Under the hood, the method calls the embedding function's embed_documents() on the page_content strings, then passes the vectors and metadata to the underlying database's insert API. Most implementations batch the embedding calls automatically, so passing a thousand documents at once is efficient. The optional ids parameter lets you specify custom IDs instead of auto-generated UUIDs — important for idempotent indexing pipelines where you want to avoid duplicates on re-ingestion.
The key distinction from add_texts() is that add_documents() accepts Document objects, which carry a metadata dict alongside page_content. This metadata — source URL, timestamp, section heading, chunk index — is stored alongside the vector and surfaced in retrieval results as doc.metadata. For any RAG pipeline that needs to cite sources or filter at query time with metadata filters, always use add_documents() with rich metadata rather than add_texts().
Use Cases
- • Incremental indexing
- • Adding new docs
- • Updating indexes
- • Batch additions
- • Growing knowledge base
- • Continuous updates
Key Features
- ✓ Add to existing
- ✓ Metadata support
- ✓ Batch addition
- ✓ Returns IDs
- ✓ Efficient updates
- ✓ Maintains index
When NOT to Use
Creating a new store—use from_documents().
Notes
No deduplication by default
Most vector stores do not deduplicate on insert. Calling add_documents() twice with the same content creates duplicate vectors, which inflates retrieval results. Use the ids parameter with deterministic IDs (e.g., hash of content) to enable upsert behavior in stores that support it.
Metadata must use scalar values
Some vector databases, including Chroma, reject metadata values that are dicts or lists. Flatten metadata to scalar types — str, int, float, bool — before calling add_documents(). A nested dict in metadata will raise a ValueError at insert time.
Store the returned IDs for deletion
The returned IDs are assigned by the vector store. For Chroma they are UUIDs; for Pinecone they are the id field from the upsert. Store these IDs in your application database if you need targeted deletion later — vector stores do not provide a search-by-content delete method.
Async variant available
Use aadd_documents() for non-blocking addition in async pipelines. The signature is identical but the method is a coroutine: ids = await store.aadd_documents(docs). Available on all major vector stores.
Method Signature
ids = vector_store.add_documents(documents)Parameters
| Parameter | Type | Required | Purpose |
|---|---|---|---|
| documents | List[Document] | Yes | Documents to add |
Return Value
Type:
List[str]
Description:
IDs of added documents
Example Output:
['id1', 'id2', ...]Code Examples
Incremental add to existing store
new_docs = loader.load()
ids = vector_store.add_documents(new_docs)
print(f'Added {len(ids)} documents')Idempotent add with deterministic IDs
from langchain_core.documents import Document
import hashlib
def make_id(text: str) -> str:
return hashlib.md5(text.encode()).hexdigest()
docs = [
Document(
page_content='LangChain simplifies LLM apps.',
metadata={'source': 'intro', 'ts': '2026-01-01'}
),
Document(
page_content='Vector stores enable semantic search.',
metadata={'source': 'guide', 'ts': '2026-01-02'}
),
]
ids = [make_id(d.page_content) for d in docs]
vector_store.add_documents(docs, ids=ids)Async add with aadd_documents
import asyncio
async def async_index(store, docs):
ids = await store.aadd_documents(docs)
print(f'Async added {len(ids)} docs')
return ids
asyncio.run(async_index(vector_store, new_docs))Common Mistakes
❌ Use from_documents() each time to add docs
✅ Use add_documents() for efficiency
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 .add_documents() and the wider framework.
.add_documents() FAQ
What does .add_documents() do in LangChain?
Add Document objects to existing vector store. .add_documents() is the standard method for incrementally adding Document objects to an existing LangChain vector store. Where from_documents() creates a new store from scratch, add_documents() targets an already-initialized store, embeds the new documents using the store's configured embedding function, and inserts the resulting vectors. It returns a list of string IDs — one per document — that can be used later for deletion or retrieval by ID. Under the hood, the method ca…
Which LangChain classes support .add_documents()?
.add_documents() is available on Vector stores. Pin your installed LangChain version and verify the method exists in that release before deploying.
When should I use .add_documents()?
Use .add_documents() when your LangChain chains, agents, or pipelines need the behavior described in this guide.
What does .add_documents() return?
.add_documents() returns a List[str]. IDs of added documents
Does .add_documents() have an async equivalent?
Yes — use aadd_documents() for async contexts such as FastAPI handlers or asyncio-based pipelines. It is the non-blocking counterpart to .add_documents().
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.