Ticket #14120: queryset-get.diff

File queryset-get.diff, 2.9 KB (added by Adam Vandenberg, 14 years ago)

Updated patch that removes trailing spaces and links the get.

  • docs/topics/db/queries.txt

    diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt
    index 7a59f6f..2141aa6 100644
    a b That's because ``Entry.objects``, the root ``QuerySet``, is a special case  
    163163that cannot be evaluated. The ``all()`` method returns a ``QuerySet`` that
    164164*can* be evaluated.)
    165165
     166
    166167Retrieving specific objects with filters
    167168----------------------------------------
    168169
    aren't fetched from the database until you "ask" for them. When you do, the  
    258259``QuerySet`` is *evaluated* by accessing the database. For more details on
    259260exactly when evaluation takes place, see :ref:`when-querysets-are-evaluated`.
    260261
     262
     263.. _retrieving-single-object-with-get:
     264
     265Retrieving a single object with get
     266-----------------------------------
     267
     268``.filter()`` will always give you a ``QuerySet``, even if only a single
     269object matches the query - in this case, it will be a ``QuerySet`` containing
     270a single element.
     271
     272If you know there is only one object that matches your query, you can use
     273the ``get()`` method on a `Manager` which returns the object directly::
     274
     275    >>> one_entry = Entry.objects.get(pk=1)
     276
     277You can use any query expression with ``get()``, just like with ``filter()`` -
     278again, see `Field lookups`_ below.
     279
     280Note that there is a difference between using ``.get()``, and using
     281``.filter()`` with a slice of ``[0]``. If there are no results that match the
     282query, ``.get()`` will raise a ``DoesNotExist`` exception. This exception is an
     283attribute of the model class that the query is being performed on - so in the
     284code above, if there is no ``Entry`` object with a primary key of 1, Django will
     285raise ``Entry.DoesNotExist``.
     286
     287Similarly, Django will complain if more than one item matches the ``get()``
     288query. In this case, it will raise ``MultipleObjectsReturned``, which again is
     289an attribute of the model class itself.
     290
     291
    261292Other QuerySet methods
    262 ~~~~~~~~~~~~~~~~~~~~~~
     293----------------------
    263294
    264 Most of the time you'll use ``all()``, ``filter()`` and ``exclude()`` when you
    265 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
    266 of all the various ``QuerySet`` methods.
     295Most of the time you'll use ``all()``, ``get()``, ``filter()`` and ``exclude()``
     296when you need to look up objects from the database. However, that's far from all
     297there is; see the :ref:`QuerySet API Reference <queryset-api>` for a complete
     298list of all the various ``QuerySet`` methods.
    267299
    268300.. _limiting-querysets:
    269301
    This is roughly equivalent to::  
    304336
    305337Note, however, that the first of these will raise ``IndexError`` while the
    306338second will raise ``DoesNotExist`` if no objects match the given criteria. See
    307 ``get()`` for more details.
     339:meth:`~django.db.models.QuerySet.get` for more details.
    308340
    309341.. _field-lookups-intro:
    310342
Back to Top