Skip to content

AI frameworks

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.

Note

This page uses the Python package, langchain-surrealdb. For TypeScript and JavaScript, the @surrealdb/langgraph package stores LangGraph.js checkpoints, long-term memory and node results in SurrealDB. See LangGraph.

The examples on this page connect to a SurrealDB server at ws://localhost:8000 and sign in as root with the password secret. To run one locally, install SurrealDB and start it in memory with surreal db start -u root -p secret, or run it with Docker.

Then install the packages:

pip install -U langchain-surrealdb langchain_ollama surrealdb
  • surrealdb → SurrealDB Python SDK

  • langchain-surrealdb → houses SurrealDBVectorStore

  • langchain_ollama, langchain-openai (or HF, Cohere, etc.) → embeddings

SurrealDBVectorStore takes a LangChain embeddings model and a SurrealDB connection:

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)

Any LangChain embeddings class works in place of OllamaEmbeddings, such as OpenAIEmbeddings from langchain-openai. Internally, the vector store:

  1. Creates the table documents if it does not exist.

  2. Adds an HNSW index with the dimension of the embeddings model, using cosine distance and F32 vectors.

  3. Inserts each text with the embedding that the model generated for it.

The vector store implements the standard LangChain vector store methods:

MethodUse
add_documents(documents, ids)Embed and store LangChain Document objects.
similarity_search(query, k, custom_filter)Return the k documents closest to the query text. custom_filter matches on document metadata.
similarity_search_with_score(query, k, custom_filter)The same, with the distance score of each document.
as_retriever(search_type, search_kwargs)Wrap the vector store as a retriever for use in a chain, for example with search_type="mmr".

The LangChain example in the tutorial Build an AI agent with Python uses each of these on two sample documents and shows the output.

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

Several example implementations are available:

For a deeper understanding of the technology stack:

Was this page helpful?

Last updated