Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fixed #14120 - Document get() in Making Queries - thanks danielr and …

…adamv for work on the patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14820 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 111ed0195e8ff53f83b1ac74d6822111f8942727 1 parent 097072a
Tim Graham timgraham authored
Showing with 37 additions and 5 deletions.
  1. +37 −5 docs/topics/db/queries.txt
42 docs/topics/db/queries.txt
View
@@ -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:
Please sign in to comment.
Something went wrong with that request. Please try again.