FilterSet Options - django-filter 25.1 documentation (original) (raw)

View this page

Toggle table of contents sidebar

This document provides a guide on using additional FilterSet features.

Meta options

Automatic filter generation with model

The FilterSet is capable of automatically generating filters for a givenmodel’s fields. Similar to Django’s ModelForm, filters are created based on the underlying model field’s type. This option must be combined with either the fields or exclude option, which is the same requirement for Django’s ModelForm class, detailed here.

class UserFilter(django_filters.FilterSet): class Meta: model = User fields = ['username', 'last_login']

Declaring filterable fields

The fields option is combined with model to automatically generate filters. Note that generated filters will not overwrite filters declared on the FilterSet. The fields option accepts two syntaxes:

class UserFilter(django_filters.FilterSet): class Meta: model = User fields = ['username', 'last_login']

or

class UserFilter(django_filters.FilterSet): class Meta: model = User fields = { 'username': ['exact', 'contains'], 'last_login': ['exact', 'year__gt'], }

The list syntax will create an exact lookup filter for each field included in fields. The dictionary syntax will create a filter for each lookup expression declared for its corresponding model field. These expressions may include both transforms and lookups, as detailed in the lookup reference.

Note that it is not necessary to include declared filters in a fieldslist - doing so will only affect the order in which fields appear on a FilterSet’s form. Including declarative aliases in afields dict will raise an error.

class UserFilter(django_filters.FilterSet): username = filters.CharFilter() login_timestamp = filters.IsoDateTimeFilter(field_name='last_login')

class Meta:
    model = User
    fields = {
        'username': ['exact', 'contains'],
        'login_timestamp': ['exact'],
    }

TypeError("'Meta.fields' contains fields that are not defined on this FilterSet: login_timestamp")

Disable filter fields with exclude

The exclude option accepts a blacklist of field names to exclude from automatic filter generation. Note that this option will not disable filters declared directly on the FilterSet.

class UserFilter(django_filters.FilterSet): class Meta: model = User exclude = ['password']

Custom Forms using form

The inner Meta class also takes an optional form argument. This is a form class from which FilterSet.form will subclass. This works similar to the form option on a ModelAdmin.

Customise filter generation with filter_overrides

The inner Meta class also takes an optional filter_overrides argument. This is a map of model fields to filter classes with options:

class ProductFilter(django_filters.FilterSet):

 class Meta:
     model = Product
     fields = ['name', 'release_date']
     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,
             },
         },
     }

A possible usecase would be creating a custom filter to be able to filter on FileFields(FileField filtering is hard to define in a generalised way, which is why there is no FileFilter).

This example shows an override used to filter on a FileField:

class Questionnaire(models.Model): file = models.FileField(upload_to=questionnaire_path)

class QuestionnaireFilter(FilterSet): class Meta: model = Questionnaire fields = ['file'] filter_overrides = { models.FileField: { 'filter_class': CharFilter, 'extra': lambda f: {'lookup_expr': 'exact'}, }, }

Handling unknown fields with unknown_field_behavior

The unknown_field_behavior option specifies how unknown fields are handled in a FilterSet. You can set this option using the values of theUnknownFieldBehavior enum:

Note that both the WARN and IGNORE options do not include the unknown field(s) in the list of filters.

from django_filters import UnknownFieldBehavior

class UserFilter(django_filters.FilterSet): class Meta: model = User fields = ['username', 'last_login'] unknown_field_behavior = UnknownFieldBehavior.WARN

Overriding FilterSet methods

When overriding classmethods, calling super(MyFilterSet, cls) may result in a NameError exception. This is due to the FilterSetMetaclass calling these classmethods before the FilterSet class has been fully created. There are two recommmended workarounds:

  1. If using python 3.6 or newer, use the argumentless super() syntax.
  2. For older versions of python, use an intermediate class. Ex:
    class Intermediate(django_filters.FilterSet):
    @classmethod
    def method(cls, arg):
    super(Intermediate, cls).method(arg)
    ...

class ProductFilter(Intermediate):
class Meta:
model = Product
fields = ['...']

filter_for_lookup()

Prior to version 0.13.0, filter generation did not take into account thelookup_expr used. This commonly caused malformed filters to be generated for ‘isnull’, ‘in’, and ‘range’ lookups (as well as transformed lookups). The current implementation provides the following behavior:

If you want to override the filter_class and params used to instantiate filters for a model field, you can override filter_for_lookup(). Ex:

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

@classmethod
def filter_for_lookup(cls, f, lookup_type):
    # override date range lookups
    if isinstance(f, models.DateField) and lookup_type == 'range':
        return django_filters.DateRangeFilter, {}

    # use default behavior otherwise
    return super().filter_for_lookup(f, lookup_type)

Using filterset_factory

A FilterSet for a model can also be created by thefilterset_factory, which creates a FilterSet with the model set in the FilterSets Meta. You can pass a customized FilterSet class to thefilterset_factory, which then uses this class a a base for the createdFilterSet. Ex:

class CustomFilterSet(django_filters.FilterSet): class Meta: form = CustomFilterSetForm

filterset = filterset_factory(Product, filterset=CustomFilterSet)