sqlspec 0.16.2__py3-none-any.whl → 0.17.0__py3-none-any.whl

sqlspec/builder/mixins/_select_operations.py

@@ -12,11 +12,11 @@ from sqlspec.exceptions import SQLBuilderError
 from sqlspec.utils.type_guards import has_query_builder_parameters, is_expression
 
 if TYPE_CHECKING:
-    from sqlspec.builder._column import Column, FunctionColumn
+    from sqlspec.builder._column import Column, ColumnExpression, FunctionColumn
     from sqlspec.core.statement import SQL
     from sqlspec.protocols import SelectBuilderProtocol, SQLBuilderProtocol
 
-__all__ = ("CaseBuilder", "SelectClauseMixin")
+__all__ = ("Case", "CaseBuilder", "SelectClauseMixin", "SubqueryBuilder", "WindowFunctionBuilder")
 
 
 @trait
@@ -28,7 +28,7 @@ class SelectClauseMixin:
     # Type annotation for PyRight - this will be provided by the base class
     _expression: Optional[exp.Expression]
 
-    def select(self, *columns: Union[str, exp.Expression, "Column", "FunctionColumn", "SQL"]) -> Self:
+    def select(self, *columns: Union[str, exp.Expression, "Column", "FunctionColumn", "SQL", "Case"]) -> Self:
         """Add columns to SELECT clause.
 
         Raises:
@@ -602,3 +602,307 @@ class CaseBuilder:
         """
         select_expr = exp.alias_(self._case_expr, self._alias) if self._alias else self._case_expr
         return self._parent.select(select_expr)
+
+
+@trait
+class WindowFunctionBuilder:
+    """Builder for window functions with fluent syntax.
+
+    Example:
+        ```python
+        from sqlspec import sql
+
+        # sql.row_number_.partition_by("department").order_by("salary")
+        window_func = (
+            sql.row_number_.partition_by("department")
+            .order_by("salary")
+            .as_("row_num")
+        )
+        ```
+    """
+
+    def __init__(self, function_name: str) -> None:
+        """Initialize the window function builder.
+
+        Args:
+            function_name: Name of the window function (row_number, rank, etc.)
+        """
+        self._function_name = function_name
+        self._partition_by_cols: list[exp.Expression] = []
+        self._order_by_cols: list[exp.Expression] = []
+        self._alias: Optional[str] = None
+
+    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
+        """Equal to (==) - convert to expression then compare."""
+        from sqlspec.builder._column import ColumnExpression
+
+        window_expr = self._build_expression()
+        if other is None:
+            return ColumnExpression(exp.Is(this=window_expr, expression=exp.Null()))
+        return ColumnExpression(exp.EQ(this=window_expr, expression=exp.convert(other)))
+
+    def __hash__(self) -> int:
+        """Make WindowFunctionBuilder hashable."""
+        return hash(id(self))
+
+    def partition_by(self, *columns: Union[str, exp.Expression]) -> "WindowFunctionBuilder":
+        """Add PARTITION BY clause.
+
+        Args:
+            *columns: Columns to partition by.
+
+        Returns:
+            Self for method chaining.
+        """
+        for col in columns:
+            col_expr = exp.column(col) if isinstance(col, str) else col
+            self._partition_by_cols.append(col_expr)
+        return self
+
+    def order_by(self, *columns: Union[str, exp.Expression]) -> "WindowFunctionBuilder":
+        """Add ORDER BY clause.
+
+        Args:
+            *columns: Columns to order by.
+
+        Returns:
+            Self for method chaining.
+        """
+        for col in columns:
+            if isinstance(col, str):
+                col_expr = exp.column(col).asc()
+                self._order_by_cols.append(col_expr)
+            else:
+                # Convert to ordered expression
+                self._order_by_cols.append(exp.Ordered(this=col, desc=False))
+        return self
+
+    def as_(self, alias: str) -> exp.Alias:
+        """Complete the window function with an alias.
+
+        Args:
+            alias: Alias name for the window function.
+
+        Returns:
+            Aliased window function expression.
+        """
+        window_expr = self._build_expression()
+        return cast("exp.Alias", exp.alias_(window_expr, alias))
+
+    def build(self) -> exp.Expression:
+        """Complete the window function without an alias.
+
+        Returns:
+            Window function expression.
+        """
+        return self._build_expression()
+
+    def _build_expression(self) -> exp.Expression:
+        """Build the complete window function expression."""
+        # Create the function expression
+        func_expr = exp.Anonymous(this=self._function_name.upper(), expressions=[])
+
+        # Build the OVER clause arguments
+        over_args: dict[str, Any] = {}
+
+        if self._partition_by_cols:
+            over_args["partition_by"] = self._partition_by_cols
+
+        if self._order_by_cols:
+            over_args["order"] = exp.Order(expressions=self._order_by_cols)
+
+        return exp.Window(this=func_expr, **over_args)
+
+
+@trait
+class SubqueryBuilder:
+    """Builder for subquery operations with fluent syntax.
+
+    Example:
+        ```python
+        from sqlspec import sql
+
+        # sql.exists_(subquery)
+        exists_check = sql.exists_(
+            sql.select("1")
+            .from_("orders")
+            .where_eq("user_id", sql.users.id)
+        )
+
+        # sql.in_(subquery)
+        in_check = sql.in_(
+            sql.select("category_id")
+            .from_("categories")
+            .where_eq("active", True)
+        )
+        ```
+    """
+
+    def __init__(self, operation: str) -> None:
+        """Initialize the subquery builder.
+
+        Args:
+            operation: Type of subquery operation (exists, in, any, all)
+        """
+        self._operation = operation
+
+    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
+        """Equal to (==) - not typically used but needed for type consistency."""
+        from sqlspec.builder._column import ColumnExpression
+
+        # SubqueryBuilder doesn't have a direct expression, so this is a placeholder
+        # In practice, this shouldn't be called as subqueries are used differently
+        placeholder_expr = exp.Literal.string(f"subquery_{self._operation}")
+        if other is None:
+            return ColumnExpression(exp.Is(this=placeholder_expr, expression=exp.Null()))
+        return ColumnExpression(exp.EQ(this=placeholder_expr, expression=exp.convert(other)))
+
+    def __hash__(self) -> int:
+        """Make SubqueryBuilder hashable."""
+        return hash(id(self))
+
+    def __call__(self, subquery: Union[str, exp.Expression, Any]) -> exp.Expression:
+        """Build the subquery expression.
+
+        Args:
+            subquery: The subquery - can be a SQL string, SelectBuilder, or expression
+
+        Returns:
+            The subquery expression (EXISTS, IN, ANY, ALL, etc.)
+        """
+        subquery_expr: exp.Expression
+        if isinstance(subquery, str):
+            # Parse as SQL
+            parsed: Optional[exp.Expression] = exp.maybe_parse(subquery)
+            if not parsed:
+                msg = f"Could not parse subquery SQL: {subquery}"
+                raise SQLBuilderError(msg)
+            subquery_expr = parsed
+        elif hasattr(subquery, "build") and callable(getattr(subquery, "build", None)):
+            # It's a query builder - build it to get the SQL and parse
+            built_query = subquery.build()  # pyright: ignore[reportAttributeAccessIssue]
+            subquery_expr = exp.maybe_parse(built_query.sql)
+            if not subquery_expr:
+                msg = f"Could not parse built query: {built_query.sql}"
+                raise SQLBuilderError(msg)
+        elif isinstance(subquery, exp.Expression):
+            subquery_expr = subquery
+        else:
+            # Try to convert to expression
+            parsed = exp.maybe_parse(str(subquery))
+            if not parsed:
+                msg = f"Could not convert subquery to expression: {subquery}"
+                raise SQLBuilderError(msg)
+            subquery_expr = parsed
+
+        # Build the appropriate expression based on operation
+        if self._operation == "exists":
+            return exp.Exists(this=subquery_expr)
+        if self._operation == "in":
+            # For IN, we create a subquery that can be used with WHERE column IN (subquery)
+            return exp.In(expressions=[subquery_expr])
+        if self._operation == "any":
+            return exp.Any(this=subquery_expr)
+        if self._operation == "all":
+            return exp.All(this=subquery_expr)
+        msg = f"Unknown subquery operation: {self._operation}"
+        raise SQLBuilderError(msg)
+
+
+@trait
+class Case:
+    """Builder for CASE expressions using the SQL factory.
+
+    Example:
+        ```python
+        from sqlspec import sql
+
+        case_expr = (
+            sql.case()
+            .when(sql.age < 18, "Minor")
+            .when(sql.age < 65, "Adult")
+            .else_("Senior")
+            .end()
+        )
+        ```
+    """
+
+    def __init__(self) -> None:
+        """Initialize the CASE expression builder."""
+        self._conditions: list[exp.If] = []
+        self._default: Optional[exp.Expression] = None
+
+    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
+        """Equal to (==) - convert to expression then compare."""
+        from sqlspec.builder._column import ColumnExpression
+
+        case_expr = exp.Case(ifs=self._conditions, default=self._default)
+        if other is None:
+            return ColumnExpression(exp.Is(this=case_expr, expression=exp.Null()))
+        return ColumnExpression(exp.EQ(this=case_expr, expression=exp.convert(other)))
+
+    def __hash__(self) -> int:
+        """Make Case hashable."""
+        return hash(id(self))
+
+    def when(self, condition: Union[str, exp.Expression], value: Union[str, exp.Expression, Any]) -> Self:
+        """Add a WHEN clause.
+
+        Args:
+            condition: Condition to test.
+            value: Value to return if condition is true.
+
+        Returns:
+            Self for method chaining.
+        """
+        from sqlspec._sql import SQLFactory
+
+        cond_expr = exp.maybe_parse(condition) or exp.column(condition) if isinstance(condition, str) else condition
+        val_expr = SQLFactory._to_literal(value)
+
+        # SQLGlot uses exp.If for CASE WHEN clauses, not exp.When
+        when_clause = exp.If(this=cond_expr, true=val_expr)
+        self._conditions.append(when_clause)
+        return self
+
+    def else_(self, value: Union[str, exp.Expression, Any]) -> Self:
+        """Add an ELSE clause.
+
+        Args:
+            value: Default value to return.
+
+        Returns:
+            Self for method chaining.
+        """
+        from sqlspec._sql import SQLFactory
+
+        self._default = SQLFactory._to_literal(value)
+        return self
+
+    def end(self) -> Self:
+        """Complete the CASE expression.
+
+        Returns:
+            Complete CASE expression.
+        """
+        return self
+
+    @property
+    def _expression(self) -> exp.Case:
+        """Get the sqlglot expression for this case builder.
+
+        This allows the CaseBuilder to be used wherever expressions are expected.
+        """
+        return exp.Case(ifs=self._conditions, default=self._default)
+
+    def as_(self, alias: str) -> exp.Alias:
+        """Complete the CASE expression with an alias.
+
+        Args:
+            alias: Alias name for the CASE expression.
+
+        Returns:
+            Aliased CASE expression.
+        """
+        case_expr = exp.Case(ifs=self._conditions, default=self._default)
+        return cast("exp.Alias", exp.alias_(case_expr, alias))

sqlspec/builder/mixins/_where_clause.py

@@ -214,20 +214,22 @@ class WhereClauseMixin:
         condition: Union[
             str, exp.Expression, exp.Condition, tuple[str, Any], tuple[str, str, Any], "ColumnExpression", "SQL"
         ],
-        value: Optional[Any] = None,
+        *values: Any,
         operator: Optional[str] = None,
+        **kwargs: Any,
     ) -> Self:
         """Add a WHERE clause to the statement.
 
         Args:
             condition: The condition for the WHERE clause. Can be:
-                - A string condition (when value is None)
-                - A string column name (when value is provided)
+                - A string condition with or without parameter placeholders
+                - A string column name (when values are provided)
                 - A sqlglot Expression or Condition
                 - A 2-tuple (column, value) for equality comparison
                 - A 3-tuple (column, operator, value) for custom comparison
-            value: Value for comparison (when condition is a column name)
-            operator: Operator for comparison (when both condition and value provided)
+            *values: Positional values for parameter binding (when condition contains placeholders or is a column name)
+            operator: Operator for comparison (when condition is a column name)
+            **kwargs: Named parameters for parameter binding (when condition contains named placeholders)
 
         Raises:
             SQLBuilderError: If the current expression is not a supported statement type.
@@ -248,16 +250,63 @@ class WhereClauseMixin:
             msg = "WHERE clause requires a table to be set. Use from() to set the table first."
             raise SQLBuilderError(msg)
 
-        if value is not None:
+        # Handle string conditions with external parameters
+        if values or kwargs:
             if not isinstance(condition, str):
-                msg = "When value is provided, condition must be a column name (string)"
+                msg = "When values are provided, condition must be a string"
                 raise SQLBuilderError(msg)
 
-            if operator is not None:
-                where_expr = self._process_tuple_condition((condition, operator, value))
+            # Check if condition contains parameter placeholders
+            from sqlspec.core.parameters import ParameterStyle, ParameterValidator
+
+            validator = ParameterValidator()
+            param_info = validator.extract_parameters(condition)
+
+            if param_info:
+                # String condition with placeholders - create SQL object with parameters
+                from sqlspec import sql as sql_factory
+
+                # Create parameter mapping based on the detected parameter info
+                param_dict = dict(kwargs)  # Start with named parameters
+
+                # Handle positional parameters - these are ordinal-based ($1, $2, :1, :2, ?)
+                positional_params = [
+                    param
+                    for param in param_info
+                    if param.style in {ParameterStyle.NUMERIC, ParameterStyle.POSITIONAL_COLON, ParameterStyle.QMARK}
+                ]
+
+                # Map positional values to positional parameters
+                if len(values) != len(positional_params):
+                    msg = f"Parameter count mismatch: condition has {len(positional_params)} positional placeholders, got {len(values)} values"
+                    raise SQLBuilderError(msg)
+
+                for i, value in enumerate(values):
+                    param_dict[f"param_{i}"] = value
+
+                # Create SQL object with parameters that will be processed correctly
+                condition = sql_factory.raw(condition, **param_dict)
+                # Fall through to existing SQL object handling logic
+
+            elif len(values) == 1 and not kwargs:
+                # Single value - treat as column = value
+                if operator is not None:
+                    where_expr = self._process_tuple_condition((condition, operator, values[0]))
+                else:
+                    where_expr = self._process_tuple_condition((condition, values[0]))
+                # Process this condition and skip the rest
+                if isinstance(builder._expression, (exp.Select, exp.Update, exp.Delete)):
+                    builder._expression = builder._expression.where(where_expr, copy=False)
+                else:
+                    msg = f"WHERE clause not supported for {type(builder._expression).__name__}"
+                    raise SQLBuilderError(msg)
+                return self
             else:
-                where_expr = self._process_tuple_condition((condition, value))
-        elif isinstance(condition, str):
+                msg = f"Cannot bind parameters to condition without placeholders: {condition}"
+                raise SQLBuilderError(msg)
+
+        # Handle all condition types (including SQL objects created above)
+        if isinstance(condition, str):
             where_expr = parse_condition_expression(condition)
         elif isinstance(condition, (exp.Expression, exp.Condition)):
             where_expr = condition

sqlspec/core/compiler.py

@@ -277,11 +277,13 @@ class SQLProcessor:
             if self._config.parameter_config.needs_static_script_compilation and processed_params is None:
                 final_sql, final_params = processed_sql, processed_params
             elif ast_was_transformed and expression is not None:
-                final_sql = expression.sql(dialect=dialect_str)
-                final_params = final_parameters
-                logger.debug("AST was transformed - final SQL: %s, final params: %s", final_sql, final_params)
-
-                # Apply output transformer if configured
+                final_sql, final_params = self._parameter_processor.process(
+                    sql=expression.sql(dialect=dialect_str),
+                    parameters=final_parameters,
+                    config=self._config.parameter_config,
+                    dialect=dialect_str,
+                    is_many=is_many,
+                )
                 output_transformer = self._config.output_transformer
                 if output_transformer:
                     final_sql, final_params = output_transformer(final_sql, final_params)

sqlspec/driver/_common.py

@@ -275,7 +275,15 @@ class CommonDriverAttributesMixin:
         kwargs = kwargs or {}
 
         if isinstance(statement, QueryBuilder):
-            return statement.to_statement(statement_config)
+            sql_statement = statement.to_statement(statement_config)
+            if parameters or kwargs:
+                merged_parameters = (
+                    (*sql_statement._positional_parameters, *parameters)
+                    if parameters
+                    else sql_statement._positional_parameters
+                )
+                return SQL(sql_statement.sql, *merged_parameters, statement_config=statement_config, **kwargs)
+            return sql_statement
         if isinstance(statement, SQL):
             if parameters or kwargs:
                 merged_parameters = (

sqlspec/loader.py

@@ -14,9 +14,13 @@ from pathlib import Path
 from typing import Any, Optional, Union
 
 from sqlspec.core.cache import CacheKey, get_cache_config, get_default_cache
-from sqlspec.core.parameters import ParameterStyleConfig, ParameterValidator
-from sqlspec.core.statement import SQL, StatementConfig
-from sqlspec.exceptions import SQLFileNotFoundError, SQLFileParseError, StorageOperationFailedError
+from sqlspec.core.statement import SQL
+from sqlspec.exceptions import (
+    MissingDependencyError,
+    SQLFileNotFoundError,
+    SQLFileParseError,
+    StorageOperationFailedError,
+)
 from sqlspec.storage import storage_registry
 from sqlspec.storage.registry import StorageRegistry
 from sqlspec.utils.correlation import CorrelationContext
@@ -29,7 +33,7 @@ logger = get_logger("loader")
 # Matches: -- name: query_name (supports hyphens and special suffixes)
 # We capture the name plus any trailing special characters
 QUERY_NAME_PATTERN = re.compile(r"^\s*--\s*name\s*:\s*([\w-]+[^\w\s]*)\s*$", re.MULTILINE | re.IGNORECASE)
-TRIM_SPECIAL_CHARS = re.compile(r"[^\w-]")
+TRIM_SPECIAL_CHARS = re.compile(r"[^\w.-]")
 
 # Matches: -- dialect: dialect_name (optional dialect specification)
 DIALECT_PATTERN = re.compile(r"^\s*--\s*dialect\s*:\s*(?P<dialect>[a-zA-Z0-9_]+)\s*$", re.IGNORECASE | re.MULTILINE)
@@ -304,6 +308,12 @@ class SQLFileLoader:
             return backend.read_text(path_str, encoding=self.encoding)
         except KeyError as e:
             raise SQLFileNotFoundError(path_str) from e
+        except MissingDependencyError:
+            # Fall back to standard file reading when no storage backend is available
+            try:
+                return path.read_text(encoding=self.encoding)  # type: ignore[union-attr]
+            except FileNotFoundError as e:
+                raise SQLFileNotFoundError(path_str) from e
         except StorageOperationFailedError as e:
             if "not found" in str(e).lower() or "no such file" in str(e).lower():
                 raise SQLFileNotFoundError(path_str) from e
@@ -570,8 +580,11 @@ class SQLFileLoader:
         Raises:
             ValueError: If query name already exists.
         """
-        if name in self._queries:
-            existing_source = self._query_to_file.get(name, "<directly added>")
+        # Normalize the name for consistency with file-loaded queries
+        normalized_name = _normalize_query_name(name)
+
+        if normalized_name in self._queries:
+            existing_source = self._query_to_file.get(normalized_name, "<directly added>")
             msg = f"Query name '{name}' already exists (source: {existing_source})"
             raise ValueError(msg)
 
@@ -588,21 +601,16 @@ class SQLFileLoader:
             else:
                 dialect = normalized_dialect
 
-        statement = NamedStatement(name=name, sql=sql.strip(), dialect=dialect, start_line=0)
-        self._queries[name] = statement
-        self._query_to_file[name] = "<directly added>"
+        statement = NamedStatement(name=normalized_name, sql=sql.strip(), dialect=dialect, start_line=0)
+        self._queries[normalized_name] = statement
+        self._query_to_file[normalized_name] = "<directly added>"
 
-    def get_sql(
-        self, name: str, parameters: "Optional[Any]" = None, dialect: "Optional[str]" = None, **kwargs: "Any"
-    ) -> "SQL":
-        """Get a SQL object by statement name with dialect support.
+    def get_sql(self, name: str) -> "SQL":
+        """Get a SQL object by statement name.
 
         Args:
             name: Name of the statement (from -- name: in SQL file).
                   Hyphens in names are converted to underscores.
-            parameters: Parameters for the SQL statement.
-            dialect: Optional dialect override.
-            **kwargs: Additional parameters to pass to the SQL object.
 
         Returns:
             SQL object ready for execution.
@@ -629,46 +637,11 @@ class SQLFileLoader:
             raise SQLFileNotFoundError(name, path=f"Statement '{name}' not found. Available statements: {available}")
 
         parsed_statement = self._queries[safe_name]
-
-        effective_dialect = dialect or parsed_statement.dialect
-
-        if dialect is not None:
-            normalized_dialect = _normalize_dialect(dialect)
-            if normalized_dialect not in SUPPORTED_DIALECTS:
-                suggestions = _get_dialect_suggestions(normalized_dialect)
-                warning_msg = f"Unknown dialect '{dialect}'"
-                if suggestions:
-                    warning_msg += f". Did you mean: {', '.join(suggestions)}?"
-                warning_msg += f". Supported dialects: {', '.join(sorted(SUPPORTED_DIALECTS))}. Using dialect as-is."
-                logger.warning(warning_msg)
-                effective_dialect = dialect.lower()
-            else:
-                effective_dialect = normalized_dialect
-
-        sql_kwargs = dict(kwargs)
-        if parameters is not None:
-            sql_kwargs["parameters"] = parameters
-
         sqlglot_dialect = None
-        if effective_dialect:
-            sqlglot_dialect = _normalize_dialect_for_sqlglot(effective_dialect)
-
-        if not effective_dialect and "statement_config" not in sql_kwargs:
-            validator = ParameterValidator()
-            param_info = validator.extract_parameters(parsed_statement.sql)
-            if param_info:
-                styles = {p.style for p in param_info}
-                if styles:
-                    detected_style = next(iter(styles))
-                    sql_kwargs["statement_config"] = StatementConfig(
-                        parameter_config=ParameterStyleConfig(
-                            default_parameter_style=detected_style,
-                            supported_parameter_styles=styles,
-                            preserve_parameter_format=True,
-                        )
-                    )
+        if parsed_statement.dialect:
+            sqlglot_dialect = _normalize_dialect_for_sqlglot(parsed_statement.dialect)
 
-        return SQL(parsed_statement.sql, dialect=sqlglot_dialect, **sql_kwargs)
+        return SQL(parsed_statement.sql, dialect=sqlglot_dialect)
 
     def get_file(self, path: Union[str, Path]) -> "Optional[SQLFile]":
         """Get a loaded SQLFile object by path.

sqlspec/storage/registry.py

@@ -151,8 +151,8 @@ class StorageRegistry:
                 return self._create_backend("fsspec", uri, **kwargs)
             except (ValueError, ImportError, NotImplementedError):
                 pass
-        msg = f"No storage backend available for scheme '{scheme}'. Install obstore or fsspec."
-        raise MissingDependencyError(msg)
+        msg = "obstore"
+        raise MissingDependencyError(msg, "fsspec")
 
     def _determine_backend_class(self, uri: str) -> type[ObjectStoreProtocol]:
         """Determine the backend class for a URI based on availability."""