Ticket #14120: queryset-get.diff

docs/topics/db/queries.txt

@@ -163 +163 @@
 that cannot be evaluated. The ``all()`` method returns a ``QuerySet`` that
 *can* be evaluated.)
 
+
 Retrieving specific objects with filters
 ----------------------------------------
 
@@ -258 +259 @@
 ``QuerySet`` is *evaluated* by accessing the database. For more details on
 exactly when evaluation takes place, see :ref:`when-querysets-are-evaluated`.
 
+
+.. _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()``, ``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 <queryset-api>` for a complete list
-of all the various ``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 <queryset-api>` for a complete
+list of all the various ``QuerySet`` methods.
 
 .. _limiting-querysets:
 
@@ -304 +336 @@
 
 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: