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?
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).
There's a link in the docs there for the django lookups docs also, and what you'll find with this is that you can make searching/filtering more efficient by using that second option.
The first option in the docs, where fields is just a list will do an exact match query against each of the fields you list.
In the second option, hat the filters library will do with the fields dictionary is it'll use "double underscore" notation to create lookups of;
username__exactusername__containslast_login__exactlast_login__year__gtYou can use the double underscore to access an attribute of something, or the lookup type. So on last_login for that final example above, it'll take the year of the last_login value and for that year, the lookup type is greater than (gt).
There are lots of these lookup values that can be really helpful to learn. For example, contains is case sensitive but you can use icontains for a case insensitive match. There's also lt for less than, or lte/gte for less/greater than or equal. Check out the available lookups here.