diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 7a59f6f634..2141aa6e91 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -163,6 +163,7 @@ That's because ``Entry.objects``, the root ``QuerySet``, is a special case that cannot be evaluated. The ``all()`` method returns a ``QuerySet`` that *can* be evaluated.) + Retrieving specific objects with filters ---------------------------------------- @@ -258,12 +259,43 @@ aren't fetched from the database until you "ask" for them. When you do, the ``QuerySet`` is *evaluated* by accessing the database. For more details on exactly when evaluation takes place, see :ref:`when-querysets-are-evaluated`. -Other QuerySet methods -~~~~~~~~~~~~~~~~~~~~~~ -Most of the time you'll use ``all()``, ``filter()`` and ``exclude()`` when you -need to look up objects from the database. However, that's far from all there is; see the :ref:`QuerySet API Reference ` for a complete list -of all the various ``QuerySet`` methods. +.. _retrieving-single-object-with-get: + +Retrieving a single object with get +----------------------------------- + +``.filter()`` will always give you a ``QuerySet``, even if only a single +object matches the query - in this case, it will be a ``QuerySet`` containing +a single element. + +If you know there is only one object that matches your query, you can use +the ``get()`` method on a `Manager` which returns the object directly:: + + >>> one_entry = Entry.objects.get(pk=1) + +You can use any query expression with ``get()``, just like with ``filter()`` - +again, see `Field lookups`_ below. + +Note that there is a difference between using ``.get()``, and using +``.filter()`` with a slice of ``[0]``. If there are no results that match the +query, ``.get()`` will raise a ``DoesNotExist`` exception. This exception is an +attribute of the model class that the query is being performed on - so in the +code above, if there is no ``Entry`` object with a primary key of 1, Django will +raise ``Entry.DoesNotExist``. + +Similarly, Django will complain if more than one item matches the ``get()`` +query. In this case, it will raise ``MultipleObjectsReturned``, which again is +an attribute of the model class itself. + + +Other QuerySet methods +---------------------- + +Most of the time you'll use ``all()``, ``get()``, ``filter()`` and ``exclude()`` +when you need to look up objects from the database. However, that's far from all +there is; see the :ref:`QuerySet API Reference ` for a complete +list of all the various ``QuerySet`` methods. .. _limiting-querysets: @@ -304,7 +336,7 @@ This is roughly equivalent to:: Note, however, that the first of these will raise ``IndexError`` while the second will raise ``DoesNotExist`` if no objects match the given criteria. See -``get()`` for more details. +:meth:`~django.db.models.QuerySet.get` for more details. .. _field-lookups-intro: