🔎 QuerySets and Model Managers

Managers & QuerySets

Every Django model gets a manager named objects. The manager is the doorway to the database for that model — you call methods on it (Post.objects.all(), Post.objects.filter(...)) and it hands back a QuerySet: a collection of rows you can filter, order, and iterate.

The crucial insight is that a QuerySet is not a list of results. It's a description of a query that hasn't run yet. You build it up method by method, and Django only sends SQL to the database at the last possible moment.

💡 A useful analogy: The manager is a librarian, and a QuerySet is your written request slip. You can keep adding conditions to the slip — "published books, by this author, newest first" — without the librarian moving an inch. Only when you actually ask to read the results does the librarian walk the stacks once and bring back everything at once.

from blog.models import Post

# 'objects' is the manager; .all() returns a QuerySet
all_posts = Post.objects.all()

# Managers live on the CLASS, not on instances
first = Post.objects.first()
# first.objects.all()   # AttributeError — instances have no manager

Lazy Evaluation

QuerySets are lazy: building and chaining them costs nothing. The database is queried only when the results are genuinely needed. This lets you compose complex queries in several steps, and even pass a QuerySet around, without paying for a query at each step.

# No SQL runs on any of these three lines
qs = Post.objects.all()
qs = qs.filter(status="published")
qs = qs.order_by("-published_at")

# SQL runs HERE, once, when we iterate
for post in qs:
    print(post.title)

Core QuerySet Methods

A handful of methods cover the vast majority of everyday querying. They split into two groups: methods that return a new QuerySet (chainable, still lazy) and methods that return a concrete result (terminal — they run the query).

# Chainable — all still lazy
published = Post.objects.filter(status="published").order_by("-published_at")
not_drafts = Post.objects.exclude(status="draft")
newest_five = Post.objects.order_by("-published_at")[:5]   # slicing adds LIMIT

# Terminal — these run the query
total = Post.objects.count()
any_published = Post.objects.filter(status="published").exists()

Fetching a single object with get()

get() expects exactly one match. Guard it against the two things that can go wrong:

try:
    post = Post.objects.get(slug="hello-world")
except Post.DoesNotExist:
    post = None            # no row matched
except Post.MultipleObjectsReturned:
    raise                  # your assumption of uniqueness was wrong

Field Lookups & Q Objects

Field lookups are the double-underscore syntax that turns a filter keyword into a specific SQL condition. The pattern is field__lookup=value.

# Text
Post.objects.filter(title__icontains="django")     # case-insensitive LIKE
Post.objects.filter(title__startswith="The")

# Numbers & ranges
Post.objects.filter(rating__gte=4)                  # >= 4
Post.objects.filter(rating__range=(3, 5))           # BETWEEN 3 AND 5

# Dates
Post.objects.filter(published_at__year=2026)
Post.objects.filter(published_at__date=some_date)

# NULL test
Post.objects.filter(category__isnull=True)

# Relationship traversal — follow a ForeignKey with __
Post.objects.filter(author__username="ray")
Post.objects.filter(tags__name__icontains="python")

Passing several keyword arguments to one filter() call combines them with AND. For OR, negation, or grouping, reach for Q objects:

from django.db.models import Q

# published OR featured
Post.objects.filter(Q(status="published") | Q(is_featured=True))

# published AND NOT featured
Post.objects.filter(Q(status="published") & ~Q(is_featured=True))

# grouped: (published or featured) and in the Tech category
Post.objects.filter(
    (Q(status="published") | Q(is_featured=True)) & Q(category__name="Tech")
)

Aggregation, Annotation & F()

Aggregation — one summary value for the whole set

aggregate() collapses a QuerySet into a dictionary of computed values:

from django.db.models import Avg, Count, Max, Min

Post.objects.aggregate(Avg("rating"))
# {'rating__avg': 4.2}

Post.objects.aggregate(
    total=Count("id"),
    avg_rating=Avg("rating"),
    top=Max("rating"),
)
# {'total': 42, 'avg_rating': 4.2, 'top': 5.0}

Annotation — one computed value per row

annotate() attaches a calculated attribute to each object in the QuerySet — perfect for "count of related rows":

from django.db.models import Count

# Each author now has an .article_count attribute
authors = Author.objects.annotate(article_count=Count("articles"))
for author in authors:
    print(author.name, author.article_count)

# Conditional counting with a filter argument
from django.db.models import Q
Post.objects.annotate(
    approved_comments=Count("comments", filter=Q(comments__is_approved=True)),
)

F() — refer to a field's value in the query

F() lets the database compare or update fields against each other, with no round-trip to Python and no race conditions:

from django.db.models import F

# Atomic increment — safe under concurrency
Post.objects.filter(pk=1).update(view_count=F("view_count") + 1)

# Compare two columns to each other
Post.objects.filter(comment_count__gt=F("view_count"))

Custom Managers & QuerySets

When the same filters appear across your views, move them into the model layer. There are two building blocks, and the modern best-practice combines them.

A custom manager (simple)

from django.db import models


class PublishedManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(status="published")


class Post(models.Model):
    # ... fields ...
    objects = models.Manager()          # the default manager
    published = PublishedManager()      # Post.published.all()

The catch: manager methods aren't chainable. Post.published gives you published posts, but you can't write Post.objects.published().recent() because published() would live on the manager, not the QuerySet.

A custom QuerySet with as_manager() (recommended)

Define your reusable filters on a QuerySet subclass so they chain, then expose it as the manager with .as_manager():

from datetime import timedelta
from django.db import models
from django.utils import timezone


class PostQuerySet(models.QuerySet):
    def published(self):
        return self.filter(status="published")

    def recent(self, days=7):
        cutoff = timezone.now() - timedelta(days=days)
        return self.filter(published_at__gte=cutoff)

    def by_author(self, author):
        return self.filter(author=author)


class Post(models.Model):
    # ... fields ...
    objects = PostQuerySet.as_manager()

Now every method chains freely, in any order:

# Reads like a sentence — and it's all one SQL query
Post.objects.published().recent(days=30).by_author(ray).order_by("-published_at")

Query Optimization

The single most common Django performance bug is the N+1 query problem: you fetch a list of N objects, then trigger one extra query per object while looping to access a related object. A page that should run 1 query ends up running 51.

# ❌ N+1: one query for the posts, then one MORE per post for its author
posts = Post.objects.all()
for post in posts:
    print(post.author.username)      # a new query every iteration

select_related — for ForeignKey / OneToOne

Follows the relation with a SQL JOIN, pulling the related object in the same query:

# ✅ One query total, via a JOIN
posts = Post.objects.select_related("author")
for post in posts:
    print(post.author.username)      # no extra queries

prefetch_related — for ManyToMany / reverse ForeignKey

Runs a second query for the related rows and joins them in Python — the right tool for "to-many" relations a JOIN can't collapse:

# ✅ Two queries total, no matter how many posts
posts = Post.objects.prefetch_related("tags")
for post in posts:
    print([tag.name for tag in post.tags.all()])

# Combine both when a view needs each
posts = Post.objects.select_related("author").prefetch_related("tags")

Fetch only what you need

# Dictionaries instead of model instances
Post.objects.values("title", "author__username")

# A flat list of one column
Post.objects.values_list("title", flat=True)

# Load a subset of columns (the rest load lazily if touched)
Post.objects.only("title", "published_at")

Hands-on Exercise

from datetime import timedelta
from django.db import models
from django.utils import timezone


class PostQuerySet(models.QuerySet):
    def published(self):
        return self.filter(status="published")

    def recent(self, days=7):
        cutoff = timezone.now() - timedelta(days=days)
        return self.filter(published_at__gte=cutoff)

    def popular(self, min_comments=5):
        return self.annotate(
            comment_count=models.Count("comments")
        ).filter(comment_count__gte=min_comments)


class Post(models.Model):
    # ... fields ...
    objects = PostQuerySet.as_manager()


# One clean expression
featured = (
    Post.objects.published()
    .recent(days=30)
    .popular(min_comments=10)
    .order_by("-published_at")
)

# Optimized view query
def post_list(request):
    posts = (
        Post.objects.published()
        .select_related("author")
        .prefetch_related("tags")
        .order_by("-published_at")
    )
    return render(request, "blog/list.html", {"posts": posts})

Best Practices

Summary & Quiz

📚 Further Reading

• Django Docs — Making queries
• Django Docs — QuerySet API reference
• Django Docs — Managers
• Django Docs — Aggregation
• Django Docs — Database access optimization

🚀 What's Next?

You can now read and write data fluently. In the next lesson, Function-Based Views, you'll wire these queries into request handlers that turn URLs into HTTP responses — the layer where your models finally meet the browser.