Filter Reference

This is a reference document with a list of the filters and their arguments.

Filters

CharFilter

This filter does simple character matches, used with CharField and TextField by default.

BooleanFilter

This filter matches a boolean, either True or False, used with BooleanField and NullBooleanField by default.

ChoiceFilter

This filter matches an item of any type by choices, used with any field that has choices.

Requires choices kwarg to be passed if explicitly declared on the FilterSet. For example:

class User(models.Model):
    username = models.CharField(max_length=255)
    first_name = SubCharField(max_length=100)
    last_name = SubSubCharField(max_length=100)

    status = models.IntegerField(choices=STATUS_CHOICES, default=0)

STATUS_CHOICES = (
    (0, 'Regular'),
    (1, 'Manager'),
    (2, 'Admin'),
)

class F(FilterSet):
    status = ChoiceFilter(choices=STATUS_CHOICES)
    class Meta:
        model = User
        fields = ['status']

TypedChoiceFilter

The same as ChoiceFilter with the added possibility to convert value to match against. This could be done by using coerce parameter. An example use-case is limiting boolean choices to match against so only some predefined strings could be used as input of a boolean filter:

import django_filters
from distutils.util import strtobool

BOOLEAN_CHOICES = (('false', 'False'), ('true', 'True'),)

class YourFilterSet(django_filters.FilterSet):
    ...
    flag = django_filters.TypedChoiceFilter(choices=BOOLEAN_CHOICES,
                                            coerce=strtobool)

MultipleChoiceFilter

The same as ChoiceFilter except the user can select multiple choices and the filter will form the OR of these choices by default to match items. The filter will form the AND of the selected choices when the conjoined=True argument is passed to this class.

Multiple choices are represented in the query string by reusing the same key with different values (e.g. ‘’?status=Regular&status=Admin’‘).

Advanced Use: Depending on your application logic, when all or no choices are selected, filtering may be a noop. In this case you may wish to avoid the filtering overhead, particularly of the distinct call.

Set always_filter to False after instantiation to enable the default is_noop test.

Override is_noop if you require a different test for your application.

DateFilter

Matches on a date. Used with DateField by default.

TimeFilter

Matches on a time. Used with TimeField by default.

DateTimeFilter

Matches on a date and time. Used with DateTimeField by default.

IsoDateTimeFilter

Uses IsoDateTimeField to support filtering on ISO 8601 formatted dates, as are often used in APIs, and are employed by default by Django REST Framework.

Example.

class F(FilterSet):
    """Filter for Books by date published, using ISO 8601 formatted dates"""
    published = IsoDateTimeFilter()

    class Meta:
        model = Book
        fields = ['published']

ModelChoiceFilter

Similar to a ChoiceFilter except it works with related models, used for ForeignKey by default.

If automatically instantiated ModelChoiceFilter will use the default QuerySet for the related field. If manually instantiated you must provide the queryset kwarg.

ModelMultipleChoiceFilter

Similar to a MultipleChoiceFilter except it works with related models, used for ManyToManyField by default.

As with ModelChoiceFilter, if automatically instantiated ModelMultipleChoiceFilter will use the default QuerySet for the related field. If manually instantiated you must provide the queryset kwarg.

NumberFilter

Filters based on a numerical value, used with IntegerField, FloatField, and DecimalField by default.

NumericRangeFilter

Filters where a value is between two numerical values, or greater than a minimum or less than a maximum where only one limit value is provided. This filter is designed to work with the Postgres Numerical Range Fields, including IntegerRangeField, BigIntegerRangeField and FloatRangeField, available since Django 1.8. The default widget used is the RangeField.

RangeField lookup_types can be used, including overlap, contains, and contained_by. More lookups can be found in the Django docs ([https://docs.djangoproject.com/en/1.8/ref/contrib/postgres/fields/#querying-range-fields](https://docs.djangoproject.com/en/1.8/ref/contrib/postgres/fields/#querying-range-fields)).

If the lower limit value is provided, the filter automatically defaults to __startswith as the lookup type and if only the upper limit value is provided, the filter uses __endswith.

RangeFilter

Filters where a value is between two numerical values, or greater than a minimum or less than a maximum where only one limit value is provided.

class F(FilterSet):
    """Filter for Books by Price"""
    price = RangeFilter()

    class Meta:
        model = Book
        fields = ['price']

qs = Book.objects.all().order_by('title')

# Range: Books between 5€ and 15€
f = F({'price_0': '5', 'price_1': '15'}, queryset=qs)

# Min-Only: Books costing more the 11€
f = F({'price_0': '11'}, queryset=qs)

# Max-Only: Books costing less than 19€
f = F({'price_1': '19'}, queryset=qs)

DateRangeFilter

Filter similar to the admin changelist date one, it has a number of common selections for working with date fields.

DateFromToRangeFilter

Similar to a RangeFilter except it uses dates instead of numerical values. It can be used with DateField and DateTimeField.

TimeRangeFilter

Similar to a RangeFilter except it uses time format values instead of numerical values. It can be used with TimeField.

AllValuesFilter

This is a ChoiceFilter whose choices are the current values in the database. So if in the DB for the given field you have values of 5, 7, and 9 each of those is present as an option. This is similar to the default behavior of the admin.

MethodFilter

This is a Filter that will allow you to run a method that exists on the filter set that this filter is a property of. Set the action to a string that will map to a method on the filter set class.

Core Arguments

name

The name of the field this filter is supposed to filter on, if this is not provided it automatically becomes the filter’s name on the FilterSet.

label

The label as it will apear in the HTML, analogous to a form field’s label argument.

widget

The django.form Widget class which will represent the Filter. In addition to the widgets that are included with Django that you can use there are additional ones that django-filter provides which may be useful:

  • django_filters.widgets.LinkWidget – this displays the options in a mannner similar to the way the Django Admin does, as a series of links. The link for the selected option will have class="selected".

action

An optional callable that tells the filter how to handle the queryset. It recieves a QuerySet and the value to filter on and should return a Queryset that is filtered appropriately.

lookup_type

The type of lookup that should be performed using the [Django ORM](https://docs.djangoproject.com/en/dev/ref/models/querysets/#field-lookups “Django’s ORM Lookups”). All the normal options are allowed, and should be provided as a string. You can also provide either None or a list or a tuple. If None is provided, then the user can select the lookup type from all the ones available in the Django ORM. If a list or tuple is provided, then the user can select from those options.

distinct

A boolean value that specifies whether the Filter will use distinct on the queryset. This option can be used to eliminate duplicate results when using filters that span related models. Defaults to False.

exclude

A boolean value that specifies whether the Filter should use filter or exclude on the queryset. Defaults to False.

ModelChoiceFilter and ModelMultipleChoiceFilter

queryset

ModelChoiceFilter and ModelMultipleChoiceFilter require a queryset to operate on which must be passed as a kwarg.

**kwargs

Any extra keyword arguments will be provided to the accompanying form Field. This can be used to provide arguments like choices.