Commits

Anonymous committed f673eee

Edited doc changes from [17244]

  • Participants
  • Parent commits 61917d7

Comments (0)

Files changed (3)

docs/ref/models/querysets.txt

 
 .. 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

 * 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

 * 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`.