Filter Reference¶
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 expression
that 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 the
FilterSet
class. Field names can traverse relationships
by joining the related parts with the ORM lookup separator (__
). e.g., a product’s
manufacturer__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 the
FilterSet
. The callable receives a
QuerySet
, the name of the model field to filter
on, and the value to filter with. It should return a filtered
QuerySet
.
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 exclude
on 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:
LinkWidget
– this displays the options in a manner similar to the way the Django Admin does, as a series of links. The link for the selected option will haveclass="selected"
.
BooleanWidget
– this widget converts its input into Python’s True/False values. It will convert all case variations ofTrue
andFalse
into the internal Python values.
CSVWidget
– this widget expects a comma separated value and converts it into a list of string values. It is expected that the field class handle a list of values as well as type conversion.
RangeWidget
– this widget is used withRangeFilter
to generate two form input elements using a single field.
ModelChoiceFilter
and ModelMultipleChoiceFilter
arguments¶
These arguments apply specifically to ModelChoiceFilter
and
ModelMultipleChoiceFilter
only.
QuerySet
¶
ModelChoiceFilter
and
ModelMultipleChoiceFilter
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
and
TextField
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 with
BooleanField
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).
empty_label
: The display label to use for the select choice to not filter. The choice may be disabled by setting this argument toNone
. Defaults toFILTERS_EMPTY_CHOICE_LABEL
.null_label
: The display label to use for the choice to filter byNone
values. The choice may be disabled by setting this argument toNone
. Defaults toFILTERS_NULL_CHOICE_LABEL
.null_value
: The special value to match to enable filtering byNone
values. This value defaultsFILTERS_NULL_CHOICE_VALUE
and needs to be a non-empty value (''
,None
,[]
,()
,{}
).
- 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=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’’).
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_noop test.
Override is_noop if you require a different test for your application.
- class TypedMultipleChoiceFilter¶
Like MultipleChoiceFilter
, but in addition accepts the
coerce
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 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.
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 default
QuerySet
for the related field. If manually instantiated
you must provide the QuerySet
kwarg. Like
ModelChoiceFilter
, the
QuerySet
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 todjango.forms.Field.validators
. By default uses a limit value of1e50
. ReturnNone
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
and
FloatRangeField
(available since Django 1.8). The default
widget used is the RangeWidget
.
Regular field lookups are available in addition to several containment lookups, including
overlap
, contains
, and contained_by
. More details in the Django docs.
If the lower limit value is provided, the filter automatically defaults to startswith
as 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 with
IsoDateTimeField
.
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.
lookup_choices
is an optional argument that accepts multiple input formats, and is ultimately normalized as the choices used in the lookup dropdown. See.get_lookup_choices()
for more information.field_class
is an optional argument that allows you to set the inner form field class used to validate the value. Default:forms.CharField
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 ChoiceFilter
it accepts two additional arguments that are used to build the ordering choices.
fields
is a mapping of {model field name: parameter name}. The parameter names are exposed in the choices and mask/alias the field names used in theorder_by()
call. Similar to fieldchoices
,fields
accepts the ‘list of two-tuples’ syntax that retains order.fields
may also just be an iterable of strings. In this case, the field names simply double as the exposed parameter names.field_labels
is an optional argument that allows you to customize the display label for the corresponding parameter. It accepts a mapping of {field name: human readable label}. Keep in mind that the key is the field name, and not the exposed parameter name.
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 an
OrderingFilter
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)