@an5/adapters 0.2.4 → 0.2.6

package/python/table_client.py

@@ -1,216 +1,619 @@
-import json
-import uuid
-from typing import Dict, List, Optional
-try:
-    from .base import DIALECT_MSSQL, DIALECT_POSTGRES, model_fields, _build_order_by, _parse_where, _quote, _quote_table, _resolve_table
-except ImportError:
-    from base import DIALECT_MSSQL, DIALECT_POSTGRES, model_fields, _build_order_by, _parse_where, _quote, _quote_table, _resolve_table
-
-# ─── Table Client ───────────────────────────────────────────────────────────────────
-
-class AdapterTableClient:
-    def __init__(self, adapter: An5Adapter, model_name: str):
-        self._adapter = adapter
-        self._model = model_name
-        self._dialect = adapter._dialect
-
-    @property
-    def _table(self) -> str:
-        return _resolve_table(self._model)
-
-    @property
-    def _table_sql(self) -> str:
-        return _quote_table(self._table, self._dialect)
-
-    @property
-    def _nolock(self) -> str:
-        return "" if self._dialect == DIALECT_POSTGRES else " WITH (NOLOCK)"
-
-    @property
-    def _fields(self) -> List[Dict]:
-        fields = model_fields.get(self._model, [])
-        if isinstance(fields, dict):
-            raise TypeError(
-                "AN5 Python metadata is out of date. Regenerate with @an5/orm >= 1.0.4 "
-                "so MODEL_FIELDS uses a list of field objects."
-            )
-        return fields
-
-    def _pagination(self, take: Optional[int], skip: int, order_sql: str) -> str:
-        if take is None:
-            return ""
-        if self._dialect == DIALECT_POSTGRES:
-            return f" LIMIT {take} OFFSET {skip}"
-        order_prefix = "" if order_sql else " ORDER BY (SELECT NULL)"
-        return f"{order_prefix} OFFSET {skip} ROWS FETCH NEXT {take} ROWS ONLY"
-
-    def find_many(self, where=None, order_by=None, skip: int = 0, take: Optional[int] = None, select=None) -> List[Dict]:
-        params: Dict = {}
-        where_sql = _parse_where(self._model, where, params, self._dialect)
-        order_sql = _build_order_by(order_by, self._dialect)
-
-        query = f"SELECT * FROM {self._table_sql}{self._nolock}"
-        if where_sql:
-            query += f" WHERE {where_sql}"
-        if order_sql:
-            query += f" {order_sql}"
-        query += self._pagination(take, skip, order_sql)
-        return self._adapter.exec(query, list(params.values()))
-
-    def find_first(self, where=None, order_by=None, select=None) -> Optional[Dict]:
-        rows = self.find_many(where=where, order_by=order_by, take=1, select=select)
-        return rows[0] if rows else None
-
-    def find_unique(self, where: Dict) -> Optional[Dict]:
-        return self.find_first(where=where)
-
-    def count(self, where=None) -> int:
-        params: Dict = {}
-        where_sql = _parse_where(self._model, where, params, self._dialect)
-        query = f"SELECT COUNT(*) AS cnt FROM {self._table_sql}{self._nolock}"
-        if where_sql:
-            query += f" WHERE {where_sql}"
-        rows = self._adapter.exec(query, list(params.values()))
-        return int(rows[0]["cnt"]) if rows else 0
-
-    def create(self, data: Dict) -> Dict:
-        id_field = next((f for f in self._fields if f.get("isId")), None)
-        if id_field and id_field["name"] not in data:
-            data = {**data, id_field["name"]: str(uuid.uuid4())}
-
-        cols = [k for k, v in data.items() if v is not None]
-        values = [data[c] for c in cols]
-        placeholders = ", ".join(["?" if self._dialect == DIALECT_MSSQL else "%s"] * len(cols))
-        col_list = ", ".join(_quote(c, self._dialect) for c in cols)
-        query = f"INSERT INTO {self._table_sql} ({col_list}) VALUES ({placeholders})"
-        self._adapter.execute(query, values)
-
-        if id_field:
-            return self.find_first(where={id_field["name"]: data[id_field["name"]]}) or data
-        return data
-
-    def create_many(self, data: List[Dict], skip_duplicates: bool = False) -> Dict:
-        count = 0
-        for row in data:
-            try:
-                self.create(row)
-                count += 1
-            except Exception:
-                if not skip_duplicates:
-                    raise
-        return {"count": count}
-
-    def update(self, where: Dict, data: Dict) -> Optional[Dict]:
-        params: Dict = {}
-        where_sql = _parse_where(self._model, where, params, self._dialect, "w_")
-        set_parts: List[str] = []
-        set_values: List = []
-        placeholder = "?" if self._dialect == DIALECT_MSSQL else "%s"
-        for col, val in data.items():
-            if val is not None:
-                set_parts.append(f"{_quote(col, self._dialect)} = {placeholder}")
-                set_values.append(val)
-
-        all_values = set_values + list(params.values())
-        query = f"UPDATE {self._table_sql} SET {', '.join(set_parts)}"
-        if where_sql:
-            query += f" WHERE {where_sql}"
-        self._adapter.execute(query, all_values)
-        return self.find_first(where=where)
-
-    def update_many(self, where: Optional[Dict], data: Dict) -> Dict:
-        params: Dict = {}
-        where_sql = _parse_where(self._model, where, params, self._dialect, "w_")
-        set_parts: List[str] = []
-        set_values: List = []
-        placeholder = "?" if self._dialect == DIALECT_MSSQL else "%s"
-        for col, val in data.items():
-            set_parts.append(f"{_quote(col, self._dialect)} = {placeholder}")
-            set_values.append(val)
-        all_values = set_values + list(params.values())
-        query = f"UPDATE {self._table_sql} SET {', '.join(set_parts)}"
-        if where_sql:
-            query += f" WHERE {where_sql}"
-        count = self._adapter.execute(query, all_values)
-        return {"count": count}
-
-    def delete(self, where: Dict) -> Optional[Dict]:
-        existing = self.find_first(where=where)
-        params: Dict = {}
-        where_sql = _parse_where(self._model, where, params, self._dialect)
-        query = f"DELETE FROM {self._table_sql} WHERE {where_sql}"
-        self._adapter.execute(query, list(params.values()))
-        return existing
-
-    def delete_many(self, where: Optional[Dict] = None) -> Dict:
-        params: Dict = {}
-        where_sql = _parse_where(self._model, where, params, self._dialect)
-        query = f"DELETE FROM {self._table_sql}"
-        if where_sql:
-            query += f" WHERE {where_sql}"
-        count = self._adapter.execute(query, list(params.values()))
-        return {"count": count}
-
-    def upsert(self, where: Dict, create: Dict, update: Dict) -> Dict:
-        existing = self.find_first(where=where)
-        if existing:
-            return self.update(where=where, data=update) or existing
-        return self.create(data=create)
-
-    def aggregate(self, where=None, _count=None, _sum=None, _avg=None, _min=None, _max=None) -> Dict:
-        params: Dict = {}
-        where_sql = _parse_where(self._model, where, params, self._dialect)
-        aggs: List[str] = []
-        if _count:
-            aggs.append("COUNT(*) AS _count")
-        if _sum:
-            for f in (_sum if isinstance(_sum, list) else [_sum]):
-                aggs.append(f"SUM({_quote(f, self._dialect)}) AS _sum_{f}")
-        if _avg:
-            for f in (_avg if isinstance(_avg, list) else [_avg]):
-                aggs.append(f"AVG({_quote(f, self._dialect)}) AS _avg_{f}")
-        if _min:
-            for f in (_min if isinstance(_min, list) else [_min]):
-                aggs.append(f"MIN({_quote(f, self._dialect)}) AS _min_{f}")
-        if _max:
-            for f in (_max if isinstance(_max, list) else [_max]):
-                aggs.append(f"MAX({_quote(f, self._dialect)}) AS _max_{f}")
-        if not aggs:
-            aggs = ["COUNT(*) AS _count"]
-
-        query = f"SELECT {', '.join(aggs)} FROM {self._table_sql}"
-        if where_sql:
-            query += f" WHERE {where_sql}"
-        rows = self._adapter.exec(query, list(params.values()))
-        return rows[0] if rows else {}
-
-    def vector_search(self, vector: List[float], take: int = 10, where=None, vector_field: str = "embedding", distance_metric: str = "cosine") -> List[Dict]:
-        rows = self.find_many(where=where)
-        scored = []
-        for row in rows:
-            raw = row.get(vector_field)
-            if raw is None:
-                continue
-            try:
-                vec = json.loads(raw) if isinstance(raw, str) else list(raw)
-            except Exception:
-                continue
-            if not vec or len(vec) != len(vector):
-                continue
-
-            dot = sum(a * b for a, b in zip(vector, vec))
-            m1 = sum(a ** 2 for a in vector) ** 0.5
-            m2 = sum(b ** 2 for b in vec) ** 0.5
-            cosine = dot / (m1 * m2) if m1 and m2 else 0.0
-
-            if distance_metric == "cosine":
-                dist = 1.0 - cosine
-            elif distance_metric == "dot":
-                dist = -dot
-            else:
-                dist = sum((a - b) ** 2 for a, b in zip(vector, vec)) ** 0.5
-
-            scored.append((row, dist))
-
-        scored.sort(key=lambda x: x[1])
-        return [{**row, "distance": dist} for row, dist in scored[:take]]
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any, Dict, Generic, List, Optional, TypeVar
+try:
+    from .base import DIALECT_MSSQL, DIALECT_POSTGRES, model_fields, _build_order_by, _parse_where, _quote, _quote_table, _resolve_table, get_relations_for_model
+except ImportError:
+    from base import DIALECT_MSSQL, DIALECT_POSTGRES, model_fields, _build_order_by, _parse_where, _quote, _quote_table, _resolve_table, get_relations_for_model
+
+# ─── Select / Include helpers ────────────────────────────────────────────────────────
+
+def _selected_fields(select: Any) -> List[str]:
+    """Extract scalar column names from a select object (list or dict with truthy values)."""
+    if not select:
+        return []
+    if isinstance(select, str):
+        return [select] if select else []
+    if isinstance(select, list):
+        return [f for f in select if isinstance(f, str) and f]
+    if isinstance(select, dict):
+        return [str(k) for k, v in select.items() if v]
+    return []
+
+
+def _has_relation_select(select: Any, relations: Dict) -> bool:
+    for key in _selected_fields(select):
+        if key == "_count" or key in relations:
+            return True
+    return False
+
+
+def _project_fields(row: Dict, select: Any) -> Dict:
+    """Keep only selected fields on a row (mirrors TypeScript projectFields)."""
+    if not row or not select:
+        return row
+    projected = {}
+    for key in _selected_fields(select):
+        if key in row:
+            projected[key] = row[key]
+    if "_count" in row:
+        projected["_count"] = row["_count"]
+    return projected
+
+
+def _to_list(value: Any) -> List:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    if isinstance(value, tuple):
+        return list(value)
+    return [value]
+
+
+def _resolve_includes(model_name: str, rows: List[Dict], include: Any, adapter: Any) -> None:
+    """Eager-load relation rows and attach them onto each row (mirrors TypeScript resolveIncludes)."""
+    if not rows or not include:
+        return
+    if not isinstance(include, dict):
+        return
+    model_relations = get_relations_for_model(model_name)
+
+    for key, value in include.items():
+        if not value:
+            continue
+
+        if key == "_count":
+            for row in rows:
+                if "_count" not in row or row["_count"] is None:
+                    row["_count"] = {}
+            for rel_key, relation in model_relations.items():
+                if relation.get("relationType") != "many":
+                    continue
+                unique_keys = list({row.get(relation["localKey"]) for row in rows if row.get(relation["localKey"]) is not None})
+                if unique_keys:
+                    rel_client = adapter.table(relation["modelName"])
+                    related = rel_client.find_many(where={relation["foreignKey"]: {"in": unique_keys}})
+                    count_map = {}
+                    for r in related:
+                        k = r.get(relation["foreignKey"])
+                        count_map[k] = count_map.get(k, 0) + 1
+                    for row in rows:
+                        k = row.get(relation["localKey"])
+                        row["_count"][rel_key] = count_map.get(k, 0)
+                else:
+                    for row in rows:
+                        row["_count"][rel_key] = 0
+            continue
+
+        relation = model_relations.get(key)
+        if not relation:
+            continue
+
+        is_many = relation.get("relationType") == "many"
+        local_key = relation["localKey"]
+        foreign_key = relation["foreignKey"]
+        join_key = local_key if is_many else foreign_key
+        match_key = foreign_key if is_many else local_key
+        unique_keys = list({row.get(join_key) for row in rows if row.get(join_key) is not None})
+
+        if not unique_keys:
+            for row in rows:
+                row[key] = [] if is_many else None
+            continue
+
+        sub_args = value if isinstance(value, dict) else {}
+        sub_where = {match_key: {"in": unique_keys}}
+        if sub_args.get("where"):
+            sub_where.update(sub_args["where"])
+
+        rel_client = adapter.table(relation["modelName"])
+        related = rel_client.find_many(
+            where=sub_where,
+            order_by=sub_args.get("orderBy"),
+            take=sub_args.get("take"),
+            skip=sub_args.get("skip"),
+        )
+
+        if sub_args.get("include"):
+            _resolve_includes(relation["modelName"], related, sub_args["include"], adapter)
+
+        output_rows = related
+        if sub_args.get("select"):
+            output_rows = [_project_fields(r, sub_args["select"]) for r in related]
+
+        group_map = {}
+        for i, r in enumerate(related):
+            k = r.get(foreign_key if is_many else local_key)
+            group_map.setdefault(k, []).append(output_rows[i])
+
+        for row in rows:
+            k = row.get(local_key if is_many else foreign_key)
+            matches = group_map.get(k) or []
+            row[key] = matches if is_many else (matches[0] if matches else None)
+
+
+def _split_relation_writes(model_name: str, data: Dict) -> (Dict, Dict):
+    """Separate relation-write objects from scalar data using model metadata."""
+    relations = get_relations_for_model(model_name)
+    scalars = {}
+    rel_writes = {}
+    for k, v in data.items():
+        if k in relations and isinstance(v, dict) and v is not None:
+            rel_writes[k] = v
+        else:
+            scalars[k] = v
+    return scalars, rel_writes
+
+# ─── Table Client ───────────────────────────────────────────────────────────────────
+
+def _selected_aggregate_fields(fields: Any) -> List[str]:
+    if not fields:
+        return []
+    if isinstance(fields, str):
+        return [fields]
+    if isinstance(fields, list):
+        return [f for f in fields if isinstance(f, str) and f]
+    if isinstance(fields, dict):
+        return [str(f) for f, enabled in fields.items() if enabled]
+    return []
+
+
+def _normalize_by_fields(by: Any) -> List[str]:
+    if isinstance(by, str):
+        return [by]
+    if isinstance(by, list):
+        return [f for f in by if isinstance(f, str) and f]
+    return []
+
+
+def _to_non_negative_int(value: Any, fallback: int = 0) -> int:
+    try:
+        n = int(value)
+        return n if n >= 0 else fallback
+    except Exception:
+        return fallback
+
+
+def _append_update_set(set_parts: List[str], values: List[Any], col: str, val: Any, dialect: str) -> None:
+    quoted = _quote(col, dialect)
+    placeholder = "?" if dialect == DIALECT_MSSQL else "%s"
+    if isinstance(val, dict):
+        if "increment" in val:
+            set_parts.append(f"{quoted} = {quoted} + {placeholder}")
+            values.append(val["increment"])
+            return
+        if "decrement" in val:
+            set_parts.append(f"{quoted} = {quoted} - {placeholder}")
+            values.append(val["decrement"])
+            return
+        if "multiply" in val:
+            set_parts.append(f"{quoted} = {quoted} * {placeholder}")
+            values.append(val["multiply"])
+            return
+        if "divide" in val:
+            set_parts.append(f"{quoted} = {quoted} / {placeholder}")
+            values.append(val["divide"])
+            return
+        if "set" in val:
+            set_parts.append(f"{quoted} = {placeholder}")
+            values.append(val["set"])
+            return
+
+    set_parts.append(f"{quoted} = {placeholder}")
+    values.append(val)
+
+
+T = TypeVar("T")
+
+
+class AdapterTableClient(Generic[T]):
+    """Typed table client.
+
+    Bind a row type for ORM-standard autocomplete, e.g.
+    ``AdapterTableClient[UserRow]`` where ``UserRow`` is the generated
+    ``TypedDict`` describing the model's row shape (the runtime returns
+    plain dicts). Unparameterized ``AdapterTableClient`` behaves as before.
+    """
+    def __init__(self, adapter: An5Adapter, model_name: str):
+        self._adapter = adapter
+        self._model = model_name
+        self._dialect = adapter._dialect
+
+    @property
+    def _table(self) -> str:
+        return _resolve_table(self._model)
+
+    @property
+    def _table_sql(self) -> str:
+        return _quote_table(self._table, self._dialect)
+
+    @property
+    def _nolock(self) -> str:
+        return "" if self._dialect == DIALECT_POSTGRES else " WITH (NOLOCK)"
+
+    @property
+    def _fields(self) -> List[Dict]:
+        fields = model_fields.get(self._model, [])
+        if isinstance(fields, dict):
+            raise TypeError(
+                "AN5 Python metadata is out of date. Regenerate with @an5/orm >= 1.0.4 "
+                "so MODEL_FIELDS uses a list of field objects."
+            )
+        return fields
+
+    def _pagination(self, take: Optional[int], skip: int, order_sql: str) -> str:
+        if take is None:
+            return ""
+        if self._dialect == DIALECT_POSTGRES:
+            return f" LIMIT {take} OFFSET {skip}"
+        order_prefix = "" if order_sql else " ORDER BY (SELECT NULL)"
+        return f"{order_prefix} OFFSET {skip} ROWS FETCH NEXT {take} ROWS ONLY"
+
+    def find_many(self, where=None, order_by=None, skip: int = 0, take: Optional[int] = None, select=None, include=None) -> List[T]:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect)
+        order_sql = _build_order_by(order_by, self._dialect)
+
+        relations = get_relations_for_model(self._model)
+        cols = "SELECT *"
+        if select and len(_selected_fields(select)) > 0 and not _has_relation_select(select, relations):
+            cols = "SELECT " + ", ".join(_quote(c, self._dialect) for c in _selected_fields(select))
+
+        query = f"{cols} FROM {self._table_sql}{self._nolock}"
+        if where_sql:
+            query += f" WHERE {where_sql}"
+        if order_sql:
+            query += f" {order_sql}"
+        query += self._pagination(take, skip, order_sql)
+
+        rows = self._adapter.exec(query, list(params.values()))
+
+        if include:
+            _resolve_includes(self._model, rows, include, self._adapter)
+        if select:
+            if _has_relation_select(select, relations):
+                _resolve_includes(self._model, rows, select, self._adapter)
+            rows = [_project_fields(r, select) for r in rows]
+        return rows
+
+    def find_first(self, where=None, order_by=None, select=None, include=None) -> Optional[T]:
+        rows = self.find_many(where=where, order_by=order_by, take=1, select=select, include=include)
+        return rows[0] if rows else None
+
+    def find_unique(self, where: Dict, select=None, include=None) -> Optional[T]:
+        return self.find_first(where=where, select=select, include=include)
+
+    def count(self, where=None) -> int:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect)
+        query = f"SELECT COUNT(*) AS cnt FROM {self._table_sql}{self._nolock}"
+        if where_sql:
+            query += f" WHERE {where_sql}"
+        rows = self._adapter.exec(query, list(params.values()))
+        return int(rows[0]["cnt"]) if rows else 0
+
+    def create(self, data: Dict, include=None, select=None) -> T:
+        id_field = next((f for f in self._fields if f.get("isId")), None)
+        if id_field and id_field["name"] not in data:
+            data = {**data, id_field["name"]: str(uuid.uuid4())}
+
+        data, relation_writes = _split_relation_writes(self._model, data)
+
+        cols = [k for k, v in data.items() if v is not None]
+        values = [data[c] for c in cols]
+        placeholders = ", ".join(["?" if self._dialect == DIALECT_MSSQL else "%s"] * len(cols))
+        col_list = ", ".join(_quote(c, self._dialect) for c in cols)
+        query = f"INSERT INTO {self._table_sql} ({col_list}) VALUES ({placeholders})"
+        self._adapter.execute(query, values)
+
+        if id_field:
+            created = self.find_first(where={id_field["name"]: data[id_field["name"]]}) or data
+        else:
+            created = data
+
+        # Handle nested relation writes
+        relations = get_relations_for_model(self._model)
+        for rel_key, rel_write in relation_writes.items():
+            relation = relations.get(rel_key)
+            if not relation:
+                continue
+            child_client = self._adapter.table(relation["modelName"])
+            if "create" in rel_write:
+                create_items = _to_list(rel_write["create"])
+                for item in create_items:
+                    merged = {**item, relation["foreignKey"]: created.get(relation["localKey"])}
+                    child_client.create(data=merged)
+
+        if include:
+            _resolve_includes(self._model, [created], include, self._adapter)
+        if select:
+            _resolve_includes(self._model, [created], select, self._adapter)
+            return _project_fields(created, select)
+        return created
+
+    def create_many(self, data: List[Dict], skip_duplicates: bool = False) -> Dict:
+        count = 0
+        for row in data:
+            try:
+                self.create(row)
+                count += 1
+            except Exception:
+                if not skip_duplicates:
+                    raise
+        return {"count": count}
+
+    def update(self, where: Dict, data: Dict, include=None, select=None) -> Optional[T]:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect, "w_")
+        data, relation_writes = _split_relation_writes(self._model, data)
+        set_parts: List[str] = []
+        set_values: List = []
+        for col, val in data.items():
+            if val is not None:
+                _append_update_set(set_parts, set_values, col, val, self._dialect)
+
+        if set_parts:
+            all_values = set_values + list(params.values())
+            query = f"UPDATE {self._table_sql} SET {', '.join(set_parts)}"
+            if where_sql:
+                query += f" WHERE {where_sql}"
+            self._adapter.execute(query, all_values)
+
+        updated = self.find_first(where=where)
+
+        # Handle nested relation writes
+        relations = get_relations_for_model(self._model)
+        for rel_key, rel_write in relation_writes.items():
+            relation = relations.get(rel_key)
+            if not relation:
+                continue
+            child_client = self._adapter.table(relation["modelName"])
+            if "create" in rel_write:
+                create_items = _to_list(rel_write["create"])
+                for item in create_items:
+                    merged = {**item, relation["foreignKey"]: (updated or {}).get(relation["localKey"])}
+                    child_client.create(data=merged)
+            if "update" in rel_write:
+                update_obj = rel_write["update"]
+                child_client.update(where=update_obj.get("where"), data=update_obj.get("data") or {})
+            if "disconnect" in rel_write:
+                child_client.update_many(where=rel_write["disconnect"], data={relation["foreignKey"]: None})
+
+        if include and updated:
+            _resolve_includes(self._model, [updated], include, self._adapter)
+        if select and updated:
+            _resolve_includes(self._model, [updated], select, self._adapter)
+            return _project_fields(updated, select)
+        return updated
+
+    def update_many(self, where: Optional[Dict], data: Dict) -> Dict:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect, "w_")
+        set_parts: List[str] = []
+        set_values: List = []
+        for col, val in data.items():
+            if val is not None:
+                _append_update_set(set_parts, set_values, col, val, self._dialect)
+
+        if not set_parts:
+            return {"count": 0}
+
+        all_values = set_values + list(params.values())
+        query = f"UPDATE {self._table_sql} SET {', '.join(set_parts)}"
+        if where_sql:
+            query += f" WHERE {where_sql}"
+        count = self._adapter.execute(query, all_values)
+        return {"count": count}
+
+    def delete(self, where: Dict) -> Optional[T]:
+        existing = self.find_first(where=where)
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect)
+        query = f"DELETE FROM {self._table_sql} WHERE {where_sql}"
+        self._adapter.execute(query, list(params.values()))
+        return existing
+
+    def delete_many(self, where: Optional[Dict] = None) -> Dict:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect)
+        query = f"DELETE FROM {self._table_sql}"
+        if where_sql:
+            query += f" WHERE {where_sql}"
+        count = self._adapter.execute(query, list(params.values()))
+        return {"count": count}
+
+    def upsert(self, where: Dict, create: Dict, update: Dict) -> T:
+        existing = self.find_first(where=where)
+        if existing:
+            return self.update(where=where, data=update) or existing
+        return self.create(data=create)
+
+    def aggregate(self, where=None, _count=None, _sum=None, _avg=None, _min=None, _max=None) -> Dict:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect)
+        aggs: List[str] = []
+        if _count:
+            aggs.append("COUNT(*) AS _count")
+        if _sum:
+            for f in _selected_aggregate_fields(_sum):
+                aggs.append(f"SUM({_quote(f, self._dialect)}) AS _sum_{f}")
+        if _avg:
+            for f in _selected_aggregate_fields(_avg):
+                aggs.append(f"AVG({_quote(f, self._dialect)}) AS _avg_{f}")
+        if _min:
+            for f in _selected_aggregate_fields(_min):
+                aggs.append(f"MIN({_quote(f, self._dialect)}) AS _min_{f}")
+        if _max:
+            for f in _selected_aggregate_fields(_max):
+                aggs.append(f"MAX({_quote(f, self._dialect)}) AS _max_{f}")
+        if not aggs:
+            raise ValueError("Aggregate requires at least one aggregator field")
+
+        query = f"SELECT {', '.join(aggs)} FROM {self._table_sql}"
+        if where_sql:
+            query += f" WHERE {where_sql}"
+        rows = self._adapter.exec(query, list(params.values()))
+        return rows[0] if rows else {}
+
+    def group_by(self, by, where=None, order_by=None, skip: int = 0, take: Optional[int] = None,
+                 _sum=None, _avg=None, _min=None, _max=None) -> List[Dict]:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect)
+        by_fields = _normalize_by_fields(by)
+        if not by_fields:
+            raise ValueError("group_by requires 'by' fields")
+
+        by_cols = ", ".join(_quote(f, self._dialect) for f in by_fields)
+        aggs = ["COUNT(*) AS _count"]
+        for f in _selected_aggregate_fields(_sum):
+            aggs.append(f"SUM({_quote(f, self._dialect)}) AS _sum_{f}")
+        for f in _selected_aggregate_fields(_avg):
+            aggs.append(f"AVG({_quote(f, self._dialect)}) AS _avg_{f}")
+        for f in _selected_aggregate_fields(_min):
+            aggs.append(f"MIN({_quote(f, self._dialect)}) AS _min_{f}")
+        for f in _selected_aggregate_fields(_max):
+            aggs.append(f"MAX({_quote(f, self._dialect)}) AS _max_{f}")
+
+        query = f"SELECT {by_cols}, {', '.join(aggs)} FROM {self._table_sql}"
+        if where_sql:
+            query += f" WHERE {where_sql}"
+        query += f" GROUP BY {by_cols}"
+        order_sql = _build_order_by(order_by, self._dialect)
+        has_take = take is not None
+        has_skip = skip is not None and skip > 0
+        if order_sql:
+            query += f" {order_sql}"
+        elif has_take or has_skip:
+            query += f" ORDER BY {by_cols}"
+        if has_take or has_skip:
+            final_skip = _to_non_negative_int(skip)
+            if self._dialect == DIALECT_POSTGRES:
+                if has_take:
+                    query += f" LIMIT {_to_non_negative_int(take, 1)}"
+                query += f" OFFSET {final_skip}"
+            else:
+                query += f" OFFSET {final_skip} ROWS"
+                if has_take:
+                    query += f" FETCH NEXT {_to_non_negative_int(take, 1)} ROWS ONLY"
+
+        return self._adapter.exec(query, list(params.values()))
+
+    def vector_search(self, vector: List[float], take: int = 10, where=None, vector_field: str = "embedding", distance_metric: str = "cosine") -> List[Dict]:
+        dim = len(vector)
+        vec_json = json.dumps(vector)
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect)
+
+        # 1. Primary path: Native database SQL vector query execution (MSSQL VECTOR_DISTANCE / Postgres pgvector)
+        try:
+            field_sql = _quote(vector_field, self._dialect)
+            if self._dialect == DIALECT_POSTGRES:
+                op = "<=>" if distance_metric == "cosine" else ("<->" if distance_metric == "euclidean" else "<#>")
+                query = f"SELECT *, ({field_sql} {op} %s::vector) AS distance FROM {self._table_sql}"
+                query_params = [vec_json] + list(params.values())
+                if where_sql:
+                    query += f" WHERE {field_sql} IS NOT NULL AND ({where_sql})"
+                else:
+                    query += f" WHERE {field_sql} IS NOT NULL"
+                query += f" ORDER BY distance ASC LIMIT {take}"
+            else:
+                placeholder = "?"
+                query = f"SELECT TOP ({take}) *, VECTOR_DISTANCE('{distance_metric}', CAST({field_sql} AS VECTOR({dim}, float32)), CAST({placeholder} AS VECTOR({dim}, float32))) AS distance FROM {self._table_sql}{self._nolock}"
+                query_params = [vec_json] + list(params.values())
+                if where_sql:
+                    query += f" WHERE {field_sql} IS NOT NULL AND ({where_sql})"
+                else:
+                    query += f" WHERE {field_sql} IS NOT NULL"
+                query += " ORDER BY distance ASC"
+
+            native_rows = self._adapter.exec(query, query_params)
+
+
+            if native_rows is not None:
+                return native_rows
+        except Exception:
+            pass
+
+        # 2. Secondary fallback: In-memory similarity computation if DB engine lacks native vector extension
+        rows = self.find_many(where=where)
+        scored = []
+        for row in rows:
+            raw = row.get(vector_field)
+            if raw is None:
+                continue
+            try:
+                vec = json.loads(raw) if isinstance(raw, str) else list(raw)
+            except Exception:
+                continue
+            if not vec or len(vec) != len(vector):
+                continue
+
+            dot = sum(a * b for a, b in zip(vector, vec))
+            m1 = sum(a ** 2 for a in vector) ** 0.5
+            m2 = sum(b ** 2 for b in vec) ** 0.5
+            cosine = dot / (m1 * m2) if m1 and m2 else 0.0
+
+            if distance_metric == "cosine":
+                dist = 1.0 - cosine
+            elif distance_metric == "dot":
+                dist = -dot
+            else:
+                dist = sum((a - b) ** 2 for a, b in zip(vector, vec)) ** 0.5
+
+            scored.append((row, dist))
+
+        scored.sort(key=lambda x: x[1])
+        return [{**row, "distance": dist} for row, dist in scored[:take]]
+
+
+class ViewClient:
+    """Read-only view client for querying database views without permitting mutations."""
+
+    def __init__(self, adapter: Any, view_name: str):
+        self._client = AdapterTableClient(adapter, view_name)
+        self.view_name = view_name
+
+    def find_many(self, *args, **kwargs):
+        return self._client.find_many(*args, **kwargs)
+
+    def find_first(self, *args, **kwargs):
+        return self._client.find_first(*args, **kwargs)
+
+    def find_unique(self, *args, **kwargs):
+        return self._client.find_unique(*args, **kwargs)
+
+    def count(self, *args, **kwargs):
+        return self._client.count(*args, **kwargs)
+
+    def aggregate(self, *args, **kwargs):
+        return self._client.aggregate(*args, **kwargs)
+
+    def group_by(self, *args, **kwargs):
+        return self._client.group_by(*args, **kwargs)
+
+    def vector_search(self, *args, **kwargs):
+        return self._client.vector_search(*args, **kwargs)
+
+    def create(self, *args, **kwargs):
+        raise PermissionError(f"View '{self.view_name}' is read-only. Mutation operations (create) are not allowed.")
+
+    def create_many(self, *args, **kwargs):
+        raise PermissionError(f"View '{self.view_name}' is read-only. Mutation operations (create_many) are not allowed.")
+
+    def update(self, *args, **kwargs):
+        raise PermissionError(f"View '{self.view_name}' is read-only. Mutation operations (update) are not allowed.")
+
+    def update_many(self, *args, **kwargs):
+        raise PermissionError(f"View '{self.view_name}' is read-only. Mutation operations (update_many) are not allowed.")
+
+    def delete(self, *args, **kwargs):
+        raise PermissionError(f"View '{self.view_name}' is read-only. Mutation operations (delete) are not allowed.")
+
+    def delete_many(self, *args, **kwargs):
+        raise PermissionError(f"View '{self.view_name}' is read-only. Mutation operations (delete_many) are not allowed.")
+
+    def upsert(self, *args, **kwargs):
+        raise PermissionError(f"View '{self.view_name}' is read-only. Mutation operations (upsert) are not allowed.")