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