fastapi-sqlalchemy-querykit 0.1.0__py3-none-any.whl

fastapi_sqlalchemy_querykit-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: fastapi-sqlalchemy-querykit
+Version: 0.1.0
+Summary: Deny-by-default declarative filtering, sorting, and searching for FastAPI + SQLAlchemy 2.0.
+Project-URL: Homepage, https://github.com/Rooler-ai/fastapi-sqlalchemy-querybuilder
+Project-URL: Repository, https://github.com/Rooler-ai/fastapi-sqlalchemy-querybuilder
+Project-URL: Documentation, https://rooler-ai.github.io/fastapi-sqlalchemy-querybuilder/
+Project-URL: Changelog, https://github.com/Rooler-ai/fastapi-sqlalchemy-querybuilder/blob/main/CHANGELOG.md
+Author-email: Yaqupboyev Yoqubboy <yoqubboy.yaqupboyev@rooler.ai>
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: api,fastapi,filter,filtering,pagination,query,querybuilder,rest,search,sort,sqlalchemy
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# fastapi-sqlalchemy-querykit
+
+Deny-by-default declarative filtering, sorting, and searching for **FastAPI +
+SQLAlchemy 2.0** (async-safe). A field is filterable, sortable, or searchable only
+if the model explicitly declares it — the opposite of the open-by-default library
+this is derived from.
+
+```bash
+pip install fastapi-sqlalchemy-querykit
+```
+
+> Distribution: `fastapi-sqlalchemy-querykit` · import package: `querybuilder`.
+> Full docs in [`docs/`](docs/index.md).
+
+## Why
+
+- **Deny by default.** Undeclared fields return a generic 400, never a silent query.
+- **Declare policy on the model.** A `Queryable` mixin lists the allowed fields once;
+  endpoints may narrow but never widen.
+- **Correct relationships.** Filters and search across relationships compile to
+  correlated `EXISTS` (`.has()` / `.any()`) — no row fan-out, no `DISTINCT`, to-many
+  supported; two paths to the same model never collide. Sorting uses path-keyed joins.
+- **Type-aware & enum-safe.** Operators are validated against the column type; enums
+  match by value (Postgres-safe).
+- **Caller-owned base scope.** The builder is purely additive — it never adds or
+  inspects your own `WHERE` (tenant, soft-delete, visibility).
+
+## Quick example
+
+```python
+from querybuilder import Queryable, QueryParams, build_query
+
+class User(Base, Queryable):
+    __filterable__ = frozenset({"status", "username", "age", "organization.name"})
+    __sortable__   = frozenset({"created_at", "username"})
+    __searchable__ = frozenset({"username", "organization.name"})
+
+# inside your data/query layer
+async def list_users(db, params: QueryParams):
+    stmt = build_query(User, params)                 # filters + search + sort
+    stmt = stmt.where(User.is_deleted.is_(False))     # caller-owned base scope
+    return (await db.execute(stmt)).scalars().all()
+```
+
+```text
+GET /users?filters={"status":{"$eq":"active"},"organization.name":{"$contains":"acme"}}&sort=created_at:desc&search=jdoe
+```
+
+The filter travels as one JSON object, `{field: {operator: value}}`, with `$and` /
+`$or` for grouping and a dot for relationship traversal (`organization.name`).
+
+## Operators
+
+`$eq` `$ne` `$gt` `$gte` `$lt` `$lte` `$in` `$nin` · `$contains` `$ncontains`
+`$startswith` `$endswith` · `$isnull` `$isnotnull` · logical `$and` `$or`.
+
+String comparisons are case-insensitive by default (`case_sensitive=true` to opt
+out). Enum filters resolve the operand to the matching member, so you filter by the
+enum value regardless of how SQLAlchemy stores it.
+
+## Endpoint-level narrowing
+
+The model declares the maximum; an endpoint may expose a subset (never a superset):
+
+```python
+stmt = build_query(User, params, allowed_filters={"status", "username"})
+```
+
+## Documentation
+
+- [Operator reference](docs/operators.md) — wire format, every operator, the per-type matrix
+- [Guide](docs/guide.md) — `Queryable`, relationships, search, sort, errors, limits, startup validation
+- [FastAPI integration](docs/integration.md)
+
+Build the docs site locally: `pip install -e ".[docs]" && mkdocs serve`.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT. Derivative work of [fastapi-querybuilder](https://github.com/bhadri01/fastapi-querybuilder)
+by bhadri01 — see `LICENSE` and `NOTICE`.

fastapi_sqlalchemy_querykit-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+querybuilder/__init__.py,sha256=NIxtKiOIeas6dpnjurihR0lCL2n5xV0J7uLdVqzWq7w,825
+querybuilder/allowlist.py,sha256=OeJRFt2u8oJg6gUO0mz_4mFEVRNunyWlhZzyW1cl-rY,3514
+querybuilder/builder.py,sha256=BCSyRsiI-t44BD9sSx7Simp0qcvBleUjq1995rKF4Q4,11538
+querybuilder/columns.py,sha256=IybmfUho1d-a5CQ7A530a6WyDZ5sjeGwBih6W14tuAc,1986
+querybuilder/dates.py,sha256=CtG1mxAC6NNofe2FVj40Fx3kB1IfbEXSE1BnsRymi08,1994
+querybuilder/errors.py,sha256=o7SfFhEZMZAktr1nSuHkhNajKBcHBjirHpV5y5Sd3pY,1504
+querybuilder/mixin.py,sha256=nvVkAVKubt8pDDbE5xcmIFm64FxL04A1y-IY0Ik4kCA,1185
+querybuilder/operators.py,sha256=0NN9oxZjUvJX02NasTKmSocFC8WoULNnXvmtxw5hwPA,9957
+querybuilder/params.py,sha256=lyFvyFSEA0QU2R8w4mqVITN0Eeda6YYap1aDPm3f3aY,1362
+querybuilder/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+querybuilder/resolver.py,sha256=5RjArTbfrn5bheXmnfHX8GUUqRY08VVsb6-hQdhk_bQ,4009
+querybuilder/validation.py,sha256=kHudpTbCJvsBVHkQV3J2zJVM10_tubNUPgvVETpnXJU,2178
+fastapi_sqlalchemy_querykit-0.1.0.dist-info/METADATA,sha256=HKxZpLeeQXCZVzRkYLSZhhAK11Y_I4oc5_jnH0hDvYc,4870
+fastapi_sqlalchemy_querykit-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+fastapi_sqlalchemy_querykit-0.1.0.dist-info/licenses/LICENSE,sha256=cqZedEuNrvR7QYfocPvfNbKnnfYb14dvpFES61HGq7I,1166
+fastapi_sqlalchemy_querykit-0.1.0.dist-info/licenses/NOTICE,sha256=Wi8KVt1WphKO-KtYXuWEfxrsYRPAimbgAvI7_E9LP_E,394
+fastapi_sqlalchemy_querykit-0.1.0.dist-info/RECORD,,

fastapi_sqlalchemy_querykit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

fastapi_sqlalchemy_querykit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 bhadri01 (original work: fastapi-querybuilder)
+Copyright (c) 2026 querybuilder contributors (derivative work)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_sqlalchemy_querykit-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,13 @@
+fastapi-sqlalchemy-querykit
+
+This product is a derivative work that adapts engine concepts and the JSON filter
+wire format from:
+
+  fastapi-querybuilder by bhadri01
+  https://github.com/bhadri01/fastapi-querybuilder
+  Licensed under the MIT License.
+
+Portions Copyright (c) 2025 bhadri01.
+
+The full MIT license text (covering both the original and this derivative work)
+is in the LICENSE file.

querybuilder/__init__.py

@@ -0,0 +1,35 @@
+"""querybuilder — deny-by-default declarative filtering, sorting, and
+searching for FastAPI + SQLAlchemy 2.0 (async-safe).
+
+Derivative work adapting the engine concepts and JSON wire format of
+fastapi-querybuilder (bhadri01, MIT). See NOTICE.
+"""
+
+from __future__ import annotations
+
+from .allowlist import validate_queryable, validate_queryables
+from .builder import build_query
+from .errors import (
+    FilterError,
+    QueryBuilderError,
+    QueryConfigurationError,
+    SearchError,
+    SortError,
+)
+from .mixin import Queryable
+from .params import QueryParams
+
+__all__ = [
+    "build_query",
+    "Queryable",
+    "QueryParams",
+    "validate_queryable",
+    "validate_queryables",
+    "QueryBuilderError",
+    "FilterError",
+    "SortError",
+    "SearchError",
+    "QueryConfigurationError",
+]
+
+__version__ = "0.1.0"

querybuilder/allowlist.py

@@ -0,0 +1,88 @@
+"""Deny-by-default allowlist enforcement and endpoint-level narrowing.
+
+The model declares the maximum via the Queryable frozensets. An endpoint may pass
+a subset through ``build_query``'s ``allowed_*`` arguments to expose less, but a
+subset containing a field the model never declared is a configuration error.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional, Type
+
+
+def effective_allowlist(model, attr: str, override: Optional[Iterable[str]]) -> frozenset:
+    """Resolve the effective allowlist for one dimension.
+
+    Returns the model's declared set, or — when an endpoint override is given —
+    the override, after verifying it does not widen beyond the declaration.
+    Raises :class:`QueryConfigurationError` (a programmer error) on widening.
+    """
+    from .errors import QueryConfigurationError
+
+    declared = frozenset(getattr(model, attr, frozenset()))
+    if override is None:
+        return declared
+    override_set = frozenset(override)
+    widened = override_set - declared
+    if widened:
+        raise QueryConfigurationError(
+            f"Endpoint {attr} allowlist widens beyond the model declaration: "
+            f"{sorted(widened)}"
+        )
+    return override_set
+
+
+def ensure_allowed(
+    field_path: str,
+    allowed: frozenset,
+    error_cls: Type[Exception],
+    message: str,
+) -> None:
+    """Raise ``error_cls(message)`` if ``field_path`` is not allowlisted."""
+    if field_path not in allowed:
+        raise error_cls(message)
+
+
+def validate_queryable(model) -> None:
+    """Validate a model's Queryable allowlists at startup (spec §8).
+
+    Every declared path must resolve to a real leaf column — each segment a real
+    relationship, the leaf a real column — so typos like ``"organizaton.name"``
+    fail at deploy time rather than per request. ``__sortable__`` additionally may
+    not cross a to-many relationship (you can't ``ORDER BY`` a to-many); to-many
+    paths are fine in ``__filterable__`` / ``__searchable__`` (they compile to
+    EXISTS). Raises :class:`QueryConfigurationError` naming the offending path.
+
+    Call once at startup, e.g. ``validate_queryables(User, Order, ...)``. Run it
+    *after* all models are imported (i.e. in app startup, not at a module top
+    level): it reads relationship metadata, which requires SQLAlchemy mappers to
+    be configured — calling it too early surfaces SQLAlchemy's own error, not a
+    :class:`QueryConfigurationError`.
+    """
+    from .errors import FilterError, QueryConfigurationError
+    from .resolver import describe_path
+
+    name = getattr(model, "__name__", repr(model))
+    for attr, allow_to_many in (
+        ("__filterable__", True),
+        ("__searchable__", True),
+        ("__sortable__", False),
+    ):
+        for path in getattr(model, attr, frozenset()):
+            try:
+                _, has_to_many = describe_path(model, path.split("."))
+            except FilterError:
+                raise QueryConfigurationError(
+                    f"{name}.{attr}: path {path!r} does not resolve to a column."
+                )
+            if has_to_many and not allow_to_many:
+                raise QueryConfigurationError(
+                    f"{name}.{attr}: path {path!r} crosses a to-many relationship, "
+                    f"which cannot be sorted."
+                )
+
+
+def validate_queryables(*models) -> None:
+    """Validate several models' allowlists — call once at app startup."""
+    for model in models:
+        validate_queryable(model)

querybuilder/builder.py

@@ -0,0 +1,307 @@
+"""The build pipeline: ``build_query`` turns request params into a SQLAlchemy
+``Select``, additively.
+
+Pipeline order (spec §10):
+1. Start from ``select(model)``. The caller owns the mandatory base scope
+   (e.g. tenant / soft-delete / visibility filters); the builder never adds nor
+   inspects it — it ANDs cleanly onto whatever the caller has.
+2. Filters — deny-by-default allowlist, then a predicate per field.
+3. Search — OR a single term across the declared searchable set.
+4. Sort — validated against the sortable set.
+
+Relationships in a WHERE position (filters and search) compile to correlated
+EXISTS (``.has()`` for to-one, ``.any()`` for to-many), so they never join or
+fan-out the root. Only sort joins — relationships in ORDER BY use the path-keyed
+LEFT-JOIN resolver, because a column must be projected to be ordered.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from typing import Any, Dict, List, Optional, Tuple
+
+from sqlalchemy import String, asc, cast, desc, func, or_, select
+from sqlalchemy.sql import Select, and_
+
+from .allowlist import effective_allowlist, ensure_allowed
+from .columns import (
+    is_boolean_column,
+    is_datetime_like_column,
+    is_enum_column,
+    is_integer_column,
+    is_string_column,
+)
+from .errors import FilterError, SortError
+from .operators import (
+    LOGICAL_OPERATORS,
+    NULL_OPERATORS,
+    enum_value_members,
+    get_comparison_operators,
+)
+from .resolver import JoinCache, describe_path, resolve_path
+from .validation import validate_operator
+
+#: Default bounds on the filter payload (spec §19), overridable per call.
+DEFAULT_MAX_FILTER_BYTES = 8192
+DEFAULT_MAX_FILTER_DEPTH = 10
+
+
+def build_query(
+    model,
+    params,
+    *,
+    allowed_filters: Optional[Any] = None,
+    allowed_sorts: Optional[Any] = None,
+    allowed_search: Optional[Any] = None,
+    max_filter_bytes: int = DEFAULT_MAX_FILTER_BYTES,
+    max_filter_depth: int = DEFAULT_MAX_FILTER_DEPTH,
+) -> Select:
+    """Build a ``Select`` for ``model`` from ``params``.
+
+    ``params`` is any object exposing ``filters`` / ``sort`` / ``search`` and an
+    optional ``case_sensitive`` attribute (see :class:`QueryParams`).
+
+    The ``allowed_*`` arguments optionally narrow the model's declared allowlists
+    for this endpoint; each must be a subset of the model declaration.
+
+    ``max_filter_bytes`` / ``max_filter_depth`` bound the filter payload size and
+    its ``$and``/``$or`` nesting depth (spec §19).
+    """
+    query: Select = select(model)
+
+    filterable = effective_allowlist(model, "__filterable__", allowed_filters)
+    sortable = effective_allowlist(model, "__sortable__", allowed_sorts)
+    searchable = effective_allowlist(model, "__searchable__", allowed_search)
+
+    filters = getattr(params, "filters", None)
+    if filters:
+        if len(filters.encode("utf-8")) > max_filter_bytes:
+            raise FilterError("Filter payload too large.")
+        parsed = _parse_filter_json(filters)
+        expr = _parse_filters(
+            model, parsed, filterable,
+            case_sensitive=getattr(params, "case_sensitive", False),
+            max_depth=max_filter_depth,
+        )
+        if expr is not None:
+            query = query.where(expr)
+
+    search = getattr(params, "search", None)
+    if search:
+        expr = _build_search(model, search, searchable)
+        if expr is not None:
+            query = query.where(expr)
+
+    sort = getattr(params, "sort", None)
+    if sort:
+        query = _apply_sort(
+            model, sort, query, sortable,
+            case_sensitive=getattr(params, "case_sensitive", False),
+        )
+
+    return query
+
+
+@lru_cache(maxsize=1024)
+def _parse_filter_json(raw: str) -> Dict:
+    """Parse the filter JSON string (cached). Generic 400 on any malformation."""
+    try:
+        parsed = json.loads(raw)
+    except (ValueError, TypeError):
+        raise FilterError("Invalid filter format.")
+    if not isinstance(parsed, dict):
+        raise FilterError("Invalid filter format.")
+    return parsed
+
+
+def _parse_filters(
+    model,
+    filters: Any,
+    filterable: frozenset,
+    *,
+    case_sensitive: bool,
+    depth: int = 0,
+    max_depth: int = DEFAULT_MAX_FILTER_DEPTH,
+) -> Optional[Any]:
+    """Recursively build the filter predicate tree.
+
+    Root-column fields compile to a direct predicate; relationship paths compile
+    to correlated EXISTS, so nothing is joined onto the outer query here. ``depth``
+    counts ``$and``/``$or`` nesting and is bounded by ``max_depth``.
+    """
+    if not isinstance(filters, dict):
+        raise FilterError("Invalid filter format.")
+
+    operators = get_comparison_operators(case_sensitive=case_sensitive)
+    expressions = []
+
+    for key, value in filters.items():
+        if key in LOGICAL_OPERATORS:
+            if depth + 1 > max_depth:
+                raise FilterError("Filter nesting too deep.")
+            if not isinstance(value, list):
+                raise FilterError("Invalid filter format.")
+            sub_expressions = [
+                sub
+                for sub in (
+                    _parse_filters(
+                        model, sub_filter, filterable,
+                        case_sensitive=case_sensitive,
+                        depth=depth + 1, max_depth=max_depth,
+                    )
+                    for sub_filter in value
+                )
+                if sub is not None
+            ]
+            if sub_expressions:
+                expressions.append(LOGICAL_OPERATORS[key](*sub_expressions))
+
+        elif isinstance(value, dict):
+            ensure_allowed(key, filterable, FilterError, "Unknown or disallowed filter field.")
+            parts = key.split(".")
+            for operator, operand in value.items():
+                expressions.append(
+                    _field_predicate(model, parts, operator, operand, operators)
+                )
+        else:
+            raise FilterError("Invalid filter format.")
+
+    return and_(*expressions) if expressions else None
+
+
+def _field_predicate(model, parts: List[str], operator: str, operand: Any, operators) -> Any:
+    """One field predicate: a direct comparison for a root column, or a correlated
+    EXISTS chain for a relationship path. Type validation runs on the leaf column."""
+    if operator not in operators:
+        raise FilterError("Invalid or unsupported operator.")
+
+    def make_leaf(column):
+        validate_operator(column, operator)  # type-aware (spec §9), on the leaf
+        if operator in NULL_OPERATORS:
+            return operators[operator](column)
+        return operators[operator](column, operand)
+
+    leaf, _ = describe_path(model, parts)
+    predicate = make_leaf(leaf)
+    return predicate if len(parts) == 1 else _wrap_relationship(model, parts, predicate)
+
+
+def _wrap_relationship(model, parts: List[str], inner: Any) -> Any:
+    """Wrap a prebuilt leaf predicate in the ``.has()`` (to-one) / ``.any()``
+    (to-many) chain for ``parts[:-1]``, yielding a correlated EXISTS. Auto-selected
+    by ``uselist`` — the caller never chooses join vs EXISTS. Shared by filters and
+    search; the path is assumed already validated by ``describe_path``."""
+    name, rest = parts[0], parts[1:]
+    rel_attr = getattr(model, name)
+    prop = rel_attr.property
+    wrapped = inner if len(rest) == 1 else _wrap_relationship(prop.mapper.class_, rest, inner)
+    return rel_attr.any(wrapped) if prop.uselist else rel_attr.has(wrapped)
+
+
+def _build_search(model, term: str, searchable: frozenset) -> Optional[Any]:
+    """OR a single search term across the declared searchable paths.
+
+    Relationship paths compile to correlated EXISTS (to-many included); root
+    columns compile directly. The client supplies only the term, never the field
+    list, so there is no per-field allowlist check here.
+    """
+    expressions = []
+    for path in sorted(searchable):
+        parts = path.split(".")
+        leaf, _ = describe_path(model, parts)
+        expr = _search_leaf(leaf, term)
+        if expr is None:
+            continue
+        expressions.append(expr if len(parts) == 1 else _wrap_relationship(model, parts, expr))
+    return or_(*expressions) if expressions else None
+
+
+def _search_leaf(column: Any, term: str):
+    """Per-column-type search expression, or None when the term doesn't apply.
+
+    Enum search matches by VALUE (resolving members whose value contains the term),
+    consistent with ``$contains`` filtering — not the stored member name.
+    """
+    if is_enum_column(column):
+        members = enum_value_members(column, term)
+        if members is None:  # raw value enum (no Python class) -> text match
+            return cast(column, String).ilike(f"%{term}%")
+        return column.in_(members)
+    if is_string_column(column):
+        return column.ilike(f"%{term}%")
+    if is_integer_column(column):
+        return (column == int(term)) if term.isdigit() else None
+    if is_boolean_column(column):
+        low = term.casefold()
+        if low in ("true", "false"):
+            return column == (low == "true")
+        return None
+    return None
+
+
+def _apply_sort(
+    model,
+    sort_value: str,
+    query: Select,
+    sortable: frozenset,
+    *,
+    case_sensitive: bool,
+) -> Select:
+    joins: JoinCache = {}  # path-keyed; reused across multi-clause sorts
+    order_expressions = []
+    for path_parts, direction in _parse_sort_clauses(sort_value):
+        field_path = ".".join(path_parts)
+        ensure_allowed(field_path, sortable, SortError, "Unknown or disallowed sort field.")
+        column, query = resolve_path(model, path_parts, query, joins)
+        expr = _sort_expr(column, case_sensitive=case_sensitive)
+        order_expressions.append(asc(expr) if direction == "asc" else desc(expr))
+    if order_expressions:
+        query = query.order_by(*order_expressions)
+    return query
+
+
+def _parse_sort_clauses(sort_value: str) -> List[Tuple[List[str], str]]:
+    """Parse ``"name:asc,organization.name:desc"`` (dot or double-underscore notation)."""
+    if not sort_value or not sort_value.strip():
+        return []
+
+    parsed: List[Tuple[List[str], str]] = []
+    for clause in (c.strip() for c in sort_value.split(",")):
+        if not clause:
+            continue
+        if ":" in clause:
+            raw_field, _, raw_dir = clause.partition(":")
+            raw_field = raw_field.strip()
+            raw_dir = raw_dir.strip().lower() or "asc"
+        else:
+            raw_field, raw_dir = clause, "asc"
+
+        if not raw_field:
+            raise SortError("Invalid sort field.")
+        if raw_dir not in ("asc", "desc"):
+            raise SortError("Invalid sort direction.")
+
+        path_parts = [p.strip() for p in raw_field.replace("__", ".").split(".")]
+        if any(not p for p in path_parts):
+            raise SortError("Invalid sort field.")
+        parsed.append((path_parts, raw_dir))
+
+    return parsed
+
+
+def _sort_expr(column: Any, *, case_sensitive: bool):
+    """Sort expression. Real date/datetime columns sort directly; strings sort
+    case-insensitively by default; enums are cast to text before ``lower()``.
+
+    The fork's fragile "string column named ``*_at`` is a timestamp" heuristic is
+    intentionally dropped (spec §16): fix the column type instead.
+    """
+    if is_datetime_like_column(column):
+        return column
+    if not case_sensitive:
+        if is_enum_column(column):
+            return func.lower(cast(column, String))
+        if is_string_column(column):
+            return func.lower(column)
+    return column

querybuilder/columns.py

@@ -0,0 +1,64 @@
+"""Column type predicates, centralized so operators, resolver, and builder agree
+on what counts as a string / enum / numeric / boolean / datetime column.
+
+These are deliberately the single source of truth: the fork duplicated this logic
+across modules and they drifted.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any
+
+from sqlalchemy import Date, DateTime, Enum, String
+
+
+def _python_type(column: Any):
+    """Best-effort Python type for a column, or None if undefined.
+
+    ``column.type.python_type`` raises ``NotImplementedError`` for some types, so
+    this is guarded.
+    """
+    col_type = getattr(column, "type", None)
+    try:
+        return col_type.python_type
+    except (NotImplementedError, AttributeError):
+        return None
+
+
+def is_enum_column(column: Any) -> bool:
+    return isinstance(getattr(column, "type", None), Enum)
+
+
+def is_string_column(column: Any) -> bool:
+    """True for string columns.
+
+    NOTE: SQLAlchemy's ``Enum`` subclasses ``String``, so this also returns True
+    for enum columns. Callers that must treat enums differently should check
+    :func:`is_enum_column` first.
+    """
+    return isinstance(getattr(column, "type", None), String)
+
+
+def is_string_like_column(column: Any) -> bool:
+    return is_string_column(column) or is_enum_column(column)
+
+
+def is_datetime_like_column(column: Any) -> bool:
+    return isinstance(getattr(column, "type", None), (Date, DateTime))
+
+
+def is_integer_column(column: Any) -> bool:
+    # Identity check keeps Boolean (python_type is bool) out, even though bool is
+    # a subclass of int.
+    return _python_type(column) is int
+
+
+def is_boolean_column(column: Any) -> bool:
+    return _python_type(column) is bool
+
+
+def is_numeric_column(column: Any) -> bool:
+    # bool is excluded: its python_type is bool, which is not in this set
+    # (membership compares by ==, and bool != int as type objects).
+    return _python_type(column) in (int, float, Decimal)

querybuilder/dates.py

@@ -0,0 +1,57 @@
+"""Date parsing and date-only range expansion (ported from the fork's utils).
+
+A date-only string (``"2024-01-15"``) compared against a DateTime column expands
+to a full-day range, so ``$eq`` on a date matches the whole day rather than only
+midnight. Full datetimes are used as-is.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from functools import lru_cache
+from typing import Any, Tuple
+
+from sqlalchemy import DateTime
+from sqlalchemy.sql import and_, or_
+
+from .errors import FilterError
+
+_FORMATS = ("%Y-%m-%d", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%SZ")
+
+
+@lru_cache(maxsize=512)
+def parse_datetime(value: str) -> datetime:
+    for fmt in _FORMATS:
+        try:
+            return datetime.strptime(value, fmt)
+        except ValueError:
+            continue
+    raise FilterError("Invalid date value.")
+
+
+def adjust_date_range(column: Any, value: Any, operator: str) -> Tuple[Any, bool]:
+    """Return ``(value_or_expression, is_range)``.
+
+    For a date-only string on a DateTime column, returns a full-day range
+    expression (``is_range=True``) for ``$eq``/``$ne`` or a shifted boundary for
+    the ordering operators. Otherwise returns the parsed/raw value unchanged.
+    """
+    if not isinstance(getattr(column, "type", None), DateTime) or not isinstance(value, str):
+        return value, False
+
+    dt = parse_datetime(value)
+    is_date_only = ("T" not in value) and (" " not in value)
+    if is_date_only:
+        if operator == "$eq":
+            return and_(column >= dt, column < dt + timedelta(days=1)), True
+        if operator == "$ne":
+            return or_(column < dt, column >= dt + timedelta(days=1)), True
+        if operator == "$gt":
+            return dt + timedelta(days=1), False
+        if operator == "$gte":
+            return dt, False
+        if operator == "$lt":
+            return dt, False
+        if operator == "$lte":
+            return dt + timedelta(days=1), False
+    return dt, False

querybuilder/errors.py

@@ -0,0 +1,43 @@
+"""Exception types for querybuilder.
+
+Client-input failures subclass :class:`fastapi.HTTPException` so FastAPI renders
+them as HTTP 400 with a generic, schema-free message — never a model class name
+or a column list (see spec §19). Programmer mistakes (e.g. an endpoint widening
+past the model allowlist, or a malformed allowlist entry) raise
+:class:`QueryConfigurationError`, which is *not* an HTTPException because it is a
+bug to fix at deploy time, not a client error to report.
+"""
+
+from __future__ import annotations
+
+from fastapi import HTTPException
+
+
+class QueryBuilderError(HTTPException):
+    """Base for client-facing query errors. Always HTTP 400, always generic."""
+
+    def __init__(self, detail: str = "Invalid query.") -> None:
+        super().__init__(status_code=400, detail=detail)
+
+
+class FilterError(QueryBuilderError):
+    def __init__(self, detail: str = "Invalid filter.") -> None:
+        super().__init__(detail=detail)
+
+
+class SortError(QueryBuilderError):
+    def __init__(self, detail: str = "Invalid sort.") -> None:
+        super().__init__(detail=detail)
+
+
+class SearchError(QueryBuilderError):
+    def __init__(self, detail: str = "Invalid search.") -> None:
+        super().__init__(detail=detail)
+
+
+class QueryConfigurationError(Exception):
+    """Raised for developer misconfiguration (not a client error).
+
+    Surfaces as an unhandled 500 in production, which is correct: it means the
+    code declared an allowlist or path that the library cannot honor.
+    """

querybuilder/mixin.py

@@ -0,0 +1,30 @@
+"""The Queryable mixin: declarative, deny-by-default policy declared on the model.
+
+This is the Pythonic equivalent of a Spatie/Eloquent trait — the model declares
+the maximum set of fields that may ever be filtered, sorted, or searched. An
+endpoint may narrow these further (see ``build_query``'s ``allowed_*`` arguments)
+but can never widen beyond them.
+"""
+
+from __future__ import annotations
+
+
+class Queryable:
+    """Declarative allowlist for query building. Deny-by-default.
+
+    A field path is filterable / sortable / searchable **only** if it appears in
+    the matching frozenset. Relationship paths use dotted notation, e.g.
+    ``"organization.name"``. The three sets are independent: a field may be
+    sortable without being filterable.
+
+    Example::
+
+        class User(Base, Queryable):
+            __filterable__ = frozenset({"status", "username", "organization.name"})
+            __sortable__   = frozenset({"created_at", "username"})
+            __searchable__ = frozenset({"username", "organization.name"})
+    """
+
+    __filterable__: frozenset[str] = frozenset()
+    __sortable__: frozenset[str] = frozenset()
+    __searchable__: frozenset[str] = frozenset()

querybuilder/operators.py

@@ -0,0 +1,294 @@
+"""Operator dispatch table.
+
+Differences from the fork (per spec §6):
+- ``$isempty``/``$isnotempty`` renamed to ``$isnull``/``$isnotnull``.
+- Added ``$nin`` (not-in); dropped the ``$isanyof`` alias.
+- Removed the ``$eq: "" -> IS NULL`` transform — empty string and NULL are
+  different; callers use ``$isnull`` explicitly.
+
+Enum handling (refines spec §18): SQLAlchemy persists the enum member *name* by
+default, so the fork's "cast to text and compare to the operand" silently returned
+zero rows whenever ``name.lower() != value``. Instead, for enum columns that carry
+a Python enum class we resolve the operand to the matching member(s) and compare
+natively (``col.in_(members)``) — correct regardless of whether the database stores
+names or values. Equality matches the operand against member value *or* name;
+substring operators match the member value. Raw ``Enum("a", "b")`` columns with no
+Python class fall back to the text comparison (there the stored text *is* the value).
+
+Per-type operator *validation* (rejecting e.g. ``$contains`` on an integer) lives
+in ``validation.py``; this module only defines the operators themselves.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List
+
+from sqlalchemy import String, and_, cast, func, or_
+from sqlalchemy.sql import operators as sa_operators
+
+from .columns import is_enum_column, is_string_like_column
+from .dates import adjust_date_range
+from .errors import FilterError
+
+LOGICAL_OPERATORS: Dict[str, Callable] = {"$and": and_, "$or": or_}
+
+#: Operators that take only a column (the JSON operand is ignored).
+NULL_OPERATORS = frozenset({"$isnull", "$isnotnull"})
+
+
+# --- enum resolution --------------------------------------------------------
+
+def _enum_class(column):
+    """The Python enum class behind an Enum column, or None (raw value enums)."""
+    return getattr(getattr(column, "type", None), "enum_class", None)
+
+
+def _member_value(member) -> str:
+    value = member.value
+    return value.casefold() if isinstance(value, str) else str(value).casefold()
+
+
+def _enum_members(enum_class, value: Any, match: str) -> List[Any]:
+    """Members of ``enum_class`` matching ``value`` under ``match``.
+
+    ``exact`` matches the operand against member value *or* name; the substring
+    matches (``contains``/``startswith``/``endswith``) match the member value.
+    An operand that is already a member is taken as-is.
+    """
+    if isinstance(value, enum_class):
+        return [value]
+    target = (value if isinstance(value, str) else str(value)).casefold()
+    out = []
+    for member in enum_class:
+        mv = _member_value(member)
+        if match == "exact":
+            ok = target == mv or target == member.name.casefold()
+        elif match == "contains":
+            ok = target in mv
+        elif match == "startswith":
+            ok = mv.startswith(target)
+        elif match == "endswith":
+            ok = mv.endswith(target)
+        else:  # pragma: no cover - guarded by callers
+            ok = False
+        if ok:
+            out.append(member)
+    return out
+
+
+def _enum_match(enum_class, values: List[Any], match: str) -> List[Any]:
+    """Resolve a list of operands to a de-duplicated member list."""
+    seen = set()
+    result = []
+    for value in values:
+        for member in _enum_members(enum_class, value, match):
+            if member not in seen:
+                seen.add(member)
+                result.append(member)
+    return result
+
+
+def enum_value_members(column, term: str):
+    """Members of an enum column whose ``.value`` contains ``term`` (case-insensitive),
+    or ``None`` if the column's Enum has no Python class (a raw value enum). Lets
+    value-based search reuse the same member resolution as ``$contains`` filtering."""
+    enum_class = _enum_class(column)
+    if enum_class is None:
+        return None
+    return _enum_match(enum_class, [term], "contains")
+
+
+# --- string helpers ---------------------------------------------------------
+
+def _casefold_string_like(value: Any):
+    """Casefold plain strings and enum-member ``.value`` strings; else None."""
+    if isinstance(value, str):
+        return value.casefold()
+    enum_value = getattr(value, "value", None)
+    if isinstance(enum_value, str):
+        return enum_value.casefold()
+    return None
+
+
+def _ci_expr(column):
+    """Case-insensitive comparison target (enum-safe, for raw value enums)."""
+    if is_enum_column(column):
+        return func.lower(cast(column, String))
+    return func.lower(column)
+
+
+def _ilike_target(column):
+    """ILIKE target (enums cast to text so Postgres doesn't choke)."""
+    if is_enum_column(column):
+        return cast(column, String)
+    return column
+
+
+def _require_list(value: Any) -> None:
+    if not isinstance(value, (list, tuple)):
+        raise FilterError("This operator expects a list value.")
+
+
+def _normalized_list(column, value):
+    return [
+        (_casefold_string_like(v) if _casefold_string_like(v) is not None else v)
+        for v in value
+    ]
+
+
+# --- comparison -------------------------------------------------------------
+
+def _eq(column, value):
+    enum_class = _enum_class(column)
+    if enum_class is not None:
+        return column.in_(_enum_match(enum_class, [value], "exact"))
+    adjusted, is_range = adjust_date_range(column, value, "$eq")
+    return adjusted if is_range else column == adjusted
+
+
+def _eq_ci(column, value):
+    enum_class = _enum_class(column)
+    if enum_class is not None:
+        return column.in_(_enum_match(enum_class, [value], "exact"))
+    norm = _casefold_string_like(value)
+    if norm is not None and is_string_like_column(column):
+        return _ci_expr(column) == norm
+    adjusted, is_range = adjust_date_range(column, value, "$eq")
+    return adjusted if is_range else column == adjusted
+
+
+def _ne(column, value):
+    enum_class = _enum_class(column)
+    if enum_class is not None:
+        return column.not_in(_enum_match(enum_class, [value], "exact"))
+    adjusted, is_range = adjust_date_range(column, value, "$ne")
+    return adjusted if is_range else column != adjusted
+
+
+def _ne_ci(column, value):
+    enum_class = _enum_class(column)
+    if enum_class is not None:
+        return column.not_in(_enum_match(enum_class, [value], "exact"))
+    norm = _casefold_string_like(value)
+    if norm is not None and is_string_like_column(column):
+        return _ci_expr(column) != norm
+    adjusted, is_range = adjust_date_range(column, value, "$ne")
+    return adjusted if is_range else column != adjusted
+
+
+def _gt(column, value):
+    return sa_operators.gt(column, adjust_date_range(column, value, "$gt")[0])
+
+
+def _gte(column, value):
+    return sa_operators.ge(column, adjust_date_range(column, value, "$gte")[0])
+
+
+def _lt(column, value):
+    return sa_operators.lt(column, adjust_date_range(column, value, "$lt")[0])
+
+
+def _lte(column, value):
+    return sa_operators.le(column, adjust_date_range(column, value, "$lte")[0])
+
+
+def _in(column, value):
+    _require_list(value)
+    enum_class = _enum_class(column)
+    if enum_class is not None:
+        return column.in_(_enum_match(enum_class, list(value), "exact"))
+    return column.in_(value)
+
+
+def _in_ci(column, value):
+    _require_list(value)
+    enum_class = _enum_class(column)
+    if enum_class is not None:
+        return column.in_(_enum_match(enum_class, list(value), "exact"))
+    if is_string_like_column(column):
+        return _ci_expr(column).in_(_normalized_list(column, value))
+    return column.in_(value)
+
+
+def _nin(column, value):
+    _require_list(value)
+    enum_class = _enum_class(column)
+    if enum_class is not None:
+        return column.not_in(_enum_match(enum_class, list(value), "exact"))
+    return column.not_in(value)
+
+
+def _nin_ci(column, value):
+    _require_list(value)
+    enum_class = _enum_class(column)
+    if enum_class is not None:
+        return column.not_in(_enum_match(enum_class, list(value), "exact"))
+    if is_string_like_column(column):
+        return _ci_expr(column).not_in(_normalized_list(column, value))
+    return column.not_in(value)
+
+
+# --- string -----------------------------------------------------------------
+
+def _contains(column, value):
+    enum_class = _enum_class(column)
+    if enum_class is not None:
+        return column.in_(_enum_match(enum_class, [value], "contains"))
+    return _ilike_target(column).ilike(f"%{value}%")
+
+
+def _ncontains(column, value):
+    enum_class = _enum_class(column)
+    if enum_class is not None:
+        return column.not_in(_enum_match(enum_class, [value], "contains"))
+    return ~_ilike_target(column).ilike(f"%{value}%")
+
+
+def _startswith(column, value):
+    enum_class = _enum_class(column)
+    if enum_class is not None:
+        return column.in_(_enum_match(enum_class, [value], "startswith"))
+    return _ilike_target(column).ilike(f"{value}%")
+
+
+def _endswith(column, value):
+    enum_class = _enum_class(column)
+    if enum_class is not None:
+        return column.in_(_enum_match(enum_class, [value], "endswith"))
+    return _ilike_target(column).ilike(f"%{value}")
+
+
+# --- null -------------------------------------------------------------------
+
+def _isnull(column):
+    return column.is_(None)
+
+
+def _isnotnull(column):
+    return column.is_not(None)
+
+
+def get_comparison_operators(case_sensitive: bool = False) -> Dict[str, Callable]:
+    eq = _eq if case_sensitive else _eq_ci
+    ne = _ne if case_sensitive else _ne_ci
+    in_ = _in if case_sensitive else _in_ci
+    nin = _nin if case_sensitive else _nin_ci
+    return {
+        "$eq": eq,
+        "$ne": ne,
+        "$gt": _gt,
+        "$gte": _gte,
+        "$lt": _lt,
+        "$lte": _lte,
+        "$in": in_,
+        "$nin": nin,
+        "$contains": _contains,
+        "$ncontains": _ncontains,
+        "$startswith": _startswith,
+        "$endswith": _endswith,
+        "$isnull": _isnull,
+        "$isnotnull": _isnotnull,
+    }
+
+
+COMPARISON_OPERATORS = get_comparison_operators(case_sensitive=False)

querybuilder/params.py

@@ -0,0 +1,39 @@
+"""FastAPI-injectable query parameters.
+
+Routers depend on :class:`QueryParams` and pass it through to ``build_query`` in
+your data/query layer (keep the builder out of route handlers).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import Query
+
+
+class QueryParams:
+    def __init__(
+        self,
+        filters: Optional[str] = Query(
+            None,
+            description='JSON filter object, e.g. {"status":{"$eq":"active"},"organization.name":{"$contains":"acme"}}.',
+        ),
+        sort: Optional[str] = Query(
+            None,
+            description="Comma-separated sort clauses, e.g. created_at:desc,username:asc.",
+        ),
+        search: Optional[str] = Query(
+            None,
+            description="Search term applied across the model's declared searchable fields.",
+        ),
+        case_sensitive: bool = Query(
+            False,
+            description="When true, string filters and sorting are case-sensitive (default: case-insensitive).",
+        ),
+    ):
+        self.filters = filters
+        self.sort = sort
+        self.search = search
+        # Guard direct (non-FastAPI) instantiation, where an unset bool default
+        # would arrive as a Query() FieldInfo rather than a real bool.
+        self.case_sensitive = case_sensitive if isinstance(case_sensitive, bool) else False

querybuilder/resolver.py

@@ -0,0 +1,100 @@
+"""Path-aware relationship resolver, used by **sort** (relationships in ORDER BY).
+
+The join cache is keyed by ``(relationship_path_tuple, target_model)`` rather than
+by target model class alone, so two distinct sort paths to the same model (e.g.
+``home_address.city`` and ``work_address.city``, both to ``Address``) get two
+distinct aliases instead of colliding into one.
+
+To-one relationships use a path-aliased LEFT OUTER JOIN (so sorting never drops
+rows). To-many relationships are rejected — you can't ``ORDER BY`` a to-many
+column. Filters and search compile relationships to correlated EXISTS instead
+(see ``builder``); ``describe_path`` below is the shared no-join path walker they
+use to find the leaf column.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Tuple
+
+from sqlalchemy.orm import RelationshipProperty, aliased
+from sqlalchemy.sql import Select
+
+from .errors import FilterError, QueryConfigurationError
+
+#: (relationship path tuple, target model) -> alias
+JoinCache = Dict[Tuple[Tuple[str, ...], type], Any]
+
+
+def resolve_path(
+    model: Any,
+    path_parts: List[str],
+    query: Select,
+    joins: JoinCache,
+) -> Tuple[Any, Select]:
+    """Resolve a field path to ``(column, query)``, adding path-keyed joins.
+
+    ``path_parts`` is the already-split path, e.g. ``["organization", "name"]``. The
+    final segment must be a column; every earlier segment must be a to-one
+    relationship.
+    """
+    current = model
+    rel_path: List[str] = []
+
+    for index, attr in enumerate(path_parts):
+        candidate = getattr(current, attr, None)
+        prop = getattr(candidate, "property", None)
+
+        if isinstance(prop, RelationshipProperty):
+            if prop.uselist:
+                # You can't ORDER BY a to-many column, and a plain join would
+                # multiply root rows. (Filters/search handle to-many via EXISTS.)
+                raise QueryConfigurationError(
+                    "To-many relationship paths cannot be sorted."
+                )
+            related = prop.mapper.class_
+            rel_path.append(attr)
+            key = (tuple(rel_path), related)
+            if key not in joins:
+                alias = aliased(related)
+                joins[key] = alias
+                query = query.outerjoin(candidate.of_type(alias))
+            current = joins[key]
+            continue
+
+        # Not a relationship: must be the terminal column.
+        if index != len(path_parts) - 1:
+            raise FilterError("Unknown or disallowed field.")
+        if candidate is None:
+            raise FilterError("Unknown or disallowed field.")
+        return candidate, query
+
+    # Path ended on a relationship rather than a column.
+    raise FilterError("Unknown or disallowed field.")
+
+
+def describe_path(model: Any, path_parts: List[str]) -> Tuple[Any, bool]:
+    """Walk a dotted path WITHOUT joining; return ``(leaf_column, has_to_many)``.
+
+    ``has_to_many`` is True if any traversed relationship is to-many. Used by the
+    filter/search EXISTS builders (to find the leaf column) and by
+    ``validate_queryable``. Raises :class:`FilterError` if a segment is missing, an
+    intermediate segment is not a relationship, or the path does not end on a column.
+    """
+    current = model
+    has_to_many = False
+    for index, attr in enumerate(path_parts):
+        candidate = getattr(current, attr, None)
+        prop = getattr(candidate, "property", None)
+        is_last = index == len(path_parts) - 1
+
+        if isinstance(prop, RelationshipProperty):
+            if is_last:  # path ends on a relationship, not a column
+                raise FilterError("Unknown or disallowed field.")
+            has_to_many = has_to_many or bool(prop.uselist)
+            current = prop.mapper.class_
+        else:
+            if not is_last or candidate is None:
+                raise FilterError("Unknown or disallowed field.")
+            return candidate, has_to_many
+
+    raise FilterError("Unknown or disallowed field.")

querybuilder/validation.py

@@ -0,0 +1,58 @@
+"""Type-aware operator validation (spec §9).
+
+After a field passes the allowlist and resolves to a column, its operator is
+checked against the column's type. This is the second safety layer: even an
+allowlisted column cannot be probed with an operator that makes no sense for its
+type (e.g. ``$contains`` on an integer, or ordering on an enum), which closes the
+blind-enumeration surface.
+
+``$isnull`` / ``$isnotnull`` are allowed on every type — a column reached through a
+LEFT JOIN is effectively nullable in the result (the row may have no related
+record), so "nullable only" would wrongly reject valid queries.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .columns import (
+    is_boolean_column,
+    is_datetime_like_column,
+    is_enum_column,
+    is_numeric_column,
+    is_string_column,
+)
+from .errors import FilterError
+
+_EQUALITY = frozenset({"$eq", "$ne", "$in", "$nin"})
+_NULL = frozenset({"$isnull", "$isnotnull"})
+_SUBSTRING = frozenset({"$contains", "$ncontains", "$startswith", "$endswith"})
+_ORDERING = frozenset({"$gt", "$gte", "$lt", "$lte"})
+
+_STRING_OPS = _EQUALITY | _SUBSTRING | _NULL
+_NUMERIC_OPS = _EQUALITY | _ORDERING | _NULL
+_DATETIME_OPS = _EQUALITY | _ORDERING | _NULL
+_BOOLEAN_OPS = frozenset({"$eq", "$ne"}) | _NULL
+#: Conservative default for column types we don't specifically recognize.
+_OTHER_OPS = _EQUALITY | _NULL
+
+
+def allowed_operators_for(column: Any) -> frozenset:
+    """The operators permitted for a column, by its SQLAlchemy type."""
+    # Enum subclasses String, so enum and string share the same set; checking
+    # either first is fine.
+    if is_enum_column(column) or is_string_column(column):
+        return _STRING_OPS
+    if is_boolean_column(column):
+        return _BOOLEAN_OPS
+    if is_numeric_column(column):
+        return _NUMERIC_OPS
+    if is_datetime_like_column(column):
+        return _DATETIME_OPS
+    return _OTHER_OPS
+
+
+def validate_operator(column: Any, operator: str) -> None:
+    """Raise a generic 400 if ``operator`` is not valid for ``column``'s type."""
+    if operator not in allowed_operators_for(column):
+        raise FilterError("Operator not allowed for this field.")