Django QuerySets allow you to retrieve, filter, and manipulate data from your database. Field lookups are a core feature that enables querying specific fields using a variety of conditions. This reference guide from The Coding College provides an overview of common field lookups, with examples to help you use them effectively.
1. Basic Equality Lookups
Exact Match (exact)
Matches a field exactly to the given value.
Example:
# Fetch users with the exact username "john"
User.objects.filter(username__exact="john")Case-Insensitive Match (iexact)
Matches a field case-insensitively to the given value.
Example:
# Fetch users with username "John" (case-insensitive)
User.objects.filter(username__iexact="John")2. Contains Lookups
Substring Match (contains)
Checks if a field contains the given substring.
Example:
# Fetch users with "john" in their email
User.objects.filter(email__contains="john")Case-Insensitive Substring Match (icontains)
Case-insensitive version of contains.
Example:
# Fetch users with "John" in their email (case-insensitive)
User.objects.filter(email__icontains="John")3. Comparison Lookups
Greater Than (gt)
Filters objects where a field is greater than the given value.
Example:
# Fetch products with price greater than 50
Product.objects.filter(price__gt=50)Greater Than or Equal To (gte)
Filters objects where a field is greater than or equal to the given value.
Example:
# Fetch products with price greater than or equal to 50
Product.objects.filter(price__gte=50)Less Than (lt)
Filters objects where a field is less than the given value.
Example:
# Fetch products with price less than 50
Product.objects.filter(price__lt=50)Less Than or Equal To (lte)
Filters objects where a field is less than or equal to the given value.
Example:
# Fetch products with price less than or equal to 50
Product.objects.filter(price__lte=50)4. Null Lookups
Is Null (isnull)
Filters objects where a field is NULL or not.
Example:
# Fetch users with no email set
User.objects.filter(email__isnull=True)5. Boolean Lookups
Is Exact Boolean (is)
Filters objects by an exact boolean value.
Example:
# Fetch active users
User.objects.filter(is_active__exact=True)6. In Lookups
In List (in)
Filters objects where a field matches any value in a list.
Example:
# Fetch users with IDs 1, 2, or 3
User.objects.filter(id__in=[1, 2, 3])7. Date and Time Lookups
Year (year)
Filters objects by a specific year.
Example:
# Fetch orders placed in 2023
Order.objects.filter(created_at__year=2023)Month (month)
Filters objects by a specific month.
Example:
# Fetch orders placed in January
Order.objects.filter(created_at__month=1)Day (day)
Filters objects by a specific day.
Example:
# Fetch orders placed on the 15th
Order.objects.filter(created_at__day=15)Range (range)
Filters objects where a field’s value falls within a range.
Example:
# Fetch products with price between 10 and 50
Product.objects.filter(price__range=(10, 50))8. Regex Lookups
Regex Match (regex)
Filters objects where a field matches a regular expression.
Example:
# Fetch users with email ending in ".com"
User.objects.filter(email__regex=r'.*\.com$')Case-Insensitive Regex Match (iregex)
Case-insensitive version of regex.
Example:
# Fetch users with email ending in ".com" (case-insensitive)
User.objects.filter(email__iregex=r'.*\.com$')9. Other Useful Lookups
Starts With (startswith)
Filters objects where a field starts with a given value.
Example:
# Fetch users with usernames starting with "A"
User.objects.filter(username__startswith="A")Case-Insensitive Starts With (istartswith)
Case-insensitive version of startswith.
Example:
# Fetch users with usernames starting with "a" (case-insensitive)
User.objects.filter(username__istartswith="a")Ends With (endswith)
Filters objects where a field ends with a given value.
Example:
# Fetch users with email ending in "@gmail.com"
User.objects.filter(email__endswith="@gmail.com")Case-Insensitive Ends With (iendswith)
Case-insensitive version of endswith.
Example:
# Fetch users with email ending in "@GMAIL.COM" (case-insensitive)
User.objects.filter(email__iendswith="@GMAIL.COM")Final Thoughts
Understanding Django QuerySet field lookups empowers you to query and manipulate data effectively. By mastering these lookups, you can build efficient and flexible queries for your applications.
For more Django resources and tutorials, visit The Coding College!