Introduction to Django ORM

Notice in the picture that filter() and order_by() happen entirely in Python. The database sees only the one SELECT that the loop triggers.

Getting One Row

When you need exactly one object, use get(). It returns the object itself, not a queryset:

article = Article.objects.get(title="Understanding Querysets")
print(article.author)

Ben Carter

The most common use is fetching a row by its primary key, as in Article.objects.get(pk=1). The name pk always means the primary key, which for this model is id.

The get() method raises an exception when it does not find exactly one row. With no match, it raises the model's DoesNotExist exception, and with more than one match, it raises MultipleObjectsReturned:

blog.models.Article.DoesNotExist: Article matching query does not exist.
blog.models.Article.MultipleObjectsReturned: get() returned more than one Article -- it returned 2!

The second message comes from Article.objects.get(author="Ana Lopez"), because two articles match. Each model has its own copy of both exceptions, so you can catch them by name:

try:
    article = Article.objects.get(title="No such article")
except Article.DoesNotExist:
    article = None

When a missing row is normal rather than an error, first() is shorter. It returns the first matching object, or None when nothing matches:

print(Article.objects.filter(author="Ana Lopez").first())
print(Article.objects.filter(author="Nobody").first())

Getting Started with Django
None

Sorting, Slicing and Searching

The order_by() method sorts the results by one or more fields. A hyphen before the field name reverses the order:

print(Article.objects.order_by("view_count"))
print(Article.objects.order_by("-view_count"))

<QuerySet [<Article: Getting Started with Django>, <Article: Django Models in Practice>, <Article: Understanding Querysets>]>
<QuerySet [<Article: Understanding Querysets>, <Article: Django Models in Practice>, <Article: Getting Started with Django>]>

Slicing a queryset with Python's slice syntax limits the number of rows. Django turns the slice into a LIMIT clause, so the database returns only those rows:

top_two = Article.objects.order_by("-view_count")[:2]
print(top_two)
print(top_two.query)

<QuerySet [<Article: Understanding Querysets>, <Article: Django Models in Practice>]>
SELECT ... FROM "blog_article" ORDER BY "blog_article"."view_count" DESC LIMIT 2

Always sort before you slice when the order matters. Without order_by(), the database may return rows in any order, so Article.objects.all()[:3] gives you three articles, but not necessarily the first three you created.

For text, the iexact lookup matches a whole value and ignores letter case, while icontains matches any value that contains the given text, also ignoring case:

print(Article.objects.get(title__iexact="understanding QUERYSETS"))
print(Article.objects.filter(title__icontains="django"))

Understanding Querysets
<QuerySet [<Article: Getting Started with Django>, <Article: Django Models in Practice>]>

The lookups without the i, exact and contains, compare the case as well. On SQLite, contains still ignores case, because SQLite's LIKE operator does not support case-sensitive matching. PostgreSQL follows the difference for both lookups. On MySQL, contains respects case, but whether exact does depends on the collation of the table, and the default collations ignore case.

Counting and Aggregating

To count rows, call count() on a queryset. Django runs a SELECT COUNT(*) and does not load the rows:

print(Article.objects.count())
print(Article.objects.filter(author="Ana Lopez").count())

3
2

For other totals, the aggregate() method computes a value over all the rows of a queryset in the database. The functions Count, Sum, Avg, Min and Max come from django.db.models, and the result is a dictionary:

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

print(Article.objects.aggregate(Count("id")))
print(Article.objects.aggregate(Avg("view_count")))
print(Article.objects.aggregate(total=Sum("view_count"), top=Max("view_count")))
print(Article.objects.filter(author="Ana Lopez").aggregate(Avg("view_count")))

{'id__count': 3}
{'view_count__avg': 55.0}
{'total': 165, 'top': 120}
{'view_count__avg': 22.5}

Without names, each key is the field name, two underscores, and the function name, such as view_count__avg. With a keyword such as total=, you choose the key. The last line shows that aggregate() works on a filtered queryset too: Ana Lopez's two articles have 0 and 45 views, so their average is 22.5.

Updating Rows

To change one row, fetch the object, change its attributes and call save() again. Because the object already has an id, Django runs an UPDATE instead of an INSERT:

article = Article.objects.get(title="Getting Started with Django")
article.view_count = 10
article.save()

Captured with CaptureQueriesContext, as in the laziness example, the save() call sends this SQL:

UPDATE "blog_article" SET "title" = 'Getting Started with Django', "content" = 'Install Django and create a project.', "author" = 'Ana Lopez', "published_date" = '2026-11-05 22:35:42.793237', "view_count" = 10 WHERE "blog_article"."id" = 1

The SQL shows that save() writes every column, not only the one you changed. If another request changed the title between your get() and your save(), your save() would write the old title back. To write only some columns, name them: article.save(update_fields=["view_count"]) runs UPDATE "blog_article" SET "view_count" = 10 WHERE "blog_article"."id" = 1.

To change many rows at once, call update() on a queryset. It runs a single UPDATE statement and returns the number of rows it changed:

changed = Article.objects.filter(author="Ana Lopez").update(author="Ana M. Lopez")
print(changed)

2

The whole change is one statement:

UPDATE "blog_article" SET "author" = 'Ana M. Lopez' WHERE "blog_article"."author" = 'Ana Lopez'

The update() method does not load the objects and does not call their save() methods. That makes it much faster for many rows, but any extra logic you put in a model's save() method does not run.

Deleting Rows

To delete one row, call delete() on the object. To delete every row that matches a filter, call delete() on the queryset. Both return the number of rows deleted, and a dictionary with the count for each model:

article = Article.objects.get(title="Django Models in Practice")
print(article.delete())
print(Article.objects.filter(author="Ana M. Lopez").delete())

(1, {'blog.Article': 1})
(1, {'blog.Article': 1})

The second call deleted one article because the first call had already removed the other article by the same author. After delete(), the Python object still exists with its field values, but its id is None, and the row is gone from the database. A deleted row cannot be recovered from Django, so be careful with a queryset delete() in the shell. Article.objects.all().delete() empties the table.

Key Takeaways

• Every query starts from the model's manager, Article.objects. Methods such as all(), filter(), exclude() and order_by() return querysets, which you can chain.
• A queryset is lazy. It runs its SQL when you use the rows, once, and it keeps the results. Print queryset.query to see the SQL.
• get() returns one object and raises DoesNotExist or MultipleObjectsReturned otherwise. first() returns None when nothing matches.
• Sort before you slice. count() and aggregate() compute in the database and return numbers, not objects.
• save() writes every column of one row, while update() and delete() on a queryset change many rows in one statement without calling save().