Add opt-in no-count pagination and window grouping

[hugohvf]

TL;DR

• Adds opt-in no-count pagination modes without changing default full pagination.
• Adds opt-in window grouped execution for simple/date grouped top-N use cases with legacy fallback.
• Documents rollout behavior and adds coverage for legacy and opt-in paths.

Summary

• Added pagination.mode: full remains the default and still runs the count query, none fetches items only, and has_next fetches limit + 1 then trims the extra row.
• Added grouping options for strategy, include_counts, per_group_limit, per_group_offset, and fallback.
• Added a window grouping strategy that uses one window-function query for supported simple model-field selections and simple/date group keys.
• Unsupported relationship selects, relationship group fields, and custom value sort dictionaries fall back to legacy by default or raise a clear error when fallback is error.
• Legacy request payload serialization and default grouped/paginated execution stay unchanged unless callers provide the new option blocks.
• Updated pagination/grouping docs and changelog entries.

Flow

flowchart TD
    A[Querymate request] --> B{pagination.mode}
    B -->|full default| C[Fetch page and run count]
    B -->|none| D[Fetch page only]
    B -->|has_next| E[Fetch limit plus one and trim]
    A --> F{grouping.strategy}
    F -->|legacy default| G[Group keys plus per-group item queries]
    F -->|window opt-in| H{Supported shape}
    H -->|yes| I[Single window query for top N per group]
    H -->|no, fallback legacy| G
    H -->|no, fallback error| J[Clear validation error]

Loading

Tests

• uv run --python 3.13 ruff check querymate tests
• uv run --python 3.13 mypy querymate
• uv run --python 3.13 pytest -q

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 87.04663% with 25 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
querymate/core/querymate.py	85.11%	25 Missing ⚠️

📢 Thoughts on this report? Let us know!