Added support for modifying the effect of ``DISTINCT`` clauses so they

only consider some fields (PostgreSQL only).

For this, the ``distinct()`` QuerySet method now accepts an optional
list of model fields names and generates ``DISTINCT ON`` clauses on
these cases. Thanks Jeffrey Gelens and Anssi Kääriäinen for their work.

Fixes #6422.

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

3 files changed, 58 insertions, 1 deletions

diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 6f2cad3464..b7bc647981 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -345,7 +345,7 @@ remain undefined afterward).
 distinct
 ~~~~~~~~
 
-.. method:: distinct()
+.. method:: distinct([*fields])
 
 Returns a new ``QuerySet`` that uses ``SELECT DISTINCT`` in its SQL query. This
 eliminates duplicate rows from the query results.
@@ -374,6 +374,43 @@ query spans multiple tables, it's possible to get duplicate results when a
     :meth:`values()` together, be careful when ordering by fields not in the
     :meth:`values()` call.
 
+.. 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.
+
+.. note::
+    Note that the 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.
+
+Examples::
+
+    >>> Author.objects.distinct()
+    [...]
+
+    >>> Entry.objects.order_by('pub_date').distinct('pub_date')
+    [...]
+
+    >>> Entry.objects.order_by('blog').distinct('blog')
+    [...]
+
+    >>> Entry.objects.order_by('author', 'pub_date').distinct('author', 'pub_date')
+    [...]
+
+    >>> Entry.objects.order_by('blog__name', 'mod_date').distinct('blog__name', 'mod_date')
+    [...]
+
+    >>> Entry.objects.order_by('author', 'pub_date').distinct('author')
+    [...]
+
 values
 ~~~~~~
 
diff --git a/docs/releases/1.4-alpha-1.txt b/docs/releases/1.4-alpha-1.txt
index 11bd8bdef6..8050ca91f6 100644
--- a/docs/releases/1.4-alpha-1.txt
+++ b/docs/releases/1.4-alpha-1.txt
@@ -507,6 +507,16 @@ Django 1.4 also includes several smaller improvements worth noting:
   ``pickle.HIGHEST_PROTOCOL`` for better compatibility with the other
   cache backends.
 
+* Support in the ORM for generating ``SELECT`` queries containing ``DISTINCT ON``
+
+  The ``distinct()`` ``Queryset`` method now accepts an optional list of model
+  field names. If specified, then the ``DISTINCT`` statement is limited to these
+  fields.  The PostgreSQL is the only of the database backends shipped with
+  Django that supports this new functionality.
+
+  For more details, see the documentation for
+  :meth:`~django.db.models.query.QuerySet.distinct`.
+
 Backwards incompatible changes in 1.4
 =====================================
 
diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt
index ee9943cbed..4c1caee309 100644
--- a/docs/releases/1.4.txt
+++ b/docs/releases/1.4.txt
@@ -498,6 +498,16 @@ Django 1.4 also includes several smaller improvements worth noting:
   ``pickle.HIGHEST_PROTOCOL`` for better compatibility with the other
   cache backends.
 
+* Support in the ORM for generating ``SELECT`` queries containing ``DISTINCT ON``
+
+  The ``distinct()`` ``Queryset`` method now accepts an optional list of model
+  field names. If specified, then the ``DISTINCT`` statement is limited to these
+  fields.  The PostgreSQL is the only of the database backends shipped with
+  Django that supports this new functionality.
+
+  For more details, see the documentation for
+  :meth:`~django.db.models.query.QuerySet.distinct`.
+
 .. _backwards-incompatible-changes-1.4:
 
 Backwards incompatible changes in 1.4