SurrealEngine Documentation¶

SurrealEngine is a comprehensive Object-Document Mapper (ODM) for SurrealDB that provides an intuitive Python interface for database operations. It supports both synchronous and asynchronous operations, connection pooling, field validation, query building, and graph-based relationships.

Key Features¶

Dual sync/async support for all operations
Connection pooling and management with automatic retry logic
Rich field types with comprehensive validation
Query builder with Django-style filtering and chaining
Graph relationships and path traversal
Materialized views and data aggregations
Schema management and migrations
Signals for model lifecycle events
Multi-backend support for SurrealDB and ClickHouse

Quick Start¶

from surrealengine import Document, StringField, IntField, create_connection

# Define a document model
class User(Document):
    name = StringField(required=True)
    age = IntField()

    class Meta:
        collection = "users"

# Create connection and save user
async def main():
    connection = create_connection("ws://localhost:8000/rpc")
    await connection.connect()

    user = User(name="Alice", age=30)
    await user.save()
    print(f"Created user: {user.id}")

Installation¶

Install SurrealEngine using pip:

pip install surrealengine

Or with optional dependencies:

pip install surrealengine[all]

Table of Contents¶

User Guide

API Reference

Examples

Development

SurrealEngine Documentation¶

Key Features¶

Quick Start¶

Installation¶

Table of Contents¶

Indices and tables¶