When retrieving a single record in Django, the ORM offers two possible methods:
.first(). Let's learn how each one works and when to use them.
Django's most basic way to retrieve a single record is the .get() method. It is used as follows:
burger = Menu.objects.get(name="Beef Burger")
Quick facts about
It retrieves only one record.
If no record exists that meets the given criteria, it raises a
If more than one record with the given criteria exists, it raises a
A different way to get one record is to use .first() on a QuerySet. For example:
burger = Menu.objects.filter(name="Beef Burger").first()
Quick facts about
It will return the first item of a recordset.
If no record exists, it returns
Handling unexpected situations
If Django's ORM can't return one record (i.e. there is either no record, or there are more than one), you have to catch the relevant exception. For example:
try: return Menu.objects.get(name="Beef Burger") except Menu.DoesNotExist: raise Exception("Could not find a burger") except Menu.MultipleObjectsReturned: raise Exception("Found too many burgers")
.first(), the only unexpected situation is if no record was present in the QuerySet. Since it's not a problem if multiple records exist that meet the criteria, we have to deal only with the one case. For example:
burger = Menu.objects.filter(name="Beef Burger").first() if not burger: raise Exception("Could not find a burger") return burger
Did you notice the differences between the two above? For
.get() we have to deal with more "error" scenarios. But why is that? The
.get() method expects no more and no less than one record to be returned, whereas
.first() assumes there might be multiple records, and it returns the first. So we have a fundamental difference in the assumptions each of these makes.
Should we care? Does it really make a difference which of the two methods we use if we get the same result?
I used to think it didn't matter, but I was wrong.
.get()might point to a problem with our Model that we are unaware of. If we are expecting only one record to be returned, but we get back multiple, we have failed to make sure that one of the fields (or multiple ones) enforce a unique constraint. Handling this at a database layer is crucial. If we had used
.first(), and had not added a unique constraint, we might have never noticed if there were multiple records where we are expecting only one.
What about readability? I never thought about how the code reads in each case, and what it tells the reader about the data models. When you use
.get(), the reader will (or should) know immediately that the record should be unique for the fields you filtered on. However, if you use
.first(), it implies to the reader that multiple records might exist, but you only care about the first one.
When to use which
.get() when you are expecting only one (or a maximum of one) record to be returned. The code makes your intentions clear, and there's less room for undetected errors.
.first() when you know there might be multiple records (and that's ok), but you only care about the first. In most cases you should also have some order defined on the model (or specified on your query), otherwise the first record might be random. In some cases you might not even care about the order, but just be aware of it.
If you use
.first(), you run the risk of using the
None(in the case of no record found) as a different return data type to signify the fact that nothing was found. It's not very likely, but I've caught myself doing this. I wrote about that trap here.
The SQL query generated by
.get()does not have a limit. So if you have multiple records, before the
MultipleObjectsReturnedexception is raised, your database will return all the records matching that criteria. But using
LIMIT 1to your query, so it will only ever return one record. Be careful which one you choose.
If you query the database and only ever expect one record (maximum) to be returned, don't use
.first(), but rather
.get() instead. You'll thank yourself later.