Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 39 ยท Filtering, Pagination and Throttling

Filtering DRF Querysets with django-filter

Filter Django REST Framework list endpoints by query string with django-filter: filterset_fields, lookup dictionaries, custom FilterSet classes, range and method filters and error handling.

A list endpoint that returns every row stops being useful quickly. Clients want "only the fantasy books", "cheaper than 20 dollars", "published after 2018". The classic approach is to read request.query_params inside get_queryset() and chain .filter() calls by hand, which works for one or two parameters and then turns into a pile of if statements with no validation.

The package django-filter solves this properly. You declare which fields can be filtered, and it builds the query, converts types ("true" becomes True, "12.5" becomes a decimal) and returns a clean 400 response for invalid values. DRF has first-class support for it through DjangoFilterBackend.

Setup

Install the package (pip install django-filter), add it to INSTALLED_APPS and make the backend the default:

Python
# settings.py (read-only)
INSTALLED_APPS = [..., "rest_framework", "django_filters"]

REST_FRAMEWORK = {
    "DEFAULT_FILTER_BACKENDS": ["django_filters.rest_framework.DjangoFilterBackend"],
}

You can also set the backend per view with filter_backends = [DjangoFilterBackend]. The examples below use a small bookstore: twelve books with title, author, genre, price, year and in_stock.

Exact matches with filterset_fields

The shortest form is a list of field names. Each one becomes a query parameter that matches the value exactly.

Python filterset_fields: exact matches

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Output:

TEXT
{} -> ['Night Trains', 'Salt and Iron', 'The Quiet Harbor', 'Learning Rust Slowly', 'Gardens of Glass', 'Python by Doing', 'Small Kitchens', 'Bread at Dawn', 'Maps of Nowhere', 'Atlas of Storms', 'Cells and Stars', 'Deep Roots']
{'genre': 'fantasy'} -> ['Salt and Iron', 'Gardens of Glass']
{'author': 'Ada Lin', 'genre': 'fiction'} -> ['Night Trains', 'Maps of Nowhere']
{'in_stock': 'false'} -> ['The Quiet Harbor', 'Bread at Dawn', 'Deep Roots']
{'in_stock': 'maybe'} -> ['Night Trains', 'Salt and Iron', 'The Quiet Harbor', 'Learning Rust Slowly', 'Gardens of Glass', 'Python by Doing', 'Small Kitchens', 'Bread at Dawn', 'Maps of Nowhere', 'Atlas of Storms', 'Cells and Stars', 'Deep Roots']
{'colour': 'red'} -> ['Night Trains', 'Salt and Iron', 'The Quiet Harbor', 'Learning Rust Slowly', 'Gardens of Glass', 'Python by Doing', 'Small Kitchens', 'Bread at Dawn', 'Maps of Nowhere', 'Atlas of Storms', 'Cells and Stars', 'Deep Roots']

Three behaviours are worth remembering:

  • Several parameters are combined with AND.
  • A value that cannot be converted to a number or date gives a 400 that names the field (you will see one in the next example). Boolean filters are lenient: text such as maybe is treated as "no filter" and returns everything, so check the boolean spelling in your client.
  • Unknown parameters are silently ignored. A typo in a parameter name returns unfiltered data, so document your parameter names well.

Lookups with a dictionary

Exact match is rarely enough. If you give filterset_fields a dictionary, each field maps to a list of lookups and django-filter creates one parameter per pair, named field__lookup. These are the same lookups you use in the ORM (see Lookups and Q objects).

Python Lookup dictionaries: price ranges, title search

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Output:

TEXT
{'price__gte': '20'} -> ['Learning Rust Slowly', 'Python by Doing', 'Small Kitchens', 'Atlas of Storms', 'Cells and Stars']
{'price__gte': '15', 'price__lte': '20'} -> ['Salt and Iron', 'Gardens of Glass', 'Bread at Dawn', 'Deep Roots']
{'year__gt': '2020'} -> ['Salt and Iron', 'Learning Rust Slowly', 'Python by Doing', 'Atlas of Storms']
{'title__icontains': 'the'} -> ['The Quiet Harbor']
{'genre__in': 'tech,cooking'} -> ['Learning Rust Slowly', 'Python by Doing', 'Small Kitchens', 'Bread at Dawn']
{'price__gte': 'cheap'} -> (400, {'price__gte': ['Enter a number.']})

Pick lookups on purpose. Every filter you expose is a query you must be able to afford. A parameter such as title__icontains cannot use a normal index, so on a big table it turns into a full scan. Expose it only where the table is small or you add a proper search backend (see Search and Ordering).

A custom FilterSet for full control

When you want friendlier parameter names (min_price rather than price__gte), validation, or filters that are not plain field lookups, write a FilterSet class. It works like a form: declared filters become parameters, and Meta can add the automatic ones.

Useful building blocks:

Filter Use for
CharFilter(lookup_expr="icontains") text search on one field
NumberFilter(field_name="price", lookup_expr="gte") numeric bounds
BooleanFilter true/false flags
ChoiceFilter(choices=...) restricted values
BaseInFilter + CharFilter comma-separated lists
RangeFilter ?year_min=...&year_max=... from one declaration
DateFromToRangeFilter date ranges
filters.CharFilter(method="name") anything else: you write the queryset logic
Python A FilterSet with friendly names and a method filter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Output:

TEXT
{'min_price': '20', 'max_price': '30'} -> ['Python by Doing', 'Small Kitchens', 'Atlas of Storms', 'Cells and Stars']
{'year_min': '2018', 'year_max': '2020'} -> ['Night Trains', 'Gardens of Glass', 'Small Kitchens', 'Cells and Stars']
{'genre': ['fantasy', 'tech']} -> ['Salt and Iron', 'Learning Rust Slowly', 'Gardens of Glass', 'Python by Doing']
{'q': 'lin'} -> ['Night Trains', 'Salt and Iron', 'Maps of Nowhere']
{'q': 'lin', 'in_stock': 'true', 'min_price': '12'} -> ['Night Trains', 'Salt and Iron']
{'min_price': 'abc'} -> (400, {'min_price': ['Enter a number.']})

Note that RangeFilter creates two parameters, year_min and year_max, from a single line. And the method filter receives the queryset, the filter name and the cleaned value, so it can express any logic, here an OR across two columns.

Filtering in get_queryset() is still fine

django-filter is for user-controlled filters. Filters that must always apply (only the current user's rows, only published items) belong in get_queryset(), where a client cannot remove them. The two work together: get_queryset() runs first, then the filter backend narrows its result.

Tips for production

  • Whitelist, do not default. filterset_fields = "__all__" exposes every column, including ones you never meant to expose and ones that make slow queries.
  • Index the columns you filter on. A filter without an index is a table scan.
  • Combine with pagination. A filtered list can still be large. See Pagination.
  • Document the parameters. Names, types and examples belong in your API docs; see OpenAPI schema generation, which reads your FilterSet automatically with the right extension.
  • Mind the relation filters. Filtering across relations (author__country) is allowed with FilterSet, but remember select_related() on the queryset to avoid extra queries.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens when a client sends an unknown query parameter such as ?colour=red?

    Only declared filters are applied. Unknown parameters are ignored, so a typo returns unfiltered data.
  2. 2. How do you let clients send ?price__gte=20 with filterset_fields?

    The dictionary form maps each field to a list of lookups, which become field__lookup parameters.
  3. 3. What is a method filter used for?

    CharFilter(method='name') calls your FilterSet method with the queryset, the field name and the cleaned value.
  4. 4. Where should a rule like 'users only see their own rows' live?

    Mandatory restrictions belong in get_queryset(). Optional, user-chosen narrowing belongs in the filter backend.

Summary

  • DjangoFilterBackend turns query parameters into queryset filters, validates them and returns 400 for bad values.
  • filterset_fields as a list gives exact matches; as a dictionary it gives field__lookup parameters.
  • A FilterSet class gives friendly names, ranges, multiple choices and method filters.
  • Unknown parameters are ignored; whitelist the fields you expose and index them.
  • Mandatory restrictions go in get_queryset().

Next: Search and Ordering