affinity-sdk 0.9.5__py3-none-any.whl

affinity/cli/query/filters.py

@@ -0,0 +1,248 @@
+"""Filter operators for query WHERE clauses.
+
+This module provides extended filter operators beyond what the SDK supports.
+It is CLI-only and NOT part of the public SDK API.
+
+Uses the shared compare module (affinity/compare.py) for comparison logic,
+ensuring consistent behavior between SDK filter and Query tool.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from ...compare import compare_values
+from .dates import parse_date_value
+from .exceptions import QueryValidationError
+from .models import WhereClause
+
+# =============================================================================
+# Operator Definitions
+# =============================================================================
+
+# Type alias for operator functions
+OperatorFunc = Callable[[Any, Any], bool]
+
+
+def _make_operator(op_name: str) -> OperatorFunc:
+    """Create an operator function that delegates to compare_values().
+
+    This is a factory function that creates operator functions for the OPERATORS
+    registry. Each function wraps compare_values() with the appropriate operator name.
+    """
+
+    def op_func(field_value: Any, target: Any) -> bool:
+        return compare_values(field_value, target, op_name)
+
+    return op_func
+
+
+# Operator registry - all operators delegate to compare_values() from the shared module
+# This ensures consistent comparison behavior between SDK filter and Query tool
+OPERATORS: dict[str, OperatorFunc] = {
+    "eq": _make_operator("eq"),
+    "neq": _make_operator("neq"),
+    "gt": _make_operator("gt"),
+    "gte": _make_operator("gte"),
+    "lt": _make_operator("lt"),
+    "lte": _make_operator("lte"),
+    "contains": _make_operator("contains"),
+    "starts_with": _make_operator("starts_with"),
+    "ends_with": _make_operator("ends_with"),  # New: was missing in query tool
+    "in": _make_operator("in"),
+    "between": _make_operator("between"),
+    "is_null": _make_operator("is_null"),
+    "is_not_null": _make_operator("is_not_null"),
+    "is_empty": _make_operator("is_empty"),  # New: was missing in query tool
+    "contains_any": _make_operator("contains_any"),
+    "contains_all": _make_operator("contains_all"),
+    "has_any": _make_operator("has_any"),
+    "has_all": _make_operator("has_all"),
+}
+
+
+# =============================================================================
+# Field Path Resolution
+# =============================================================================
+
+
+def resolve_field_path(record: dict[str, Any], path: str) -> Any:
+    """Resolve a field path to a value.
+
+    Supports:
+    - Simple fields: "firstName"
+    - Nested fields: "address.city"
+    - Array fields: "emails[0]"
+    - Special fields: "fields.Status" for list entry fields
+
+    Args:
+        record: The record to extract value from
+        path: The field path
+
+    Returns:
+        The resolved value, or None if not found
+    """
+    if not path:
+        return None
+
+    parts = _parse_field_path(path)
+    current: Any = record
+
+    for part in parts:
+        if current is None:
+            return None
+
+        if isinstance(part, int):
+            # Array index
+            if isinstance(current, list) and 0 <= part < len(current):
+                current = current[part]
+            else:
+                return None
+        elif isinstance(current, dict):
+            # Object property
+            current = current.get(part)
+        else:
+            return None
+
+    return current
+
+
+def _parse_field_path(path: str) -> list[str | int]:
+    """Parse a field path into parts.
+
+    Examples:
+        "firstName" -> ["firstName"]
+        "address.city" -> ["address", "city"]
+        "emails[0]" -> ["emails", 0]
+        "fields.Status" -> ["fields", "Status"]
+    """
+    parts: list[str | int] = []
+    current = ""
+    i = 0
+
+    while i < len(path):
+        char = path[i]
+
+        if char == ".":
+            if current:
+                parts.append(current)
+                current = ""
+            i += 1
+        elif char == "[":
+            if current:
+                parts.append(current)
+                current = ""
+            # Find closing bracket
+            end = path.find("]", i)
+            if end == -1:
+                raise QueryValidationError(f"Unclosed bracket in field path: {path}")
+            index_str = path[i + 1 : end]
+            try:
+                parts.append(int(index_str))
+            except ValueError:
+                # Non-numeric index, treat as string
+                parts.append(index_str)
+            i = end + 1
+        else:
+            current += char
+            i += 1
+
+    if current:
+        parts.append(current)
+
+    return parts
+
+
+# =============================================================================
+# Filter Compilation
+# =============================================================================
+
+
+def compile_filter(where: WhereClause) -> Callable[[dict[str, Any]], bool]:
+    """Compile a WHERE clause into a filter function.
+
+    Args:
+        where: The WHERE clause to compile
+
+    Returns:
+        A function that takes a record and returns True if it matches
+    """
+    # Single condition
+    if where.op is not None:
+        return _compile_condition(where)
+
+    # Compound conditions
+    if where.and_ is not None:
+        filters = [compile_filter(clause) for clause in where.and_]
+        return lambda record: all(f(record) for f in filters)
+
+    if where.or_ is not None:
+        filters = [compile_filter(clause) for clause in where.or_]
+        return lambda record: any(f(record) for f in filters)
+
+    if where.not_ is not None:
+        inner = compile_filter(where.not_)
+        return lambda record: not inner(record)
+
+    # Quantifiers (all, none) - placeholder, requires relationship fetching
+    if where.all_ is not None or where.none_ is not None:
+        # These require relationship data and are handled by executor
+        # For now, pass through
+        return lambda _: True
+
+    # Exists - placeholder, requires subquery execution
+    if where.exists_ is not None:
+        return lambda _: True
+
+    # No conditions - match all
+    return lambda _: True
+
+
+def _compile_condition(where: WhereClause) -> Callable[[dict[str, Any]], bool]:
+    """Compile a single filter condition."""
+    if where.op is None:
+        return lambda _: True
+
+    op_func = OPERATORS.get(where.op)
+    if op_func is None:
+        raise QueryValidationError(f"Unknown operator: {where.op}")
+
+    path = where.path
+    value = where.value
+
+    # Parse date values if they look like relative dates
+    if value is not None and isinstance(value, str):
+        parsed_value = parse_date_value(value)
+        if parsed_value is not None:
+            value = parsed_value
+
+    # Handle _count pseudo-field
+    if path and path.endswith("._count"):
+        # This requires relationship counting, handled by executor
+        # Return a placeholder that always matches
+        return lambda _: True
+
+    def filter_func(record: dict[str, Any]) -> bool:
+        if path is None:
+            return True
+        field_value = resolve_field_path(record, path)
+        return op_func(field_value, value)
+
+    return filter_func
+
+
+def matches(record: dict[str, Any], where: WhereClause | None) -> bool:
+    """Check if a record matches a WHERE clause.
+
+    Args:
+        record: The record to check
+        where: The WHERE clause, or None (matches all)
+
+    Returns:
+        True if the record matches
+    """
+    if where is None:
+        return True
+    filter_func = compile_filter(where)
+    return filter_func(record)

affinity/cli/query/models.py

@@ -0,0 +1,333 @@
+"""Pydantic models for the query language.
+
+These models define the structure of structured queries. They are CLI-only
+and NOT part of the public SDK API.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if TYPE_CHECKING:
+    from ..results import ResultSummary
+
+# =============================================================================
+# Filter Condition Models
+# =============================================================================
+
+
+class FilterCondition(BaseModel):
+    """A single filter condition.
+
+    Examples:
+        {"path": "email", "op": "contains", "value": "@acme.com"}
+        {"path": "createdAt", "op": "gt", "value": "-30d"}
+        {"path": "companies._count", "op": "gte", "value": 2}
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    path: str | None = None
+    expr: dict[str, Any] | None = None
+    op: Literal[
+        "eq",
+        "neq",
+        "gt",
+        "gte",
+        "lt",
+        "lte",
+        "contains",
+        "starts_with",
+        "in",
+        "between",
+        "is_null",
+        "is_not_null",
+        "contains_any",
+        "contains_all",
+    ]
+    value: Any = None
+
+
+class QuantifierClause(BaseModel):
+    """Quantifier clause for 'all' or 'none' predicates.
+
+    Examples:
+        {"all": {"path": "interactions", "where": {"path": "type", "op": "eq", "value": "MEETING"}}}
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    path: str
+    where: WhereClause
+
+
+class ExistsClause(BaseModel):
+    """EXISTS subquery clause.
+
+    Examples:
+        {"exists": {"from": "interactions", "via": "personId", "where": {...}}}
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    from_: str = Field(..., alias="from")
+    via: str | None = None
+    where: WhereClause | None = None
+
+
+class WhereClause(BaseModel):
+    """WHERE clause supporting compound conditions.
+
+    Can be:
+    - A single condition: {"path": "x", "op": "eq", "value": "y"}
+    - Compound: {"and": [...]} or {"or": [...]}
+    - Negation: {"not": {...}}
+    - Quantifiers: {"all": {...}} or {"none": {...}}
+    - Existence: {"exists": {...}}
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    # Single condition fields
+    path: str | None = None
+    expr: dict[str, Any] | None = None
+    op: str | None = None
+    value: Any = None
+
+    # Compound conditions
+    and_: list[WhereClause] | None = Field(None, alias="and")
+    or_: list[WhereClause] | None = Field(None, alias="or")
+    not_: WhereClause | None = Field(None, alias="not")
+
+    # Quantifiers
+    all_: QuantifierClause | None = Field(None, alias="all")
+    none_: QuantifierClause | None = Field(None, alias="none")
+
+    # Existence
+    exists_: ExistsClause | None = Field(None, alias="exists")
+
+
+# =============================================================================
+# Aggregate Models
+# =============================================================================
+
+
+class AggregateFunc(BaseModel):
+    """Aggregate function definition.
+
+    Examples:
+        {"sum": "amount"}
+        {"count": true}
+        {"avg": "score"}
+        {"percentile": {"field": "amount", "p": 90}}
+        {"multiply": ["count", "avgAmount"]}
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Simple aggregates
+    sum: str | None = None
+    avg: str | None = None
+    min: str | None = None
+    max: str | None = None
+    count: bool | str | None = None  # True for count(*), str for count(field)
+
+    # Advanced aggregates
+    percentile: dict[str, Any] | None = None  # {"field": "x", "p": 90}
+    first: str | None = None
+    last: str | None = None
+
+    # Expression aggregates (operate on other aggregates)
+    multiply: list[str | int | float] | None = None
+    divide: list[str | int | float] | None = None
+    add: list[str | int | float] | None = None
+    subtract: list[str | int | float] | None = None
+
+
+class HavingClause(BaseModel):
+    """HAVING clause for filtering aggregated results.
+
+    Examples:
+        {"path": "totalAmount", "op": "gt", "value": 1000}
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    path: str | None = None
+    op: str | None = None
+    value: Any = None
+
+    and_: list[HavingClause] | None = Field(None, alias="and")
+    or_: list[HavingClause] | None = Field(None, alias="or")
+
+
+# =============================================================================
+# Order By Models
+# =============================================================================
+
+
+class OrderByClause(BaseModel):
+    """ORDER BY clause.
+
+    Examples:
+        {"field": "lastName", "direction": "asc"}
+        {"field": "createdAt", "direction": "desc"}
+        {"expr": {"daysUntil": "dueDate"}, "direction": "asc"}
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    field: str | None = None
+    expr: dict[str, Any] | None = None
+    direction: Literal["asc", "desc"] = "asc"
+
+
+# =============================================================================
+# Subquery Models
+# =============================================================================
+
+
+class SubqueryDef(BaseModel):
+    """Named subquery definition.
+
+    Examples:
+        {
+            "recentDeals": {
+                "from": "opportunities",
+                "where": {"path": "closedAt", "op": "gt", "value": "-90d"}
+            }
+        }
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    from_: str = Field(..., alias="from")
+    where: WhereClause | None = None
+    select: list[str] | None = None
+    limit: int | None = None
+
+
+# =============================================================================
+# Main Query Model
+# =============================================================================
+
+
+class Query(BaseModel):
+    """The main query model.
+
+    This is the top-level structure for a structured query.
+
+    Examples:
+        {
+            "$version": "1.0",
+            "from": "persons",
+            "where": {"path": "email", "op": "contains", "value": "@acme.com"},
+            "include": ["companies"],
+            "orderBy": [{"field": "lastName", "direction": "asc"}],
+            "limit": 50
+        }
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    # Version (optional but recommended)
+    version: str | None = Field(None, alias="$version")
+
+    # Required: entity to query
+    from_: str = Field(..., alias="from")
+
+    # Optional: field selection
+    select: list[str] | None = None
+
+    # Optional: filtering
+    where: WhereClause | None = None
+
+    # Optional: includes (relationships to fetch)
+    include: list[str] | None = None
+
+    # Optional: named subqueries
+    subqueries: dict[str, SubqueryDef] | None = None
+
+    # Optional: ordering
+    order_by: list[OrderByClause] | None = Field(None, alias="orderBy")
+
+    # Optional: grouping and aggregation
+    group_by: str | None = Field(None, alias="groupBy")
+    aggregate: dict[str, AggregateFunc] | None = None
+    having: HavingClause | None = None
+
+    # Optional: pagination
+    limit: int | None = None
+    cursor: str | None = None
+
+
+# =============================================================================
+# Execution Plan Models (used by planner and executor)
+# =============================================================================
+
+
+@dataclass
+class PlanStep:
+    """A single step in the execution plan."""
+
+    step_id: int
+    operation: Literal[
+        "fetch",
+        "filter",
+        "include",
+        "aggregate",
+        "sort",
+        "limit",
+        "exists_check",
+        "count_relationship",
+    ]
+    description: str
+    entity: str | None = None
+    relationship: str | None = None
+    estimated_api_calls: int = 0
+    estimated_records: int | None = None
+    is_client_side: bool = False
+    warnings: list[str] = field(default_factory=list)
+    depends_on: list[int] = field(default_factory=list)
+
+    # Additional metadata for specific operations
+    filter_pushdown: bool = False
+    pushdown_filter: str | None = None
+    client_filter: WhereClause | None = None
+
+
+@dataclass
+class ExecutionPlan:
+    """Complete execution plan for a query."""
+
+    query: Query
+    steps: list[PlanStep]
+    total_api_calls: int
+    estimated_records_fetched: int | None
+    estimated_memory_mb: float | None
+    warnings: list[str]
+    recommendations: list[str]
+    has_expensive_operations: bool
+    requires_full_scan: bool
+    version: str = "1.0"
+
+
+@dataclass
+class QueryResult:
+    """Result of query execution."""
+
+    data: list[dict[str, Any]]
+    included: dict[str, list[dict[str, Any]]] = field(default_factory=dict)
+    summary: ResultSummary | None = None  # Standardized result summary
+    meta: dict[str, Any] = field(default_factory=dict)  # Additional metadata (executionTime, etc.)
+    pagination: dict[str, Any] | None = None
+    rate_limit: Any | None = None  # RateLimitSnapshot from client
+    warnings: list[str] = field(default_factory=list)
+
+
+# Enable forward references
+WhereClause.model_rebuild()
+HavingClause.model_rebuild()