Annotation in Django ORM allows you to attach additional information to each object in a QuerySet. It's a powerful feature for augmenting the results of queries with calculated values, which can be aggregates computed over related objects or values derived from model fields.

Basic Annotation

Example 1:

Assume each Book has a pages field. This annotates each genre with the total number of pages of all books within that genre.

from django.db.models import Sum

genre_with_page_count = Genre.objects.annotate(total_pages=Sum("book__pages"))

Example 2:

Assume each Book has a rating field.

from django.db.models import Avg

author_with_avg_rating = Author.objects.annotate(avg_rating=Avg("book__rating"))

Adds an average rating for the books written by each author.

Advanced Annotation Use Cases

Example 1:

Assume each Book has a publication_date field.

from django.db.models import Count, F, Year

books_per_year = Author.objects.annotate(year=F("book__publication_date__year")).values("year").annotate(count=Count("book"))

Counts how many books each author published per year.

Example 2:

Finds the most recently published book for each genre.

from django.db.models import Max

latest_book_per_genre = Genre.objects.annotate(latest_book=Max("book__publication_date"))

Annotation with Filters

Example 1:

Counts the number of fantasy books written by each author.

author_genre_count = Author.objects.filter(book__genre__name="Fantasy").annotate(fantasy_books_count=Count("book"))