Support Our Site

To ensure we can continue delivering content and maintaining a free platform for all users, we kindly request that you disable your adblocker. Your contribution greatly supports our site's growth and development.

How to Use Subquery() in Django With Practical Examples

4 min read

In the realm of web development, Django stands as a powerful and versatile framework for building robust applications. One of the key aspects of developing efficient and optimized web applications is handling database queries effectively. In this article, we will delve into the world of subqueries in Django, exploring their significance, practical examples of their usage, and a comparison between subquery and non-subquery approaches.

Understanding Subqueries

A subquery, also known as a nested query, is a query embedded within another query. It enables developers to retrieve data from one table based on the results of another query. Subqueries facilitate complex filtering, aggregating, and joining of data, which can lead to more concise and efficient code.

Practical Examples of Subquery Usage

Let's look at some practical usage of Subquery() in Django.

Filtering Based on Subquery

Suppose we have two models: Author and Book, where an author can have multiple books. We want to find authors who have written books published in the last year.

This code snippet demonstrates how to use a subquery in Django to retrieve authors who have written books published within the last year. It then provides an equivalent non-subquery approach for comparison.

from datetime import datetime, timedelta
from django.db.models import Subquery, OuterRef

last_year = - timedelta(days=365)

# Using Subquery
recent_books = Book.objects.filter(published_date__gte=last_year)
authors_with_recent_books = Author.objects.filter(id__in=Subquery(recent_books.values('author_id')))

# Equivalent Non-Subquery Approach
recent_books = Book.objects.filter(published_date__gte=last_year)
author_ids = [book.author_id for book in recent_books]
authors_with_recent_books = Author.objects.filter(id__in=author_ids)

  1. First, the code imports necessary modules:

    • datetime and timedelta from the datetime module to work with dates.
    • Subquery and OuterRef from django.db.models for subquery and outer reference functionality.
  2. last_year is calculated using the current date ( minus a timedelta of 365 days. This represents the date from one year ago.

  3. Using Subquery Approach:

    • recent_books is a queryset of Book objects filtered to retrieve books published on or after last_year.
    • authors_with_recent_books is a queryset of Author objects filtered to include only those authors whose id is present in the subquery result obtained from recent_books.
  4. Equivalent Non-Subquery Approach:

    • Here, the same filtering of recent_books is done as in the subquery approach.
    • An empty list author_ids is created to store author IDs.
    • A loop iterates through each book in recent_books and appends its author_id to author_ids.
    • authors_with_recent_books is a queryset of Author objects filtered to include only those authors whose id is present in the author_ids list.

In both approaches, the goal is to retrieve a queryset of authors who have written books published within the last year.


OuterRef is a powerful tool provided by Django that allows you to reference a value from the outer query within a subquery. It is especially useful when you want to perform filtering or lookups based on values from the outer query.

In the given code snippet:

  • In the subquery approach, OuterRef('pk') is used to reference the primary key of the Author model in the subquery. It's used within the subquery to filter the books for each author in the outer query.
  • The subquery approach efficiently filters the authors directly in the database without needing to retrieve all the author IDs and then filter the authors based on those IDs, as done in the non-subquery approach.

Using OuterRef along with subqueries can help optimize database queries and reduce the number of database hits, leading to better performance in certain scenarios.

Annotating with Subqueries

Let's say we want to find authors along with the count of their books.

from django.db.models import Count

# Using Subquery
authors_with_book_count = Author.objects.annotate(book_count=Subquery(Book.objects.filter(author=OuterRef('pk')).values('author').annotate(count=Count('id')).values('count')))

# Equivalent Non-Subquery Approach
authors = Author.objects.all()
authors_with_book_count = []
for author in authors:
    book_count = Book.objects.filter(author=author).count()
    authors_with_book_count.append({'author': author, 'book_count': book_count})

Here's how the subquery approach works:

  1. Author.objects.annotate(...) is used to annotate the queryset of Author objects with additional data, which in this case is the book count.

  2. Subquery(...) is used to create a subquery. This subquery calculates the book count for each author and returns it as a subquery result.

  3. Inside the subquery:

    • Book.objects.filter(author=OuterRef('pk')) filters the Book objects based on the current Author being processed in the outer query. The OuterRef('pk') references the primary key of the Author in the outer query.
    • .values('author') groups the filtered Book objects by the author.
    • .annotate(count=Count('id')) annotates each group with the count of Book objects using the Count aggregation function on the id field.
    • .values('count') extracts the book count for each author.
  4. The result of the subquery is used to annotate the Author objects with the calculated book count.

Both approaches aim to achieve the same goal: annotating authors with their book counts. The subquery approach achieves this with a single database query by utilizing the power of subqueries and annotations, resulting in potentially better performance.

The non-subquery approach, while simpler, requires multiple database queries (one for each author), which might result in more database hits and potentially slower performance, especially for larger datasets.

Subqueries vs. Non-Subquery: Which is Better?

Both subquery and non-subquery approaches have their merits. Subqueries are powerful and can lead to more optimized queries, especially when dealing with complex filtering and aggregation. They often result in fewer database hits, enhancing performance.

However, non-subquery methods might be more straightforward for smaller datasets or less complex scenarios. They can also be easier to understand for developers who are new to Django or database optimization.


Subqueries in Django offer a potent tool for optimizing database queries, streamlining code, and enhancing application performance. While both subquery and non-subquery approaches have their place, subqueries shine in scenarios involving complex filtering, aggregation, and annotation. As you delve into the world of Django development, mastering subqueries can undoubtedly elevate your database querying skills and lead to more efficient and maintainable code.

Remember, the choice between subquery and non-subquery methods should be based on the specific needs of your application and the complexity of your data retrieval tasks.


Latest Articles

Latest from djangocentral

DRF Serializer: Handling OrderedDict and Converting It to a Dictionary or JSON

In Django Rest Framework (DRF) tests, when you access, you might encounter an OrderedDict instead of a regular dictionary. This behavior is intentional and reflects the design of DRF's serialization process.Understanding the Problem The u…
Read more →

3 min read

Django Rest Framework CheetSheet: Mastering API Development

Django Rest Framework (DRF) is a powerful toolkit that makes building robust and scalable web APIs with Django a breeze. Whether you're a seasoned Django developer or a newcomer, having a comprehensive cheat sheet at your disposal can be a game-changer. …
Read more →

5 min read

How to Perform NOT Queries in Django ORM

In Django, performing NOT queries allows you to exclude certain records from the query results based on specific conditions. The NOT operator, represented by the tilde (~) when used in conjunction with the Django ORM's Q object, helps you construct compl…
Read more →

3 min read

How to Perform OR Queries in Django ORM

Django is a popular web framework for Python that provides an intuitive and powerful Object-Relational Mapping (ORM) system. The Django ORM allows developers to interact with databases using Python classes and methods, abstracting away the underlying SQL…
Read more →

3 min read