LangChain

LangChain is a framework for developing applications powered by large language models (LLMs). SurrealDB suits LangChain projects mainly because of its multi-model capabilities: a single database manages all of the application's data.

It handles structured and unstructured data, with vector search, graph traversal, relational queries, full-text search, document storage, and time-series data all within one ACID-compliant engine.

LangChain applications often work with several types of data for tasks such as context retrieval. Keeping all of them in one database simplifies the architecture, reduces latency, and keeps the data consistent.

This guide shows how to use SurrealDB as a vector store for LangChain.

Setup

You can run SurrealDB locally or start with a free SurrealDB Cloud account.

For local, two options:

1.
Install SurrealDB and run SurrealDB. Run in-memory with:
```
 surreal start -u root -p secret
```

Run with Docker.

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

Install dependencies

# -- 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
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.

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}]")

Internally the helper will:

Create table documents (if it doesn’t exist).
Add an HNSW index with the correct dimensionality, using cosine distance and F32 vectors.
Insert each text with its freshly generated embedding.

Similarity search

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.

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

The following resources cover more advanced use of SurrealDB with LangChain.

Several example implementations are available:

A basic example with a ready-to-use Dockerfile - perfect for your first steps
A more advanced graph example showcasing graph capabilities
An interactive Jupyter notebook for hands-on learning

Setup

Install dependencies

Quick start

Similarity search

Next steps

Further reading and resources