Fields¶

QuantumEngine provides a comprehensive set of field types for defining document schemas. These fields handle validation, serialization, and backend-specific transformations.

Overview ¶

Fields in QuantumEngine serve multiple purposes:

Type validation: Ensure data conforms to expected types
Default values: Provide sensible defaults for missing data
Required validation: Enforce mandatory fields
Custom validation: Apply business logic rules
Backend adaptation: Translate between Python types and database-specific formats

Basic Usage ¶

Fields are typically used as class attributes in document definitions:

from quantumengine import Document
from quantumengine.fields import StringField, IntField, DateTimeField

class User(Document):
    name = StringField(required=True)
    age = IntField(default=0)
    created_at = DateTimeField(auto_now_add=True)

Field Categories ¶

Scalar Fields ¶

Basic data types for simple values:

StringField - Text data
IntField - Integer numbers
FloatField - Floating-point numbers
BooleanField - True/False values
DecimalField - Precise decimal numbers

DateTime Fields ¶

Temporal data handling:

DateTimeField - Date and time values
TimeSeriesField - Time series data
DurationField - Time duration values

Collection Fields ¶

Container types for multiple values:

ListField - Ordered lists
DictField - Key-value mappings
SetField - Unique value collections

Reference Fields ¶

Relationships between documents:

ReferenceField - Document references
RelationField - Graph-style relations (SurrealDB)

Specialized Fields ¶

Domain-specific field types:

EmailField - Email addresses
URLField - Web URLs
UUIDField - UUID values
IPAddressField - IP addresses
SlugField - URL-friendly strings
ChoiceField - Enumerated choices
RegexField - Regex-validated strings

ClickHouse-Specific Fields ¶

Optimized fields for ClickHouse backend:

LowCardinalityField - Low cardinality optimization
FixedStringField - Fixed-length strings
ArrayField - Native array support
CompressedStringField - Compressed text data

Common Field Options ¶

All fields support these common parameters:

Parameter	Description
`required`	Whether the field must have a value (default: `False`)
`default`	Default value or callable that returns a default
`db_field`	Override the database field name
`unique`	Enforce uniqueness constraint
`choices`	Restrict values to a predefined set
`validation`	Custom validation function or list of functions

Validation ¶

Fields provide multiple levels of validation:

Type Validation ¶

Automatic type checking based on field class:

age = IntField()  # Only accepts integers
name = StringField()  # Only accepts strings

Custom Validators ¶

Add custom validation logic:

def validate_age(value):
    if value < 0 or value > 150:
        raise ValidationError("Age must be between 0 and 150")

age = IntField(validation=validate_age)

Required Fields ¶

Enforce mandatory fields:

email = EmailField(required=True)  # Must be provided

Backend Considerations ¶

Different backends may handle fields differently:

SurrealDB ¶

Supports all field types including relations
Handles complex nested structures
Native support for geometric data

ClickHouse ¶

Optimized for analytical workloads
Special fields for compression and low cardinality
No support for document references

Examples ¶

Basic Document ¶

from quantumengine import Document
from quantumengine.fields import *

class Product(Document):
    name = StringField(required=True)
    price = DecimalField(required=True)
    description = StringField()
    tags = ListField(StringField())
    in_stock = BooleanField(default=True)
    created_at = DateTimeField(auto_now_add=True)

With Validation ¶

class User(Document):
    username = StringField(required=True, unique=True)
    email = EmailField(required=True)
    age = IntField(validation=lambda v: v >= 18)
    role = ChoiceField(choices=['admin', 'user', 'guest'])

ClickHouse Analytics ¶

class Event(Document):
    __backend__ = 'clickhouse'

    event_type = LowCardinalityField(StringField())
    timestamp = DateTimeField(required=True)
    user_id = UUIDField()
    properties = DictField()
    tags = ArrayField(StringField())