github/langchain
1
0
Fork 0
mirror of https://github.com/hwchase17/langchain.git synced 2025-08-01 00:49:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update surrealdb vectorestore documentation (#31199)

Browse Source
This commit is contained in:
Martin Schaer 2025-06-25 21:16:43 +01:00 committed by GitHub
parent 2fb27b63f5
commit 421554007f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 265 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/docs/integrations/providers/surrealdb.mdx Normal file
View File

@ -0,0 +1,22 @@
# SurrealDB
[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.
## Installation and Setup
```bash
pip install langchain-surrealdb
```
## Vector Store
[This notebook](/docs/integrations/vectorstores/surrealdb) covers how to get started with the SurrealDB vector store.
Find more [examples](https://github.com/surrealdb/langchain-surrealdb/blob/main/README.md#simple-example) in the repository.

402
docs/docs/integrations/vectorstores/surrealdb.ipynb
View File

@ -2,279 +2,353 @@
"cells": [
{
"cell_type": "markdown",
"id": "a3afefb0-7e99-4912-a222-c6b186da11af",
"id": "ef1f0986",
"metadata": {},
"source": [
"# SurrealDB\n",
"# SurrealDBVectorStore\n",
"\n",
">[SurrealDB](https://surrealdb.com/) is an end-to-end cloud-native database designed for modern applications, including web, mobile, serverless, Jamstack, backend, and traditional applications. With SurrealDB, you can simplify your database and API infrastructure, reduce development time, and build secure, performant apps quickly and cost-effectively.\n",
"> [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.\n",
">\n",
">**Key features of SurrealDB include:**\n",
">\n",
">* **Reduces development time:** SurrealDB simplifies your database and API stack by removing the need for most server-side components, allowing you to build secure, performant apps faster and cheaper.\n",
">* **Real-time collaborative API backend service:** SurrealDB functions as both a database and an API backend service, enabling real-time collaboration.\n",
">* **Support for multiple querying languages:** SurrealDB supports SQL querying from client devices, GraphQL, ACID transactions, WebSocket connections, structured and unstructured data, graph querying, full-text indexing, and geospatial querying.\n",
">* **Granular access control:** SurrealDB provides row-level permissions-based access control, giving you the ability to manage data access with precision.\n",
">\n",
">View the [features](https://surrealdb.com/features), the latest [releases](https://surrealdb.com/releases), and [documentation](https://surrealdb.com/docs).\n",
"> **Why SurrealDB Matters for GenAI Systems**\n",
"> - **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.\n",
"> - **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.\n",
"> - **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.\n",
"> - **Versioned, durable context:** SurrealDB supports time-travel queries and versioned records, letting agents audit or “replay” past states for consistent, explainable reasoning.\n",
"> - **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.\n",
"\n",
"This notebook shows how to use functionality related to the `SurrealDBStore`."
"This notebook covers how to get started with the SurrealDB vector store."
]
},
{
"cell_type": "markdown",
"id": "5031a3ec",
"id": "255057477211075c",
"metadata": {},
"source": [
"## Setup\n",
"\n",
"Uncomment the below cells to install surrealdb."
"You can run SurrealDB locally or start with a [free SurrealDB cloud account](https://surrealdb.com/docs/cloud/getting-started).\n",
"\n",
"For local, two options:\n",
"1. [Install SurrealDB](https://surrealdb.com/docs/surrealdb/installation) and [run SurrealDB](https://surrealdb.com/docs/surrealdb/installation/running). Run in-memory with:\n",
"\n",
" ```bash\n",
" surreal start -u root -p root\n",
" ```\n",
"\n",
"2. [Run with Docker](https://surrealdb.com/docs/surrealdb/installation/running/docker).\n",
"\n",
" ```bash\n",
" docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:latest start\n",
" ```\n",
"\n",
"## Install dependencies\n",
"\n",
"Install `langchain-surrealdb` and `surrealdb` python packages.\n",
"\n",
"```shell\n",
"# -- Using pip\n",
"pip install --upgrade langchain-surrealdb surrealdb\n",
"# -- Using poetry\n",
"poetry add langchain-surrealdb surrealdb\n",
"# -- Using uv\n",
"uv add --upgrade langchain-surrealdb surrealdb\n",
"```\n",
"\n",
"To run this notebook, we just need to install the additional dependencies required by this example:\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "7cd7391f-7759-4a21-952a-2ec972d818c6",
"id": "e403ffc28477aee5",
"metadata": {
"tags": []
"ExecuteTime": {
"end_time": "2025-06-18T14:34:13.173597Z",
"start_time": "2025-06-18T14:34:11.280299Z"
}
},
"outputs": [],
"source": [
"# %pip install --upgrade --quiet surrealdb langchain langchain-community"
]
"!poetry add --quiet --group docs langchain-ollama langchain-surrealdb"
],
"outputs": [],
"execution_count": 3
},
{
"cell_type": "markdown",
"id": "6e57a389-f637-4b8f-9ab2-759ae7485f78",
"id": "93df377e",
"metadata": {},
"source": [
"## Using SurrealDBStore"
]
"source": "## Initialization\n"
},
{
"cell_type": "code",
"execution_count": 1,
"id": "1c2d942d-5d90-4f9f-af96-dff976e4510f",
"metadata": {},
"outputs": [],
"source": [
"# add this import for running in jupyter notebook\n",
"import nest_asyncio\n",
"\n",
"nest_asyncio.apply()"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "e49be085-ddf1-4028-8c0c-97836ce4a873",
"id": "dc37144c-208d-4ab3-9f3a-0407a69fe052",
"metadata": {
"tags": []
"tags": [],
"ExecuteTime": {
"end_time": "2025-06-18T14:34:13.432705Z",
"start_time": "2025-06-18T14:34:13.179649Z"
}
},
"outputs": [],
"source": [
"from langchain_community.document_loaders import TextLoader\n",
"from langchain_community.vectorstores import SurrealDBStore\n",
"from langchain_huggingface import HuggingFaceEmbeddings\n",
"from langchain_text_splitters import CharacterTextSplitter"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "38222aee-adc5-44c2-913c-97977b394cf5",
"metadata": {
"tags": []
},
"outputs": [],
"source": [
"documents = TextLoader(\"../../how_to/state_of_the_union.txt\").load()\n",
"text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=0)\n",
"docs = text_splitter.split_documents(documents)\n",
"from langchain_ollama import OllamaEmbeddings\n",
"from langchain_surrealdb.vectorstores import SurrealDBVectorStore\n",
"from surrealdb import Surreal\n",
"\n",
"model_name = \"sentence-transformers/all-mpnet-base-v2\"\n",
"embeddings = HuggingFaceEmbeddings(model_name=model_name)"
]
"conn = Surreal(\"ws://localhost:8000/rpc\")\n",
"conn.signin({\"username\": \"root\", \"password\": \"root\"})\n",
"conn.use(\"langchain\", \"demo\")\n",
"vector_store = SurrealDBVectorStore(OllamaEmbeddings(model=\"llama3.2\"), conn)"
],
"outputs": [],
"execution_count": 4
},
{
"cell_type": "markdown",
"id": "8e240306-803c-4c1a-b036-b9fc69eb6cba",
"id": "ac6071d4",
"metadata": {},
"source": [
"### Creating a SurrealDBStore object"
"## Manage vector store\n",
"\n",
"### Add items to vector store\n"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "ff9d0304-1e11-4db2-9454-1350db7907e6",
"metadata": {},
"id": "8f03bdd3ffc7d75c",
"metadata": {
"ExecuteTime": {
"end_time": "2025-06-18T14:34:13.622354Z",
"start_time": "2025-06-18T14:34:13.438965Z"
}
},
"source": [
"from langchain_core.documents import Document\n",
"\n",
"_url = \"https://surrealdb.com\"\n",
"d1 = Document(page_content=\"foo\", metadata={\"source\": _url})\n",
"d2 = Document(page_content=\"SurrealDB\", metadata={\"source\": _url})\n",
"d3 = Document(page_content=\"bar\", metadata={\"source\": _url})\n",
"d4 = Document(page_content=\"this is surreal\", metadata={\"source\": _url})\n",
"\n",
"vector_store.add_documents(documents=[d1, d2, d3, d4], ids=[\"1\", \"2\", \"3\", \"4\"])"
],
"outputs": [
{
"data": {
"text/plain": [
"['documents:38hz49bv1p58f5lrvrdc',\n",
" 'documents:niayw63vzwm2vcbh6w2s',\n",
" 'documents:it1fa3ktplbuye43n0ch',\n",
" 'documents:il8f7vgbbp9tywmsn98c',\n",
" 'documents:vza4c6cqje0avqd58gal']"
"['1', '2', '3', '4']"
]
},
"execution_count": 4,
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"execution_count": 5
},
{
"cell_type": "markdown",
"id": "91a19092754d6723",
"metadata": {},
"source": "### Update items in vector store"
},
{
"cell_type": "code",
"id": "9e6d3ff68383d6da",
"metadata": {
"ExecuteTime": {
"end_time": "2025-06-18T14:34:13.699211Z",
"start_time": "2025-06-18T14:34:13.628105Z"
}
},
"source": [
"db = SurrealDBStore(\n",
" dburl=\"ws://localhost:8000/rpc\", # url for the hosted SurrealDB database\n",
" embedding_function=embeddings,\n",
" db_user=\"root\", # SurrealDB credentials if needed: db username\n",
" db_pass=\"root\", # SurrealDB credentials if needed: db password\n",
" # ns=\"langchain\", # namespace to use for vectorstore\n",
" # db=\"database\", # database to use for vectorstore\n",
" # collection=\"documents\", #collection to use for vectorstore\n",
"updated_document = Document(\n",
" page_content=\"zar\", metadata={\"source\": \"https://example.com\"}\n",
")\n",
"\n",
"# this is needed to initialize the underlying async library for SurrealDB\n",
"await db.initialize()\n",
"\n",
"# delete all existing documents from the vectorstore collection\n",
"await db.adelete()\n",
"\n",
"# add documents to the vectorstore\n",
"ids = await db.aadd_documents(docs)\n",
"\n",
"# document ids of the added documents\n",
"ids[:5]"
]
"vector_store.add_documents(documents=[updated_document], ids=[\"3\"])"
],
"outputs": [
{
"data": {
"text/plain": [
"['3']"
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"execution_count": 6
},
{
"cell_type": "markdown",
"id": "94a742a9-9507-4076-9cc3-616a4ed6866f",
"id": "d645a4f864f0b374",
"metadata": {},
"source": [
"### (alternatively) Create a SurrealDBStore object and add documents"
]
"source": "### Delete items from vector store\n"
},
{
"cell_type": "code",
"execution_count": 5,
"id": "73d66563-4e1f-4edf-9e95-5fc9adcfa2cb",
"metadata": {},
"outputs": [],
"id": "9f31cc27bf61959e",
"metadata": {
"ExecuteTime": {
"end_time": "2025-06-18T14:34:13.723069Z",
"start_time": "2025-06-18T14:34:13.716396Z"
}
},
"source": [
"await db.adelete()\n",
"\n",
"db = await SurrealDBStore.afrom_documents(\n",
" dburl=\"ws://localhost:8000/rpc\", # url for the hosted SurrealDB database\n",
" embedding=embeddings,\n",
" documents=docs,\n",
" db_user=\"root\", # SurrealDB credentials if needed: db username\n",
" db_pass=\"root\", # SurrealDB credentials if needed: db password\n",
" # ns=\"langchain\", # namespace to use for vectorstore\n",
" # db=\"database\", # database to use for vectorstore\n",
" # collection=\"documents\", #collection to use for vectorstore\n",
")"
]
"vector_store.delete(ids=[\"3\"])"
],
"outputs": [],
"execution_count": 7
},
{
"cell_type": "markdown",
"id": "efbb6684-3846-4332-a624-ddd4d75844c1",
"id": "c3620501",
"metadata": {},
"source": [
"### Similarity search"
"## Query vector store\n",
"\n",
"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. \n",
"\n",
"### Query directly\n",
"\n",
"Performing a simple similarity search can be done as follows:\n"
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "aa28a7f8-41d0-4299-84eb-91d1576e8a63",
"id": "b14e63173710a63f",
"metadata": {
"tags": []
"ExecuteTime": {
"end_time": "2025-06-18T14:34:13.808318Z",
"start_time": "2025-06-18T14:34:13.734463Z"
}
},
"outputs": [],
"source": [
"query = \"What did the president say about Ketanji Brown Jackson\"\n",
"docs = await db.asimilarity_search(query)"
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "1eb16d2a-b466-456a-b412-5e74bb8523dd",
"metadata": {
"tags": []
},
"results = vector_store.similarity_search(\n",
" query=\"surreal\", k=1, custom_filter={\"source\": \"https://surrealdb.com\"}\n",
")\n",
"for doc in results:\n",
" print(f\"{doc.page_content} [{doc.metadata}]\") # noqa: T201"
],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Tonight. I call on the Senate to: Pass the Freedom to Vote Act. Pass the John Lewis Voting Rights Act. And while you’re at it, pass the Disclose Act so Americans can know who is funding our elections. \n",
"\n",
"Tonight, I’d like to honor someone who has dedicated his life to serve this country: Justice Stephen Breyer—an Army veteran, Constitutional scholar, and retiring Justice of the United States Supreme Court. Justice Breyer, thank you for your service. \n",
"\n",
"One of the most serious constitutional responsibilities a President has is nominating someone to serve on the United States Supreme Court. \n",
"\n",
"And I did that 4 days ago, when I nominated Circuit Court of Appeals Judge Ketanji Brown Jackson. One of our nation’s top legal minds, who will continue Justice Breyer’s legacy of excellence.\n"
"this is surreal [{'source': 'https://surrealdb.com'}]\n"
]
}
],
"source": [
"print(docs[0].page_content)"
]
"execution_count": 8
},
{
"cell_type": "markdown",
"id": "43896697-f99e-47b6-9117-47a25e9afa9c",
"id": "3ed9d733",
"metadata": {},
"source": "If you want to execute a similarity search and receive the corresponding scores you can run:\n"
},
{
"cell_type": "code",
"id": "20b694cd6fc9529c",
"metadata": {
"ExecuteTime": {
"end_time": "2025-06-18T14:34:13.880648Z",
"start_time": "2025-06-18T14:34:13.812341Z"
}
},
"source": [
"### Similarity search with score"
]
"results = vector_store.similarity_search_with_score(\n",
" query=\"thud\", k=1, custom_filter={\"source\": \"https://surrealdb.com\"}\n",
")\n",
"for doc, score in results:\n",
" print(f\"[similarity={score:.0%}] {doc.page_content}\") # noqa: T201"
],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"[similarity=57%] this is surreal\n"
]
}
],
"execution_count": 9
},
{
"cell_type": "markdown",
"id": "414a9bc9",
"id": "b1e75fd5932f4c6a",
"metadata": {},
"source": [
"The returned distance score is cosine distance. Therefore, a lower score is better."
"### Query by turning into retriever\n",
"\n",
"You can also transform the vector store into a retriever for easier usage in your chains. \n"
]
},
{
"cell_type": "code",
"execution_count": 8,
"id": "8e9eef05-1516-469a-ad36-880c69aef7a9",
"id": "73b330f83225256b",
"metadata": {
"tags": []
"ExecuteTime": {
"end_time": "2025-06-18T14:34:13.970711Z",
"start_time": "2025-06-18T14:34:13.884730Z"
}
},
"outputs": [],
"source": [
"docs = await db.asimilarity_search_with_score(query)"
]
},
{
"cell_type": "code",
"execution_count": 9,
"id": "bd5fb0e4-2a94-4bb4-af8a-27327ecb1a7f",
"metadata": {
"tags": []
},
"retriever = vector_store.as_retriever(\n",
" search_type=\"mmr\", search_kwargs={\"k\": 1, \"lambda_mult\": 0.5}\n",
")\n",
"retriever.invoke(\"surreal\")"
],
"outputs": [
{
"data": {
"text/plain": [
"(Document(page_content='Tonight. I call on the Senate to: Pass the Freedom to Vote Act. Pass the John Lewis Voting Rights Act. And while you’re at it, pass the Disclose Act so Americans can know who is funding our elections. \\n\\nTonight, I’d like to honor someone who has dedicated his life to serve this country: Justice Stephen Breyer—an Army veteran, Constitutional scholar, and retiring Justice of the United States Supreme Court. Justice Breyer, thank you for your service. \\n\\nOne of the most serious constitutional responsibilities a President has is nominating someone to serve on the United States Supreme Court. \\n\\nAnd I did that 4 days ago, when I nominated Circuit Court of Appeals Judge Ketanji Brown Jackson. One of our nation’s top legal minds, who will continue Justice Breyer’s legacy of excellence.', metadata={'id': 'documents:slgdlhjkfknhqo15xz0w', 'source': '../../how_to/state_of_the_union.txt'}),\n",
" 0.39839531721941895)"
"[Document(id='4', metadata={'source': 'https://surrealdb.com'}, page_content='this is surreal')]"
]
},
"execution_count": 9,
"execution_count": 10,
"metadata": {},
"output_type": "execute_result"
}
],
"execution_count": 10
},
{
"cell_type": "markdown",
"id": "901c75dc",
"metadata": {},
"source": [
"docs[0]"
"## Usage for retrieval-augmented generation\n",
"\n",
"For guides on how to use this vector store for retrieval-augmented generation (RAG), see the following sections:\n",
"\n",
"- [How-to: Question and answer with RAG](https://python.langchain.com/docs/how_to/#qa-with-rag)\n",
"- [Retrieval conceptual docs](https://python.langchain.com/docs/concepts/retrieval/)"
]
},
{
"cell_type": "markdown",
"id": "8a27244f",
"metadata": {},
"source": [
"## API reference\n",
"\n",
"For detailed documentation of all SurrealDBVectorStore features and configurations head to the API reference: https://python.langchain.com/api_reference/surrealdb/index.html"
]
},
{
"cell_type": "markdown",
"id": "85901cdb62057fe5",
"metadata": {},
"source": [
"## Next steps\n",
"\n",
"- look at the [basic example](https://github.com/surrealdb/langchain-surrealdb/tree/main/examples/basic). Use the Dockerfile to try it out!\n",
"- look at the [graph example](https://github.com/surrealdb/langchain-surrealdb/tree/main/examples/graph)\n",
"- try the [jupyther notebook](https://github.com/langchain-ai/langchain/blob/master/docs/docs/integrations/vectorstores/surrealdb.ipynb)\n",
"- [Awesome SurrealDB](https://github.com/surrealdb/awesome-surreal), A curated list of SurrealDB resources, tools, utilities, and applications\n"
]
}
],

5
libs/packages.yml
View File

@ -678,3 +678,8 @@ packages:
repo: nebius/langchain-nebius
downloads: 96
downloads_updated_at: '2025-06-25T19:52:06.942587+00:00'
- name: langchain-surrealdb
path: .
repo: surrealdb/langchain-surrealdb
downloads: 291
downloads_updated_at: '2025-06-25T20:06:46.206625+00:00'