*   [](/v0.2/)
*   [Tutorials](/v0.2/docs/tutorials/)
*   Vector stores and retrievers

On this page

Vector stores and retrievers
============================

This tutorial will familiarize you with LangChain's vector store and retriever abstractions. These abstractions are designed to support retrieval of data-- from (vector) databases and other sources-- for integration with LLM workflows. They are important for applications that fetch data to be reasoned over as part of model inference, as in the case of retrieval-augmented generation, or RAG (see our RAG tutorial [here](/v0.2/docs/tutorials/rag/)).

Concepts[​](#concepts "Direct link to Concepts")
------------------------------------------------

This guide focuses on retrieval of text data. We will cover the following concepts:

*   Documents;
*   Vector stores;
*   Retrievers.

Setup[​](#setup "Direct link to Setup")
---------------------------------------

### Jupyter Notebook[​](#jupyter-notebook "Direct link to Jupyter Notebook")

This and other tutorials are perhaps most conveniently run in a Jupyter notebook. See [here](https://jupyter.org/install) for instructions on how to install.

### Installation[​](#installation "Direct link to Installation")

This tutorial requires the `langchain`, `langchain-chroma`, and `langchain-openai` packages:

*   Pip
*   Conda

    pip install langchain langchain-chroma langchain-openai

    conda install langchain langchain-chroma langchain-openai -c conda-forge

For more details, see our [Installation guide](/v0.2/docs/how_to/installation/).

### LangSmith[​](#langsmith "Direct link to LangSmith")

Many of the applications you build with LangChain will contain multiple steps with multiple invocations of LLM calls. As these applications get more and more complex, it becomes crucial to be able to inspect what exactly is going on inside your chain or agent. The best way to do this is with [LangSmith](https://smith.langchain.com).

After you sign up at the link above, make sure to set your environment variables to start logging traces:

    export LANGCHAIN_TRACING_V2="true"export LANGCHAIN_API_KEY="..."

Or, if in a notebook, you can set them with:

    import getpassimport osos.environ["LANGCHAIN_TRACING_V2"] = "true"os.environ["LANGCHAIN_API_KEY"] = getpass.getpass()

Documents[​](#documents "Direct link to Documents")
---------------------------------------------------

LangChain implements a [Document](https://api.python.langchain.com/en/latest/documents/langchain_core.documents.base.Document.html) abstraction, which is intended to represent a unit of text and associated metadata. It has two attributes:

*   `page_content`: a string representing the content;
*   `metadata`: a dict containing arbitrary metadata.

The `metadata` attribute can capture information about the source of the document, its relationship to other documents, and other information. Note that an individual `Document` object often represents a chunk of a larger document.

Let's generate some sample documents:

    from langchain_core.documents import Documentdocuments = [    Document(        page_content="Dogs are great companions, known for their loyalty and friendliness.",        metadata={"source": "mammal-pets-doc"},    ),    Document(        page_content="Cats are independent pets that often enjoy their own space.",        metadata={"source": "mammal-pets-doc"},    ),    Document(        page_content="Goldfish are popular pets for beginners, requiring relatively simple care.",        metadata={"source": "fish-pets-doc"},    ),    Document(        page_content="Parrots are intelligent birds capable of mimicking human speech.",        metadata={"source": "bird-pets-doc"},    ),    Document(        page_content="Rabbits are social animals that need plenty of space to hop around.",        metadata={"source": "mammal-pets-doc"},    ),]

**API Reference:**[Document](https://api.python.langchain.com/en/latest/documents/langchain_core.documents.base.Document.html)

Here we've generated five documents, containing metadata indicating three distinct "sources".

Vector stores[​](#vector-stores "Direct link to Vector stores")
---------------------------------------------------------------

Vector search is a common way to store and search over unstructured data (such as unstructured text). The idea is to store numeric vectors that are associated with the text. Given a query, we can [embed](/v0.2/docs/concepts/#embedding-models) it as a vector of the same dimension and use vector similarity metrics to identify related data in the store.

LangChain [VectorStore](https://api.python.langchain.com/en/latest/vectorstores/langchain_core.vectorstores.VectorStore.html) objects contain methods for adding text and `Document` objects to the store, and querying them using various similarity metrics. They are often initialized with [embedding](/v0.2/docs/how_to/embed_text/) models, which determine how text data is translated to numeric vectors.

LangChain includes a suite of [integrations](/v0.2/docs/integrations/vectorstores/) with different vector store technologies. Some vector stores are hosted by a provider (e.g., various cloud providers) and require specific credentials to use; some (such as [Postgres](/v0.2/docs/integrations/vectorstores/pgvector/)) run in separate infrastructure that can be run locally or via a third-party; others can run in-memory for lightweight workloads. Here we will demonstrate usage of LangChain VectorStores using [Chroma](/v0.2/docs/integrations/vectorstores/chroma/), which includes an in-memory implementation.

To instantiate a vector store, we often need to provide an [embedding](/v0.2/docs/how_to/embed_text/) model to specify how text should be converted into a numeric vector. Here we will use [OpenAI embeddings](/v0.2/docs/integrations/text_embedding/openai/).

    from langchain_chroma import Chromafrom langchain_openai import OpenAIEmbeddingsvectorstore = Chroma.from_documents(    documents,    embedding=OpenAIEmbeddings(),)

**API Reference:**[OpenAIEmbeddings](https://api.python.langchain.com/en/latest/embeddings/langchain_openai.embeddings.base.OpenAIEmbeddings.html)

Calling `.from_documents` here will add the documents to the vector store. [VectorStore](https://api.python.langchain.com/en/latest/vectorstores/langchain_core.vectorstores.VectorStore.html) implements methods for adding documents that can also be called after the object is instantiated. Most implementations will allow you to connect to an existing vector store-- e.g., by providing a client, index name, or other information. See the documentation for a specific [integration](/v0.2/docs/integrations/vectorstores/) for more detail.

Once we've instantiated a `VectorStore` that contains documents, we can query it. [VectorStore](https://api.python.langchain.com/en/latest/vectorstores/langchain_core.vectorstores.VectorStore.html) includes methods for querying:

*   Synchronously and asynchronously;
*   By string query and by vector;
*   With and without returning similarity scores;
*   By similarity and [maximum marginal relevance](https://api.python.langchain.com/en/latest/vectorstores/langchain_core.vectorstores.VectorStore.html#langchain_core.vectorstores.VectorStore.max_marginal_relevance_search) (to balance similarity with query to diversity in retrieved results).

The methods will generally include a list of [Document](https://api.python.langchain.com/en/latest/documents/langchain_core.documents.base.Document.html#langchain_core.documents.base.Document) objects in their outputs.

### Examples[​](#examples "Direct link to Examples")

Return documents based on similarity to a string query:

    vectorstore.similarity_search("cat")

    [Document(page_content='Cats are independent pets that often enjoy their own space.', metadata={'source': 'mammal-pets-doc'}), Document(page_content='Dogs are great companions, known for their loyalty and friendliness.', metadata={'source': 'mammal-pets-doc'}), Document(page_content='Rabbits are social animals that need plenty of space to hop around.', metadata={'source': 'mammal-pets-doc'}), Document(page_content='Parrots are intelligent birds capable of mimicking human speech.', metadata={'source': 'bird-pets-doc'})]

Async query:

    await vectorstore.asimilarity_search("cat")

    [Document(page_content='Cats are independent pets that often enjoy their own space.', metadata={'source': 'mammal-pets-doc'}), Document(page_content='Dogs are great companions, known for their loyalty and friendliness.', metadata={'source': 'mammal-pets-doc'}), Document(page_content='Rabbits are social animals that need plenty of space to hop around.', metadata={'source': 'mammal-pets-doc'}), Document(page_content='Parrots are intelligent birds capable of mimicking human speech.', metadata={'source': 'bird-pets-doc'})]

Return scores:

    # Note that providers implement different scores; Chroma here# returns a distance metric that should vary inversely with# similarity.vectorstore.similarity_search_with_score("cat")

    [(Document(page_content='Cats are independent pets that often enjoy their own space.', metadata={'source': 'mammal-pets-doc'}),  0.3751849830150604), (Document(page_content='Dogs are great companions, known for their loyalty and friendliness.', metadata={'source': 'mammal-pets-doc'}),  0.48316916823387146), (Document(page_content='Rabbits are social animals that need plenty of space to hop around.', metadata={'source': 'mammal-pets-doc'}),  0.49601367115974426), (Document(page_content='Parrots are intelligent birds capable of mimicking human speech.', metadata={'source': 'bird-pets-doc'}),  0.4972994923591614)]

Return documents based on similarity to a embedded query:

    embedding = OpenAIEmbeddings().embed_query("cat")vectorstore.similarity_search_by_vector(embedding)

    [Document(page_content='Cats are independent pets that often enjoy their own space.', metadata={'source': 'mammal-pets-doc'}), Document(page_content='Dogs are great companions, known for their loyalty and friendliness.', metadata={'source': 'mammal-pets-doc'}), Document(page_content='Rabbits are social animals that need plenty of space to hop around.', metadata={'source': 'mammal-pets-doc'}), Document(page_content='Parrots are intelligent birds capable of mimicking human speech.', metadata={'source': 'bird-pets-doc'})]

Learn more:

*   [API reference](https://api.python.langchain.com/en/latest/vectorstores/langchain_core.vectorstores.VectorStore.html)
*   [How-to guide](/v0.2/docs/how_to/vectorstores/)
*   [Integration-specific docs](/v0.2/docs/integrations/vectorstores/)

Retrievers[​](#retrievers "Direct link to Retrievers")
------------------------------------------------------

LangChain `VectorStore` objects do not subclass [Runnable](https://api.python.langchain.com/en/latest/core_api_reference.html#module-langchain_core.runnables), and so cannot immediately be integrated into LangChain Expression Language [chains](/v0.2/docs/concepts/#langchain-expression-language-lcel).

LangChain [Retrievers](https://api.python.langchain.com/en/latest/core_api_reference.html#module-langchain_core.retrievers) are Runnables, so they implement a standard set of methods (e.g., synchronous and asynchronous `invoke` and `batch` operations) and are designed to be incorporated in LCEL chains.

We can create a simple version of this ourselves, without subclassing `Retriever`. If we choose what method we wish to use to retrieve documents, we can create a runnable easily. Below we will build one around the `similarity_search` method:

    from typing import Listfrom langchain_core.documents import Documentfrom langchain_core.runnables import RunnableLambdaretriever = RunnableLambda(vectorstore.similarity_search).bind(k=1)  # select top resultretriever.batch(["cat", "shark"])

**API Reference:**[Document](https://api.python.langchain.com/en/latest/documents/langchain_core.documents.base.Document.html) | [RunnableLambda](https://api.python.langchain.com/en/latest/runnables/langchain_core.runnables.base.RunnableLambda.html)

    [[Document(page_content='Cats are independent pets that often enjoy their own space.', metadata={'source': 'mammal-pets-doc'})], [Document(page_content='Goldfish are popular pets for beginners, requiring relatively simple care.', metadata={'source': 'fish-pets-doc'})]]

Vectorstores implement an `as_retriever` method that will generate a Retriever, specifically a [VectorStoreRetriever](https://api.python.langchain.com/en/latest/vectorstores/langchain_core.vectorstores.VectorStoreRetriever.html). These retrievers include specific `search_type` and `search_kwargs` attributes that identify what methods of the underlying vector store to call, and how to parameterize them. For instance, we can replicate the above with the following:

    retriever = vectorstore.as_retriever(    search_type="similarity",    search_kwargs={"k": 1},)retriever.batch(["cat", "shark"])

    [[Document(page_content='Cats are independent pets that often enjoy their own space.', metadata={'source': 'mammal-pets-doc'})], [Document(page_content='Goldfish are popular pets for beginners, requiring relatively simple care.', metadata={'source': 'fish-pets-doc'})]]

`VectorStoreRetriever` supports search types of `"similarity"` (default), `"mmr"` (maximum marginal relevance, described above), and `"similarity_score_threshold"`. We can use the latter to threshold documents output by the retriever by similarity score.

Retrievers can easily be incorporated into more complex applications, such as retrieval-augmented generation (RAG) applications that combine a given question with retrieved context into a prompt for a LLM. Below we show a minimal example.

*   OpenAI
*   Anthropic
*   Azure
*   Google
*   Cohere
*   FireworksAI
*   Groq
*   MistralAI
*   TogetherAI

    pip install -qU langchain-openai

    import getpassimport osos.environ["OPENAI_API_KEY"] = getpass.getpass()from langchain_openai import ChatOpenAIllm = ChatOpenAI(model="gpt-3.5-turbo-0125")

    pip install -qU langchain-anthropic

    import getpassimport osos.environ["ANTHROPIC_API_KEY"] = getpass.getpass()from langchain_anthropic import ChatAnthropicllm = ChatAnthropic(model="claude-3-sonnet-20240229")

    pip install -qU langchain-openai

    import getpassimport osos.environ["AZURE_OPENAI_API_KEY"] = getpass.getpass()from langchain_openai import AzureChatOpenAIllm = AzureChatOpenAI(    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],    azure_deployment=os.environ["AZURE_OPENAI_DEPLOYMENT_NAME"],    openai_api_version=os.environ["AZURE_OPENAI_API_VERSION"],)

    pip install -qU langchain-google-vertexai

    import getpassimport osos.environ["GOOGLE_API_KEY"] = getpass.getpass()from langchain_google_vertexai import ChatVertexAIllm = ChatVertexAI(model="gemini-pro")

    pip install -qU langchain-cohere

    import getpassimport osos.environ["COHERE_API_KEY"] = getpass.getpass()from langchain_cohere import ChatCoherellm = ChatCohere(model="command-r")

    pip install -qU langchain-fireworks

    import getpassimport osos.environ["FIREWORKS_API_KEY"] = getpass.getpass()from langchain_fireworks import ChatFireworksllm = ChatFireworks(model="accounts/fireworks/models/mixtral-8x7b-instruct")

    pip install -qU langchain-groq

    import getpassimport osos.environ["GROQ_API_KEY"] = getpass.getpass()from langchain_groq import ChatGroqllm = ChatGroq(model="llama3-8b-8192")

    pip install -qU langchain-mistralai

    import getpassimport osos.environ["MISTRAL_API_KEY"] = getpass.getpass()from langchain_mistralai import ChatMistralAIllm = ChatMistralAI(model="mistral-large-latest")

    pip install -qU langchain-openai

    import getpassimport osos.environ["TOGETHER_API_KEY"] = getpass.getpass()from langchain_openai import ChatOpenAIllm = ChatOpenAI(    base_url="https://api.together.xyz/v1",    api_key=os.environ["TOGETHER_API_KEY"],    model="mistralai/Mixtral-8x7B-Instruct-v0.1",)

    from langchain_core.prompts import ChatPromptTemplatefrom langchain_core.runnables import RunnablePassthroughmessage = """Answer this question using the provided context only.{question}Context:{context}"""prompt = ChatPromptTemplate.from_messages([("human", message)])rag_chain = {"context": retriever, "question": RunnablePassthrough()} | prompt | llm

**API Reference:**[ChatPromptTemplate](https://api.python.langchain.com/en/latest/prompts/langchain_core.prompts.chat.ChatPromptTemplate.html) | [RunnablePassthrough](https://api.python.langchain.com/en/latest/runnables/langchain_core.runnables.passthrough.RunnablePassthrough.html)

    response = rag_chain.invoke("tell me about cats")print(response.content)

    Cats are independent pets that often enjoy their own space.

Learn more:[​](#learn-more "Direct link to Learn more:")
--------------------------------------------------------

Retrieval strategies can be rich and complex. For example:

*   We can [infer hard rules and filters](/v0.2/docs/how_to/self_query/) from a query (e.g., "using documents published after 2020");
*   We can [return documents that are linked](/v0.2/docs/how_to/parent_document_retriever/) to the retrieved context in some way (e.g., via some document taxonomy);
*   We can generate [multiple embeddings](/v0.2/docs/how_to/multi_vector/) for each unit of context;
*   We can [ensemble results](/v0.2/docs/how_to/ensemble_retriever/) from multiple retrievers;
*   We can assign weights to documents, e.g., to weigh [recent documents](/v0.2/docs/how_to/time_weighted_vectorstore/) higher.

The [retrievers](/v0.2/docs/how_to/#retrievers) section of the how-to guides covers these and other built-in retrieval strategies.

It is also straightforward to extend the [BaseRetriever](https://api.python.langchain.com/en/latest/retrievers/langchain_core.retrievers.BaseRetriever.html) class in order to implement custom retrievers. See our how-to guide [here](/v0.2/docs/how_to/custom_retriever/).

[Edit this page](https://github.com/langchain-ai/langchain/edit/master/docs/docs/tutorials/retrievers.ipynb)

* * *

#### Was this page helpful?

  

#### You can also leave detailed feedback [on GitHub](https://github.com/langchain-ai/langchain/issues/new?assignees=&labels=03+-+Documentation&projects=&template=documentation.yml&title=DOC%3A+%3CPlease+write+a+comprehensive+title+after+the+%27DOC%3A+%27+prefix%3E).

[

Previous

Build a Retrieval Augmented Generation (RAG) App

](/v0.2/docs/tutorials/rag/)[

Next

Build a Question/Answering system over SQL data

](/v0.2/docs/tutorials/sql_qa/)

*   [Concepts](#concepts)
*   [Setup](#setup)
    *   [Jupyter Notebook](#jupyter-notebook)
    *   [Installation](#installation)
    *   [LangSmith](#langsmith)
*   [Documents](#documents)
*   [Vector stores](#vector-stores)
    *   [Examples](#examples)
*   [Retrievers](#retrievers)
*   [Learn more:](#learn-more)