dataface 0.1.2__py3-none-any.whl

dataface/core/compile/models/query/compiled.py

@@ -0,0 +1,710 @@
+"""Unified query interface types — compiled representation.
+
+Stage: COMPILE (Output) / EXECUTE (Input)
+Purpose: Define type-safe query classes with a unified interface.
+
+This module implements the unified query interface pattern where:
+- All queries inherit from a common Query base class
+- Each query type has its own class with type-specific fields
+- Type guards enable type-safe narrowing in adapter code
+- The interface makes adapter routing clear and type-safe
+
+Benefits:
+- Type safety: Compile-time verification of query fields
+- Self-documenting: Each query class shows exactly which fields apply
+- Extensibility: Adding new query types is isolated
+- IDE support: Autocomplete and refactoring work correctly
+
+Dependencies:
+    - pydantic (BaseModel)
+    - abc (ABC, abstractmethod)
+
+See also:
+    - execute/adapters/base.py: Adapters consume these types
+"""
+
+import hashlib
+import json
+from abc import ABC, abstractmethod
+from typing import Any, TypeGuard
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from dataface.core.compile.models.query.authored import Pivot, RestMethod, TimeGrain
+
+# Note: source field can be a string reference or inline Dict config
+
+
+# ============================================================================
+# BASE QUERY CLASS
+# ============================================================================
+
+
+class Query(BaseModel, ABC):
+    """Base query interface - all queries return tabular data.
+
+    This abstract base class defines the common interface for all query types.
+    Subclasses must implement query_type and source_description properties.
+
+    Common Fields (available on all queries):
+        filters: Optional filter conditions to apply to results
+        limit: Optional maximum number of rows to return
+
+    Abstract Properties:
+        query_type: Type identifier for adapter routing (e.g., "sql", "csv")
+        source_description: Human-readable description of data source
+
+    Example:
+        >>> class CustomQuery(Query):
+        ...     custom_field: str
+        ...
+        ...     @property
+        ...     def query_type(self) -> str:
+        ...         return "custom"
+        ...
+        ...     @property
+        ...     def source_description(self) -> str:
+        ...         return f"Custom: {self.custom_field}"
+    """
+
+    # Common fields all queries can have
+    description: str | None = Field(
+        default=None, description="Human-readable description of this query."
+    )
+    filters: dict[str, Any] | None = Field(
+        default=None, description="Filter conditions applied to query results."
+    )
+    limit: int | None = Field(
+        default=None, description="Maximum number of rows to return."
+    )
+
+    # Query-level pivot rendering hint.
+    # Note: pivot is a table-renderer hint (cross-tab layout), not a SQL transformation.
+    # Chart consumers receive long-form rows; only render_table_svg consumes this field.
+    # This lives on the compiled Query base (not just types.Query) so it survives
+    # normalize_query's model_dump → SqlQuery(**dict) round-trip.
+    pivot: Pivot | None = Field(
+        default=None,
+        description="Cross-tab pivot hint: column values become headers, value fills cells.",
+    )
+
+    # Diagnostic suppression — list of diagnostic codes to suppress
+    ignore: list[str] | None = Field(
+        default=None,
+        description="Diagnostic codes to suppress (e.g., ['fanout_risk', 'reaggregation']).",
+    )
+
+    # Variable dependencies - computed during normalization
+    variable_dependencies: set[str] = Field(
+        default_factory=set,
+        description="Variable names this query references in SQL/filters (computed during normalization).",
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+    @property
+    @abstractmethod
+    def query_type(self) -> str:
+        """Type identifier for adapter routing.
+
+        Returns:
+            String identifying the query type (e.g., "sql", "csv", "http")
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def source_description(self) -> str:
+        """Human-readable description of data source.
+
+        Returns:
+            String describing the data source for debugging/logging
+        """
+        pass
+
+    def apply_limit(self, data: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Apply limit to result data.
+
+        Args:
+            data: Query results as list of dicts
+
+        Returns:
+            Possibly truncated list of dicts
+        """
+        if self.limit and self.limit > 0:
+            return data[: self.limit]
+        return data
+
+
+# ============================================================================
+# TYPE-SPECIFIC QUERY CLASSES
+# ============================================================================
+
+
+class SqlQuery(Query):
+    """SQL query against a database.
+
+    Executes raw SQL against the configured database connection.
+    Supports Jinja templating for variable substitution.
+
+    Required Fields:
+        sql: SQL query string (may contain Jinja templates)
+
+    Connection Fields (one required):
+        source: Source name or inline config
+
+    Optional Fields:
+        target: dbt target name (defaults to 'dev' if not specified)
+
+    Example:
+        >>> query = SqlQuery(
+        ...     sql="SELECT * FROM users WHERE id = {{ user_id }}",
+        ...     source="my_postgres"
+        ... )
+        >>> query.query_type  # "sql"
+        >>> query.source_description  # "SQL: SELECT * FROM users WHERE id = {{ user_..."
+    """
+
+    sql: str = Field(
+        description="SQL query string. May contain Jinja templates (e.g., {{ variable_name }})."
+    )
+    setup_sql: str | None = Field(
+        default=None,
+        description="Non-nestable SQL preamble (e.g., CREATE TEMP FUNCTION). Runs before the main query.",
+    )
+    # Connection configuration
+    source: str | dict[str, Any] | None = Field(
+        default=None,
+        description="Source name or inline source config dict for the database connection.",
+    )
+    target: str | None = Field(
+        default=None,
+        description="dbt target name (defaults to 'dev' if not specified).",
+    )
+
+    @property
+    def query_type(self) -> str:
+        """Return 'sql' as query type."""
+        return "sql"
+
+    @property
+    def source_description(self) -> str:
+        """Return truncated SQL for description."""
+        sql_preview = self.sql[:50] if len(self.sql) > 50 else self.sql
+        return f"SQL: {sql_preview}..."
+
+
+class CsvQuery(Query):
+    """Query data from a CSV file.
+
+    Loads and queries data from CSV files. Supports column selection,
+    filtering, and limiting results.
+
+    Fields (one required):
+        file: Path to CSV file (relative to project root or absolute)
+        source: Source reference or inline CSV source config
+
+    Optional Fields:
+        columns: List of columns to select (default: all)
+        filter: Dict of column->value for exact match filtering
+
+    Example:
+        >>> query = CsvQuery(file="data/sales.csv", columns=["date", "amount"])
+        >>> query.query_type  # "csv"
+        >>> query.source_description  # "CSV: data/sales.csv"
+    """
+
+    file: str | None = Field(
+        default=None,
+        description="Path to CSV file (relative to project root or absolute). Use 'source' for named sources.",
+    )
+    source: str | dict[str, Any] | None = Field(
+        default=None, description="Source name or inline CSV source config dict."
+    )
+    columns: list[str] | None = Field(
+        default=None, description="List of columns to select. Default: all columns."
+    )
+    filter: dict[str, Any] | None = Field(
+        default=None, description="Dict of column->value for exact match row filtering."
+    )
+    # Additional CSV options
+    delimiter: str | None = Field(
+        default=None, description="Column delimiter character. Default: comma (',')."
+    )
+    encoding: str | None = Field(
+        default=None, description="File encoding. Default: UTF-8."
+    )
+
+    @property
+    def query_type(self) -> str:
+        """Return 'csv' as query type."""
+        return "csv"
+
+    @property
+    def source_description(self) -> str:
+        """Return file path for description."""
+        if self.file:
+            return f"CSV: {self.file}"
+        elif isinstance(self.source, str):
+            return f"CSV source: {self.source}"
+        elif isinstance(self.source, dict) and "file" in self.source:
+            return f"CSV: {self.source['file']}"
+        return "CSV query"
+
+    @property
+    def effective_file(self) -> str | None:
+        """Get effective file path from file or source config."""
+        if self.file:
+            return self.file
+        if isinstance(self.source, dict) and "file" in self.source:
+            return self.source["file"]
+        return None
+
+
+class MetricFlowQuery(Query):
+    """Query the dbt Semantic Layer.
+
+    Executes queries against dbt's Semantic Layer using MetricFlow.
+    Supports metrics, dimensions, filters, and time grains.
+
+    Required Fields:
+        metrics: List of metric names to query
+
+    Optional Fields:
+        dimensions: List of dimension names to group by
+        time_grain: Time grain for time-based dimensions (day, week, month, etc.)
+
+    Example:
+        >>> query = MetricFlowQuery(
+        ...     metrics=["revenue", "orders"],
+        ...     dimensions=["date_day", "region"]
+        ... )
+        >>> query.query_type  # "metricflow"
+        >>> query.source_description  # "MetricFlow: revenue, orders"
+    """
+
+    metrics: list[str] = Field(
+        description="Metric names to query from the dbt Semantic Layer."
+    )
+    dimensions: list[str] | None = Field(
+        default=None,
+        description="Dimension names to group by (e.g., 'date_day', 'region').",
+    )
+    time_grain: TimeGrain | None = Field(
+        default=None,
+        description="Time grain for time-based dimensions (day, week, month, quarter, year).",
+    )
+    source: str | dict[str, Any] | None = Field(
+        default=None, description="Source name or inline MetricFlow source config."
+    )
+
+    @property
+    def query_type(self) -> str:
+        """Return 'metricflow' as query type."""
+        return "metricflow"
+
+    @property
+    def source_description(self) -> str:
+        """Return metrics list for description."""
+        return f"MetricFlow: {', '.join(self.metrics)}"
+
+
+class HttpQuery(Query):
+    """Query data from an HTTP API.
+
+    Fetches data from REST API endpoints. Supports various HTTP methods,
+    headers, query parameters, and request bodies.
+
+    Required Fields:
+        url: Full URL of the API endpoint
+
+    Optional Fields:
+        method: HTTP method (default: GET)
+        headers: Request headers
+        params: Query parameters
+        body: Request body (for POST/PUT/PATCH)
+        json_path: JSONPath expression to extract data from response
+
+    Example:
+        >>> query = HttpQuery(
+        ...     url="https://api.example.com/predict",
+        ...     method="POST",
+        ...     body={"input": "data"}
+        ... )
+        >>> query.query_type  # "http"
+        >>> query.source_description  # "HTTP: POST https://api.example.com/predict"
+    """
+
+    url: str = Field(
+        description="Full URL of the HTTP endpoint.",
+    )
+    method: RestMethod = Field(
+        default="GET",
+        description="HTTP method (GET, POST, PUT, DELETE, PATCH). Default: GET.",
+    )
+    headers: dict[str, str] | None = Field(
+        default=None, description="Request headers (merged with source-level headers)."
+    )
+    params: dict[str, Any] | None = Field(
+        default=None, description="URL query parameters."
+    )
+    body: dict[str, Any] | str | None = Field(
+        default=None,
+        description="Request body for POST/PUT/PATCH (dict or JSON string).",
+    )
+    json_path: str | None = Field(
+        default=None,
+        description="JSONPath expression to extract tabular data from the response.",
+    )
+
+    @property
+    def query_type(self) -> str:
+        """Return 'http' as query type."""
+        return "http"
+
+    @property
+    def source_description(self) -> str:
+        """Return method and URL for description."""
+        return f"HTTP: {self.method} {self.url}"
+
+
+class ValuesQuery(Query):
+    """Inline data query with rows embedded directly in the YAML.
+
+    Provides two syntaxes:
+    1. Dict rows (verbose): rows: [{month: "Jan", revenue: 100}, ...]
+    2. Columns + values (compact, SQL-style): columns: [month, revenue], values: [["Jan", 100], ...]
+
+    When using columns + values, rows are computed automatically via model_post_init.
+
+    Example (dict rows):
+        >>> query = ValuesQuery(rows=[{"month": "Jan", "revenue": 100}])
+
+    Example (columns + values):
+        >>> query = ValuesQuery(
+        ...     columns=["month", "revenue"],
+        ...     values=[["Jan", 100], ["Feb", 140]],
+        ... )
+        >>> query.rows  # [{"month": "Jan", "revenue": 100}, {"month": "Feb", "revenue": 140}]
+    """
+
+    rows: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Inline data rows as a list of dicts (e.g., [{month: 'Jan', revenue: 100}]).",
+    )
+    columns: list[str] | None = Field(
+        default=None, description="Column names for compact 'columns + values' syntax."
+    )
+    values: list[list[Any]] | None = Field(
+        default=None,
+        description="Row values for compact syntax, parallel to 'columns' (e.g., [['Jan', 100], ['Feb', 140]]).",
+    )
+
+    def model_post_init(self, _context: Any) -> None:
+        """Build rows from columns + values if provided."""
+        if self.columns and self.values is not None and not self.rows:
+            ncols = len(self.columns)
+            for i, row in enumerate(self.values):
+                if len(row) != ncols:
+                    raise ValueError(
+                        f"Values row {i} has {len(row)} items, "
+                        f"expected {ncols} (columns: {self.columns})"
+                    )
+            self.rows = [
+                dict(zip(self.columns, row, strict=True)) for row in self.values
+            ]
+
+    @property
+    def query_type(self) -> str:
+        """Return 'values' as query type."""
+        return "values"
+
+    @property
+    def source_description(self) -> str:
+        """Return content-based description for caching.
+
+        Includes a hash of actual row data so that distinct ValuesQuery
+        instances with the same row count produce different cache keys.
+        Cached after first computation since rows are set once in model_post_init.
+        """
+        if not hasattr(self, "_cached_source_description"):
+            n = len(self.rows)
+            content_hash = hashlib.sha256(
+                json.dumps(self.rows, sort_keys=True, default=str).encode()
+            ).hexdigest()[:12]
+            object.__setattr__(
+                self,
+                "_cached_source_description",
+                f"Values: {n} {'row' if n == 1 else 'rows'} [{content_hash}]",
+            )
+        return self._cached_source_description  # type: ignore[attr-defined]
+
+
+class DbtModelQuery(Query):
+    """Query against a dbt model.
+
+    Executes queries against a dbt model, using the model's compiled SQL
+    or the model's relation name for direct querying.
+
+    Required Fields:
+        model: Name of the dbt model
+
+    Optional Fields:
+        columns: List of columns to select (default: all)
+
+    Example:
+        >>> query = DbtModelQuery(model="stg_customers", columns=["id", "name"])
+        >>> query.query_type  # "dbt_model"
+        >>> query.source_description  # "dbt Model: stg_customers"
+    """
+
+    model: str = Field(
+        description="Name of the dbt model to query (e.g., 'stg_customers', 'fct_orders')."
+    )
+    columns: list[str] | None = Field(
+        default=None,
+        description="Columns to select from the model. Default: all columns.",
+    )
+
+    @property
+    def query_type(self) -> str:
+        """Return 'dbt_model' as query type."""
+        return "dbt_model"
+
+    @property
+    def source_description(self) -> str:
+        """Return model name for description."""
+        return f"dbt Model: {self.model}"
+
+
+class SchemaResolverQuery(Query):
+    """Query the LayeredSchemaResolver in-process.
+
+    Dispatches to list_schemas / list_tables / profile_table / profile_column
+    based on which optional fields are populated:
+    - source only → list_schemas(source)
+    - source + schema → list_tables(source, schema)
+    - source + schema + table → profile_table(source, schema, table) → column rows
+    - source + schema + table + column → profile_column(source, schema, table, column)
+
+    Note: The YAML field is ``schema`` but the Python attribute is ``schema_name``
+    to avoid shadowing ``BaseModel.schema`` (a Pydantic v2 legacy classmethod).
+
+    Fields must be literal strings — Jinja templates (``{{``, ``{%``, ``{#``)
+    are rejected at model construction time.  Field prerequisites are also
+    validated at construction time: ``table`` requires ``schema``; ``column``
+    requires both ``schema`` and ``table``.
+    """
+
+    source: str = Field(description="dbt source name to query.")
+    # alias="schema" so YAML authors write `schema: analytics`; Python code uses
+    # query.schema_name to avoid the BaseModel.schema classmethod conflict.
+    schema_name: str | None = Field(
+        default=None, alias="schema", description="Schema name (omit to list schemas)."
+    )
+    table: str | None = Field(
+        default=None, description="Table name (omit to list tables)."
+    )
+    column: str | None = Field(
+        default=None, description="Column name (omit for full table profile)."
+    )
+
+    # populate_by_name=True: 'schema' is a Pydantic BaseModel class method name
+    # (BaseModel.schema() in v1 / model_json_schema() in v2), so using it as a
+    # field name directly would shadow the classmethod. The Python field is
+    # `schema_name`; YAML authors write `schema:` and the alias bridges the two.
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    @field_validator("source", "schema_name", "table", "column", mode="before")
+    @classmethod
+    def _no_jinja(cls, v: Any) -> Any:
+        if isinstance(v, str) and any(tok in v for tok in ("{{", "{%", "{#")):
+            raise ValueError(
+                "schema_resolver fields must be literal strings; "
+                "Jinja templates ({{ }}, {% %}, {# #}) are not supported."
+            )
+        return v
+
+    @model_validator(mode="after")
+    def _field_prerequisites(self) -> "SchemaResolverQuery":
+        if self.table is not None and self.schema_name is None:
+            raise ValueError("schema_resolver: 'table' requires 'schema' to be set")
+        if self.column is not None and self.table is None:
+            raise ValueError(
+                "schema_resolver: 'column' requires 'table' (and 'schema') to be set"
+            )
+        return self
+
+    @property
+    def query_type(self) -> str:
+        return "schema_resolver"
+
+    @property
+    def source_description(self) -> str:
+        parts = [self.source]
+        if self.schema_name:
+            parts.append(self.schema_name)
+        if self.table:
+            parts.append(self.table)
+        if self.column:
+            parts.append(self.column)
+        return f"schema_resolver: {'.'.join(parts)}"
+
+
+# ============================================================================
+# TYPE ALIASES
+# ============================================================================
+
+
+# Type alias for any query - union of all query types
+# Use this for type annotations when you want to accept any query type
+AnyQuery = (
+    SqlQuery
+    | CsvQuery
+    | MetricFlowQuery
+    | HttpQuery
+    | DbtModelQuery
+    | ValuesQuery
+    | SchemaResolverQuery
+)
+
+
+# Set of valid query type strings
+VALID_QUERY_TYPES: set[str] = {
+    "sql",
+    "csv",
+    "metricflow",
+    "http",
+    "dbt_model",
+    "values",
+    "schema_resolver",
+}
+
+
+# ============================================================================
+# TYPE GUARDS
+# ============================================================================
+
+
+def is_sql_query(query: AnyQuery) -> TypeGuard[SqlQuery]:
+    """Type guard for SQL queries.
+
+    Use this for type-safe narrowing in conditional blocks.
+    After this check, the type checker knows the query is SqlQuery.
+
+    Args:
+        query: Any compiled query
+
+    Returns:
+        True if query is a SqlQuery
+
+    Example:
+        >>> if is_sql_query(query):
+        ...     # Type checker knows query.sql exists
+        ...     print(query.sql)
+    """
+    return query.query_type == "sql"
+
+
+def is_csv_query(query: AnyQuery) -> TypeGuard[CsvQuery]:
+    """Type guard for CSV queries.
+
+    Use this for type-safe narrowing in conditional blocks.
+    After this check, the type checker knows the query is CsvQuery.
+
+    Args:
+        query: Any compiled query
+
+    Returns:
+        True if query is a CsvQuery
+
+    Example:
+        >>> if is_csv_query(query):
+        ...     # Type checker knows query.file exists
+        ...     print(query.file)
+    """
+    return query.query_type == "csv"
+
+
+def is_metricflow_query(query: AnyQuery) -> TypeGuard[MetricFlowQuery]:
+    """Type guard for MetricFlow queries.
+
+    Use this for type-safe narrowing in conditional blocks.
+    After this check, the type checker knows the query is MetricFlowQuery.
+
+    Args:
+        query: Any compiled query
+
+    Returns:
+        True if query is a MetricFlowQuery
+
+    Example:
+        >>> if is_metricflow_query(query):
+        ...     # Type checker knows query.metrics exists
+        ...     print(query.metrics)
+    """
+    return query.query_type == "metricflow"
+
+
+def is_http_query(query: AnyQuery) -> TypeGuard[HttpQuery]:
+    """Type guard for HTTP queries.
+
+    Use this for type-safe narrowing in conditional blocks.
+    After this check, the type checker knows the query is HttpQuery.
+
+    Args:
+        query: Any compiled query
+
+    Returns:
+        True if query is a HttpQuery
+
+    Example:
+        >>> if is_http_query(query):
+        ...     # Type checker knows query.url exists
+        ...     print(query.url)
+    """
+    return query.query_type == "http"
+
+
+def is_dbt_model_query(query: AnyQuery) -> TypeGuard[DbtModelQuery]:
+    """Type guard for dbt model queries.
+
+    Use this for type-safe narrowing in conditional blocks.
+    After this check, the type checker knows the query is DbtModelQuery.
+
+    Args:
+        query: Any compiled query
+
+    Returns:
+        True if query is a DbtModelQuery
+
+    Example:
+        >>> if is_dbt_model_query(query):
+        ...     # Type checker knows query.model exists
+        ...     print(query.model)
+    """
+    return query.query_type == "dbt_model"
+
+
+def is_values_query(query: AnyQuery) -> TypeGuard[ValuesQuery]:
+    """Type guard for values queries.
+
+    Args:
+        query: Any compiled query
+
+    Returns:
+        True if query is a ValuesQuery
+    """
+    return query.query_type == "values"
+
+
+def is_schema_resolver_query(query: AnyQuery) -> TypeGuard[SchemaResolverQuery]:
+    """Type guard for schema resolver queries.
+
+    Args:
+        query: Any compiled query
+
+    Returns:
+        True if query is a SchemaResolverQuery
+    """
+    return query.query_type == "schema_resolver"