Fixed #14758 - Remove entire method signatures from QuerySet headings - thanks adamv for the patch.

QuerySet API

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

Though you usually won't create one manually -- you'll go through a :class:`Manager` -- here's the formal declaration of a ``QuerySet``:

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

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

.. class:: QuerySet([model=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.

QuerySet methods that return new QuerySets

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

Methods that return new QuerySets

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

Django provides a range of ``QuerySet`` refinement methods that modify either

the types of results returned by the ``QuerySet`` or the way its SQL query is

executed.

``filter(**kwargs)``

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

filter

~~~~~~

.. method:: filter(**kwargs)

`Field lookups`_ below. Multiple parameters are joined via ``AND`` in the

underlying SQL statement.

``exclude(**kwargs)``

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

exclude

~~~~~~~

.. method:: exclude(**kwargs)

Note the second example is more restrictive.

``annotate(*args, **kwargs)``

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

annotate

~~~~~~~~

.. method:: annotate(*args, **kwargs)

For an in-depth discussion of aggregation, see :doc:`the topic guide on

Aggregation </topics/db/aggregation>`.

``order_by(*fields)``

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

order_by

~~~~~~~~

.. method:: order_by(*fields)

...since the ``Blog`` model has no default ordering specified.

Be cautious when ordering by fields in related models if you are also using

``distinct()``. See the note in the `distinct()`_ section for an explanation

of how related model ordering can change the expected results.

``distinct()``. See the note in :meth:`distinct` for an explanation of how

related model ordering can change the expected results.

It is permissible to specify a multi-valued field to order the results by (for

example, a ``ManyToMany`` field). Normally this won't be a sensible thing to

.. versionadded:: 1.0

If you don't want any ordering to be applied to a query, not even the default

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

.. versionadded:: 1.0

The syntax for ordering across related models has changed. See the `Django 0.96

documentation`_ for the old behaviour.

respect to case-sensitivity, Django will order results however your database

backend normally orders them.

If you don't want any ordering to be applied to a query, not even the default

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

.. versionadded:: 1.1

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

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

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

``reverse()``

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

reverse

~~~~~~~

.. method:: reverse()

ordering was undefined prior to calling ``reverse()``, and will remain

undefined afterward).

``distinct()``

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

distinct

~~~~~~~~

.. method:: distinct()

``QuerySet`` is evaluated. That's when you'd use ``distinct()``.

.. note::

    Any fields used in an `order_by(*fields)`_ call are included in the SQL

    Any fields used in an :meth:`order_by` call are included in the SQL

    ``SELECT`` columns. This can sometimes lead to unexpected results when

    used in conjunction with ``distinct()``. If you order by fields from a

    related model, those fields will be added to the selected columns and they

    ``values()`` together, be careful when ordering by fields not in the

    ``values()`` call.

``values(*fields)``

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

values

~~~~~~

.. method:: values(*fields)

        >>> Entry.objects.values('blog_id')

        [{'blog_id': 1}, ...]

    * When using ``values()`` together with ``distinct()``, be aware that

      ordering can affect the results. See the note in the `distinct()`_

      section, above, for details.

      ordering can affect the results. See the note in :meth:`distinct` for

      details.

    * If you use a ``values()`` clause after an ``extra()`` clause,

      any fields defined by a ``select`` argument in the ``extra()``

      must be explicitly included in the ``values()`` clause. However,

but it doesn't really matter. This is your chance to really flaunt your

individualism.

``values_list(*fields)``

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

values_list

~~~~~~~~~~~

.. method:: values_list(*fields)

If you don't pass any values to ``values_list()``, it will return all the

fields in the model, in the order they were declared.

``dates(field, kind, order='ASC')``

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

dates

~~~~~

.. method:: dates(field, kind, order='ASC')

    >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')

    [datetime.datetime(2005, 3, 20)]

``none()``

~~~~~~~~~~

none

~~~~

.. method:: none()

    >>> Entry.objects.none()

    []

``all()``

~~~~~~~~~

all

~~~

.. method:: all()

.. versionadded:: 1.0

Returns a ''copy'' of the current ``QuerySet`` (or ``QuerySet`` subclass you

Returns a *copy* of the current ``QuerySet`` (or ``QuerySet`` subclass you

pass in). This can be useful in some situations where you might want to pass

in either a model manager or a ``QuerySet`` and do further filtering on the

result. You can safely call ``all()`` on either object and then you'll

.. _select-related:

``select_related()``

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

select_related

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

.. method:: select_related()

``OneToOneFields`` will not be traversed in the reverse direction if you

are performing a depth-based ``select_related``.

``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)``

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

extra

~~~~~

.. method:: extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)

        Entry.objects.extra(where=['headline=%s'], params=['Lennon'])

``defer(*fields)``

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

defer

~~~~~

.. method:: defer(*fields)

    # Defers both the body and headline fields.

    Entry.objects.defer("body").filter(rating=5).defer("headline")

The order in which fields are added to the deferred set does not matter. Calling ``defer()`` with a field name that has already been deferred is harmless (the field will still be deferred).

The order in which fields are added to the deferred set does not matter.

Calling ``defer()`` with a field name that has already been deferred is

harmless (the field will still be deferred).

You can defer loading of fields in related models (if the related models are

loading via ``select_related()``) by using the standard double-underscore

    bother using ``defer()``; leave it until your query construction has

    settled down and you understand where the hot-points are.

``only(*fields)``

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

only

~~~~

.. method:: only(*fields)

    # existing set of fields).

    Entry.objects.defer("body").only("headline", "body")

``using(alias)``

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

using

~~~~~

.. method:: using(alias)

    >>> Entry.objects.using('backup')

QuerySet methods that do not return QuerySets

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

Methods that do not return QuerySets

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

The following ``QuerySet`` methods evaluate the ``QuerySet`` and return

something *other than* a ``QuerySet``.

These methods do not use a cache (see :ref:`caching-and-querysets`). Rather,

they query the database each time they're called.

``get(**kwargs)``

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

get

~~~

.. method:: get(**kwargs)

    except ObjectDoesNotExist:

        print "Either the entry or blog doesn't exist."

``create(**kwargs)``

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

create

~~~~~~

.. method:: create(**kwargs)

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 ``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:`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(**kwargs)``

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

get_or_create

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

.. method:: get_or_create(**kwargs)

.. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1

``count()``

~~~~~~~~~~~

count

~~~~~

.. method:: count()

is an underlying implementation quirk that shouldn't pose any real-world

problems.

``in_bulk(id_list)``

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

in_bulk

~~~~~~~

.. method:: in_bulk(id_list)

If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary.

``iterator()``

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

iterator

~~~~~~~~

.. method:: iterator()

.. _iterator: http://www.python.org/dev/peps/pep-0234/

``latest(field_name=None)``

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

latest

~~~~~~

.. method:: latest(field_name=None)

Note ``latest()`` exists purely for convenience and readability.

``aggregate(*args, **kwargs)``

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

aggregate

~~~~~~~~~

.. method:: aggregate(*args, **kwargs)

For an in-depth discussion of aggregation, see :doc:`the topic guide on

Aggregation </topics/db/aggregation>`.

``exists()``

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

exists

~~~~~~

.. method:: exists()

more overall work (an additional query) than simply using

``bool(some_query_set)``.

``update(**kwargs)``

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

update

~~~~~~

.. method:: update(**kwargs)

methods on your models, nor does it emit the ``pre_save`` or ``post_save``

signals (which are a consequence of calling ``save()``).

``delete()``

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

delete

~~~~~~

.. method:: delete()

Note this is only available in MySQL and requires direct manipulation of the

database to add the full-text index. By default Django uses BOOLEAN MODE for

full text searches. `Please check MySQL documentation for additional details. <http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_

full text searches. `See the MySQL documentation for additional details.

<http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_

.. fieldlookup:: regex

aggregate functions, see

:doc:`the topic guide on aggregation </topics/db/aggregation>`.

``Avg``

~~~~~~~

Avg

~~~

.. class:: Avg(field)

    * Default alias: ``<field>__avg``

    * Return type: float

``Count``

~~~~~~~~~

Count

~~~~~

.. class:: Count(field, distinct=False)

    If distinct=True, the count will only include unique instances. This has

    the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``.

``Max``

~~~~~~~

Max

~~~

.. class:: Max(field)

    * Default alias: ``<field>__max``

    * Return type: same as input field

``Min``

~~~~~~~

Min

~~~

.. class:: Min(field)

    * Default alias: ``<field>__min``

    * Return type: same as input field

``StdDev``

~~~~~~~~~~

StdDev

~~~~~~

.. class:: StdDev(field, sample=False)

    available as an extension module for SQLite. Consult the SQlite

    documentation for instructions on obtaining and installing this extension.

``Sum``

~~~~~~~

Sum

~~~

.. class:: Sum(field)

    * Default alias: ``<field>__sum``

    * Return type: same as input field

``Variance``

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

Variance

~~~~~~~~

.. class:: Variance(field, sample=False)