nl2sql-engine 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

nl2sql/__init__.py

@@ -1,7 +1,15 @@
 # nl2sql package
 
+import importlib
+
 from .public_api import NL2SQL, QueryResult
 
+# The shapes a client renders and the hooks an application entry point needs,
+# so REST and SDK clients never import engine submodules.
+from .api.query_api import SubQueryResult, RowSample
+from .services.callbacks.token_handler import QuestionUsage
+from .common.logger import configure_logging
+
 # Also expose individual API modules for more granular access
 from .api.query_api import QueryAPI
 from .api.datasource_api import DatasourceAPI
@@ -9,14 +17,26 @@ from .api.llm_api import LLM_API
 from .api.indexing_api import IndexingAPI
 from .api.auth_api import AuthAPI
 from .api.settings_api import SettingsAPI
-from .api.result_api import ResultAPI
 from .api.policy_api import PolicyAPI
-from .api.benchmark_api import BenchmarkAPI
 
 # Also expose core models and enums
 from .common.errors import ErrorSeverity, ErrorCode, PipelineError
+from .common.cancellation import CancellationToken
 from .auth.models import UserContext
-from .evaluation.types import BenchmarkConfig
+
+# The benchmark lives in nl2sql.evaluation, which the runtime never needs, so
+# its names are imported only when first asked for.
+_LAZY = {
+    "BenchmarkAPI": "nl2sql.api.benchmark_api",
+    "BenchmarkConfig": "nl2sql.evaluation.types",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY:
+        return getattr(importlib.import_module(_LAZY[name]), name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
 
 __all__ = [
     "NL2SQL",
@@ -27,12 +47,16 @@ __all__ = [
     "IndexingAPI",
     "AuthAPI",
     "SettingsAPI",
-    "ResultAPI",
     "PolicyAPI",
     "BenchmarkAPI",
     "ErrorSeverity",
     "ErrorCode",
     "PipelineError",
+    "CancellationToken",
     "UserContext",
+    "SubQueryResult",
+    "RowSample",
+    "QuestionUsage",
+    "configure_logging",
     "BenchmarkConfig",
 ]

nl2sql/adapters/mssql/adapter.py

@@ -1,6 +1,5 @@
 from typing import Any, List, Dict
 from sqlalchemy import create_engine, text, inspect
-from sqlalchemy.dialects import mssql
 from nl2sql.adapters.sqlalchemy_base import (
     CostEstimate,
     DryRunResult,
@@ -88,7 +87,8 @@ class MssqlAdapter(BaseSQLAlchemyAdapter):
 
     def get_dialect(self) -> str:
         """MSSQL uses T-SQL dialect."""
-        return mssql.dialect.name
+        # A sqlglot dialect name (SQLAlchemy calls it "mssql").
+        return "tsql"
 
     def cost_estimate(self, sql: str) -> CostEstimate:
         import re

nl2sql/adapters/postgres/adapter.py

@@ -1,6 +1,5 @@
 from typing import Dict, Any
 from sqlalchemy import create_engine, inspect, text
-from sqlalchemy.dialects import postgresql
 from nl2sql.adapters.sqlalchemy_base import (
     DryRunResult,
     QueryPlan,
@@ -54,7 +53,9 @@ class PostgresAdapter(BaseSQLAlchemyAdapter):
             from urllib.parse import urlencode
             query_str = "?" + urlencode(options)
             
-        return f"postgresql://{creds}{netloc}/{database}{query_str}"
+        # Name the driver: the `postgres` extra installs psycopg2, and a bare
+        # `postgresql://` means psycopg (v3) from SQLAlchemy 2.1 onwards.
+        return f"postgresql+psycopg2://{creds}{netloc}/{database}{query_str}"
 
     def connect(self) -> None:
         """Postgres-specific connection with Native Server-Side Timeout."""
@@ -107,7 +108,8 @@ class PostgresAdapter(BaseSQLAlchemyAdapter):
             return CostEstimate(estimated_cost=0.0, estimated_rows=0)
 
     def get_dialect(self) -> str:
-        return postgresql.dialect.name
+        # A sqlglot dialect name (SQLAlchemy calls it "postgresql").
+        return "postgres"
 
 
     @property

nl2sql/adapters/sqlalchemy_base/__init__.py

@@ -1,17 +1,13 @@
 from .adapter import BaseSQLAlchemyAdapter
 from .models import (
-    QueryResult,
     CostEstimate,
     DryRunResult,
     QueryPlan,
-    AdapterError,
 )
 
 __all__ = [
     "BaseSQLAlchemyAdapter",
-    "QueryResult",
     "CostEstimate",
     "DryRunResult",
     "QueryPlan",
-    "AdapterError",
 ]

nl2sql/adapters/sqlalchemy_base/adapter.py

@@ -101,12 +101,7 @@ class BaseSQLAlchemyAdapter:
 
     def capabilities(self) -> set[DatasourceCapability]:
         """Default capability set for SQL adapters."""
-        return {
-            DatasourceCapability.SUPPORTS_SQL,
-            DatasourceCapability.SUPPORTS_SCHEMA_INTROSPECTION,
-            DatasourceCapability.SUPPORTS_DRY_RUN,
-            DatasourceCapability.SUPPORTS_COST_ESTIMATE,
-        }
+        return {DatasourceCapability.SUPPORTS_SQL}
 
     def execute_sql(self, sql: str) -> ResultFrame:
         """Executes a SQL query against the datasource.
@@ -458,6 +453,16 @@ class BaseSQLAlchemyAdapter:
     def get_dialect(self) -> str:
         raise NotImplementedError(f"Adapter {self.__class__.__name__} must implement get_dialect")
 
+    def render_sql(self, expression: Any) -> str:
+        """Renders the engine's finished sqlglot tree as this database's SQL.
+
+        The default is sqlglot's own rendering for ``get_dialect()``. Override
+        it to rewrite what sqlglot cannot express for the database, keeping the
+        result types in the SDK contract (a date part is an integer, a
+        truncated date a ``YYYY-MM-DD`` string).
+        """
+        return expression.sql(dialect=self.get_dialect())
+
     def cost_estimate(self, sql: str) -> CostEstimate:
         raise NotImplementedError(f"Adapter {self.__class__.__name__} must implement cost_estimate")
     

nl2sql/adapters/sqlalchemy_base/models.py

@@ -1,15 +1,9 @@
-from pydantic import BaseModel, Field, ConfigDict
-from typing import List, Optional, Any
+from pydantic import BaseModel
+from typing import Optional, Any
 
+# Results and errors use the SDK's ResultFrame and ResultError
+# (nl2sql_adapter_sdk.contracts); these are the SQL-only extras.
 
-class QueryResult(BaseModel):
-    """Normalized results from a datasource execution."""
-    columns: List[str]
-    rows: List[List[Any]]
-    row_count: int
-    raw: Optional[Any] = None
-    execution_time_ms: Optional[float] = None
-    bytes_returned: Optional[int] = None
 
 class DryRunResult(BaseModel):
     """Result of a query validation/dry-run."""
@@ -27,10 +21,3 @@ class CostEstimate(BaseModel):
     estimated_cost: float
     estimated_rows: int
     estimated_time_ms: Optional[float] = None
-
-class AdapterError(BaseModel):
-    """Standardized error envelope for adapter failures."""
-    code: str
-    message: str
-    retriable: bool
-    raw: Optional[Any] = None

nl2sql/adapters/sqlite/adapter.py

@@ -10,6 +10,41 @@ from nl2sql.adapters.sqlalchemy_base import (
 
 from pydantic import BaseModel, Field
 from typing import Optional
+import sqlglot
+from sqlglot import exp
+
+# SQLite has no EXTRACT and no date truncation. Each template reads the date
+# with STRFTIME/DATE; ``__x__`` stands for the operand. The engine wraps a
+# date part in CAST(... AS INT) and a truncation in a YYYY-MM-DD format, so
+# the types match every other adapter.
+_DATE_PARTS = {
+    "YEAR": "STRFTIME('%Y', __x__)",
+    "QUARTER": "(CAST(STRFTIME('%m', __x__) AS INTEGER) + 2) / 3",
+    "MONTH": "STRFTIME('%m', __x__)",
+    "DAY": "STRFTIME('%d', __x__)",
+}
+_DATE_TRUNCS = {
+    "YEAR": "DATE(__x__, 'start of year')",
+    "QUARTER": "DATE(__x__, 'start of month', '-' || ((CAST(STRFTIME('%m', __x__) AS INTEGER) - 1) % 3) || ' months')",
+    "MONTH": "DATE(__x__, 'start of month')",
+    "DAY": "DATE(__x__)",
+}
+
+
+def _from_template(template: str, operand: exp.Expression) -> exp.Expression:
+    tree = sqlglot.parse_one(template, read="sqlite")
+    return tree.transform(
+        lambda node: operand.copy() if isinstance(node, exp.Column) and node.name == "__x__" else node
+    )
+
+
+def _sqlite_dates(node: exp.Expression) -> exp.Expression:
+    """Rewrites the engine's portable date nodes with SQLite's date functions."""
+    if isinstance(node, exp.Extract) and node.name.upper() in _DATE_PARTS:
+        return _from_template(_DATE_PARTS[node.name.upper()], node.expression)
+    if isinstance(node, exp.TimestampTrunc) and node.unit and node.unit.name.upper() in _DATE_TRUNCS:
+        return _from_template(_DATE_TRUNCS[node.unit.name.upper()], node.this)
+    return node
 
 class SqliteConnectionConfig(BaseModel):
     """Strict configuration schema for SQLite adapter."""
@@ -24,16 +59,24 @@ class SqliteAdapter(BaseSQLAlchemyAdapter):
     def construct_uri(self, args: Dict[str, Any]) -> str:
         """Constructs the SQLite connection URI.
 
+        With ``options.read_only`` the file is opened through SQLite's own URI
+        form with ``mode=ro``, so the driver refuses every write before any SQL
+        is parsed. That is the last line under the policy and validator checks,
+        and the one a public demo needs: the sample databases are ours to show
+        and nobody's to change.
+
         Args:
             args: The raw connection arguments dictionary.
 
         Returns:
             str: The fully constructed SQLAlchemy connection URI.
-        
+
         Raises:
             ValidationError: If the configuration is invalid.
         """
         config = SqliteConnectionConfig(**args)
+        if config.options.get("read_only"):
+            return f"sqlite:///file:{config.database}?mode=ro&uri=true"
         return f"sqlite:///{config.database}"
 
     def connect(self) -> None:
@@ -83,6 +126,10 @@ class SqliteAdapter(BaseSQLAlchemyAdapter):
     def get_dialect(self) -> str:
         return sqlite.dialect.name
 
+    def render_sql(self, expression: exp.Expression) -> str:
+        """sqlglot's SQLite rendering, with date parts and truncation rewritten."""
+        return expression.copy().transform(_sqlite_dates).sql(dialect=self.get_dialect())
+
     @property
     def exclude_schemas(self) -> set[str]:
         return set()

nl2sql/aggregation/aggregator.py

@@ -4,8 +4,9 @@ from typing import Dict, List, Tuple
 
 import polars as pl
 from nl2sql.execution.contracts import ArtifactRef
-from nl2sql.pipeline.nodes.global_planner.schemas import ExecutionDAG, LogicalNode, LogicalEdge
+from nl2sql.execution.dag import ExecutionDAG, LogicalNode, LogicalEdge
 
+from .columns import input_order
 from .engines.polars_duckdb import PolarsDuckdbEngine
 
 
@@ -90,9 +91,5 @@ class AggregationService:
         edges: List[LogicalEdge],
         computed: Dict[str, pl.DataFrame],
     ) -> List[Tuple[str, pl.DataFrame]]:
-        def role_rank(role: str) -> int:
-            order = {"left": 0, "base": 0, "primary": 0, "right": 1, "compare": 1, "secondary": 1}
-            return order.get(role or "", 2)
-
-        ordered = sorted(edges, key=lambda e: (role_rank(e.role), e.from_id))
+        ordered = sorted(edges, key=lambda e: input_order(e.role, e.from_id))
         return [(edge.role or "", computed[edge.from_id]) for edge in ordered if edge.from_id in computed]

nl2sql/aggregation/columns.py

@@ -0,0 +1,110 @@
+"""Which columns a combine produces, and which a post-combine op reads.
+
+The aggregation engine combines sub-query results and runs post-combine ops on
+them; a post-combine op that reads a column the combine does not produce fails
+there, after every sub-query has run, and nothing upstream can retry it. The
+decomposer asks these same functions first, from the decomposition alone, so
+such a plan is rejected while the model can still be asked again.
+
+A sub-query's result columns are its ``expected_schema`` names: the logical
+validator rejects a plan whose select aliases differ from them.
+
+Plain Python, no polars: :class:`~nl2sql.aggregation.engines.polars_duckdb.PolarsDuckdbEngine`
+uses the same functions, so the prediction and the engine cannot drift apart.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+# The order a combine's inputs are given to the engine: left-hand roles first.
+_ROLE_RANK = {"left": 0, "base": 0, "primary": 0, "right": 1, "compare": 1, "secondary": 1}
+
+_SIDE_PREFIXES = ("left", "right", "base", "compare", "primary", "secondary")
+
+# What the engine appends to a right-hand column whose name the left side has.
+RIGHT_SUFFIX = "_right"
+
+
+def input_order(role: Optional[str], source_id: str) -> Tuple[int, str]:
+    """Sort key for a combine's inputs, as ``(role, source id)``."""
+    return _ROLE_RANK.get(role or "", 2), source_id
+
+
+def resolve_key(columns: Sequence[str], key: str) -> str:
+    """A join key as one of ``columns``.
+
+    Models write keys qualified by side or sub-query (``right.customer``,
+    ``sq_2.customer``); results have plain column names. An unknown key is
+    returned unchanged.
+    """
+    if key in columns or not key or "." not in key:
+        return key
+    bare = key.rsplit(".", 1)[1]
+    return bare if bare in columns else key
+
+
+def combined_columns(
+    operation: str,
+    inputs: Sequence[Sequence[str]],
+    join_keys: Iterable[Dict[str, Any]],
+) -> List[str]:
+    """The columns the engine's combine produces from inputs with these columns.
+
+    ``inputs`` are in engine order (:func:`input_order`). A ``join`` or
+    ``compare`` is an inner join of the first two on the join keys: the
+    right-hand keys are dropped and any other right-hand column the left side
+    also has is suffixed ``_right``.
+    """
+    if not inputs:
+        return []
+    left = list(inputs[0])
+    if operation in ("standalone", "union") or len(inputs) < 2:
+        return left
+    right = list(inputs[1])
+    right_keys = {resolve_key(right, (k or {}).get("right") or "") for k in join_keys}
+    out = list(left)
+    for column in right:
+        if column in right_keys:
+            continue
+        out.append(column + RIGHT_SUFFIX if column in left else column)
+    return out
+
+
+def post_op_columns(operation: str, attributes: Dict[str, Any]) -> List[str]:
+    """Every column a post-combine op reads from the combined result."""
+    return [name for name in (
+        *((g or {}).get("attribute") for g in attributes.get("group_by") or []),
+        *((m or {}).get("name") for m in attributes.get("metrics") or []),
+        *((c or {}).get("name") for c in attributes.get("expected_schema") or []
+          if operation == "project"),
+        *((f or {}).get("attribute") for f in attributes.get("filters") or []),
+        *((o or {}).get("attribute") for o in attributes.get("order_by") or []),
+    ) if name]
+
+
+def missing_columns_message(missing: Sequence[str], available: Sequence[str]) -> str:
+    """Why a post-combine op that reads ``missing`` cannot run on ``available``.
+
+    A side-qualified name (``right.customer``) is almost always one question:
+    "which customers bought jazz but never rock?". The plan language has no
+    anti-join -- every two-input combine is an inner join -- so the model
+    reaches for a right-hand column to negate against, and that column does not
+    survive the combine. Resolving the prefix away would filter the
+    *intersection* and answer "bought both", silently wrong.
+    """
+    detail = (
+        f"Post-combine operation references {', '.join(repr(m) for m in missing)}, "
+        f"which the combined result does not have. Available columns: {', '.join(available) or 'none'}."
+    )
+    if any("." in m and m.split(".", 1)[0].lower() in _SIDE_PREFIXES for m in missing):
+        detail += (
+            " A column qualified by side does not survive the combine: joining on"
+            " the shared column drops the right-hand copy, and the other right-hand"
+            " columns are suffixed '_right'. This is what a question of the form"
+            " 'has X but never Y' looks like here, and it cannot be expressed:"
+            " the plan language has no anti-join or set-difference operation"
+            " (combine is one of standalone, compare, join, union -- all inner),"
+            " so the question is refused rather than answered with the"
+            " intersection."
+        )
+    return detail

nl2sql/aggregation/engines/polars_duckdb.py

@@ -5,10 +5,77 @@ from typing import Any, Dict, List, Tuple
 import duckdb
 import polars as pl
 
+from nl2sql.aggregation.columns import missing_columns_message, post_op_columns, resolve_key
 from nl2sql.execution.contracts import ArtifactRef
 from nl2sql.execution.artifacts import build_artifact_store
 
 
+def _column(frame: pl.DataFrame, key: str) -> str:
+    """A join key as a column of ``frame``; see :func:`~nl2sql.aggregation.columns.resolve_key`."""
+    return resolve_key(frame.columns, key)
+
+
+def _check_attributes(frame: pl.DataFrame, names: List[str]) -> None:
+    """Refuses a post-combine attribute the combined frame does not have.
+
+    polars reports this as ``unable to find column "right.customer"; valid
+    columns: ["customer"]``, which tells neither the caller nor the planner
+    anything. The decomposer runs the same check on the decomposition before
+    anything executes (``nl2sql.aggregation.columns``) and asks the model
+    again, so this is the last line of defence; the message explains why a
+    side-qualified column cannot work (see ``missing_columns_message``).
+    """
+    missing = [name for name in names if name and name not in frame.columns]
+    if missing:
+        raise ValueError(missing_columns_message(missing, frame.columns))
+
+
+def _filter(rows: pl.DataFrame, filters: List[Dict[str, Any]]) -> pl.DataFrame:
+    for flt in filters:
+        col, op, val = pl.col(flt.get("attribute")), flt.get("operator"), flt.get("value")
+        if op == "=":
+            rows = rows.filter(col == val)
+        elif op == "!=":
+            rows = rows.filter(col != val)
+        elif op == ">":
+            rows = rows.filter(col > val)
+        elif op == ">=":
+            rows = rows.filter(col >= val)
+        elif op == "<":
+            rows = rows.filter(col < val)
+        elif op == "<=":
+            rows = rows.filter(col <= val)
+        elif op == "between" and isinstance(val, list) and len(val) == 2:
+            rows = rows.filter((col >= val[0]) & (col <= val[1]))
+        elif op == "in" and isinstance(val, list):
+            rows = rows.filter(col.is_in(val))
+        elif op == "contains":
+            rows = rows.filter(col.cast(pl.Utf8).str.contains(str(val)))
+    return rows
+
+
+_AGGREGATIONS = {
+    "count": lambda c: c.count(),
+    "sum": lambda c: c.sum(),
+    "avg": lambda c: c.mean(),
+    "min": lambda c: c.min(),
+    "max": lambda c: c.max(),
+}
+
+
+def _aggregate(frame: pl.DataFrame, attributes: Dict[str, Any]) -> pl.DataFrame:
+    group_by = [g.get("attribute") for g in attributes.get("group_by", []) if g.get("attribute")]
+    exprs = [
+        _AGGREGATIONS[m.get("aggregation")](pl.col(m.get("name"))).alias(m.get("name"))
+        for m in attributes.get("metrics", [])
+        if m.get("aggregation") in _AGGREGATIONS
+    ]
+    if group_by:
+        # polars 1.x: group_by (groupby was removed).
+        return frame.group_by(group_by, maintain_order=True).agg(exprs)
+    return frame.select(exprs)
+
+
 class PolarsDuckdbEngine:
     def __init__(self):
         self.artifact_store = build_artifact_store()
@@ -34,16 +101,16 @@ class PolarsDuckdbEngine:
                 return frames[0]
             left = frames[0]
             right = frames[1]
-            left_on = [k.get("left") for k in join_keys]
-            right_on = [k.get("right") for k in join_keys]
+            left_on = [_column(left, k.get("left")) for k in join_keys]
+            right_on = [_column(right, k.get("right")) for k in join_keys]
             return left.join(right, left_on=left_on, right_on=right_on, how="inner", suffix="_right")
         if operation == "compare":
             if len(frames) < 2:
                 return frames[0]
             left = frames[0]
             right = frames[1]
-            left_on = [k.get("left") for k in join_keys]
-            right_on = [k.get("right") for k in join_keys]
+            left_on = [_column(left, k.get("left")) for k in join_keys]
+            right_on = [_column(right, k.get("right")) for k in join_keys]
             joined = left.join(right, left_on=left_on, right_on=right_on, how="inner", suffix="_right")
             diff_cols = []
             for col in left.columns:
@@ -59,67 +126,33 @@ class PolarsDuckdbEngine:
         raise ValueError(f"Unsupported combine operation '{operation}'.")
 
     def post_op(self, operation: str, frame: pl.DataFrame, attributes: Dict[str, Any]) -> pl.DataFrame:
-        if operation == "filter":
-            rows = frame
-            for flt in attributes.get("filters", []):
-                attr = flt.get("attribute")
-                op = flt.get("operator")
-                val = flt.get("value")
-                col = pl.col(attr)
-                if op == "=":
-                    rows = rows.filter(col == val)
-                elif op == "!=":
-                    rows = rows.filter(col != val)
-                elif op == ">":
-                    rows = rows.filter(col > val)
-                elif op == ">=":
-                    rows = rows.filter(col >= val)
-                elif op == "<":
-                    rows = rows.filter(col < val)
-                elif op == "<=":
-                    rows = rows.filter(col <= val)
-                elif op == "between" and isinstance(val, list) and len(val) == 2:
-                    rows = rows.filter((col >= val[0]) & (col <= val[1]))
-                elif op == "in" and isinstance(val, list):
-                    rows = rows.filter(col.is_in(val))
-                elif op == "contains":
-                    rows = rows.filter(col.cast(pl.Utf8).str.contains(str(val)))
-            return rows
+        """Applies one post-combine op, every field it carries, in SQL's order.
+
+        ``operation`` picks the reshaping step (``aggregate`` or ``project``);
+        whatever the operation, the op's filters, order_by and limit are then
+        applied, in that order. A filter after an aggregate filters the
+        aggregated rows, as HAVING does. The decomposer's own example is a
+        ``filter`` op carrying ``order_by`` and ``limit``, so applying only the
+        named field dropped them.
+        """
+        if operation not in {"filter", "aggregate", "project", "sort", "limit"}:
+            raise ValueError(f"Unsupported post-combine operation '{operation}'.")
+        # Every column this op will read, checked against the combined frame
+        # before polars is asked for any of them. See `_check_attributes`.
+        _check_attributes(frame, post_op_columns(operation, attributes))
+        rows = frame
         if operation == "aggregate":
-            group_by = [g.get("attribute") for g in attributes.get("group_by", []) if g.get("attribute")]
-            metrics = attributes.get("metrics", [])
-            agg_exprs = []
-            for metric in metrics:
-                name = metric.get("name")
-                agg = metric.get("aggregation")
-                col = pl.col(name)
-                if agg == "count":
-                    agg_exprs.append(col.count().alias(name))
-                elif agg == "sum":
-                    agg_exprs.append(col.sum().alias(name))
-                elif agg == "avg":
-                    agg_exprs.append(col.mean().alias(name))
-                elif agg == "min":
-                    agg_exprs.append(col.min().alias(name))
-                elif agg == "max":
-                    agg_exprs.append(col.max().alias(name))
-            if group_by:
-                return frame.groupby(group_by).agg(agg_exprs)
-            return frame.select(agg_exprs)
-        if operation == "project":
+            rows = _aggregate(rows, attributes)
+        elif operation == "project":
             columns = [c.get("name") for c in attributes.get("expected_schema", []) if c.get("name")]
-            return frame.select(columns) if columns else frame
-        if operation == "sort":
-            order_by = attributes.get("order_by", [])
-            sort_cols = [o.get("attribute") for o in order_by if o.get("attribute")]
-            descending = [o.get("direction") == "desc" for o in order_by if o.get("attribute")]
-            if sort_cols:
-                return frame.sort(sort_cols, descending=descending)
-            return frame
-        if operation == "limit":
-            limit = attributes.get("limit")
-            return frame.head(limit) if limit is not None else frame
-        raise ValueError(f"Unsupported post-combine operation '{operation}'.")
+            rows = rows.select(columns) if columns else rows
+        rows = _filter(rows, attributes.get("filters", []))
+        order_by = [o for o in attributes.get("order_by", []) if o.get("attribute")]
+        if order_by:
+            rows = rows.sort([o["attribute"] for o in order_by],
+                             descending=[o.get("direction") == "desc" for o in order_by])
+        limit = attributes.get("limit")
+        return rows.head(limit) if limit is not None else rows
 
     def to_rows(self, frame: pl.DataFrame) -> List[Dict[str, Any]]:
         return frame.to_dicts()