Welcome to my fridge door!

created_at = models.DateTimeField(auto_now_add=True) # creation timestamp
updated_at = models.DateTimeField(auto_now=True) # last modified timestamp

Returns a QuerySet with the annotated fields added.

Each object in the queryset will have the extra field as an attribute.

Often used with aggregation functions from django.db.models, like Count, Sum, Avg, Max, Min.

class Author(models.Model):
name = models.CharField(max_length=100)

class Book(models.Model):
author = models.ForeignKey(Author, on_delete=models.CASCADE)
title = models.CharField(max_length=100)

authors = Author.objects.annotate(num_books=Count('book'))

for author in authors:
print(author.name, author.num_books)

___
actor = Actor.objects.prefetch_related('starring_movies')
.annotate(avg_r=Avg('starring_movies__rating'), stars=Count('starring_movies'))
.order_by('-stars', 'full_name').first()

annotate(avg_r=Avg(...), stars=Count(...))

Adds per-actor fields:
avg_r → average rating of that actor’s movies
stars → number of movies that actor starred in
These are calculated individually for each actor.

Why .aggregate() is different

Actor.objects.aggregate(avg_r=Avg('starring_movies__rating'))
Computes one single value for the entire queryset.

Returns a dictionary: {'avg_r': 7.5}

You cannot chain .annotate() or .order_by() after it, because it’s no longer a queryset — it’s a single summary.


annotate()    - Per object / per row    - QuerySet of objects with extra fields -    Average rating of each actor’s movies
aggregate()    - Whole queryset    - Single dict    - Average rating across all actors’ movies

class Movie(models.Model):
class StoryChoice(models.TextChoices):
AC = 'Action', 'Action'
CO = 'Comedy', 'Comedy'
DR = 'Drama','Drama'
OT = 'Other', 'Other'

title = models.CharField(max_length=150, validators=[MinLengthValidator(5)])
release_date = models.DateField()
storyline = models.TextField(blank=True, null=True)
genre = models.CharField(max_length=6, default=StoryChoice.OT, choices=StoryChoice.choices)

@admin.register(Director)
class DirectorAdmin(admin.ModelAdmin):
list_display = ['full_name','birth_date','nationality','years_of_experience'] # columns shown in the list view
list_filter = ['years_of_experience','nationality'] # sidebar filters to quickly narrow results
search_fields = ['full_name','nationality'] # fields searchable via the search box
list_display_links = ['full_name'] # which columns link to the detail/edit page
list_editable = ['years_of_experience'] # columns editable directly in the list view
ordering = ['full_name'] # default sorting of the list view
list_per_page = 25 # number of items displayed per page

readonly_fields = ['birth_date'] # this field cannot be edited in the admin form

search_help_text = "Enter full or partial names to quickly find directors."

Use ISO format: 'YYYY-MM-DD', e.g. '2001-05-25'.

query = Q()
if search_name is not None:
query &= Q(full_name__icontains=search_name)
if search_nationality is not None:
query &= Q(nationality__icontains=search_nationality)
dire = Director.objects.filter(query)

aggregate() returns a single dict, not a queryset.

Use it when you want summary statistics for the whole table (or filtered subset).

For grouped summaries, use annotate() instead.

stats = Movie.objects.aggregate(
total_movies=Count('id'),
average_rating=Avg('rating'),
highest_rating=Max('rating'),
lowest_rating=Min('rating'),
sum_rating=Sum('rating')
)

print(stats)

{
'total_movies': 10,
'average_rating': 7.5,
'highest_rating': 10.0,
'lowest_rating': 5.0,
'sum_rating': 75.0
}

If the filter() matches no movies, then first() returns None instead of raising an error.
Normally, if the queryset has results, first() returns the first model instance from the queryset - an object.

update() does not return a queryset, it returns the number of rows updated (an integer)
um = Movie.objects.filter(is_classic=True, rating__lt=10.0).update(rating=F('rating') + 0.1)
return f"Rating increased for {um} movies." if um else "No ratings increased."