Skip to main content

​
SurrealStorage

class SurrealStorage(BaseVectorStorage):
An implementation of the BaseVectorStorage using SurrealDB, a scalable, distributed database with WebSocket support, for efficient vector storage and similarity search. SurrealDB official site and documentation can be found at: SurrealDB <https://surrealdb.com>_ Parameters:
  • url (str): WebSocket URL for connecting to SurrealDB (default: “ws://localhost:8000/rpc”).
  • table (str): Name of the table used for storing vectors (default: “vector_store”).
  • vector_dim (int): Dimensionality of the stored vectors.
  • distance (VectorDistance): Distance metric used for similarity comparisons (default: VectorDistance.COSINE).
  • namespace (str): SurrealDB namespace to use (default: “default”). (default: "default")
  • database (str): SurrealDB database name (default: “demo”). (default: "demo")
  • user (str): Username for authentication (default: “root”). (default: "root")
  • password (str): Password for authentication (default: “root”). (default: "root")
Note:
  • SurrealDB supports flexible schema and powerful querying capabilities via SQL-like syntax over WebSocket.
  • This implementation manages connection setup and ensures the target table exists.
  • Suitable for applications requiring distributed vector storage and search with real-time updates.

​
init

def __init__(self):
Initialize SurrealStorage with connection settings and ensure the target table exists. Parameters:
  • url (str): WebSocket URL for connecting to SurrealDB. (default: :obj:"ws://localhost:8000/rpc")
  • table (str): Name of the table used for vector storage. (default: :obj:"vector_store")
  • vector_dim (int): Dimensionality of the stored vectors. (default: :obj:786)
  • distance (VectorDistance): Distance metric for similarity searches. (default: :obj:VectorDistance.COSINE)
  • namespace (str): SurrealDB namespace to use. (default: :obj:"default")
  • database (str): SurrealDB database name. (default: :obj:"demo")
  • user (str): Username for authentication. (default: :obj:"root")
  • password (str): Password for authentication. (default: :obj:"root")

​
_table_exists

def _table_exists(self):
Returns: bool: True if the table exists, False otherwise.

​
_get_table_info

def _get_table_info(self):
Returns: Dict[str, int]: A dictionary with ‘dim’ and ‘count’ keys.

​
_create_table

def _create_table(self):
Define and create the vector storage table with HNSW index. Documentation: https://surrealdb.com/docs/surrealdb/reference-guide/ vector-search#vector-search-cheat-sheet

​
_drop_table

def _drop_table(self):
Drop the vector storage table if it exists.

​
_check_and_create_table

def _check_and_create_table(self):
Check if the table exists and matches the expected vector dimension. If not, create a new table.

​
_validate_and_convert_records

def _validate_and_convert_records(self, records: List[VectorRecord]):
Validate and convert VectorRecord instances into SurrealDB-compatible dictionaries. Parameters:
  • records (List[VectorRecord]): List of vector records to insert.
Returns: List[Dict]: Transformed list of dicts ready for insertion.

​
query

def query(self, query: VectorDBQuery, **kwargs: Any):
Perform a top-k similarity search using the configured distance metric. Parameters:
  • query (VectorDBQuery): Query containing the query vector and top_k value.
Returns: List[VectorDBQueryResult]: Ranked list of matching records with similarity scores.

​
add

def add(self, records: List[VectorRecord], **kwargs):
Insert validated vector records into the SurrealDB table. Parameters:
  • records (List[VectorRecord]): List of vector records to add.

​
delete

def delete(
    self,
    ids: Optional[List[str]] = None,
    if_all: bool = False,
    **kwargs
):
Delete specific records by ID or clear the entire table. Parameters:
  • ids (Optional[List[str]]): List of record IDs to delete.
  • if_all (bool): Whether to delete all records in the table.

​
status

def status(self):
Returns: VectorDBStatus: Object containing vector table metadata.

​
clear

def clear(self):
Reset the vector table by dropping and recreating it.

​
load

def load(self):
Load the collection hosted on cloud service.

​
client

def client(self):
Provides access to the underlying SurrealDB client.