Fixed #15558 -- Improved QuerySet reference docs and cleaned up numerous reST/sphinx problems.

QuerySet API reference

======================

.. currentmodule:: django.db.models.QuerySet

.. currentmodule:: django.db.models.query

This document describes the details of the ``QuerySet`` API. It builds on the

material presented in the :doc:`model </topics/db/models>` and :doc:`database

============

Though you usually won't create one manually -- you'll go through a

:class:`Manager` -- here's the formal declaration of a ``QuerySet``:

:class:`~django.db.models.Manager` -- here's the formal declaration of a

``QuerySet``:

.. class:: QuerySet([model=None])

.. class:: QuerySet([model=None, query=None, using=None])

Usually when you'll interact with a ``QuerySet`` you'll use it by :ref:`chaining

filters <chaining-filters>`. To make this work, most ``QuerySet`` methods return new querysets.

    Usually when you'll interact with a ``QuerySet`` you'll use it by

    :ref:`chaining filters <chaining-filters>`. To make this work, most

    ``QuerySet`` methods return new querysets. These methods are covered in

    detail later in this section.

    The ``QuerySet`` class has two public attributes you can use for

    introspection:

    .. attribute:: ordered

        ``True`` if the ``QuerySet`` is ordered -- i.e. has an order_by()

        clause or a default ordering on the model. ``False`` otherwise.

    .. attribute:: db

        The database that will be used if this query is executed now.

    .. note::

        The ``query`` parameter to :class:`QuerySet` exists so that specialized

        query subclasses such as

        :class:`~django.contrib.gis.db.models.GeoQuerySet` can reconstruct

        internal query state. The value of the parameter is an opaque

        representation of that query state and is not part of a public API.

        To put it simply: if you need to ask, you don't need to use it.

.. currentmodule:: django.db.models.query.QuerySet

Methods that return new QuerySets

---------------------------------

ordering, call ``order_by()`` with no parameters.

You can tell if a query is ordered or not by checking the

:attr:`QuerySet.ordered` attribute, which will be ``True`` if the

:attr:`.QuerySet.ordered` attribute, which will be ``True`` if the

``QuerySet`` has been ordered in any way.

reverse

elsewhere, but all it means is that a new object will always be created.

Normally you won't need to worry about this. However, if your model contains a

manual primary key value that you set and if that value already exists in the

database, a call to ``create()`` will fail with an :exc:`IntegrityError` since

primary keys must be unique. So remember to be prepared to handle the exception

if you are using manual primary keys.

database, a call to ``create()`` will fail with an

:exc:`~django.db.IntegrityError` since primary keys must be unique. So remember

to be prepared to handle the exception if you are using manual primary keys.

get_or_create

~~~~~~~~~~~~~

.. versionadded:: 1.2

Returns ``True`` if the :class:`QuerySet` contains any results, and ``False``

Returns ``True`` if the :class:`.QuerySet` contains any results, and ``False``

if not. This tries to perform the query in the simplest and fastest way

possible, but it *does* execute nearly the same query. This means that calling

:meth:`QuerySet.exists()` is faster than ``bool(some_query_set)``, but not by

:meth:`.QuerySet.exists` is faster than ``bool(some_query_set)``, but not by

a large degree.  If ``some_query_set`` has not yet been evaluated, but you know

that it will be at some point, then using ``some_query_set.exists()`` will do

more overall work (an additional query) than simply using

Performs an SQL update query for the specified fields, and returns

the number of rows affected. The ``update()`` method is applied instantly and

the only restriction on the :class:`QuerySet` that is updated is that it can

the only restriction on the :class:`.QuerySet` that is updated is that it can

only update columns in the model's main table. Filtering based on related

fields is still possible. You cannot call ``update()`` on a

:class:`QuerySet` that has had a slice taken or can otherwise no longer be

:class:`.QuerySet` that has had a slice taken or can otherwise no longer be

filtered.

For example, if you wanted to update all the entries in a particular blog

.. method:: delete()

Performs an SQL delete query on all rows in the :class:`QuerySet`. The

Performs an SQL delete query on all rows in the :class:`.QuerySet`. The

``delete()`` is applied instantly. You cannot call ``delete()`` on a

:class:`QuerySet` that has had a slice taken or can otherwise no longer be

:class:`.QuerySet` that has had a slice taken or can otherwise no longer be

filtered.

For example, to delete all the entries in a particular blog::

   :func:`render()` is the same as a call to

   :func:`render_to_response()` with a `context_instance` argument that

   that forces the use of a :class:`RequestContext`.

   that forces the use of a :class:`~django.template.RequestContext`.

Required arguments

------------------

.. function:: get_object_or_404(klass, *args, **kwargs)

   Calls :meth:`~django.db.models.QuerySet.get()` on a given model manager,

   Calls :meth:`~django.db.models.query.QuerySet.get()` on a given model manager,

   but it raises :class:`~django.http.Http404` instead of the model's

   :class:`~django.core.exceptions.DoesNotExist` exception.

``klass``

    A :class:`~django.db.models.Model`, :class:`~django.db.models.Manager` or

    :class:`~django.db.models.QuerySet` instance from which to get the object.

    :class:`~django.db.models.query.QuerySet` instance from which to get the

    object.

``**kwargs``

    Lookup parameters, which should be in the format accepted by ``get()`` and

.. function:: get_list_or_404(klass, *args, **kwargs)

   Returns the result of :meth:`~django.db.models.QuerySet.filter()` on a

   Returns the result of :meth:`~django.db.models.query.QuerySet.filter()` on a

   given model manager, raising :class:`~django.http.Http404` if the resulting

   list is empty.