semql 0.1.0__py3-none-any.whl

semql/__init__.py

@@ -0,0 +1,153 @@
+"""Public surface of the semantic layer.
+
+Most users only need ``Catalog``, ``Cube``, the field types
+(``Measure`` / ``Dimension`` / ``TimeDimension``), and
+``SemanticQuery``. The rest is exported for callers building their own
+tooling on top of the compiler (custom validators, MCP servers,
+prompt rendering, etc.).
+"""
+
+from __future__ import annotations
+
+from semql.catalog import Catalog
+from semql.compile import MAX_UNGROUPED_ROWS, Compiled, compile_query
+from semql.docs import render_catalog_markdown
+from semql.errors import (
+    CompileError,
+    CrossBackendError,
+    FilterTypeError,
+    JoinPathError,
+    PhaseDeferredError,
+    PlaceholderError,
+    ResolveError,
+    SemQLError,
+    UnknownIdentifierError,
+)
+from semql.introspect import (
+    CATALOG_CUBES,
+    CATALOG_DIMENSIONS,
+    CATALOG_MEASURES,
+    META_CUBES,
+    ResolvedQuery,
+    iter_cubes,
+    iter_fields,
+    iter_joins,
+    resolve_field,
+    resolve_query,
+)
+from semql.model import (
+    AggLiteral,
+    AuthContext,
+    Backend,
+    BaseField,
+    ChartTypeLiteral,
+    Cube,
+    Dimension,
+    DimTypeLiteral,
+    FormatLiteral,
+    GranularityLiteral,
+    Join,
+    Measure,
+    ScopePredicate,
+    Segment,
+    TimeDimension,
+    View,
+)
+from semql.plan import (
+    DrilldownSuggestion,
+    DrilldownSuggestions,
+    Presentation,
+    QueryIntent,
+    QueryPlan,
+    QueryStep,
+    RouterDecision,
+    RouterPath,
+)
+from semql.prompt import (
+    build_drilldown_prompt_fragment,
+    build_planner_prompt_fragment,
+    build_presenter_prompt_fragment,
+    build_query_generator_prompt_fragment,
+    build_router_prompt_fragment,
+    render_catalogue_block,
+)
+from semql.safe import is_safe_select
+from semql.spec import (
+    BoolExpr,
+    CompareWindow,
+    Filter,
+    FilterOp,
+    SemanticQuery,
+    TimeWindow,
+)
+from semql.validate import ValidationError, validate
+from semql.visualize import VizColumn, VizDecision, decide_visualization
+
+__all__ = [
+    "AggLiteral",
+    "AuthContext",
+    "Backend",
+    "BaseField",
+    "BoolExpr",
+    "CATALOG_CUBES",
+    "CATALOG_DIMENSIONS",
+    "CATALOG_MEASURES",
+    "Catalog",
+    "ChartTypeLiteral",
+    "CompareWindow",
+    "CompileError",
+    "Compiled",
+    "CrossBackendError",
+    "Cube",
+    "DimTypeLiteral",
+    "Dimension",
+    "DrilldownSuggestion",
+    "DrilldownSuggestions",
+    "Filter",
+    "FilterOp",
+    "FilterTypeError",
+    "FormatLiteral",
+    "GranularityLiteral",
+    "Join",
+    "JoinPathError",
+    "MAX_UNGROUPED_ROWS",
+    "META_CUBES",
+    "Measure",
+    "PhaseDeferredError",
+    "PlaceholderError",
+    "Presentation",
+    "QueryIntent",
+    "QueryPlan",
+    "QueryStep",
+    "ResolveError",
+    "ResolvedQuery",
+    "RouterDecision",
+    "RouterPath",
+    "ScopePredicate",
+    "Segment",
+    "SemQLError",
+    "SemanticQuery",
+    "TimeDimension",
+    "TimeWindow",
+    "UnknownIdentifierError",
+    "ValidationError",
+    "View",
+    "VizColumn",
+    "VizDecision",
+    "build_drilldown_prompt_fragment",
+    "build_planner_prompt_fragment",
+    "build_presenter_prompt_fragment",
+    "build_query_generator_prompt_fragment",
+    "build_router_prompt_fragment",
+    "compile_query",
+    "decide_visualization",
+    "is_safe_select",
+    "iter_cubes",
+    "iter_fields",
+    "iter_joins",
+    "render_catalog_markdown",
+    "render_catalogue_block",
+    "resolve_field",
+    "resolve_query",
+    "validate",
+]

semql/__main__.py

@@ -0,0 +1,110 @@
+"""``python -m semql.compile``  CLI.
+
+Compiles a ``SemanticQuery`` JSON spec against a Catalog declared
+in a Python module and prints the SQL + params to stdout. Useful
+for ad-hoc cube authoring (no need to write a runner script) and
+as a smoke target in CI.
+
+    python -m semql.compile --catalog mypkg.catalogs:default \\
+        '{"measures": ["orders.revenue"], "dimensions": ["orders.region"]}'
+
+The ``--catalog`` arg is ``module.path:attr`` — the module is
+imported, the named attribute must be a ``Catalog`` instance.
+Context substitutions for ``{schema}`` / ``{tenant}`` placeholders
+go through repeated ``--context key=value`` flags.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import sys
+from typing import Any
+
+from semql import Catalog, SemanticQuery
+
+
+def _load_catalog(spec: str) -> Catalog:
+    """Resolve ``module.path:attr`` into the named ``Catalog``."""
+    if ":" not in spec:
+        raise SystemExit(
+            f"--catalog must be 'module.path:attr', got {spec!r}. "
+            "Example: --catalog mypkg.catalogs:default"
+        )
+    module_path, attr = spec.rsplit(":", 1)
+    try:
+        module = importlib.import_module(module_path)
+    except ModuleNotFoundError as exc:
+        raise SystemExit(f"Could not import {module_path!r}: {exc}") from exc
+    try:
+        catalog = getattr(module, attr)
+    except AttributeError as exc:
+        raise SystemExit(f"Module {module_path!r} has no attribute {attr!r}.") from exc
+    if not isinstance(catalog, Catalog):
+        raise SystemExit(f"{spec!r} resolved to {type(catalog).__name__}, not semql.Catalog.")
+    return catalog
+
+
+def _parse_context(pairs: list[str]) -> dict[str, str]:
+    """Parse repeated ``--context key=value`` flags into a dict."""
+    out: dict[str, str] = {}
+    for pair in pairs:
+        if "=" not in pair:
+            raise SystemExit(f"--context expects key=value, got {pair!r}.")
+        k, v = pair.split("=", 1)
+        out[k] = v
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m semql.compile",
+        description="Compile a SemanticQuery JSON spec to SQL.",
+    )
+    parser.add_argument(
+        "--catalog",
+        required=True,
+        help="Catalog locator: module.path:attr (e.g. mypkg.catalogs:default).",
+    )
+    parser.add_argument(
+        "--context",
+        action="append",
+        default=[],
+        help="Compile-time context pair (key=value). May be repeated.",
+    )
+    parser.add_argument(
+        "--params-format",
+        choices=("comment", "json"),
+        default="comment",
+        help="How to print the params: as a SQL comment (default) or a JSON line.",
+    )
+    parser.add_argument(
+        "spec",
+        help="SemanticQuery as a JSON string. Use '-' to read from stdin.",
+    )
+    args = parser.parse_args(argv)
+
+    raw_spec = sys.stdin.read() if args.spec == "-" else args.spec
+    try:
+        spec_dict: dict[str, Any] = json.loads(raw_spec)
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"--spec must be JSON: {exc}") from exc
+    query = SemanticQuery.model_validate(spec_dict)
+
+    catalog = _load_catalog(args.catalog)
+    ctx = _parse_context(args.context)
+
+    compiled = catalog.compile(query, context=ctx)
+
+    print(compiled.sql)
+    if args.params_format == "json":
+        print(json.dumps(compiled.params, default=str))
+    else:
+        print(f"-- params: {json.dumps(compiled.params, default=str)}")
+        print(f"-- columns: {compiled.columns}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

semql/_resolve.py

@@ -0,0 +1,63 @@
+"""Shared identifier resolution for the semantic layer.
+
+Both `compile.py` and `visualize.py` parse the planner's `cube.field`
+references against the catalogue. Keeping a single resolver here makes
+the validation, regex shape, and error class consistent across both
+modules.
+"""
+
+from __future__ import annotations
+
+import re
+
+from semql.errors import ResolveError, UnknownIdentifierError, closest_match
+from semql.model import Cube, Dimension, Measure, TimeDimension
+
+_QUALIFIED_RE = re.compile(r"^([a-z_][a-z0-9_]*)\.([a-z_][a-z0-9_]*)$", re.IGNORECASE)
+
+
+def split(qualified: str) -> tuple[str, str]:
+    m = _QUALIFIED_RE.match(qualified)
+    if not m:
+        raise ResolveError(f"Field reference must be 'cube.field', got: {qualified!r}")
+    return m.group(1), m.group(2)
+
+
+def resolve_field(
+    qualified: str,
+    catalog: dict[str, Cube],
+) -> tuple[Cube, Measure | Dimension | TimeDimension]:
+    cube_name, field_name = split(qualified)
+    if cube_name not in catalog:
+        hint = closest_match(cube_name, catalog.keys())
+        known = ", ".join(sorted(catalog))
+        suffix = f" Did you mean {hint!r}?" if hint else ""
+        raise UnknownIdentifierError(
+            f"Unknown cube: {cube_name!r}. Known cubes: {known}.{suffix}",
+            kind="cube",
+            name=cube_name,
+            hint=hint,
+        )
+    cube = catalog[cube_name]
+    for m in cube.measures:
+        if m.name == field_name:
+            return cube, m
+    for d in cube.dimensions:
+        if d.name == field_name:
+            return cube, d
+    for td in cube.time_dimensions:
+        if td.name == field_name:
+            return cube, td
+    hint = closest_match(field_name, cube.field_names())
+    known = ", ".join(sorted(cube.field_names()))
+    suffix = f" Did you mean {hint!r}?" if hint else ""
+    raise UnknownIdentifierError(
+        f"Unknown field {field_name!r} on cube {cube_name!r}. Known fields: {known}.{suffix}",
+        kind="field",
+        name=field_name,
+        cube=cube_name,
+        hint=hint,
+    )
+
+
+__all__ = ["ResolveError", "UnknownIdentifierError", "split", "resolve_field"]