surreal-orm-lite 0.2.2__tar.gz → 0.3.0__tar.gz

{surreal_orm_lite-0.2.2 → surreal_orm_lite-0.3.0}/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-02-05
+
+### Added
+
+- **Aggregation Functions**: New aggregation classes for database calculations
+  - `Count()` - Count records
+  - `Sum(field)` - Sum numeric field values
+  - `Avg(field)` - Calculate average of numeric field
+  - `Min(field)` - Find minimum value
+  - `Max(field)` - Find maximum value
+
+- **QuerySet Aggregation Methods**: Shortcut methods for common aggregations
+  - `count()` - Returns count as integer directly
+  - `sum(field)` - Returns sum as float/int
+  - `avg(field)` - Returns average as float
+  - `min(field)` - Returns minimum value
+  - `max(field)` - Returns maximum value
+
+- **GROUP BY Support**: Django-style grouping with annotations
+  - `values(*fields)` - Specify fields for GROUP BY
+  - `annotate(**aggregations)` - Add aggregation annotations
+
+- **exists() Method**: Efficiently check if records exist
+
+- **raw_query() Class Method**: Execute arbitrary SurrealQL queries with variables
+
+- New test file `tests/test_aggregations.py` with comprehensive unit and e2e tests
+
+### Changed
+
+- QuerySet now tracks `_group_by_fields` and `_annotations` for GROUP BY queries
+- `exec()` method now handles GROUP BY queries differently, returning dicts instead of model instances
+
 ## [0.2.2] - 2026-02-05
 
 ### Fixed

{surreal_orm_lite-0.2.2 → surreal_orm_lite-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-orm-lite
-Version: 0.2.2
+Version: 0.3.0
 Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
 Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
 Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite

{surreal_orm_lite-0.2.2 → surreal_orm_lite-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "surreal-orm-lite"
-version = "0.2.2"
+version = "0.3.0"
 description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
 readme = "README.md"
 requires-python = ">=3.11"

{surreal_orm_lite-0.2.2 → surreal_orm_lite-0.3.0}/src/surreal_orm_lite/__init__.py

@@ -1,5 +1,6 @@
-__version__ = "0.2.2"
+__version__ = "0.3.0"
 
+from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
 from .connection_manager import SurrealDBConnectionManager
 from .enum import OrderBy
 from .exceptions import (
@@ -14,11 +15,22 @@ from .query_set import QuerySet
 
 __all__ = [
     "__version__",
+    # Connection
     "SurrealDBConnectionManager",
+    # Model
     "BaseSurrealModel",
+    "SurrealConfigDict",
+    # QuerySet
     "QuerySet",
     "OrderBy",
-    "SurrealConfigDict",
+    # Aggregations
+    "Aggregation",
+    "Count",
+    "Sum",
+    "Avg",
+    "Min",
+    "Max",
+    # Exceptions
     "SurrealORMError",
     "SurrealDbError",
     "SurrealDbConnectionError",

surreal_orm_lite-0.3.0/src/surreal_orm_lite/aggregations.py

@@ -0,0 +1,279 @@
+"""
+Aggregation classes for SurrealDB-ORM-lite.
+
+This module provides Django-style aggregation functions that can be used
+with QuerySet to perform aggregate calculations on database fields.
+
+Example:
+    ```python
+    from surreal_orm_lite import Count, Sum, Avg, Min, Max
+
+    # Simple aggregations
+    count = await User.objects().count()
+    total = await Order.objects().sum("amount")
+
+    # With GROUP BY
+    results = await User.objects().values("status").annotate(count=Count()).exec()
+    ```
+"""
+
+from abc import ABC, abstractmethod
+
+from .utils import validate_field_name
+
+
+class Aggregation(ABC):
+    """
+    Base class for all aggregation functions.
+
+    Aggregations are used to compute summary values from a set of records.
+    Each aggregation must implement the `to_sql()` method that returns
+    the SurrealDB SQL expression for the aggregation.
+    """
+
+    def __init__(self, field: str | None = None, alias: str | None = None) -> None:
+        """
+        Initialize an aggregation.
+
+        Args:
+            field: The field name to aggregate. Some aggregations (like Count)
+                   don't require a field.
+            alias: Optional alias for the result. If not provided, a default
+                   alias will be generated.
+        """
+        self.field = field
+        self.alias = alias
+
+    @abstractmethod
+    def to_sql(self) -> str:
+        """
+        Convert the aggregation to a SurrealDB SQL expression.
+
+        Returns:
+            str: The SQL expression for this aggregation.
+        """
+        pass  # pragma: no cover
+
+    def get_alias(self) -> str:
+        """
+        Get the alias for this aggregation result.
+
+        Returns:
+            str: The alias name for the aggregation result.
+        """
+        if self.alias:
+            return self.alias
+        if self.field:
+            return f"{self.__class__.__name__.lower()}_{self.field}"
+        return self.__class__.__name__.lower()
+
+
+class Count(Aggregation):
+    """
+    Count aggregation function.
+
+    Counts the number of records in a query result.
+
+    Example:
+        ```python
+        # Count all users
+        count = await User.objects().count()
+
+        # Count with filter
+        active_count = await User.objects().filter(status="active").count()
+
+        # Count with GROUP BY
+        results = await User.objects().values("status").annotate(count=Count()).exec()
+        ```
+    """
+
+    def __init__(self, field: str | None = None, alias: str | None = None) -> None:
+        """
+        Initialize a Count aggregation.
+
+        Args:
+            field: Optional field name. If not provided, counts all records.
+            alias: Optional alias for the result.
+        """
+        if field is not None:
+            validate_field_name(field, "Count field")
+        super().__init__(field, alias)
+
+    def to_sql(self) -> str:
+        """
+        Convert to SurrealDB SQL.
+
+        Returns:
+            str: "count()" or "count(field)" expression.
+        """
+        if self.field:
+            return f"count({self.field})"
+        return "count()"
+
+
+class Sum(Aggregation):
+    """
+    Sum aggregation function.
+
+    Calculates the sum of a numeric field.
+
+    Example:
+        ```python
+        # Sum of all order amounts
+        total = await Order.objects().sum("amount")
+
+        # Sum with filter
+        total_completed = await Order.objects().filter(status="completed").sum("amount")
+
+        # Sum with GROUP BY
+        results = await Order.objects().values("customer_id").annotate(total=Sum("amount")).exec()
+        ```
+    """
+
+    def __init__(self, field: str, alias: str | None = None) -> None:
+        """
+        Initialize a Sum aggregation.
+
+        Args:
+            field: The numeric field to sum.
+            alias: Optional alias for the result.
+        """
+        if not field or not field.strip():
+            raise ValueError("Sum requires a field name")
+        validate_field_name(field, "Sum field")
+        super().__init__(field, alias)
+
+    def to_sql(self) -> str:
+        """
+        Convert to SurrealDB SQL.
+
+        Returns:
+            str: "math::sum(field)" expression.
+        """
+        return f"math::sum({self.field})"
+
+
+class Avg(Aggregation):
+    """
+    Average aggregation function.
+
+    Calculates the average of a numeric field.
+
+    Example:
+        ```python
+        # Average age of all users
+        avg_age = await User.objects().avg("age")
+
+        # Average with filter
+        avg_active = await User.objects().filter(status="active").avg("age")
+
+        # Average with GROUP BY
+        results = await User.objects().values("department").annotate(avg_salary=Avg("salary")).exec()
+        ```
+    """
+
+    def __init__(self, field: str, alias: str | None = None) -> None:
+        """
+        Initialize an Avg aggregation.
+
+        Args:
+            field: The numeric field to average.
+            alias: Optional alias for the result.
+        """
+        if not field or not field.strip():
+            raise ValueError("Avg requires a field name")
+        validate_field_name(field, "Avg field")
+        super().__init__(field, alias)
+
+    def to_sql(self) -> str:
+        """
+        Convert to SurrealDB SQL.
+
+        Returns:
+            str: "math::mean(field)" expression.
+        """
+        return f"math::mean({self.field})"
+
+
+class Min(Aggregation):
+    """
+    Minimum aggregation function.
+
+    Finds the minimum value of a field.
+
+    Example:
+        ```python
+        # Minimum price
+        min_price = await Product.objects().min("price")
+
+        # Minimum with filter
+        min_active = await Product.objects().filter(active=True).min("price")
+
+        # Minimum with GROUP BY
+        results = await Product.objects().values("category").annotate(min_price=Min("price")).exec()
+        ```
+    """
+
+    def __init__(self, field: str, alias: str | None = None) -> None:
+        """
+        Initialize a Min aggregation.
+
+        Args:
+            field: The field to find the minimum value of.
+            alias: Optional alias for the result.
+        """
+        if not field or not field.strip():
+            raise ValueError("Min requires a field name")
+        validate_field_name(field, "Min field")
+        super().__init__(field, alias)
+
+    def to_sql(self) -> str:
+        """
+        Convert to SurrealDB SQL.
+
+        Returns:
+            str: "math::min(field)" expression.
+        """
+        return f"math::min({self.field})"
+
+
+class Max(Aggregation):
+    """
+    Maximum aggregation function.
+
+    Finds the maximum value of a field.
+
+    Example:
+        ```python
+        # Maximum price
+        max_price = await Product.objects().max("price")
+
+        # Maximum with filter
+        max_active = await Product.objects().filter(active=True).max("price")
+
+        # Maximum with GROUP BY
+        results = await Product.objects().values("category").annotate(max_price=Max("price")).exec()
+        ```
+    """
+
+    def __init__(self, field: str, alias: str | None = None) -> None:
+        """
+        Initialize a Max aggregation.
+
+        Args:
+            field: The field to find the maximum value of.
+            alias: Optional alias for the result.
+        """
+        if not field or not field.strip():
+            raise ValueError("Max requires a field name")
+        validate_field_name(field, "Max field")
+        super().__init__(field, alias)
+
+    def to_sql(self) -> str:
+        """
+        Convert to SurrealDB SQL.
+
+        Returns:
+            str: "math::max(field)" expression.
+        """
+        return f"math::max({self.field})"

{surreal_orm_lite-0.2.2 → surreal_orm_lite-0.3.0}/src/surreal_orm_lite/model_base.py

@@ -2,6 +2,7 @@ import logging
 from typing import Any, Self
 
 from pydantic import BaseModel, ConfigDict, model_validator
+from pydantic_core import ValidationError
 from surrealdb import RecordID
 
 from .connection_manager import SurrealDBConnectionManager
@@ -224,3 +225,62 @@ class BaseSurrealModel(BaseModel):
         from .query_set import QuerySet
 
         return QuerySet(cls)
+
+    @classmethod
+    async def raw_query(
+        cls,
+        query: str,
+        variables: dict[str, Any] | None = None,
+    ) -> list[Self] | list[dict[str, Any]]:
+        """
+        Execute a raw SurrealQL query and return the results.
+
+        This method allows executing arbitrary SurrealQL queries directly against
+        the database. It's useful for complex queries that can't be expressed
+        using the QuerySet API.
+
+        Args:
+            query: The SurrealQL query string to execute.
+            variables: Optional dictionary of variables to substitute into the query.
+                      Use $variable_name syntax in the query string.
+
+        Returns:
+            list[Self] | list[dict]: A list of model instances if the results match
+            the model schema, otherwise a list of dictionaries.
+
+        Example:
+            ```python
+            # Simple query
+            users = await User.raw_query("SELECT * FROM User WHERE age > 21")
+
+            # With variables (safe from injection)
+            users = await User.raw_query(
+                "SELECT * FROM User WHERE status = $status AND age > $min_age",
+                variables={"status": "active", "min_age": 18}
+            )
+
+            # Complex graph query
+            results = await User.raw_query('''
+                SELECT *, ->purchased->Product AS products
+                FROM User
+                WHERE id = $user_id
+            ''', variables={"user_id": "user:123"})
+            ```
+        """
+        from .utils import remove_quotes_for_variables
+
+        client = await SurrealDBConnectionManager.get_client()
+        results = await client.query(
+            remove_quotes_for_variables(query),
+            variables or {},
+        )
+
+        # SDK 1.0.8 returns list directly from query()
+        if isinstance(results, list):
+            try:
+                return cls.from_db(results)  # type: ignore
+            except (ValueError, TypeError, ValidationError):
+                # If validation fails, return raw dicts
+                return results
+
+        return []

{surreal_orm_lite-0.2.2 → surreal_orm_lite-0.3.0}/src/surreal_orm_lite/query_set.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Any, Self, cast
+from typing import TYPE_CHECKING, Any, Self, cast
 
 from pydantic_core import ValidationError
 
@@ -7,7 +7,10 @@ from . import BaseSurrealModel, SurrealDBConnectionManager
 from .constants import LOOKUP_OPERATORS
 from .enum import OrderBy
 from .exceptions import SurrealDbError, SurrealDbNotFoundError
-from .utils import remove_quotes_for_variables
+from .utils import remove_quotes_for_variables, validate_alias_name, validate_field_name
+
+if TYPE_CHECKING:
+    from .aggregations import Aggregation
 
 logger = logging.getLogger(__name__)
 
@@ -57,6 +60,8 @@ class QuerySet:
         self._order_by: str | None = None
         self._model_table: str = getattr(model, "_table_name", model.__name__)
         self._variables: dict = {}
+        self._group_by_fields: list[str] = []
+        self._annotations: dict[str, Aggregation] = {}
 
     def select(self, *fields: str) -> Self:
         """
@@ -223,6 +228,23 @@ class QuerySet:
         self._order_by = f"{field_name} {type}"
         return self
 
+    def _build_where_clauses(self) -> list[str]:
+        """
+        Build WHERE clause conditions from the current filters.
+
+        Returns:
+            list[str]: A list of WHERE clause condition strings.
+        """
+        where_clauses = []
+        for field_name, lookup_name, value in self._filters:
+            op = LOOKUP_OPERATORS.get(lookup_name, "=")
+            if lookup_name == "in":
+                formatted_values = ", ".join(repr(v) for v in value)
+                where_clauses.append(f"{field_name} {op} [{formatted_values}]")
+            else:
+                where_clauses.append(f"{field_name} {op} {repr(value)}")
+        return where_clauses
+
     def _compile_query(self) -> str:
         """
         Compile the QuerySet parameters into a SQL query string.
@@ -240,15 +262,7 @@ class QuerySet:
             # "SELECT id, name FROM users WHERE age > 21 AND status = 'active' ORDER BY name ASC LIMIT 10 START 20;"
             ```
         """
-        where_clauses = []
-        for field_name, lookup_name, value in self._filters:
-            op = LOOKUP_OPERATORS.get(lookup_name, "=")
-            if lookup_name == "in":
-                # Assuming value is iterable for 'IN' operations
-                formatted_values = ", ".join(repr(v) for v in value)
-                where_clauses.append(f"{field_name} {op} [{formatted_values}]")
-            else:
-                where_clauses.append(f"{field_name} {op} {repr(value)}")
+        where_clauses = self._build_where_clauses()
 
         # Construct the SELECT clause
         if self.select_item:
@@ -284,18 +298,34 @@ class QuerySet:
         the results. If the data conforms to the model schema, it returns a list of model instances;
         otherwise, it returns a list of dictionaries.
 
+        When `values()` and `annotate()` are used, returns a list of dictionaries with
+        the grouped fields and aggregation results.
+
         Returns:
             list[BaseSurrealModel] | list[dict]: A list of model instances if validation is successful,
-            otherwise a list of dictionaries representing the raw data.
+            otherwise a list of dictionaries representing the raw data. For GROUP BY queries,
+            always returns a list of dictionaries.
 
         Raises:
             SurrealDbError: If there is an issue executing the query.
 
         Example:
             ```python
+            # Regular query
             results = await queryset.exec()
+
+            # GROUP BY query
+            results = await User.objects().values("status").annotate(count=Count()).exec()
+            # Returns: [{"status": "active", "count": 42}, ...]
             ```
         """
+        # Handle GROUP BY queries with annotations
+        if self._annotations:
+            query = self._compile_group_by_query()
+            results = await self._execute_query(query)
+            # GROUP BY queries always return dicts, not model instances
+            return results if isinstance(results, list) else []
+
         query = self._compile_query()
         results = await self._execute_query(query)
         try:
@@ -466,6 +496,343 @@ class QuerySet:
         await client.delete(self._model_table)
         return True
 
+    # ==================== Aggregation Methods ====================
+
+    def values(self, *fields: str) -> Self:
+        """
+        Specify fields for GROUP BY operations.
+
+        This method sets up the fields that will be used for grouping when
+        combined with `annotate()`. Similar to Django's `values()` method.
+
+        Args:
+            *fields: Field names to group by.
+
+        Returns:
+            Self: The current QuerySet instance for method chaining.
+
+        Example:
+            ```python
+            # Group users by status and count them
+            results = await User.objects().values("status").annotate(count=Count()).exec()
+            # Returns: [{"status": "active", "count": 42}, {"status": "inactive", "count": 8}]
+            ```
+        """
+        for field in fields:
+            validate_field_name(field, "GROUP BY field")
+        self._group_by_fields = list(fields)
+        return self
+
+    def annotate(self, **annotations: "Aggregation") -> Self:
+        """
+        Add aggregation annotations to the query.
+
+        This method adds aggregation functions to the query. When combined with
+        `values()`, it performs GROUP BY operations. Similar to Django's `annotate()`.
+
+        Args:
+            **annotations: Keyword arguments where the key is the alias and the value
+                          is an Aggregation instance (Count, Sum, Avg, Min, Max).
+
+        Returns:
+            Self: The current QuerySet instance for method chaining.
+
+        Raises:
+            TypeError: If any annotation value is not an Aggregation instance.
+
+        Example:
+            ```python
+            from surreal_orm_lite import Count, Sum, Avg
+
+            # Group by status and count
+            results = await User.objects().values("status").annotate(count=Count()).exec()
+
+            # Multiple aggregations
+            results = await Order.objects().values("customer_id").annotate(
+                total=Sum("amount"),
+                avg_order=Avg("amount"),
+                order_count=Count()
+            ).exec()
+            ```
+        """
+        from .aggregations import Aggregation as AggregationClass
+
+        for alias, agg in annotations.items():
+            validate_alias_name(alias)
+            if not isinstance(agg, AggregationClass):
+                raise TypeError(f"annotate() argument '{alias}' must be an Aggregation instance, got {type(agg).__name__}")
+        self._annotations.update(annotations)
+        return self
+
+    async def count(self) -> int:
+        """
+        Count the number of records matching the query.
+
+        This is a shortcut method that returns the count as an integer directly.
+
+        Returns:
+            int: The number of matching records.
+
+        Example:
+            ```python
+            # Count all users
+            total = await User.objects().count()
+
+            # Count with filters
+            active = await User.objects().filter(status="active").count()
+            ```
+        """
+        query = self._compile_aggregation_query("count()")
+        results = await self._execute_query(query)
+
+        if isinstance(results, list) and len(results) > 0:
+            result = results[0]
+            if isinstance(result, dict):
+                # Handle GROUP ALL result format
+                return int(result.get("count", 0))
+            return int(result)
+        return 0
+
+    async def sum(self, field: str) -> float | int:
+        """
+        Calculate the sum of a numeric field.
+
+        Args:
+            field: The name of the numeric field to sum.
+
+        Returns:
+            float | int: The sum of the field values, or 0 if no records match.
+
+        Raises:
+            ValueError: If field name is empty or invalid.
+
+        Example:
+            ```python
+            # Sum of all order amounts
+            total = await Order.objects().sum("amount")
+
+            # Sum with filter
+            completed_total = await Order.objects().filter(status="completed").sum("amount")
+            ```
+        """
+        validate_field_name(field, "sum() field")
+        query = self._compile_aggregation_query(f"math::sum({field})", alias="sum")
+        results = await self._execute_query(query)
+
+        if isinstance(results, list) and len(results) > 0:
+            result = results[0]
+            if isinstance(result, dict):
+                value = result.get("sum", 0)
+                return value if value is not None else 0
+            return result if result is not None else 0
+        return 0
+
+    async def avg(self, field: str) -> float:
+        """
+        Calculate the average of a numeric field.
+
+        Args:
+            field: The name of the numeric field to average.
+
+        Returns:
+            float: The average of the field values, or 0.0 if no records match.
+
+        Raises:
+            ValueError: If field name is empty or invalid.
+
+        Example:
+            ```python
+            # Average age of all users
+            avg_age = await User.objects().avg("age")
+
+            # Average with filter
+            avg_active = await User.objects().filter(status="active").avg("age")
+            ```
+        """
+        validate_field_name(field, "avg() field")
+        query = self._compile_aggregation_query(f"math::mean({field})", alias="avg")
+        results = await self._execute_query(query)
+
+        if isinstance(results, list) and len(results) > 0:
+            result = results[0]
+            if isinstance(result, dict):
+                value = result.get("avg", 0.0)
+                return float(value) if value is not None else 0.0
+            return float(result) if result is not None else 0.0
+        return 0.0
+
+    async def min(self, field: str) -> Any:
+        """
+        Find the minimum value of a field.
+
+        Args:
+            field: The name of the field to find the minimum value of.
+
+        Returns:
+            Any: The minimum value, or None if no records match.
+
+        Raises:
+            ValueError: If field name is empty or invalid.
+
+        Example:
+            ```python
+            # Minimum price
+            min_price = await Product.objects().min("price")
+
+            # Minimum with filter
+            min_active = await Product.objects().filter(active=True).min("price")
+            ```
+        """
+        validate_field_name(field, "min() field")
+        query = self._compile_aggregation_query(f"math::min({field})", alias="min")
+        results = await self._execute_query(query)
+
+        if isinstance(results, list) and len(results) > 0:
+            result = results[0]
+            if isinstance(result, dict):
+                return result.get("min")
+            return result
+        return None
+
+    async def max(self, field: str) -> Any:
+        """
+        Find the maximum value of a field.
+
+        Args:
+            field: The name of the field to find the maximum value of.
+
+        Returns:
+            Any: The maximum value, or None if no records match.
+
+        Raises:
+            ValueError: If field name is empty or invalid.
+
+        Example:
+            ```python
+            # Maximum price
+            max_price = await Product.objects().max("price")
+
+            # Maximum with filter
+            max_active = await Product.objects().filter(active=True).max("price")
+            ```
+        """
+        validate_field_name(field, "max() field")
+        query = self._compile_aggregation_query(f"math::max({field})", alias="max")
+        results = await self._execute_query(query)
+
+        if isinstance(results, list) and len(results) > 0:
+            result = results[0]
+            if isinstance(result, dict):
+                return result.get("max")
+            return result
+        return None
+
+    async def exists(self) -> bool:
+        """
+        Check if any records match the current query.
+
+        This method is more efficient than `count()` when you only need to know
+        if any matching records exist.
+
+        Returns:
+            bool: True if at least one record matches, False otherwise.
+
+        Example:
+            ```python
+            # Check if any admins exist
+            has_admin = await User.objects().filter(role="admin").exists()
+
+            # Check if user exists
+            user_exists = await User.objects().filter(email="alice@example.com").exists()
+            ```
+        """
+        # Use LIMIT 1 for efficiency without permanently mutating the QuerySet
+        original_limit = self._limit
+        try:
+            self._limit = 1
+            query = self._compile_query()
+            results = await self._execute_query(query)
+
+            if isinstance(results, list):
+                return len(results) > 0
+            return False
+        finally:
+            self._limit = original_limit
+
+    def _compile_aggregation_query(self, aggregation_expr: str, alias: str | None = None) -> str:
+        """
+        Compile an aggregation query.
+
+        This internal method builds the SQL query for aggregation operations.
+
+        Args:
+            aggregation_expr: The aggregation expression (e.g., "count()", "math::sum(field)").
+            alias: Optional alias for the aggregation result.
+
+        Returns:
+            str: The compiled SQL query string.
+        """
+        where_clauses = self._build_where_clauses()
+
+        # Build SELECT clause with aggregation
+        if alias:
+            query = f"SELECT {aggregation_expr} AS {alias} FROM {self._model_table}"
+        else:
+            query = f"SELECT {aggregation_expr} FROM {self._model_table}"
+
+        # Append WHERE clauses
+        if where_clauses:
+            query += " WHERE " + " AND ".join(where_clauses)
+
+        # GROUP ALL is required for aggregations without GROUP BY in SurrealDB
+        query += " GROUP ALL"
+        query += ";"
+        return query
+
+    def _compile_group_by_query(self) -> str:
+        """
+        Compile a GROUP BY query with annotations.
+
+        This internal method builds the SQL query for GROUP BY operations
+        with aggregation annotations.
+
+        Returns:
+            str: The compiled SQL query string.
+        """
+        where_clauses = self._build_where_clauses()
+
+        # Build SELECT clause with group fields and annotations
+        select_parts = list(self._group_by_fields)
+        for alias, agg in self._annotations.items():
+            select_parts.append(f"{agg.to_sql()} AS {alias}")
+
+        query = f"SELECT {', '.join(select_parts)} FROM {self._model_table}"
+
+        # Append WHERE clauses
+        if where_clauses:
+            query += " WHERE " + " AND ".join(where_clauses)
+
+        # Append GROUP BY
+        if self._group_by_fields:
+            query += f" GROUP BY {', '.join(self._group_by_fields)}"
+        else:
+            query += " GROUP ALL"
+
+        # Append ORDER BY if set
+        if self._order_by:
+            query += f" ORDER BY {self._order_by}"
+
+        # Append LIMIT if set
+        if self._limit is not None:
+            query += f" LIMIT {self._limit}"
+
+        # Append OFFSET if set
+        if self._offset is not None:
+            query += f" START {self._offset}"
+
+        query += ";"
+        return query
+
     async def query(self, query: str, variables: dict[str, Any] | None = None) -> Any:
         """
         Execute a custom SQL query on the SurrealDB database.

surreal_orm_lite-0.3.0/src/surreal_orm_lite/utils.py

@@ -0,0 +1,53 @@
+import re
+
+# Pattern for valid field names: alphanumeric, underscores, dots (for nested fields)
+# Must start with a letter or underscore
+VALID_FIELD_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*$")
+
+# Pattern for valid alias names: alphanumeric and underscores only
+# Must start with a letter or underscore (like Python identifiers)
+VALID_ALIAS_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+
+def remove_quotes_for_variables(query: str) -> str:
+    # Regex to remove single quotes around variables ($)
+    return re.sub(r"'(\$[a-zA-Z_]\w*)'", r"\1", query)
+
+
+def validate_field_name(field: str, context: str = "field") -> None:
+    """
+    Validate a field name to prevent SQL injection.
+
+    Args:
+        field: The field name to validate.
+        context: Description of where the field is used (for error messages).
+
+    Raises:
+        ValueError: If the field name contains invalid characters.
+    """
+    if not field or not field.strip():
+        raise ValueError(f"{context} name cannot be empty")
+    if not VALID_FIELD_PATTERN.match(field):
+        raise ValueError(
+            f"Invalid {context} name '{field}': must contain only alphanumeric characters, "
+            "underscores, and dots (for nested fields), and start with a letter or underscore"
+        )
+
+
+def validate_alias_name(alias: str) -> None:
+    """
+    Validate an alias name to prevent SQL injection.
+
+    Args:
+        alias: The alias name to validate.
+
+    Raises:
+        ValueError: If the alias name contains invalid characters.
+    """
+    if not alias or not alias.strip():
+        raise ValueError("alias name cannot be empty")
+    if not VALID_ALIAS_PATTERN.match(alias):
+        raise ValueError(
+            f"Invalid alias name '{alias}': must contain only alphanumeric characters "
+            "and underscores, and start with a letter or underscore"
+        )

surreal_orm_lite-0.2.2/src/surreal_orm_lite/utils.py

@@ -1,6 +0,0 @@
-import re
-
-
-def remove_quotes_for_variables(query: str) -> str:
-    # Regex to remove single quotes around variables ($)
-    return re.sub(r"'(\$[a-zA-Z_]\w*)'", r"\1", query)