DRF Filtering, Search, and Ordering

Key features

• Filter backends run in `filter_queryset()`, after `get_queryset()` and before pagination — so a filter can only ever narrow what the caller was already permitted to see
• `DjangoFilterBackend` lives in `django_filters.rest_framework`, not in DRF itself; `django_filters` goes in `INSTALLED_APPS`
• `filterset_fields = ["status", "customer"]` gives exact-match filtering on those fields and nothing else — the fast path when that is all you need
• `filterset_fields` also accepts a dict for lookups: `{"created_at": ["gte", "lte"], "status": ["exact"]}` generates `created_at__gte` and `created_at__lte` parameters
• A `FilterSet` class is the full form — each declared filter names its `field_name`, its `lookup_expr`, and optionally a `method` for anything the ORM cannot express declaratively
• `DEFAULT_FILTER_BACKENDS` is empty by default, so nothing filters until you set it globally or per view

Command

filter_backends = [DjangoFilterBackend]
filterset_class = OrderFilter     # or: filterset_fields = ["status", "customer"]

Key features

• `SearchFilter` reads `?search=` by default; the parameter name comes from the `SEARCH_PARAM` setting
• A `search_fields` entry with no prefix uses `icontains`; prefixes change it — `^` is `istartswith`, `=` is `iexact`, `@` is PostgreSQL full-text `search`, `$` is `iregex`
• Multiple `search_fields` are OR-ed together for a single term, and multiple space-separated terms are AND-ed across the whole field set
• `OrderingFilter` reads `?ordering=` (settable via `ORDERING_PARAM`); a leading `-` reverses, commas separate multiple keys, and `ordering = ["-created_at"]` sets the default when the client sends nothing
• With `ordering_fields` unset, DRF allows ordering on any field readable on the serializer — the docs warn this can leak data such as a password hash; `"__all__"` is the explicit opt-in
• A custom backend is one method — `filter_queryset(self, request, queryset, view)` — and putting it in `DEFAULT_FILTER_BACKENDS` applies it to every list endpoint in the project

Command

filter_backends = [SearchFilter, OrderingFilter]
search_fields = ["^sku", "name"]
ordering_fields = ["name", "price"]   # never leave this unset

Key features

• An unrecognised query parameter is silently ignored by both DRF and django-filter — `?statuss=paid` returns everything, with a 200
• A `FilterSet` validates declared parameters and returns 400 with per-field messages; parameters outside it are still ignored unless you check the names yourself
• Deep pagination is the common expensive case: `OFFSET 20000` makes the database produce and discard 20,000 rows before the page it returns
• Ordering on an unindexed column forces a sort of the whole filtered set before pagination can take a slice
• A required filter is expressed by overriding the FilterSet's `is_valid()`/`clean()` or by checking in `filter_queryset()` and raising `ValidationError` — a 400, not an empty list
• PostgreSQL's `statement_timeout` is the backstop: it caps what any single query can cost, whatever the application layer failed to prevent

Command

class StrictFilterSet(FilterSet):
    def is_valid(self):
        unknown = set(self.data) - set(self.filters) - {"page", "page_size", "ordering"}
        if unknown:
            raise ValidationError({"detail": f"Unknown parameters: {sorted(unknown)}"})
        return super().is_valid()