Field Lookups in QuerySets
In this page:
What Is a Field Lookup?
A field lookup tells Django how to compare a field's value, not just what value to compare it to. You write it as fieldname__lookuptype inside filter() or exclude().
Note: Without a lookup suffix, Django defaults to exact matching.
Example: What Is a Field Lookup?
Both queries find languages, but iexact ignores letter case while the plain filter needs an exact match.
from core.models import Language
# Exact match (default)
Language.objects.filter(slug='python')
# Case-insensitive match
Language.objects.filter(name__iexact='python')Comparison Lookups
gt, gte, lt, and lte let you filter numbers and dates by 'greater than' or 'less than' instead of exact equality.
Note: Combine gte and lte to filter a range, e.g. between two dates.
Example: Comparison Lookups
order__gt=5 returns chapters with an order strictly greater than 5, while gte/lte together define an inclusive range.
from core.models import Chapter
# Chapters after order 5
Chapter.objects.filter(order__gt=5)
# Chapters from order 1 to 5
Chapter.objects.filter(order__gte=1, order__lte=5)Text Lookups: contains and icontains
contains checks if a piece of text appears anywhere inside a field, and icontains does the same but ignores case.
Note: Use icontains for user-facing search boxes so Django and django both match.
Example: Text Lookups: contains and icontains
The first query only matches titles with Django capitalized exactly that way; the second matches any capitalization.
from core.models import Tutorial
# Case-sensitive substring search
Tutorial.objects.filter(title__contains='Django')
# Case-insensitive substring search
Tutorial.objects.filter(title__icontains='django')The in Lookup
in checks whether a field's value is one of several choices, similar to Python's in keyword but translated into SQL.
Note: Pass a list, tuple, or even another queryset to in.
Example: The in Lookup
This returns every tutorial whose category matches one of the three listed values, avoiding three separate OR conditions.
from core.models import Tutorial
# Tutorials in any of these categories
Tutorial.objects.filter(category__in=['Tutorial', 'Forms', 'APIs'])- Using == instead of a lookup like exact or gte inside filter() — Python operators don't work there, only keyword lookups do.
- Forgetting that lookups are case-sensitive by default (exact, contains) and reaching for icontains only after a search silently returns nothing.
- Chaining two underscores incorrectly, e.g. writing price_gte instead of price__gte, which Django doesn't understand and raises a FieldError.
- Field lookups use a double underscore after the field name, like price__gte=100.
- Common lookups include exact, iexact, contains, icontains, gt, gte, lt, lte, and in.
- Lookups let you build precise filters without writing raw SQL.
Chapter Quiz — Complete all 9 topics to unlock
0/9 topics done
Complete these topics first: