From d3ef13044e73c64e7f8f46c5030040a5566012b3 Mon Sep 17 00:00:00 2001 From: Adrian Holovaty Date: Fri, 30 Dec 2011 18:01:34 +0000 Subject: [PATCH] Edited doc changes from [17244] git-svn-id: http://code.djangoproject.com/svn/django/trunk@17302 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/models/querysets.txt | 26 ++++++++++++++++---------- docs/releases/1.4-alpha-1.txt | 5 ++--- docs/releases/1.4.txt | 5 ++--- 3 files changed, 20 insertions(+), 16 deletions(-) diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index b7bc647981..11e23c0250 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -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:: diff --git a/docs/releases/1.4-alpha-1.txt b/docs/releases/1.4-alpha-1.txt index 6e284bd405..52c8e75266 100644 --- a/docs/releases/1.4-alpha-1.txt +++ b/docs/releases/1.4-alpha-1.txt @@ -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`. diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index 1ab34d80bc..e228bc0b29 100644 --- a/docs/releases/1.4.txt +++ b/docs/releases/1.4.txt @@ -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`.