fastapi-sqlalchemy-querykit 0.1.0__tar.gz

fastapi_sqlalchemy_querykit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+# Builds on every version tag and publishes to PyPI via Trusted Publishing.
+#
+# One-time setup before the first release:
+#   1. Push this repo to GitHub.
+#   2. On PyPI, create a "pending publisher" (Account -> Publishing) for project
+#      `fastapi-sqlalchemy-querykit` (the PyPI project), repo = your GitHub repo name:
+#        owner = <your GitHub org/user>, repo = <repo name>,
+#        workflow = release.yml, environment = pypi
+#   3. Tag a release:  git tag v0.1.0 && git push origin v0.1.0
+# No API token is stored — OIDC handles auth.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fastapi_sqlalchemy_querykit-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Docs site (mkdocs output)
+site/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

fastapi_sqlalchemy_querykit-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-06-02
+
+First public release. A deny-by-default query builder for FastAPI + SQLAlchemy 2.0,
+derived from [fastapi-querybuilder](https://github.com/bhadri01/fastapi-querybuilder)
+(bhadri01, MIT) and hardened throughout.
+
+### Added
+- `Queryable` mixin with deny-by-default `__filterable__` / `__sortable__` /
+  `__searchable__` allowlists, and endpoint-level narrowing via `build_query`'s
+  `allowed_*` arguments.
+- Filter operators: `$eq` `$ne` `$gt` `$gte` `$lt` `$lte` `$in` `$nin`,
+  `$contains` `$ncontains` `$startswith` `$endswith`, `$isnull` `$isnotnull`, and
+  logical `$and` / `$or`.
+- Type-aware operator validation (per-column-type matrix) and enum matching by
+  value (Postgres-safe), case-insensitive string comparison by default with a
+  `case_sensitive` escape hatch, and date-only range expansion.
+- Correlated `EXISTS` for relationship filters and search (`.has()` to-one,
+  `.any()` to-many, auto-selected by `uselist`) — no fan-out, no `DISTINCT`,
+  to-many supported; path-keyed LEFT JOIN for relationship sorting.
+- Search across the declared searchable set (root + relationship paths); sort with
+  case-insensitive / enum-aware / datetime-aware ordering.
+- `validate_queryable` / `validate_queryables` for startup allowlist validation.
+- Filter payload size and `$and`/`$or` depth limits (`max_filter_bytes`,
+  `max_filter_depth`).
+- Generic, schema-free `400` errors; `py.typed`. Runtime dependencies limited to
+  `fastapi` and `sqlalchemy`.
+
+### Notably different from the fork
+- Deny-by-default instead of open-by-default.
+- Path-keyed relationship resolution (two paths to the same model no longer
+  collide); correlated `EXISTS` for to-many instead of fan-out joins.
+- Caller-owned base scope (no hardcoded soft-delete); generic non-leaking errors.
+- Removed the `$eq: "" → IS NULL` transform, `$isanyof`, and `$isempty`/`$isnotempty`.

fastapi_sqlalchemy_querykit-0.1.0/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/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.

fastapi_sqlalchemy_querykit-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,88 @@
+# 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/docs/guide.md

@@ -0,0 +1,132 @@
+# Guide
+
+## The `Queryable` mixin (deny-by-default)
+
+A model declares what may be filtered, sorted, and searched — and nothing else is
+allowed. Add the mixin and the three frozensets:
+
+```python
+from querybuilder import Queryable
+
+class User(Base, Queryable):
+    __filterable__ = frozenset({
+        "username", "status", "age", "created_at",
+        "organization.name", "organization.region.name",  # to-one chains
+        "posts.title",                                     # to-many (EXISTS)
+    })
+    __sortable__   = frozenset({"username", "status", "created_at", "organization.name"})
+    __searchable__ = frozenset({"username", "organization.name", "posts.title"})
+```
+
+- A field path absent from the relevant set produces a **400**.
+- The three sets are independent: a field can be sortable without being filterable.
+- Relationship paths use dotted notation; every segment must be a real
+  relationship and the leaf must be a real column.
+
+## 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"})
+```
+
+Passing a field the model never declared is a configuration error
+(`QueryConfigurationError`), not a client 400.
+
+## Startup validation
+
+Catch typos and misconfigured allowlists at deploy time rather than per request:
+
+```python
+from querybuilder import validate_queryables
+
+validate_queryables(User, Order, Invoice)   # in app startup, after models import
+```
+
+It checks every declared path resolves to a real leaf column, and that
+`__sortable__` contains no to-many path (you can't `ORDER BY` a to-many). Run it
+**after** all models are imported (mappers must be configured).
+
+## Relationships (EXISTS)
+
+Relationship paths in **filters and search** compile to a correlated `EXISTS`,
+chosen automatically by relationship direction:
+
+- to-one → `.has(...)`
+- to-many → `.any(...)`
+- chains nest, e.g. `posts.category.name` → `posts.any(category.has(name == ...))`
+
+```text
+{"posts.title": {"$contains": "hello"}}
+  ->  EXISTS (SELECT 1 FROM posts WHERE posts.author_id = users.id
+                                    AND lower(posts.title) LIKE lower('%hello%'))
+```
+
+This never multiplies root rows (no fan-out, no `DISTINCT`), and two paths to the
+same model — e.g. `home_address.city` and `work_address.city` — are independent
+EXISTS that cannot collide.
+
+**Semantics.** A predicate on `rel.col` matches rows that *have a related row
+satisfying it*. A row with **no related row matches no relationship predicate** —
+including negatives: `{"organization.name": {"$ne": "acme"}}` means "has an org
+whose name ≠ acme", and `{"organization.region.name": {"$isnull": true}}` means
+"has a region whose name is null" (not "has no region"). A relationship-level
+"has / has-no related row" filter is out of scope for now.
+
+## Sorting
+
+```text
+sort=created_at:desc,organization.name:asc       # dot notation
+sort=organization__name:asc                       # double-underscore also accepted
+```
+
+- Validated against `__sortable__`; unknown field or bad direction → 400.
+- String sorting is case-insensitive by default (`case_sensitive=true` to opt out);
+  enums are cast to text before `lower(...)`; real date/datetime columns sort
+  directly.
+- Relationship sort paths use a **path-keyed LEFT JOIN** (sorting must never drop
+  rows, and the column must be projected to be ordered). To-many sort paths are
+  rejected.
+
+## Searching
+
+A single `search` term is OR-combined across the declared `__searchable__` set:
+
+- string → `ILIKE '%term%'`; enum → matched **by value** (same as `$contains`);
+  integer → exact match when the term is a number; boolean → `true` / `false`.
+- Relationship search paths use the same `EXISTS` as filters, so **to-many search**
+  works without fan-out.
+- Only declared paths are searched — the client supplies the term, never the field
+  list.
+
+## Errors
+
+All client-input failures return **HTTP 400** with a generic, schema-free message
+— never a model class name or column list. Examples: `Unknown or disallowed
+filter field.`, `Operator not allowed for this field.`, `Invalid filter format.`
+Developer misconfiguration (e.g. widening an endpoint past the model) raises
+`QueryConfigurationError`, which is a bug to fix, not a client error.
+
+## Payload limits
+
+`build_query` bounds the filter payload (spec-driven, overridable):
+
+```python
+build_query(User, params, max_filter_bytes=8192, max_filter_depth=10)
+```
+
+- `max_filter_bytes` — reject oversized filter JSON → `Filter payload too large.`
+- `max_filter_depth` — reject deep `$and`/`$or` nesting → `Filter nesting too deep.`
+
+## Caller-owned base scope
+
+`build_query` returns `select(model)` plus the filter/search/sort predicates. It
+**never** adds or inspects your mandatory scope — tenant, soft-delete, visibility.
+AND your own `WHERE` onto the result:
+
+```python
+stmt = build_query(User, params)
+stmt = stmt.where(User.org_id == ctx.org_id, User.is_deleted.is_(False))
+```

fastapi_sqlalchemy_querykit-0.1.0/docs/index.md

@@ -0,0 +1,68 @@
+# fastapi-sqlalchemy-querykit
+
+Deny-by-default declarative **filtering, sorting, and searching** for **FastAPI +
+SQLAlchemy 2.0** (async-safe).
+
+A list endpoint accepts a structured request — a JSON filter object, a sort
+string, a search term — and the library turns it into a safe SQLAlchemy `Select`.
+A field is queryable **only** if the model explicitly declares it; everything else
+is a generic `400`.
+
+```bash
+pip install fastapi-sqlalchemy-querykit
+```
+
+!!! note
+    The distribution is **`fastapi-sqlalchemy-querykit`**; the import package is
+    **`querybuilder`** (`from querybuilder import build_query`).
+
+## Why
+
+- **Deny by default.** Undeclared fields return a generic 400 — never a silent or
+  accidental query. The opposite of the open-by-default libraries this derives from.
+- **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.
+- **Type-aware.** Operators are validated against the column type (`$contains` on
+  an integer → 400). Enums match by value and are Postgres-safe.
+- **Caller-owned scope.** The builder is purely additive — it never adds or
+  inspects your tenant / soft-delete / visibility `WHERE`.
+- **Tiny surface.** Runtime dependencies: `fastapi` + `sqlalchemy` only. Ships
+  `py.typed`.
+
+## 60-second 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"})
+
+# in 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))   # your base scope, untouched
+    return (await db.execute(stmt)).scalars().all()
+```
+
+```text
+GET /users?filters={"status":{"$eq":"active"},"organization.name":{"$contains":"acme"}}
+          &sort=created_at:desc&search=jdoe
+```
+
+## Where to next
+
+- **[Operator reference](operators.md)** — the JSON wire format and every operator.
+- **[Guide](guide.md)** — the `Queryable` mixin, relationships, search, sort,
+  errors, limits, and startup validation.
+- **[FastAPI integration](integration.md)** — wiring `QueryParams` into endpoints.
+
+## Credits
+
+A derivative work of
+[fastapi-querybuilder](https://github.com/bhadri01/fastapi-querybuilder) by
+bhadri01 (MIT). MIT licensed — see `LICENSE` and `NOTICE`.

fastapi_sqlalchemy_querykit-0.1.0/docs/integration.md

@@ -0,0 +1,82 @@
+# FastAPI integration
+
+## `QueryParams`
+
+`QueryParams` is a FastAPI-injectable dependency exposing the four query-string
+parameters: `filters`, `sort`, `search`, `case_sensitive`. Depend on it in the
+router and pass it through to `build_query` — keep the builder out of the route
+handler and inside your data/query layer.
+
+```python
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from querybuilder import QueryParams, build_query
+
+router = APIRouter()
+
+# queries/users.py — the data layer owns the builder and the base scope
+async def list_users(db: AsyncSession, org_id: int, params: QueryParams):
+    stmt = build_query(User, params)
+    stmt = stmt.where(User.org_id == org_id, User.is_deleted.is_(False))  # base scope
+    result = await db.execute(stmt)
+    return result.scalars().all()
+
+# routers/users.py — the router just forwards params
+@router.get("/users")
+async def get_users(
+    params: QueryParams = Depends(),
+    db: AsyncSession = Depends(get_db),
+    ctx: CompanyContext = Depends(get_context),
+):
+    return await list_users(db, ctx.org_id, params)
+```
+
+The query string the client sends:
+
+```text
+GET /users?filters={"status":{"$eq":"active"}}&sort=created_at:desc&search=jdoe
+```
+
+## Pagination
+
+`build_query` returns a plain `Select`, so it composes with whatever pagination
+you already use — `.limit()/.offset()`, a `COUNT(*)` over the same statement, or a
+library such as `fastapi-pagination`:
+
+```python
+from fastapi_pagination.ext.sqlalchemy import paginate
+
+stmt = build_query(User, params).where(User.is_deleted.is_(False))
+page = await paginate(db, stmt)
+```
+
+Relationship filters/search are correlated `EXISTS`, so the count is correct
+(no fan-out duplicates).
+
+## Validate at startup
+
+Register a startup check so a bad allowlist entry fails fast:
+
+```python
+from contextlib import asynccontextmanager
+from querybuilder import validate_queryables
+
+@asynccontextmanager
+async def lifespan(app):
+    validate_queryables(User, Order, Invoice)   # raises QueryConfigurationError on a bad path
+    yield
+```
+
+## OpenAPI note
+
+The filter parameter is an opaque JSON string in Swagger (`filters: string`) — a
+deliberate tradeoff: the filter-builder UI constructs the payload, and the
+operator grammar is documented in the [operator reference](operators.md) rather
+than via generated parameter docs.
+
+## Notes
+
+- `company_id` / tenant scope comes from your request context, never from the
+  filter payload — the builder never reads it.
+- The builder is async-safe: it only constructs a `Select`; you execute it on your
+  `AsyncSession` as usual.