dataface 0.1.2__py3-none-any.whl

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

@@ -0,0 +1,246 @@
+"""Authored query types — YAML input representation.
+
+Stage: COMPILE (Input)
+Purpose: Types that map directly to the YAML query schema.
+
+These live here (separate from face/authored.py) because:
+- Discriminated-union models (face/authored.py) import AuthoredQuery via QueryOrRef.
+- Keeping AuthoredQuery here avoids the discriminated-union module importing itself.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+# ============================================================================
+# QUERY-LEVEL PRIMITIVES (used by both authored and compiled layers)
+# ============================================================================
+
+TimeGrain = Literal["day", "week", "month", "quarter", "year"]
+
+RestMethod = Literal["GET", "POST", "PUT", "DELETE", "PATCH"]
+
+
+# ============================================================================
+# AUTHORED QUERY MODELS
+# ============================================================================
+
+
+class Pivot(BaseModel):
+    """Query-level pivot rendering hint for cross-tab table layout.
+
+    v1 shape: {column: scalar, value: scalar}. Row dims are inferred as all
+    SELECT columns that are neither column nor value. Chart consumers of
+    pivoted queries are unaffected — they receive long-form SQL rows as-is.
+
+    Design tension note: CLAUDE.md principle #6 says "data belongs to queries,
+    not charts." pivot: lives on AuthoredQuery but is consumed only by the table renderer
+    as a visual-encoding hint, not a SQL transformation. This is deliberate for v1
+    to avoid a separate chart-level encoding field. Future readers: pivot: does NOT
+    change the SQL or the rows returned; it only reorders long-form data into
+    wide-form at render time.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    column: str = Field(
+        description="Dimension whose distinct values become column headers in the cross-tab layout."
+    )
+    value: str = Field(
+        description="Measure that fills each cell in the cross-tab layout."
+    )
+
+    @model_validator(mode="after")
+    def _validate(self) -> "Pivot":
+        if not self.column.strip():
+            raise ValueError("pivot.column must not be empty")
+        if not self.value.strip():
+            raise ValueError("pivot.value must not be empty")
+        if self.column == self.value:
+            raise ValueError(
+                f"pivot.column and pivot.value must differ; both are {self.column!r}"
+            )
+        return self
+
+
+class AuthoredQuery(BaseModel):
+    """AuthoredQuery definition from YAML.
+
+    Queries fetch data from various sources. The type field determines
+    which adapter handles execution.
+
+    Supported types:
+    - sql: Raw SQL query (default)
+    - metricflow: dbt Semantic Layer query
+    - dbt_model: Query against a dbt model
+    - http: REST API query
+    - csv: CSV file query
+
+    Example YAML:
+        queries:
+          sales_by_date:
+            sql: SELECT date, SUM(amount) FROM sales GROUP BY date
+            source: my_postgres  # Source reference
+
+          metrics_query:
+            type: metricflow
+            metrics: [revenue, orders]
+            dimensions: [date_day]
+
+          api_data:
+            type: http
+            url: https://api.example.com/data
+    """
+
+    # populate_by_name=True: required for schema_name's alias="schema" to accept
+    # both the YAML key "schema:" and the Python attribute name "schema_name".
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    type: (
+        Literal[
+            "sql", "metricflow", "dbt_model", "http", "csv", "values", "schema_resolver"
+        ]
+        | None
+    ) = Field(
+        default=None,
+        description="Query adapter type. Defaults to 'sql'. Options: sql, metricflow, dbt_model, http, csv, values, schema_resolver.",
+    )
+
+    # Source field - can be a string reference or inline source config
+    source: str | dict[str, Any] | None = Field(
+        default=None,
+        description="Database source reference (name string) or inline source config dict.",
+    )
+    target: str | None = Field(
+        default=None,
+        description="dbt target name for dbt_model queries (defaults to 'dev').",
+    )
+
+    # SQL fields
+    sql: str | None = Field(
+        default=None,
+        description="SQL query string. Supports Jinja2 templates referencing variables.",
+    )
+    setup_sql: str | None = Field(
+        default=None,
+        description="Non-nestable SQL preamble executed before the main query (e.g., CREATE TEMP FUNCTION).",
+    )
+
+    # MetricFlow fields
+    metrics: list[str] | None = Field(
+        default=None,
+        description="MetricFlow metric names to query.",
+    )
+    dimensions: list[str] | None = Field(
+        default=None,
+        description="MetricFlow dimensions to include in the result.",
+    )
+    time_grain: TimeGrain | None = Field(
+        default=None,
+        description="MetricFlow time grain for time-series dimensions (day, week, month, quarter, year).",
+    )
+
+    # dbt model fields
+    model: str | None = Field(
+        default=None,
+        description="dbt model name to query directly.",
+    )
+    columns: list[str] | None = Field(
+        default=None,
+        description="Column subset to select from the dbt model.",
+    )
+
+    # HTTP fields
+    url: str | None = Field(
+        default=None,
+        description="HTTP endpoint URL for REST API queries.",
+    )
+    method: RestMethod | None = Field(
+        default=None,
+        description="HTTP method for REST API queries (GET, POST, PUT, DELETE, PATCH).",
+    )
+    headers: dict[str, str] | None = Field(
+        default=None,
+        description="HTTP request headers for REST API queries.",
+    )
+    params: dict[str, Any] | None = Field(
+        default=None,
+        description="HTTP query string parameters for REST API queries.",
+    )
+    body: dict[str, Any] | str | None = Field(
+        default=None,
+        description="HTTP request body for POST/PUT queries.",
+    )
+    json_path: str | None = Field(
+        default=None,
+        description="JSONPath expression to extract tabular data from HTTP response (http queries only).",
+    )
+
+    # CSV fields
+    file: str | None = Field(
+        default=None,
+        description="Path to a CSV file for csv-type queries.",
+    )
+    filter: dict[str, Any] | None = Field(
+        default=None,
+        description="Row-level filter applied to CSV or values data.",
+    )
+    delimiter: str | None = Field(
+        default=None,
+        description="Column delimiter for CSV queries. Default: comma (',').",
+    )
+    encoding: str | None = Field(
+        default=None,
+        description="File encoding for CSV queries. Default: UTF-8.",
+    )
+
+    # schema_resolver fields
+    # alias="schema" so YAML authors write `schema: analytics`; Python code uses
+    # schema_name to avoid shadowing BaseModel.schema (a Pydantic v2 legacy classmethod).
+    schema_name: str | None = Field(
+        default=None,
+        alias="schema",
+        description="Schema name for schema_resolver queries (YAML key: schema).",
+    )
+    table: str | None = Field(
+        default=None,
+        description="Table name for schema_resolver queries.",
+    )
+    column: str | None = Field(
+        default=None,
+        description="Column name for schema_resolver queries.",
+    )
+
+    # Values fields (inline data)
+    rows: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Inline data rows for values-type queries (list of row dicts).",
+    )
+    values: list[list[Any]] | None = Field(
+        default=None,
+        description="Inline column-oriented data for values-type queries (list of lists).",
+    )
+
+    # Common fields
+    description: str | None = Field(
+        default=None,
+        description="Human-readable description of the query. Used by AI search and tooling.",
+    )
+    filters: dict[str, Any] | None = Field(
+        default=None,
+        description="Jinja2 filter expressions applied to query results.",
+    )
+    limit: int | None = Field(
+        default=None,
+        description="Maximum number of rows returned.",
+    )
+
+    pivot: Pivot | None = Field(
+        default=None,
+        description="Cross-tab pivot hint: transforms long-form SQL output into a wide table at render time (table consumers only). Does not affect SQL execution.",
+    )
+
+    ignore: list[str] | None = Field(
+        default=None,
+        description="Diagnostic codes to suppress for this query (e.g., ['fanout_risk', 'reaggregation']).",
+    )