sqlspec 0.36.2__tar.gz → 0.37.0__tar.gz

{sqlspec-0.36.2 → sqlspec-0.37.0}/.gitignore

@@ -60,3 +60,4 @@ docs-build
 specs/
 .playwright-mcp
 .geminiignore
+uv.toml

{sqlspec-0.36.2 → sqlspec-0.37.0}/.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.14.11"
+    rev: "v0.14.13"
     hooks:
       - id: ruff
         args: ["--fix"]

{sqlspec-0.36.2 → sqlspec-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.36.2
+Version: 0.37.0
 Summary: SQL Experiments in Python
 Project-URL: Discord, https://discord.gg/litestar
 Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/

{sqlspec-0.36.2 → sqlspec-0.37.0}/pyproject.toml

@@ -13,7 +13,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.36.2"
+version = "0.37.0"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -222,7 +222,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.36.2"
+current_version = "0.37.0"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

{sqlspec-0.36.2 → sqlspec-0.37.0}/sqlspec/builder/__init__.py

@@ -17,6 +17,7 @@ from sqlspec.builder._ddl import (
     CreateView,
     DDLBuilder,
     DropIndex,
+    DropMaterializedView,
     DropSchema,
     DropTable,
     DropView,
@@ -117,6 +118,7 @@ __all__ = (
     "Delete",
     "DeleteFromClauseMixin",
     "DropIndex",
+    "DropMaterializedView",
     "DropSchema",
     "DropTable",
     "DropView",

{sqlspec-0.36.2 → sqlspec-0.37.0}/sqlspec/builder/_ddl.py

@@ -34,6 +34,7 @@ __all__ = (
     "CreateView",
     "DDLBuilder",
     "DropIndex",
+    "DropMaterializedView",
     "DropSchema",
     "DropTable",
     "DropView",
@@ -763,6 +764,54 @@ class DropSchema(DDLBuilder):
         )
 
 
+class DropMaterializedView(DDLBuilder):
+    """Builder for DROP MATERIALIZED VIEW [IF EXISTS] ... [CASCADE|RESTRICT]."""
+
+    __slots__ = ("_cascade", "_if_exists", "_view_name")
+
+    def __init__(self, view_name: str, dialect: "DialectType" = None) -> None:
+        """Initialize DROP MATERIALIZED VIEW with view name.
+
+        Args:
+            view_name: Name of the materialized view to drop
+            dialect: SQL dialect to use
+        """
+        super().__init__(dialect=dialect)
+        self._view_name = view_name
+        self._if_exists = False
+        self._cascade: bool | None = None
+
+    def name(self, view_name: str) -> Self:
+        """Set the materialized view name."""
+        self._view_name = view_name
+        return self
+
+    def if_exists(self) -> Self:
+        """Add IF EXISTS clause."""
+        self._if_exists = True
+        return self
+
+    def cascade(self) -> Self:
+        """Add CASCADE to drop dependent objects."""
+        self._cascade = True
+        return self
+
+    def restrict(self) -> Self:
+        """Add RESTRICT to prevent dropping if dependencies exist."""
+        self._cascade = False
+        return self
+
+    def _create_base_expression(self) -> exp.Expression:
+        if not self._view_name:
+            self._raise_sql_builder_error("View name must be set for DROP MATERIALIZED VIEW.")
+        return exp.Drop(
+            kind="MATERIALIZED VIEW",
+            this=exp.to_identifier(self._view_name),
+            exists=self._if_exists,
+            cascade=self._cascade,
+        )
+
+
 class CreateIndex(DDLBuilder):
     """Builder for CREATE [UNIQUE] INDEX [IF NOT EXISTS] ... ON ... (...)."""
 

{sqlspec-0.36.2 → sqlspec-0.37.0}/sqlspec/builder/_factory.py

@@ -24,6 +24,7 @@ from sqlspec.builder._ddl import (
     CreateTableAsSelect,
     CreateView,
     DropIndex,
+    DropMaterializedView,
     DropSchema,
     DropTable,
     DropView,
@@ -70,6 +71,7 @@ __all__ = (
     "CreateView",
     "Delete",
     "DropIndex",
+    "DropMaterializedView",
     "DropSchema",
     "DropTable",
     "DropView",
@@ -610,6 +612,18 @@ class SQLFactory:
         """
         return DropView(view_name, dialect=dialect or self.dialect)
 
+    def drop_materialized_view(self, view_name: str, dialect: DialectType = None) -> "DropMaterializedView":
+        """Create a DROP MATERIALIZED VIEW builder.
+
+        Args:
+            view_name: Name of the materialized view to drop
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropMaterializedView builder instance
+        """
+        return DropMaterializedView(view_name, dialect=dialect or self.dialect)
+
     def drop_index(self, index_name: str, dialect: DialectType = None) -> "DropIndex":
         """Create a DROP INDEX builder.
 
@@ -942,6 +956,56 @@ class SQLFactory:
         """Create a LEAD() window function builder."""
         return WindowFunctionBuilder("lead")
 
+    @property
+    def count_over_(self) -> "WindowFunctionBuilder":
+        """Create a COUNT(*) OVER() window function builder.
+
+        Returns a WindowFunctionBuilder pre-configured with COUNT(*) for fluent chaining.
+        Useful for pagination queries where you want to get the total count in the same query.
+
+        Returns:
+            WindowFunctionBuilder configured for COUNT(*) OVER()
+
+        Example:
+            >>> query = (
+            ...     sql
+            ...     .select("*", sql.count_over_.as_("total"))
+            ...     .from_("users")
+            ...     .where_eq("status", "active")
+            ...     .limit(10)
+            ... )
+            # Produces: SELECT *, COUNT(*) OVER() AS total FROM users WHERE status = :status LIMIT 10
+
+            >>> # With partition:
+            >>> query = sql.select(
+            ...     "*",
+            ...     sql.count_over_.partition_by("department").as_(
+            ...         "dept_count"
+            ...     ),
+            ... )
+        """
+        return WindowFunctionBuilder("count", exp.Star())
+
+    @property
+    def sum_over_(self) -> "WindowFunctionBuilder":
+        """Create a SUM() OVER() window function builder."""
+        return WindowFunctionBuilder("sum")
+
+    @property
+    def avg_over_(self) -> "WindowFunctionBuilder":
+        """Create an AVG() OVER() window function builder."""
+        return WindowFunctionBuilder("avg")
+
+    @property
+    def max_over_(self) -> "WindowFunctionBuilder":
+        """Create a MAX() OVER() window function builder."""
+        return WindowFunctionBuilder("max")
+
+    @property
+    def min_over_(self) -> "WindowFunctionBuilder":
+        """Create a MIN() OVER() window function builder."""
+        return WindowFunctionBuilder("min")
+
     @property
     def exists_(self) -> "SubqueryBuilder":
         """Create an EXISTS subquery builder."""
@@ -1119,6 +1183,136 @@ class SQLFactory:
         """
         return self.count(column, distinct=True)
 
+    def count_over(
+        self,
+        column: Union[str, exp.Expression, "ExpressionWrapper", "Case", "Column"] = "*",
+        partition_by: str | list[str] | exp.Expression | None = None,
+    ) -> FunctionExpression:
+        """Create a COUNT() OVER() window function for inline total counts.
+
+        This is particularly useful for pagination queries where you want to get
+        the total count in the same query as the paginated results.
+
+        Args:
+            column: Column to count (default "*" for COUNT(*)).
+            partition_by: Optional columns to partition by.
+
+        Returns:
+            COUNT() OVER() window function expression.
+
+        Example:
+            >>> # Simple total count alongside paginated results:
+            >>> query = (
+            ...     sql
+            ...     .select("id", "name", sql.count_over().as_("total"))
+            ...     .from_("users")
+            ...     .where_eq("status", "active")
+            ...     .limit(10)
+            ...     .offset(0)
+            ... )
+            # Produces: SELECT id, name, COUNT(*) OVER() AS total FROM users WHERE status = :status LIMIT 10
+
+            >>> # With partition (count per group):
+            >>> query = sql.select(
+            ...     "*",
+            ...     sql.count_over(partition_by="department").as_(
+            ...         "dept_count"
+            ...     ),
+            ... )
+        """
+        if isinstance(column, str) and column == "*":
+            count_expr = exp.Count(this=exp.Star())
+        else:
+            col_expr = extract_expression(column)
+            count_expr = exp.Count(this=col_expr)
+
+        over_args: dict[str, Any] = {}
+        if partition_by:
+            if isinstance(partition_by, str):
+                over_args["partition_by"] = [exp.column(partition_by)]
+            elif isinstance(partition_by, list):
+                over_args["partition_by"] = [exp.column(col) for col in partition_by]
+            elif isinstance(partition_by, exp.Expression):
+                over_args["partition_by"] = [partition_by]
+
+        return FunctionExpression(exp.Window(this=count_expr, **over_args))
+
+    def sum_over(
+        self,
+        column: Union[str, exp.Expression, "ExpressionWrapper", "Case"],
+        partition_by: str | list[str] | exp.Expression | None = None,
+        order_by: str | list[str] | exp.Expression | None = None,
+    ) -> FunctionExpression:
+        """Create a SUM() OVER() window function.
+
+        Args:
+            column: Column to sum.
+            partition_by: Columns to partition by.
+            order_by: Columns to order by.
+
+        Returns:
+            SUM() OVER() window function expression.
+        """
+        col_expr = extract_expression(column)
+        return self._create_window_function("SUM", [col_expr], partition_by, order_by)
+
+    def avg_over(
+        self,
+        column: Union[str, exp.Expression, "ExpressionWrapper", "Case"],
+        partition_by: str | list[str] | exp.Expression | None = None,
+        order_by: str | list[str] | exp.Expression | None = None,
+    ) -> FunctionExpression:
+        """Create an AVG() OVER() window function.
+
+        Args:
+            column: Column to average.
+            partition_by: Columns to partition by.
+            order_by: Columns to order by.
+
+        Returns:
+            AVG() OVER() window function expression.
+        """
+        col_expr = extract_expression(column)
+        return self._create_window_function("AVG", [col_expr], partition_by, order_by)
+
+    def max_over(
+        self,
+        column: Union[str, exp.Expression, "ExpressionWrapper", "Case"],
+        partition_by: str | list[str] | exp.Expression | None = None,
+        order_by: str | list[str] | exp.Expression | None = None,
+    ) -> FunctionExpression:
+        """Create a MAX() OVER() window function.
+
+        Args:
+            column: Column to find maximum.
+            partition_by: Columns to partition by.
+            order_by: Columns to order by.
+
+        Returns:
+            MAX() OVER() window function expression.
+        """
+        col_expr = extract_expression(column)
+        return self._create_window_function("MAX", [col_expr], partition_by, order_by)
+
+    def min_over(
+        self,
+        column: Union[str, exp.Expression, "ExpressionWrapper", "Case"],
+        partition_by: str | list[str] | exp.Expression | None = None,
+        order_by: str | list[str] | exp.Expression | None = None,
+    ) -> FunctionExpression:
+        """Create a MIN() OVER() window function.
+
+        Args:
+            column: Column to find minimum.
+            partition_by: Columns to partition by.
+            order_by: Columns to order by.
+
+        Returns:
+            MIN() OVER() window function expression.
+        """
+        col_expr = extract_expression(column)
+        return self._create_window_function("MIN", [col_expr], partition_by, order_by)
+
     @staticmethod
     def sum(
         column: Union[str, exp.Expression, "ExpressionWrapper", "Case"], distinct: bool = False
@@ -1653,6 +1847,70 @@ class SQLFactory:
         """
         return self._create_window_function("DENSE_RANK", [], partition_by, order_by)
 
+    def lag(
+        self,
+        column: str | exp.Expression,
+        offset: int = 1,
+        default: Any = None,
+        partition_by: str | list[str] | exp.Expression | None = None,
+        order_by: str | list[str] | exp.Expression | None = None,
+    ) -> FunctionExpression:
+        """Create a LAG() window function.
+
+        LAG accesses data from a previous row in the same result set without using a self-join.
+
+        Args:
+            column: The column to get the lagged value from.
+            offset: Number of rows to look back (default 1).
+            default: Value to return when there is no row at the offset.
+            partition_by: Columns to partition by.
+            order_by: Columns to order by.
+
+        Returns:
+            LAG window function expression.
+
+        Example:
+            >>> sql.lag("salary", offset=1, order_by="hire_date")
+            >>> sql.lag("price", partition_by="category", order_by="date")
+        """
+        col_expr = exp.column(column) if isinstance(column, str) else column
+        func_args: list[exp.Expression] = [col_expr, exp.Literal.number(offset)]
+        if default is not None:
+            func_args.append(exp.convert(default))
+        return self._create_window_function("LAG", func_args, partition_by, order_by)
+
+    def lead(
+        self,
+        column: str | exp.Expression,
+        offset: int = 1,
+        default: Any = None,
+        partition_by: str | list[str] | exp.Expression | None = None,
+        order_by: str | list[str] | exp.Expression | None = None,
+    ) -> FunctionExpression:
+        """Create a LEAD() window function.
+
+        LEAD accesses data from a subsequent row in the same result set without using a self-join.
+
+        Args:
+            column: The column to get the lead value from.
+            offset: Number of rows to look forward (default 1).
+            default: Value to return when there is no row at the offset.
+            partition_by: Columns to partition by.
+            order_by: Columns to order by.
+
+        Returns:
+            LEAD window function expression.
+
+        Example:
+            >>> sql.lead("salary", offset=1, order_by="hire_date")
+            >>> sql.lead("price", partition_by="category", order_by="date")
+        """
+        col_expr = exp.column(column) if isinstance(column, str) else column
+        func_args: list[exp.Expression] = [col_expr, exp.Literal.number(offset)]
+        if default is not None:
+            func_args.append(exp.convert(default))
+        return self._create_window_function("LEAD", func_args, partition_by, order_by)
+
     @staticmethod
     def _create_window_function(
         func_name: str,

{sqlspec-0.36.2 → sqlspec-0.37.0}/sqlspec/builder/_select.py

@@ -296,6 +296,18 @@ class SelectClauseMixin:
         self.set_expression(select_expr)
         return cast("Self", builder)
 
+    def select_only(self, *columns: Union[str, exp.Expression, "Column", "FunctionColumn", SQL, Case]) -> Self:
+        """Replace currently selected columns with new ones."""
+        builder = cast("SQLBuilderProtocol", self)
+        select_expr = _ensure_select_expression(builder, error_message="Cannot add columns to non-SELECT expression.")
+        # Clear existing expressions
+        select_expr.set("expressions", [])
+        for column in columns:
+            column_expr = column.expression if isinstance(column, Case) else parse_column_expression(column, builder)
+            select_expr = select_expr.select(column_expr, copy=False)
+        self.set_expression(select_expr)
+        return cast("Self", builder)
+
     def distinct(self, *columns: Union[str, exp.Expression, "Column", "FunctionColumn", SQL]) -> Self:
         builder = cast("SQLBuilderProtocol", self)
         select_expr = _ensure_select_expression(builder, error_message="Cannot add DISTINCT to non-SELECT expression.")

{sqlspec-0.36.2 → sqlspec-0.37.0}/sqlspec/driver/_async.py

@@ -40,6 +40,7 @@ from sqlspec.storage import AsyncStoragePipeline, StorageBridgeJob, StorageDesti
 from sqlspec.typing import VersionInfo
 from sqlspec.utils.arrow_helpers import convert_dict_to_arrow_with_schema
 from sqlspec.utils.logging import get_logger, log_with_context
+from sqlspec.utils.type_guards import has_asdict_method, is_dict_row, is_mapping_like
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -739,6 +740,7 @@ class AsyncDriverAdapterBase(CommonDriverAttributesMixin):
         *parameters: "StatementParameters | StatementFilter",
         schema_type: "type[SchemaT]",
         statement_config: "StatementConfig | None" = None,
+        count_with_window: bool = False,
         **kwargs: Any,
     ) -> "tuple[list[SchemaT], int]": ...
 
@@ -750,6 +752,7 @@ class AsyncDriverAdapterBase(CommonDriverAttributesMixin):
         *parameters: "StatementParameters | StatementFilter",
         schema_type: None = None,
         statement_config: "StatementConfig | None" = None,
+        count_with_window: bool = False,
         **kwargs: Any,
     ) -> "tuple[list[dict[str, Any]], int]": ...
 
@@ -760,6 +763,7 @@ class AsyncDriverAdapterBase(CommonDriverAttributesMixin):
         *parameters: "StatementParameters | StatementFilter",
         schema_type: "type[SchemaT] | None" = None,
         statement_config: "StatementConfig | None" = None,
+        count_with_window: bool = False,
         **kwargs: Any,
     ) -> "tuple[list[SchemaT] | list[dict[str, Any]], int]":
         """Execute a select statement and return both the data and total count.
@@ -772,6 +776,9 @@ class AsyncDriverAdapterBase(CommonDriverAttributesMixin):
             *parameters: Parameters for the SQL statement
             schema_type: Optional schema type for data transformation
             statement_config: Optional SQL configuration
+            count_with_window: If True, use a single query with COUNT(*) OVER() window
+                function instead of two separate queries. This can be more efficient
+                for some databases but adds a column to each row. Default False.
             **kwargs: Additional keyword arguments
 
         Returns:
@@ -779,12 +786,61 @@ class AsyncDriverAdapterBase(CommonDriverAttributesMixin):
             - List of data rows (transformed by schema_type if provided)
             - Total count of rows matching the query (ignoring LIMIT/OFFSET)
 
+        Example:
+            >>> # Two-query approach (default):
+            >>> data, total = await driver.select_with_total(
+            ...     sql
+            ...     .select("*")
+            ...     .from_("users")
+            ...     .where_eq("status", "active")
+            ...     .limit(10)
+            ... )
+
+            >>> # Single-query with window function:
+            >>> data, total = await driver.select_with_total(
+            ...     sql
+            ...     .select("*")
+            ...     .from_("users")
+            ...     .where_eq("status", "active")
+            ...     .limit(10),
+            ...     count_with_window=True,
+            ... )
+
         """
         sql_statement = self.prepare_statement(
             statement, parameters, statement_config=statement_config or self.statement_config, kwargs=kwargs
         )
+
+        if count_with_window:
+            modified_sql = self._add_count_over_column(sql_statement)
+            result = await self.dispatch_statement_execution(modified_sql, self.connection)
+            rows = result.all()
+
+            total = 0
+            if rows:
+                first_row = rows[0]
+                if is_dict_row(first_row):
+                    total = first_row.get("_total_count", 0)
+                else:
+                    total = getattr(first_row, "_total_count", 0)
+
+            data: list[dict[str, Any]] = []
+            for row in rows:
+                if is_dict_row(row):
+                    data.append({k: v for k, v in row.items() if k != "_total_count"})
+                elif is_mapping_like(row):
+                    data.append({k: v for k, v in dict(row).items() if k != "_total_count"})
+                elif has_asdict_method(row):
+                    data.append({k: v for k, v in row._asdict().items() if k != "_total_count"})  # pyright: ignore[reportPrivateUsage]
+                else:
+                    data.append({})
+
+            if schema_type is not None:
+                return ([schema_type(**r) for r in data], total)
+            return (data, total)
+
         count_result = await self.dispatch_statement_execution(self._create_count_query(sql_statement), self.connection)
-        select_result = await self.execute(sql_statement)
+        select_result = await self.dispatch_statement_execution(sql_statement, self.connection)
 
         return (select_result.get_data(schema_type=schema_type), count_result.scalar())
 
@@ -796,6 +852,7 @@ class AsyncDriverAdapterBase(CommonDriverAttributesMixin):
         *parameters: "StatementParameters | StatementFilter",
         schema_type: "type[SchemaT]",
         statement_config: "StatementConfig | None" = None,
+        count_with_window: bool = False,
         **kwargs: Any,
     ) -> "tuple[list[SchemaT], int]": ...
 
@@ -807,6 +864,7 @@ class AsyncDriverAdapterBase(CommonDriverAttributesMixin):
         *parameters: "StatementParameters | StatementFilter",
         schema_type: None = None,
         statement_config: "StatementConfig | None" = None,
+        count_with_window: bool = False,
         **kwargs: Any,
     ) -> "tuple[list[dict[str, Any]], int]": ...
 
@@ -817,6 +875,7 @@ class AsyncDriverAdapterBase(CommonDriverAttributesMixin):
         *parameters: "StatementParameters | StatementFilter",
         schema_type: "type[SchemaT] | None" = None,
         statement_config: "StatementConfig | None" = None,
+        count_with_window: bool = False,
         **kwargs: Any,
     ) -> "tuple[list[SchemaT] | list[dict[str, Any]], int]":
         """Execute a select statement and return both the data and total count.
@@ -832,7 +891,12 @@ class AsyncDriverAdapterBase(CommonDriverAttributesMixin):
 
         """
         return await self.select_with_total(
-            statement, *parameters, schema_type=schema_type, statement_config=statement_config, **kwargs
+            statement,
+            *parameters,
+            schema_type=schema_type,
+            statement_config=statement_config,
+            count_with_window=count_with_window,
+            **kwargs,
         )
 
     # ─────────────────────────────────────────────────────────────────────────────