Commit d3ef1304 authored by Adrian Holovaty's avatar Adrian Holovaty
Browse files

Edited doc changes from [17244] 

git-svn-id: http://code.djangoproject.com/svn/django/trunk@17302 bcc190cf-cafb-0310-a4f2-bffc1f526a37
parent afb21094

docs/ref/models/querysets.txt

+16 −10
Original line number Diff line number Diff line
@@ -376,20 +376,26 @@ query spans multiple tables, it's possible to get duplicate results when a 


.. versionadded:: 1.4



The possibility to pass positional arguments (``*fields``) is new in Django 1.4.

They are names of fields to which the ``DISTINCT`` should be limited. This

translates to a ``SELECT DISTINCT ON`` SQL query. A ``DISTINCT ON`` query eliminates

duplicate rows not by comparing all fields in a row, but by comparing only the given

fields.

As of Django 1.4, you can pass positional arguments (``*fields``) in order to

specify the names of fields to which the ``DISTINCT`` should apply. This

translates to a ``SELECT DISTINCT ON`` SQL query.



Here's the difference. For a normal ``distinct()`` call, the database compares

*each* field in each row when determining which rows are distinct. For a

``distinct()`` call with specified field names, the database will only compare

the specified field names.



.. note::

    Note that the ability to specify field names is only available in PostgreSQL.

    This ability to specify field names is only available in PostgreSQL.



.. note::

    When using the ``DISTINCT ON`` functionality it is required that the columns given

    to :meth:`distinct` match the first :meth:`order_by` columns. For example ``SELECT

    DISTINCT ON (a)`` gives you the first row for each value in column ``a``. If you

    don't specify an order, then you'll get some arbitrary row.

    When you specify field names, you *must* provide an ``order_by()`` in the

    QuerySet, and the fields in ``order_by()`` must start with the fields in

    ``distinct()``, in the same order.



    For example, ``SELECT DISTINCT ON (a)`` gives you the first row for each

    value in column ``a``. If you don't specify an order, you'll get some

    arbitrary row.



Examples::

docs/releases/1.4-alpha-1.txt

+2 −3
Original line number Diff line number Diff line
@@ -548,10 +548,9 @@ Django 1.4 also includes several smaller improvements worth noting: 
* Added support in the ORM for generating ``SELECT`` queries containing

  ``DISTINCT ON``.



  The ``distinct()`` ``Queryset`` method now accepts an optional list of model

  The ``distinct()`` ``QuerySet`` method now accepts an optional list of model

  field names. If specified, then the ``DISTINCT`` statement is limited to these

  fields. PostgreSQL is the only database backend shipped with Django that

  supports this new functionality.

  fields. This is only supported in PostgreSQL.



  For more details, see the documentation for

  :meth:`~django.db.models.query.QuerySet.distinct`.

docs/releases/1.4.txt

+2 −3
Original line number Diff line number Diff line
@@ -538,10 +538,9 @@ Django 1.4 also includes several smaller improvements worth noting: 
* Added support in the ORM for generating ``SELECT`` queries containing

  ``DISTINCT ON``.



  The ``distinct()`` ``Queryset`` method now accepts an optional list of model

  The ``distinct()`` ``QuerySet`` method now accepts an optional list of model

  field names. If specified, then the ``DISTINCT`` statement is limited to these

  fields. PostgreSQL is the only database backend shipped with Django that

  supports this new functionality.

  fields. This is only supported in PostgreSQL.



  For more details, see the documentation for

  :meth:`~django.db.models.query.QuerySet.distinct`.