SearchEngine

The SearchEngine translates nested JSON filter trees into secure, optimized SQLAlchemy expressions while enforcing configurable depth limits, wildcard escaping, inverted operators, and context security policies.

Class Definition

from collections.abc import Callable
from typing import Any, TypeVar
from zcore import SearchRequest
from zcore.config import settings
from zcore.db.setup import Base

ModelType = TypeVar("ModelType", bound=Base)

class SearchEngine:
    def __init__(self, model: type[ModelType]):
        self.model = model
        self.max_depth: int = getattr(
            model,
            "__max_search_depth__",
            getattr(settings, "SEARCH_MAX_DEPTH", 3),
        )
        self.custom_handlers: dict[str, Callable[[Any], Any]] = {}
        ...

Properties

Methods

register_handler

Binds a custom callback handler to parse a specific field's values dynamically into custom SQL clauses.

def register_handler(
    self, 
    field_name: str, 
    handler: Callable[[Any], Any]
) -> SearchEngine: ...

build_base_query

Parses search inputs, validates context security policies, and constructs the base Select statement with filters, eager loading joins, and sorting (without limit/offset).

def build_base_query(
    self, 
    search_in: SearchRequest, 
    base_query: Select | None = None
) -> Select: ...

build_query

Constructs the base Select query and applies size (limit) and page (offset) boundaries.

def build_query(self, search_in: SearchRequest) -> Select: ...

Pydantic Models

SearchRequest

Comprehensive request model containing dynamic search parameters. Automatically validates and bounds size via model_validator(mode="after").

from zcore import SearchRequest

FilterItem

Pydantic model representing a single filtering condition, inverted operator, or nested boolean group.

SortItem

Pydantic model mapping explicit sorting configurations for query results.