DRF Filtering, Search, and Ordering

What we're doing: Expose a small, deliberate filter surface on an orders endpoint, including one parameter the ORM cannot express declaratively.

class OrderFilter(django_filters.FilterSet):
    status = django_filters.ChoiceFilter(choices=Order.Status.choices)
    min_total = django_filters.NumberFilter(field_name="total", lookup_expr="gte")
    placed_after = django_filters.DateFilter(field_name="created_at", lookup_expr="gt")
    has_refund = django_filters.BooleanFilter(method="filter_has_refund")

    class Meta:
        model = Order
        fields = ["status", "min_total", "placed_after", "has_refund"]

    def filter_has_refund(self, queryset, name, value):
        return queryset.filter(refunds__isnull=not value).distinct()


class OrderViewSet(viewsets.ModelViewSet):
    serializer_class = OrderSerializer
    filter_backends = [DjangoFilterBackend]
    filterset_class = OrderFilter

    def get_queryset(self):
        return Order.objects.filter(customer=self.request.user)

2

`ChoiceFilter` rejects a value outside the model's own choices with a 400 rather than passing it to the database and returning an empty list — a wrong value and a valid-but-empty result stop looking alike.

3–4

`field_name` decouples the public parameter name from the column. `min_total` and `placed_after` read as API vocabulary; `total__gte` and `created_at__gt` leak the schema.

5–12

`method=` is the escape hatch for anything declarative filters cannot say. `.distinct()` matters here — joining to a reverse relation can multiply rows.

9

`Meta.fields` is the closed list. A parameter absent from it does not exist, which is what keeps the surface auditable.

20–21

Ownership scoping stays in `get_queryset()`, above every filter. No query parameter can reach another customer's orders, whatever it asks for.

Why this works: The `FilterSet` turns "which parameters does this endpoint accept" from something you reconstruct by reading `get_queryset()` into a declaration you can read in one place — and gives type coercion, choice validation, and 400-level errors without writing any of them.

What we're doing: Add project-wide tenant scoping as a custom backend, alongside per-view search and ordering.

class TenantScopeBackend(BaseFilterBackend):
    def filter_queryset(self, request, queryset, view):
        if not request.user.is_authenticated:
            return queryset.none()
        if not hasattr(queryset.model, "tenant_id"):
            return queryset
        return queryset.filter(tenant_id=request.user.tenant_id)


REST_FRAMEWORK = {
    "DEFAULT_FILTER_BACKENDS": [
        "common.filters.TenantScopeBackend",
        "django_filters.rest_framework.DjangoFilterBackend",
        "rest_framework.filters.SearchFilter",
        "rest_framework.filters.OrderingFilter",
    ],
}


class ProductViewSet(viewsets.ModelViewSet):
    search_fields = ["^sku", "name"]
    ordering_fields = ["name", "price", "created_at"]
    ordering = ["-created_at"]

2

The entire backend contract: take a queryset, return a queryset. Everything DRF ships implements exactly this method.

5–6

Models without a tenant column pass through untouched, so one backend can sit in the global default list without breaking unrelated endpoints.

12

Listing the tenant backend first means it narrows before anything else runs — every later backend operates on an already-scoped queryset.

22

Naming `ordering_fields` explicitly. Leaving it out would let a caller sort by any serializer-readable field, which the DRF docs flag as a data-leak risk.

23

`ordering` supplies the default sort. Without one, page 2 of an unordered queryset can repeat or skip rows that page 1 already returned.

Why this works: A cross-cutting rule expressed once as a backend is enforced on every list endpoint automatically, including ones added later — much harder to forget than a `get_queryset()` override each view has to remember to write.

What we're doing: Make an events endpoint refuse the queries it cannot serve cheaply, instead of serving them slowly.

MAX_RANGE = timedelta(days=90)


class EventFilter(django_filters.FilterSet):
    since = django_filters.IsoDateTimeFilter(
        field_name="occurred_at", lookup_expr="gte", required=True)
    until = django_filters.IsoDateTimeFilter(
        field_name="occurred_at", lookup_expr="lte", required=True)
    level = django_filters.ChoiceFilter(choices=Event.Level.choices)

    class Meta:
        model = Event
        fields = ["since", "until", "level"]

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

    def clean(self):
        cleaned = super().clean()
        since, until = cleaned.get("since"), cleaned.get("until")
        if since and until and until - since > MAX_RANGE:
            raise ValidationError(
                {"until": f"Range may not exceed {MAX_RANGE.days} days."})
        return cleaned

5–8

`required=True` turns the scope into part of the contract. Without both bounds the endpoint would have to scan the whole table, so it refuses rather than trying.

9

`ChoiceFilter` rejects an unknown level with a 400. A plain `CharFilter` would pass it to the database and return an empty list, which reads like "no matching events".

15–21

The check DRF does not do for you. Without it, `?sinse=…` is ignored, `since` is missing, and the request fails on `required` — but a typo in an optional parameter would silently return an unfiltered page.

23–28

The cost bound. Ninety days is a number chosen from what the index can serve; the point is that the limit is stated and enforced rather than discovered in production.

Why this works: Each of the three gates converts a class of slow request into a fast, explicit 400. The caller learns what is wrong on the first attempt, and the database never sees the query at all — which is the difference between an endpoint that degrades under load and one that stays predictable.