Quick Start Guide

This guide will get you up and running with QuantumEngine in just a few minutes.

Installation

Install QuantumEngine with the backend you need:

# For SurrealDB
pip install quantumengine[surrealdb]

# For ClickHouse
pip install quantumengine[clickhouse]

# For both
pip install quantumengine[all]

Basic Example

Here’s a simple example using SurrealDB:

import asyncio
import os
from quantumengine import Document, StringField, IntField, create_connection

# Define your document model
class User(Document):
    username = StringField(required=True)
    email = StringField(required=True)
    age = IntField(min_value=0)

    class Meta:
        collection = "users"
        backend = "surrealdb"

async def main():
    # Create connection
    connection = create_connection(
        url="ws://localhost:8000/rpc",
        namespace="test_ns",
        database="test_db",
        username="root",
        password="root",
        make_default=True
    )

    # Connect to database
    await connection.connect()

    # Create table
    await User.create_table()

    # Create a user
    user = User(username="alice", email="alice@example.com", age=25)
    await user.save()
    print(f"Created user: {user.id}")

    # Query users
    users = await User.objects.filter(age__gt=18).all()
    print(f"Found {len(users)} adult users")

    # Update user
    await User.objects.filter(username="alice").update(age=26)

    # Get updated user
    alice = await User.objects.get(username="alice")
    print(f"Alice's age: {alice.age}")

    # Delete user
    await alice.delete()
    print("User deleted")

# Run the example
asyncio.run(main())

Multi-Backend Example

QuantumEngine’s real power comes from using multiple backends:

from quantumengine import Document, StringField, DateTimeField, FloatField
from quantumengine.fields.clickhouse import LowCardinalityField
from datetime import datetime

# User data in SurrealDB (transactional)
class User(Document):
    username = StringField(required=True)
    email = StringField(required=True)
    created_at = DateTimeField(default=datetime.now)

    class Meta:
        collection = "users"
        backend = "surrealdb"

# Analytics events in ClickHouse (analytical)
class AnalyticsEvent(Document):
    event_type = LowCardinalityField(required=True)
    user_id = StringField(required=True)
    timestamp = DateTimeField(required=True)
    value = FloatField()

    class Meta:
        collection = "events"
        backend = "clickhouse"

async def multi_backend_example():
    # Create connections
    surrealdb_conn = create_connection(
        name="surrealdb_main",
        url="ws://localhost:8000/rpc",
        backend="surrealdb",
        namespace="myapp",
        database="production",
        make_default=True
    )

    clickhouse_conn = create_connection(
        name="clickhouse_analytics",
        url="localhost",
        backend="clickhouse",
        database="analytics",
        port=9000
    )

    # Connect to both
    await surrealdb_conn.connect()
    await clickhouse_conn.connect()

    # Create tables
    await User.create_table()
    await AnalyticsEvent.create_table()

    # Create user in SurrealDB
    user = User(username="bob", email="bob@example.com")
    await user.save()

    # Track event in ClickHouse
    event = AnalyticsEvent(
        event_type="login",
        user_id=str(user.id),
        timestamp=datetime.now(),
        value=1.0
    )
    await event.save()

    print(f"User {user.username} created in SurrealDB")
    print(f"Login event tracked in ClickHouse")

Field Types

QuantumEngine supports many field types:

from quantumengine import Document
from quantumengine.fields import (
    StringField, IntField, FloatField, BooleanField,
    DateTimeField, DecimalField, UUIDField, ListField,
    DictField, IPAddressField
)
from quantumengine.fields.clickhouse import LowCardinalityField, ArrayField

class Product(Document):
    # Basic fields
    name = StringField(required=True, max_length=100)
    price = DecimalField(max_digits=10, decimal_places=2)
    in_stock = BooleanField(default=True)
    quantity = IntField(min_value=0)
    rating = FloatField(min_value=0.0, max_value=5.0)

    # Advanced fields
    created_at = DateTimeField(auto_now_add=True)
    product_id = UUIDField(auto_generate=True)
    tags = ListField(field_type=StringField())
    metadata = DictField()
    supplier_ip = IPAddressField()

    # ClickHouse-specific fields
    category = LowCardinalityField()  # Optimized for enums
    features = ArrayField(LowCardinalityField())  # Array of categories

    class Meta:
        collection = "products"
        backend = "clickhouse"

Querying

QuantumEngine provides powerful querying capabilities:

from quantumengine import Q

# Simple filters
users = await User.objects.filter(age__gt=18).all()
users = await User.objects.filter(username__contains="admin").all()
users = await User.objects.filter(active=True).all()

# Complex queries with Q objects
complex_query = Q(age__gte=18) & Q(age__lte=65) & Q(active=True)
users = await User.objects.filter(complex_query).all()

# OR conditions
either_query = Q(role="admin") | Q(permissions__contains="admin")
users = await User.objects.filter(either_query).all()

# NOT conditions
not_query = ~Q(status="banned")
users = await User.objects.filter(not_query).all()

# Count
count = await User.objects.filter(age__gte=21).count()

# Ordering
users = await User.objects.order_by("-created_at").all()

# Limiting
recent_users = await User.objects.order_by("-created_at").limit(10).all()

Error Handling

Handle missing backends gracefully:

from quantumengine.backends import BackendRegistry
from quantumengine.exceptions import BackendNotAvailableError

try:
    # Check if backend is available
    if not BackendRegistry.is_backend_available('clickhouse'):
        print("ClickHouse backend not available")
        print("Install with: pip install quantumengine[clickhouse]")
        return

    # Use backend
    connection = create_connection(backend='clickhouse', url='localhost')
    await connection.connect()

except BackendNotAvailableError as e:
    print(f"Backend error: {e}")
    # Provide helpful installation instructions

Next Steps

Now that you have the basics working:

1. Explore the Tutorial: Learn about advanced features like relationships and schema management

2. Check the API Reference: Detailed documentation for all classes and methods

3. Browse Examples: See real-world usage patterns in the examples section

4. Join the Community: Get help and share your experiences on GitHub Discussions

Note

Make sure you have SurrealDB or ClickHouse running locally for the examples to work. See the installation guide for database setup instructions.