vectorstores — Pinecone, FAISS, Chroma, Weaviate, ... uniform interface

Pinecone, FAISS, Chroma, Weaviate, ... uniform interface

Module langchain_classic/vectorstores/ — Pinecone, FAISS, Chroma, Weaviate, ... uniform interface. Part of the Retrieval & Data group.

🎯 Why This Module Exists

VectorStore is a uniform façade over 60+ similarity-search backends (FAISS, Chroma, Pinecone, Weaviate, Milvus, Qdrant, ...). The contract: add_texts/add_documents to ingest, similarity_search/similarity_search_by_vector to query, plus optional MMR (max marginal relevance) and metadata filters. Every retriever in retrievers/ ultimately calls into one of these.

Source files

Sub-directories

Retrieval & Data

Architecture

flowchart LR
  subgraph Core["langchain_classic/vectorstores/"]
    BASE["Base abstraction"]
    IMPLS["Concrete implementations"]
    BASE --> IMPLS
  end
  subgraph Up["Upstream callers"]
    U1["chains/"]
    U2["agents/"]
  end
  subgraph Down["Downstream"]
    D1["langchain_core"]
    D2["External providers"]
  end
  Up --> Core
  Core --> Down

Data Flow

sequenceDiagram
  participant Caller as Caller
  participant Vectorst as vectorstores
  participant Core as langchain_core
  participant Ext as External
  Caller->>Vectorst: invoke(input)
  Note over Vectorst: Validate & route
  Vectorst->>Core: delegate primitive
  Core->>Ext: provider call
  Ext-->>Core: response
  Core-->>Vectorst: typed output
  Vectorst-->>Caller: result

Design Decisions

Decision	Choice Made	Alternatives	Why This Approach
Provider isolation	Each backend in its own file with optional dep import	Heavy core	Users only install drivers they need
MMR support	Optional method on base; not all backends implement	Always implement, fallback in-process	MMR done in-process can dominate latency for large k
Metadata filters	Backend-specific filter dicts pass-through	Universal filter language	Backends support different filter grammars; lossy translation would surprise users
Persistence	from_texts factory writes index; load via __init__	Always-persistent	Some backends are pure remote; nothing to persist locally

The VectorStore.as_retriever() bridge produces a BaseRetriever, connecting this module to retrievers/.

Step-by-Step Walkthrough

Follow a typical operation through the vectorstores/ module:

Caller invokes the public surface — usually .invoke(input) on a Runnable, or a legacy __call__(inputs_dict) on a Chain subclass.
Pydantic validation — every entry point is a BaseModel; constructor args, input dicts, and tool args_schema are validated before any expensive work runs. Fail-fast on type errors.
CallbackManager.configure — a fresh manager is built per call, fans on_*_start events to all subscribers (LangSmith tracer, stdout handler, custom logging), and stamps a UUID4 run_id for tree reconstruction.
vectorstores-specific logic — the module's core method runs: prompt rendering, retrieval, tool execution, memory load, document split, etc. See the deep-dive sections above.
Provider call — typically a single HTTP request to OpenAI/Anthropic/etc., or a local SDK call. Retries are handled by tenacity with exponential backoff and a configurable max-attempts knob.
Streaming fan-out — if the provider streams tokens, each chunk fires on_llm_new_token through the callback manager so downstream observers (UI, log, tracer) see partial output.
OutputParser pass — if a parser is attached, the raw provider output is parsed into a structured Python object; OutputParserException may trigger a retry chain (RetryWithErrorOutputParser).
Memory write-back — for chains/agents that have a BaseMemory attached, save_context(inputs, outputs) persists the turn before returning to the caller.
on_*_end fan-out — the callback manager closes the run span; tracers serialise the Run tree and ship it to LangSmith asynchronously.
Result returned — caller receives a typed object (AIMessage, dict, BaseModel, list[Document], ...) matching the module's declared output schema.

What Could Go Wrong

Failure Mode	Trigger	Detection	Recovery
Provider 5xx / rate-limit	OpenAI/Anthropic/etc. transient error	HTTP status from SDK	tenacity retries with exponential backoff up to `max_retries`; then surface to caller
Output parser failure	LLM returned malformed JSON / wrong schema	`OutputParserException` in parser	`RetryWithErrorOutputParser` re-prompts with the parser error included; or surface
Pydantic validation	Caller passes wrong-shaped dict	`ValidationError` at `__init__` / `invoke`	Surface immediately — no fallback is correct here
Callback handler exception	User-supplied tracer raises	Try/except around each fan-out	Logged and swallowed by default; `raise_error=True` to opt in to propagation
Provider auth missing	`OPENAI_API_KEY` unset	SDK `AuthenticationError`	Surface with a helpful message; no retry (would just fail again)

Performance Profile

Hot Paths

Provider HTTP round-trip dominates wall-clock time (100ms–30s depending on model and prompt length).
Pydantic validation is repeated on every invoke; cached schema parsing keeps it under 1ms for typical inputs.
Callback fan-out is synchronous by default — a slow handler will slow every call. Async tracers (LangSmith) push work to a background thread to avoid blocking.

Resource Usage

Memory: token-history buffers (in memory/) and document caches (in retrieval pipelines) are the largest steady-state allocations.
I/O: bounded by provider rate limits; vector store I/O for retrieval-flavored modules.
Concurrency: async support via a* methods; agents and parallel chains use asyncio.gather for concurrent tool calls.

Directory Map

Source tree for vectorstores

vectorstores/
├── __init__.py
├── alibabacloud_opensearch.py
├── analyticdb.py
├── annoy.py
├── astradb.py
├── atlas.py
├── awadb.py
├── azure_cosmos_db.py
├── azuresearch.py
├── bageldb.py
├── baiducloud_vector_search.py
├── base.py
├── cassandra.py
├── chroma.py
├── clarifai.py
├── clickhouse.py
├── dashvector.py
├── databricks_vector_search.py
├── deeplake.py
├── dingo.py
├── docarray/
├── elastic_vector_search.py
├── elasticsearch.py
├── epsilla.py
├── faiss.py
├── hippo.py
├── hologres.py
├── lancedb.py
├── llm_rails.py
├── marqo.py
├── matching_engine.py
├── meilisearch.py
├── milvus.py
├── momento_vector_index.py
├── mongodb_atlas.py
├── myscale.py
├── neo4j_vector.py
├── nucliadb.py
├── opensearch_vector_search.py
├── pgembedding.py
├── pgvecto_rs.py
├── pgvector.py
├── pinecone.py
├── qdrant.py
├── redis/
├── rocksetdb.py
├── scann.py
├── semadb.py
├── singlestoredb.py
├── sklearn.py
├── sqlitevss.py
├── starrocks.py
├── supabase.py
├── tair.py
├── tencentvectordb.py
├── tiledb.py
├── timescalevector.py
├── typesense.py
├── usearch.py
├── utils.py
    ... (more files truncated)