Using django-filter¶

Django-filter provides a simple way to filter down a queryset based on parameters a user provides. Say we have a Product model and we want to let our users filter which products they see on a list page.

The model¶

Let’s start with our model:

from django.db import models

class Product(models.Model):
    name = models.CharField(max_length=255)
    price = models.DecimalField()
    description = models.TextField()
    release_date = models.DateField()
    manufacturer = models.ForeignKey(Manufacturer)

The filter¶

We have a number of fields and we want to let our users filter based on the price or the release_date. We create a FilterSet for this:

import django_filters

class ProductFilter(django_filters.FilterSet):
    name = django_filters.CharFilter(lookup_expr='iexact')

    class Meta:
        model = Product
        fields = ['price', 'release_date']

As you can see this uses a very similar API to Django’s ModelForm. Just like with a ModelForm we can also override filters, or add new ones using a declarative syntax.

Declaring filters¶

The declarative syntax provides you with the most flexibility when creating filters, however it is fairly verbose. We’ll use the below example to outline the core filter arguments on a FilterSet:

class ProductFilter(django_filters.FilterSet):
    price = django_filters.NumberFilter()
    price__gt = django_filters.NumberFilter(name='price', lookup_expr='gt')
    price__lt = django_filters.NumberFilter(name='price', lookup_expr='lt')

    release_year = django_filters.NumberFilter(name='release_date', lookup_expr='year')
    release_year__gt = django_filters.NumberFilter(name='release_date', lookup_expr='year__gt')
    release_year__lt = django_filters.NumberFilter(name='release_date', lookup_expr='year__lt')

    manufacturer__name = django_filters.CharFilter(lookup_expr='icontains')

    class Meta:
        model = Product

There are two main arguments for filters:

name: The name of the model field to filter on. You can traverse “relationship paths” using Django’s __ syntax to filter fields on a related model. ex, manufacturer__name.
lookup_expr: The field lookup to use when filtering. Django’s __ syntax can again be used in order to support lookup transforms. ex, year__gte.

Together, the field name and lookup_expr represent a complete Django lookup expression. A detailed explanation of lookup expressions is provided in Django’s lookup reference. django-filter supports expressions containing both transforms and a final lookup for version 1.9 of Django and above. For Django version 1.8, transformed expressions are not supported.

While both of these fields are optional, it is recommended that you specify them. By default, if name is not specified, the filter’s name on the filterset class will be used. Additionally, lookup_expr defaults to exact. The following is an example of a misconfigured price filter:

class ProductFilter(django_filters.FilterSet):
    price__gt = django_filters.NumberFilter()

The filter instance will have a field name of price__gt and an exact lookup type. Under the hood, this will incorrectly be resolved as:

Produce.objects.filter(price__gt__exact=value)

Note

It’s quite common to forget to set the lookup expression for CharField and TextField and wonder why a search for “foo” does not return results for “foobar”. This is because the default lookup type is exact, but you probably want to perform an icontains lookup.

For more information on additional arguments, see Core Arguments.

Generating filters with Meta.fields¶

The FilterSet Meta class provides a fields attribute that can be used for easily specifying multiple filters without significant code duplication. The base syntax supports a list of multiple field names:

import django_filters

class ProductFilter(django_filters.FilterSet):
    class Meta:
        model = Product
        fields = ['price', 'release_date']

The above generates ‘exact’ lookups for both the ‘price’ and ‘release_date’ fields.

Additionally, a dictionary can be used to specify multiple lookup expressions for each field:

import django_filters

class ProductFilter(django_filters.FilterSet):
    class Meta:
        model = Product
        fields = {
            'price': ['lt', 'gt'],
            'release_date': ['exact', 'year__gt'],
        }

The above would generate ‘price__lt’, ‘price__gt’, ‘release_date’, and ‘release_date__year__gt’ filters.

Note

The filter lookup type ‘exact’ is an implicit default and therefore never added to a filter name. In the above example, the release date’s exact filter is ‘release_date’, not ‘release_date__exact’.

Items in the fields sequence in the Meta class may include “relationship paths” using Django’s __ syntax to filter on fields on a related model:

class ProductFilter(django_filters.FilterSet):
    class Meta:
        model = Product
        fields = ['manufacturer__country']

Overriding default filters¶

Like django.contrib.admin.ModelAdmin, it is possible to override default filters for all the models fields of the same kind using filter_overrides:

class ProductFilter(django_filters.FilterSet):
    filter_overrides = {
        models.CharField: {
            'filter_class': django_filters.CharFilter,
            'extra': lambda f: {
                'lookup_expr': 'icontains',
            },
        },
        models.BooleanField: {
            'filter_class': django_filters.BooleanFilter,
            'extra': lambda f: {
                'widget': 'forms.CheckboxInput',
            },
        },
    }

    class Meta:
        model = Product
        fields = {
            'name': ['exact'],
            'release_date': ['isnull'],
        }

Custom filtering with MethodFilter¶

If you want fine control over each individual filter attribute, you can use the MethodFilter filter.

By passing in the name of a custom defined filter function as an action, the filter attribute gets linked to the custom filter function. Here is an example of overriding the filter function of the filter attribute username

class F(django_filters.FilterSet):
        username = MethodFilter(action='my_custom_filter')

        class Meta:
            model = User
            fields = ['username']

        def my_custom_filter(self, queryset, value):
            return queryset.filter(
                username=value
            )

The filter function can also be defined outside of the filter class scope. Though you would need to pass in the actual function value, not it’s name.

def my_custom_filter(queryset, value):
    return queryset.filter(
        username=value
    )

class F(django_filters.FilterSet):
    # Notice: In this case, action accepts a func, not a string
    username = MethodFilter(action=my_custom_filter)

    class Meta:
        model = User
        fields = ['username']

Lastly, when using a MethodFilter, there is no need to define an action. You may simply do the following and filter_username will be auto-detected and used.

class F(FilterSet):
    username = MethodFilter()

    class Meta:
        model = User
        fields = ['username']

    def filter_username(self, queryset, value):
        return queryset.filter(
            username__contains='ke'
        )

Under the hood, if action is not defined, django_filter searches for a class method with a name that follows the pattern filter_{{ATTRIBUTE_NAME}}. For example, if the attribute name is email, then the filter class will be scanned for the filter function filter_email. If no action is provided, and no filter class function is found, then the filter attribute will be left unfiltered.

The view¶

Now we need to write a view:

def product_list(request):
    f = ProductFilter(request.GET, queryset=Product.objects.all())
    return render(request, 'my_app/template.html', {'filter': f})

If a queryset argument isn’t provided then all the items in the default manager of the model will be used.

If you want to access the filtered objects in your views, for example if you want to paginate them, you can do that. They are in f.qs

The URL conf¶

We need a URL pattern to call the view:

url(r'^list$', views.product_list)

The template¶

And lastly we need a template:

{% extends "base.html" %}

{% block content %}
    <form action="" method="get">
        {{ filter.form.as_p }}
        <input type="submit" />
    </form>
    {% for obj in filter %}
        {{ obj.name }} - ${{ obj.price }}<br />
    {% endfor %}
{% endblock %}

And that’s all there is to it! The form attribute contains a normal Django form, and when we iterate over the FilterSet we get the objects in the resulting queryset.

Generic view & configuration¶

In addition to the above usage there is also a class-based generic view included in django-filter, which lives at django_filters.views.FilterView. You must provide either a model or filterset_class argument, similar to ListView in Django itself:

# urls.py
from django.conf.urls import patterns, url
from django_filters.views import FilterView
from myapp.models import Product

urlpatterns = patterns('',
    (r'^list/$', FilterView.as_view(model=Product)),
)

You must provide a template at <app>/<model>_filter.html which gets the context parameter filter. Additionally, the context will contain object_list which holds the filtered queryset.

A legacy functional generic view is still included in django-filter, although its use is deprecated. It can be found at django_filters.views.object_filter. You must provide the same arguments to it as the class based view:

# urls.py
from django.conf.urls import patterns, url
from myapp.models import Product

urlpatterns = patterns('',
    (r'^list/$', 'django_filters.views.object_filter', {'model': Product}),
)

The needed template and its context variables will also be the same as the class-based view above.

Using django-filter¶

The model¶

The filter¶

Declaring filters¶

Generating filters with Meta.fields¶

Overriding default filters¶

Custom filtering with MethodFilter¶

The view¶

The URL conf¶

The template¶

Generic view & configuration¶

Table Of Contents

Previous topic

Next topic

This Page