custom filtering in django rest framework

Question

I am trying to implement custom filtering in my code and went through the documentation. But I couldnt understand the following snippets from the docs.

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 doc says we can use either one the first or second one but what is the exact difference?? What is the meaning of contains and year_gt?

Answer 1

What is the exact difference ?

With fields = ['username', 'last_login'], the generated filters are :

qs.filter(username='some_value') and qs.filter(last_login=some_date_value)

With

fields = {
        'username': ['exact', 'contains'],
        'last_login': ['exact', 'year__gt'],
    }

the generated filters are :

qs.filter(username='some_value'), qs.filter(username__contains='some_value') for the username field.

qs.filter(last_login=some_date_value), qs.filter(last_login__year__gt=some_year_value) for the last_login field.

So we can see at first time that the second produce 2 filters options for each field, and the first produce only one filter option (exact match) for the given value.

What is the meaning of contains and year__gt ?

contains is used to filter by a value that can be found inside a field. ex: dj is in django.

year__gt in other hand is only for date field. When you have a date field like created, Django let you filter by the year, month, day by just do : .filter(created__year=2021, created__month=12). And more possibility by .filter(created__year__gt=2020) that means the year of created field > 2020. It can be applied to month__gt (month > 11), day__lt (day < 25).