# LangChain

Use SurrealDB native vector indexes as a drop-in vector store for LangChain.

[LangChain](https://python.langchain.com/docs/introduction/) is a framework for developing applications powered by large language models (LLMs). SurrealDB is an excellent database choice for [LangChain](https://python.langchain.com/docs/introduction/) projects primarily because of its [multi-model capabilities](/docs/learn/data-models.md), which streamline data management by requiring only a single database.

This unified system adeptly handles structured and unstructured data, incorporating vector search, [graph traversal](/docs/learn/data-models/graph/overview.md), [relational queries](/docs/learn/data-models.md), [full-text search](/docs/learn/data-models/full-text-search/overview.md), [document storage](/docs/learn/data-models/document/overview.md), and [time-series data](/docs/learn/data-models/time-series/overview.md) all within one ACID-compliant engine.

For LangChain applications, which often juggle diverse data types for tasks like context retrieval and complex data interactions, SurrealDB's ability to consolidate these needs into one platform simplifies architecture, reduces latency, and ensures data consistency, making it a highly efficient and powerful backend solution.

In this guide, we'll walk through how to use SurrealDB as a vector store for LangChain.

<video style="width: 100%;" height="300" controls>
    <source src={VidMp4} type="video/mp4" />
    <source src={VidWebm} type="video/webm" />
</video>

## Setup

You can run SurrealDB locally or start with a [free SurrealDB Cloud account](/docs/manage/instances.md).

For local, two options:

1. [Install SurrealDB](/docs/running/installation.md) and run [SurrealDB](/docs/running/in-memory.md). Run in-memory with:

    ```sh
    surreal start -u root -p secret
    ```

2. [Run with Docker](/docs/running/docker.md).

    ```sh
    docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:latest start
    ```

## Install dependencies

```bash
# -- Using pip
pip install -U langchain-surrealdb langchain_ollama surrealdb
# -- Using poetry
poetry add langchain-surrealdb langchain_ollama surrealdb
# -- Using uv
uv add --upgrade langchain-surrealdb langchain_ollama surrealdb
```

* `surrealdb` → [SurrealDB Python SDK](/docs/reference/python/)
* `langchain-surrealdb` → houses `SurrealDBVectorStore`
* `langchain_ollama`, `langchain-openai` (or HF, Cohere, etc.) → embeddings

## Quick start

Create a vector store, and documents with embeddings, and do a similarity search.

```python
from langchain_core.documents import Document
from langchain_surrealdb.vectorstores import SurrealDBVectorStore
from langchain_ollama import OllamaEmbeddings
from surrealdb import Surreal

conn = Surreal("ws://localhost:8000/rpc")
conn.signin({"username": "root", "password": "secret"})
conn.use("langchain", "demo")
vector_store = SurrealDBVectorStore(OllamaEmbeddings(model="llama3.2"), conn)

doc_1 = Document(page_content="foo", metadata={"source": "https://surrealdb.com"})
doc_2 = Document(page_content="SurrealDB", metadata={"source": "https://surrealdb.com"})

vector_store.add_documents(documents=[doc_1, doc_2], ids=["1", "2"])

results = vector_store.similarity_search_with_score(
    query="surreal", k=1, custom_filter={"source": "https://surrealdb.com"}
)

for doc, score in results:
    print(f"* [SIM={score:3f}] {doc.page_content} [{doc.metadata}]")
```

Under the hood the helper will:

1. Create table **`documents`** (if it doesn’t exist).
2. Add an **M-Tree** index with the correct dimensionality.
3. Insert each text with its freshly generated embedding.

## Similarity search

```python
query = "How do I enable vector search in SurrealDB?"
docs = vector_store.similarity_search(
    query=query, k=1, custom_filter={"source": "https://surrealdb.com"}
)
for doc in results:
    print(f"{doc.page_content} [{doc.metadata}]")
```

```
The Vector Search feature of SurrealDB... [{'source': 'https://surrealdb.com'}]
```

If you want to get the score with the results, use `similarity_search_with_score` instead.

You can also transform the vector store into a retriever for easier usage in your chains.

```python
query = "How do I enable vector search in SurrealDB?"
docs = vector_store.similarity_search(
retriever = vector_store.as_retriever(
    search_type="mmr", search_kwargs={"k": 1, "lambda_mult": 0.5}
)
retriever.invoke(query)
```

```
[Document(id='4', metadata={'source': 'https://surrealdb.com'}, page_content='The Vector Search feature of SurrealDB...')]
```

## Next steps

Now that you have a basic understanding of how to use SurrealDB with LangChain, let's explore some additional resources to help you dive deeper and build more sophisticated applications.

To help you get started quickly, we provide several example implementations:

* A [basic example](https://github.com/surrealdb/langchain-surrealdb/tree/main/examples/basic) with a ready-to-use Dockerfile - perfect for your first steps
* A more advanced [graph example](https://github.com/surrealdb/langchain-surrealdb/tree/main/examples/graph) showcasing graph capabilities
* An interactive [Jupyter notebook](https://github.com/langchain-ai/langchain/blob/master/docs/docs/integrations/vectorstores/surrealdb.ipynb) for hands-on learning

### Further reading and resources

For a deeper understanding of the technology stack:

* Explore the [SurrealDB vector-search reference](/docs/learn/data-models/vector-search/overview.md) for detailed technical information
* Check out the [LangChain API docs for `SurrealDBStore`](https://api.python.langchain.com/en/latest/vectorstores/langchain_community.vectorstores.surrealdb.SurrealDBStore.html) for comprehensive API documentation
* Browse [Awesome SurrealDB](https://github.com/surrealdb/awesome-surreal) for a curated collection of resources, tools, and applications
That’s it - you now have a fully-featured LangChain vector store powered by SurrealDB, no boilerplate required. 🚀