> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SurrealDBVectorStore integration

> Integrate with the SurrealDBVectorStore using LangChain Python.

> [SurrealDB](https://surrealdb.com) is a unified, multi-model database purpose-built for AI systems. It combines structured and unstructured data (including vector search, graph traversal, relational queries, full-text search, document storage, and time-series data) into a single ACID-compliant engine, scaling from a 3 MB edge binary to petabyte-scale clusters in the cloud. By eliminating the need for multiple specialized stores, SurrealDB simplifies architectures, reduces latency, and ensures consistency for AI workloads.
>
> **Why SurrealDB Matters for GenAI Systems**
>
> * **One engine for storage and memory:** Combine durable storage and fast, agent-friendly memory in a single system, providing all the data your agent needs and removing the need to sync multiple systems.
> * **One-hop memory for agents:** Run vector search, graph traversal, semantic joins, and transactional writes in a single query, giving LLM agents fast, consistent memory access without stitching relational, graph and vector databases together.
> * **In-place inference and real-time updates:** SurrealDB enables agents to run inference next to data and receive millisecond-fresh updates, critical for real-time reasoning and collaboration.
> * **Versioned, durable context:** SurrealDB supports time-travel queries and versioned records, letting agents audit or “replay” past states for consistent, explainable reasoning.
> * **Plug-and-play agent memory:** Expose AI memory as a native concept, making it easy to use SurrealDB as a drop-in backend for AI frameworks.

This notebook covers how to get started with the SurrealDB vector store.

## Setup

You can run SurrealDB locally or start with a [free SurrealDB cloud account](https://surrealdb.com/docs/cloud/getting-started).

For local, two options:

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

   ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
   surreal start -u root -p root
   ```

2. [Run with Docker](https://surrealdb.com/docs/surrealdb/installation/running/docker).

   ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
   docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:latest start
   ```

## Install dependencies

Install `langchain-surrealdb` and `surrealdb` python packages.

```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# -- Using pip
pip install -U langchain-surrealdb surrealdb
# -- Using poetry
poetry add langchain-surrealdb surrealdb
# -- Using uv
uv add langchain-surrealdb surrealdb
```

To run this notebook, we just need to install the additional dependencies required by this example:

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
!poetry add --quiet --group docs langchain-ollama langchain-surrealdb
```

## Initialization

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_ollama import OllamaEmbeddings
from langchain_surrealdb.vectorstores import SurrealDBVectorStore
from surrealdb import Surreal

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

## Manage vector store

### Add items to vector store

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_core.documents import Document

_url = "https://surrealdb.com"
d1 = Document(page_content="foo", metadata={"source": _url})
d2 = Document(page_content="SurrealDB", metadata={"source": _url})
d3 = Document(page_content="bar", metadata={"source": _url})
d4 = Document(page_content="this is surreal", metadata={"source": _url})

vector_store.add_documents(documents=[d1, d2, d3, d4], ids=["1", "2", "3", "4"])
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
['1', '2', '3', '4']
```

### Update items in vector store

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
updated_document = Document(
    page_content="zar", metadata={"source": "https://example.com"}
)

vector_store.add_documents(documents=[updated_document], ids=["3"])
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
['3']
```

### Delete items from vector store

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
vector_store.delete(ids=["3"])
```

## Query vector store

Once your vector store has been created and the relevant documents have been added you will most likely wish to query it during the running of your chain or agent.

### Query directly

Performing a simple similarity search can be done as follows:

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
results = vector_store.similarity_search(
    query="surreal", k=1, custom_filter={"source": "https://surrealdb.com"}
)
for doc in results:
    print(f"{doc.page_content} [{doc.metadata}]")
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
this is surreal [{'source': 'https://surrealdb.com'}]
```

If you want to execute a similarity search and receive the corresponding scores you can run:

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
results = vector_store.similarity_search_with_score(
    query="thud", k=1, custom_filter={"source": "https://surrealdb.com"}
)
for doc, score in results:
    print(f"[similarity={score:.0%}] {doc.page_content}")
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[similarity=57%] this is surreal
```

### Query by turning into retriever

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
retriever = vector_store.as_retriever(
    search_type="mmr", search_kwargs={"k": 1, "lambda_mult": 0.5}
)
retriever.invoke("surreal")
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[Document(id='4', metadata={'source': 'https://surrealdb.com'}, page_content='this is surreal')]
```

## Usage for retrieval-augmented generation

For guides on how to use this vector store for retrieval-augmented generation (RAG), see the following sections:

* [Retrieval docs](/oss/python/langchain/retrieval)
* [Build a RAG app with LangChain](/oss/python/langchain/rag)
* [Agentic RAG](/oss/python/langgraph/agentic-rag)

***

## API reference

For detailed documentation of all `SurrealDBVectorStore` features and configurations head to the [API reference](https://reference.langchain.com/python/langchain-surrealdb/vectorstores/SurrealDBVectorStore).

## Next steps

* look at the [basic example](https://github.com/surrealdb/langchain-surrealdb/tree/main/examples/basic). Use the Dockerfile to try it out!
* look at the [graph example](https://github.com/surrealdb/langchain-surrealdb/tree/main/examples/graph)
* try the [jupyter notebook](https://github.com/langchain-ai/langchain/blob/v0.3/docs/docs/integrations/vectorstores/surrealdb.ipynb)
* [Awesome SurrealDB](https://github.com/surrealdb/awesome-surreal), A curated list of SurrealDB resources, tools, utilities, and applications

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/python/integrations/vectorstores/surrealdb.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>