Browse files

[1.2.X] Fixed #14120 - Document get() in Making Queries - thanks dani…

…elr and adamv for work on the patch.

Backport of r14820 from trunk.

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent f6294c0 commit 778782eac81c95c5fb8a70604ed8c3da0d8bd1f7 @timgraham timgraham committed Dec 4, 2010
Showing with 37 additions and 5 deletions.
  1. +37 −5 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`.
+.. _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,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:

0 comments on commit 778782e

Please sign in to comment.