Filter Reference - django-filter 25.1 documentation (original) (raw)

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

Core Arguments

The following are the core arguments that apply to all filters. Note that they are joined to construct the complete lookup expressionthat is the left hand side of the ORM filter() call.

field_name

The name of the model field that is filtered against. If this argument is not provided, it defaults the filter’s attribute name on theFilterSet class. Field names can traverse relationships by joining the related parts with the ORM lookup separator (__). e.g., a product’smanufacturer__name.

lookup_expr

The field lookup that should be performed in the filter call. Defaults to exact. The lookup_expr can contain transforms if the expression parts are joined by the ORM lookup separator (__). e.g., filter a datetime by its year part year__gt.

Keyword-only Arguments

The following are optional arguments that can be used to modify the behavior of all filters.

label

The label as it will appear in the HTML, analogous to a form field’s label argument. If a label is not provided, a verbose label will be generated based on the field field_name and the parts of the lookup_expr(see: FILTERS_VERBOSE_LOOKUPS).

method

An optional argument that tells the filter how to handle the queryset. It can accept either a callable or the name of a method on theFilterSet. The callable receives aQuerySet, the name of the model field to filter on, and the value to filter with. It should return a filteredQuerySet.

Note that the value is validated by the Filter.field, so raw value transformation and empty value checking should be unnecessary.

class F(FilterSet): """Filter for Books by if books are published or not""" published = BooleanFilter(field_name='published_on', method='filter_published')

def filter_published(self, queryset, name, value):
    # construct the full lookup expression.
    lookup = '__'.join([name, 'isnull'])
    return queryset.filter(**{lookup: False})

    # alternatively, you could opt to hardcode the lookup. e.g.,
    # return queryset.filter(published_on__isnull=False)

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

Callables may also be defined out of the class scope.

def filter_not_empty(queryset, name, value): lookup = '__'.join([name, 'isnull']) return queryset.filter(**{lookup: False})

class F(FilterSet): """Filter for Books by if books are published or not""" published = BooleanFilter(field_name='published_on', method=filter_not_empty)

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

distinct

A boolean 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 relationships. Defaults to False.

exclude

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

required

A boolean that specifies whether the Filter is required or not. Defaults to False.

**kwargs

Any additional keyword arguments are stored as the extra parameter on the filter. They are provided to the accompanying form Field and can be used to provide arguments like choices. Some field-related arguments:

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:

ModelChoiceFilter and ModelMultipleChoiceFilter arguments

These arguments apply specifically to ModelChoiceFilter andModelMultipleChoiceFilter only.

QuerySet

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

to_field_name

If you pass in to_field_name (which gets forwarded to the Django field), it will be used also in the default get_filter_predicate implementation as the model’s attribute.

Filters

class CharFilter

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

class UUIDFilter

This filter matches UUID values, used with UUIDField by default.

class BooleanFilter

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

class ChoiceFilter

This filter matches values in its choices argument. The choices must be explicitly passed when the filter is 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']

ChoiceFilter also has arguments that enable a choice for not filtering, as well as a choice for filtering by None values. Each of the arguments have a corresponding global setting (Settings Reference).

class 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)

class 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=Trueargument 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’’).

distinct defaults to True as to-many relationships will generally require this.

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_nooptest.

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

class TypedMultipleChoiceFilter

Like MultipleChoiceFilter, but in addition accepts thecoerce parameter, as in TypedChoiceFilter.

class DateFilter

Matches on a date. Used with DateField by default.

class TimeFilter

Matches on a time. Used with TimeField by default.

class DateTimeFilter

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

class 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']

class DurationFilter

Matches on a duration. Used with DurationField by default.

Supports both Django (‘%d %H:%M:%S.%f’) and ISO 8601 formatted durations (but only the sections that are accepted by Python’s timedelta, so no year, month, and week designators, e.g. ‘P3DT10H22M’).

class ModelChoiceFilter

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

If automatically instantiated, ModelChoiceFilter will use the defaultQuerySet for the related field. If manually instantiated you mustprovide the QuerySet kwarg.

Example:

class F(FilterSet): """Filter for books by author""" author = ModelChoiceFilter(queryset=Author.objects.all())

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

The QuerySet argument also supports callable behavior. If a callable is passed, it will be invoked with FilterSet.request as its only argument. This allows you to easily filter by properties on the request object without having to override the FilterSet.__init__.

Note

You should expect that the request object may be None.

def departments(request): if request is None: return Department.objects.none()

company = request.user.company
return company.department_set.all()

class EmployeeFilter(filters.FilterSet): department = filters.ModelChoiceFilter(queryset=departments) ...

class 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 defaultQuerySet for the related field. If manually instantiated you must provide the QuerySet kwarg. LikeModelChoiceFilter, theQuerySet argument has callable behavior.

To use a custom field name for the lookup, you can use to_field_name:

class FooFilter(BaseFilterSet): foo = django_filters.filters.ModelMultipleChoiceFilter( field_name='attr__uuid', to_field_name='uuid', queryset=Foo.objects.all(), )

If you want to use a custom queryset, e.g. to add annotated fields, this can be done as follows:

class MyMultipleChoiceFilter(django_filters.ModelMultipleChoiceFilter): def get_filter_predicate(self, v): return {'annotated_field': v.annotated_field}

def filter(self, qs, value):
    if value:
        qs = qs.annotate_with_custom_field()
        qs = super().filter(qs, value)
    return qs

foo = MyMultipleChoiceFilter( to_field_name='annotated_field', queryset=Model.objects.annotate_with_custom_field(), )

The annotate_with_custom_field method would be defined through a custom QuerySet, which then gets used as the model’s manager:

class CustomQuerySet(models.QuerySet): def annotate_with_custom_field(self): return self.annotate( custom_field=Case( When(foo__isnull=False, then=F('foo__uuid')), When(bar__isnull=False, then=F('bar__uuid')), default=None, ), )

class MyModel(models.Model): objects = CustomQuerySet.as_manager()

class NumberFilter

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

NumberFilter.get_max_validator()

Return a MaxValueValidator instance that will be added to django.forms.Field.validators. By default uses a limit value of 1e50. Return None to disable maximum value validation.

class 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 andFloatRangeField (available since Django 1.8). The default widget used is the RangeWidget.

Regular field lookups are available in addition to several containment lookups, includingoverlap, contains, and contained_by. More details in the Django docs.

If the lower limit value is provided, the filter automatically defaults to startswithas the lookup and endswith if only the upper limit value is provided.

class 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_min': '5', 'price_max': '15'}, queryset=qs)

Min-Only: Books costing more the 11€

f = F({'price_min': '11'}, queryset=qs)

Max-Only: Books costing less than 19€

f = F({'price_max': '19'}, queryset=qs)

class DateRangeFilter

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

class DateFromToRangeFilter

Similar to a RangeFilter except it uses dates instead of numerical values. It can be used with DateField. It also works with DateTimeField, but takes into consideration only the date.

Example of using the DateField field:

class Comment(models.Model): date = models.DateField() time = models.TimeField()

class F(FilterSet): date = DateFromToRangeFilter()

class Meta:
    model = Comment
    fields = ['date']

Range: Comments added between 2016-01-01 and 2016-02-01

f = F({'date_after': '2016-01-01', 'date_before': '2016-02-01'})

Min-Only: Comments added after 2016-01-01

f = F({'date_after': '2016-01-01'})

Max-Only: Comments added before 2016-02-01

f = F({'date_before': '2016-02-01'})

Note

When filtering ranges that occurs on DST transition dates DateFromToRangeFilter will use the first valid hour of the day for start datetime and the last valid hour of the day for end datetime. This is OK for most applications, but if you want to customize this behavior you must extend DateFromToRangeFilter and make a custom field for it.

Warning

If you’re using Django prior to 1.9 you may hit AmbiguousTimeError or NonExistentTimeError when start/end date matches DST start/end respectively. This occurs because versions before 1.9 don’t allow to change the DST behavior for making a datetime aware.

Example of using the DateTimeField field:

class Article(models.Model): published = models.DateTimeField()

class F(FilterSet): published = DateFromToRangeFilter()

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

Article.objects.create(published='2016-01-01 8:00') Article.objects.create(published='2016-01-20 10:00') Article.objects.create(published='2016-02-10 12:00')

Range: Articles published between 2016-01-01 and 2016-02-01

f = F({'published_after': '2016-01-01', 'published_before': '2016-02-01'}) assert len(f.qs) == 2

Min-Only: Articles published after 2016-01-01

f = F({'published_after': '2016-01-01'}) assert len(f.qs) == 3

Max-Only: Articles published before 2016-02-01

f = F({'published_before': '2016-02-01'}) assert len(f.qs) == 2

class DateTimeFromToRangeFilter

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

Example:

class Article(models.Model): published = models.DateTimeField()

class F(FilterSet): published = DateTimeFromToRangeFilter()

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

Article.objects.create(published='2016-01-01 8:00') Article.objects.create(published='2016-01-01 9:30') Article.objects.create(published='2016-01-02 8:00')

Range: Articles published 2016-01-01 between 8:00 and 10:00

f = F({'published_after': '2016-01-01 8:00', 'published_before': '2016-01-01 10:00'}) assert len(f.qs) == 2

Min-Only: Articles published after 2016-01-01 8:00

f = F({'published_after': '2016-01-01 8:00'}) assert len(f.qs) == 3

Max-Only: Articles published before 2016-01-01 10:00

f = F({'published_before': '2016-01-01 10:00'}) assert len(f.qs) == 2

class IsoDateTimeFromToRangeFilter

Similar to a RangeFilter except it uses ISO 8601 formatted values instead of numerical values. It can be used withIsoDateTimeField.

Example:

class Article(models.Model): published = django_filters.IsoDateTimeField()

class F(FilterSet): published = IsoDateTimeFromToRangeFilter()

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

Article.objects.create(published='2016-01-01T8:00:00+01:00') Article.objects.create(published='2016-01-01T9:30:00+01:00') Article.objects.create(published='2016-01-02T8:00:00+01:00')

Range: Articles published 2016-01-01 between 8:00 and 10:00

f = F({'published_after': '2016-01-01T8:00:00+01:00', 'published_before': '2016-01-01T10:00:00+01:00'}) assert len(f.qs) == 2

Min-Only: Articles published after 2016-01-01 8:00

f = F({'published_after': '2016-01-01T8:00:00+01:00'}) assert len(f.qs) == 3

Max-Only: Articles published before 2016-01-01 10:00

f = F({'published_before': '2016-01-01T10:00:00+0100'}) assert len(f.qs) == 2

class TimeRangeFilter

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

Example:

class Comment(models.Model): date = models.DateField() time = models.TimeField()

class F(FilterSet): time = TimeRangeFilter()

class Meta:
    model = Comment
    fields = ['time']

Range: Comments added between 8:00 and 10:00

f = F({'time_after': '8:00', 'time_before': '10:00'})

Min-Only: Comments added after 8:00

f = F({'time_after': '8:00'})

Max-Only: Comments added before 10:00

f = F({'time_before': '10:00'})

class 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.

class AllValuesMultipleFilter

This is a MultipleChoiceFilter 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.

class LookupChoiceFilter

A combined filter that allows users to select the lookup expression from a dropdown.

ex:

price = django_filters.LookupChoiceFilter( field_class=forms.DecimalField, lookup_choices=[ ('exact', 'Equals'), ('gt', 'Greater than'), ('lt', 'Less than'), ] )

class BaseInFilter

This is a base class used for creating IN lookup filters. It is expected that this filter class is used in conjunction with another filter class, as this class only validates that the incoming value is comma-separated. The secondary filter is then used to validate the individual values.

Example:

class NumberInFilter(BaseInFilter, NumberFilter): pass

class F(FilterSet): id__in = NumberInFilter(field_name='id', lookup_expr='in')

class Meta:
    model = User

User.objects.create(username='alex') User.objects.create(username='jacob') User.objects.create(username='aaron') User.objects.create(username='carl')

In: User with IDs 1 and 3.

f = F({'id__in': '1,3'}) assert len(f.qs) == 2

class BaseRangeFilter

This is a base class used for creating RANGE lookup filters. It behaves identically to BaseInFilter with the exception that it expects only two comma-separated values.

Example:

class NumberRangeFilter(BaseRangeFilter, NumberFilter): pass

class F(FilterSet): id__range = NumberRangeFilter(field_name='id', lookup_expr='range')

class Meta:
    model = User

User.objects.create(username='alex') User.objects.create(username='jacob') User.objects.create(username='aaron') User.objects.create(username='carl')

Range: User with IDs between 1 and 3.

f = F({'id__range': '1,3'}) assert len(f.qs) == 3

class OrderingFilter

Enable queryset ordering. As an extension of ChoiceFilterit accepts two additional arguments that are used to build the ordering choices.

class UserFilter(FilterSet): account = CharFilter(field_name='username') status = NumberFilter(field_name='status')

o = OrderingFilter(
    # tuple-mapping retains order
    fields=(
        ('username', 'account'),
        ('first_name', 'first_name'),
        ('last_name', 'last_name'),
    ),

    # labels do not need to retain order
    field_labels={
        'username': 'User account',
    }
)

class Meta:
    model = User
    fields = ['first_name', 'last_name']

UserFilter().filters['o'].field.choices [ ('account', 'User account'), ('-account', 'User account (descending)'), ('first_name', 'First name'), ('-first_name', 'First name (descending)'), ('last_name', 'Last name'), ('-last_name', 'Last name (descending)'), ]

Additionally, you can just provide your own choices if you require explicit control over the exposed options. For example, when you might want to disable descending sort options.

class UserFilter(FilterSet): account = CharFilter(field_name='username') status = NumberFilter(field_name='status')

o = OrderingFilter(
    choices=(
        ('account', 'Account'),
    ),
    fields={
        'username': 'account',
    },
)

This filter is also CSV-based, and accepts multiple ordering params. The default select widget does not enable the use of this, but it is useful for APIs. SelectMultiple widgets are not compatible, given that they are not able to retain selection order.

Adding Custom filter choices

If you wish to sort by non-model fields, you’ll need to add custom handling to anOrderingFilter subclass. For example, if you want to sort by a computed ‘relevance’ factor, you would need to do something like the following:

class CustomOrderingFilter(django_filters.OrderingFilter):

def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)
    self.extra['choices'] += [
        ('relevance', 'Relevance'),
        ('-relevance', 'Relevance (descending)'),
    ]


def filter(self, qs, value):
    # OrderingFilter is CSV-based, so `value` is a list
    if any(v in ['relevance', '-relevance'] for v in value):
        # sort queryset by relevance
        return ...

    return super().filter(qs, value)