From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 31 Aug 2015 17:13:04 +0000 (-0400)
Subject: - add a note about DISTINCT in query w/ ORDER BY, references #3518
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=5c8d1f33cd108f61418dc36ad15d123fa9797b37;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- add a note about DISTINCT in query w/ ORDER BY, references #3518

(cherry picked from commit 6d0c0994e9a08cf5d149af0314970d5f6e25b159)
---

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 154e9d1185..2822d2b341 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -2267,6 +2267,19 @@ class Query(object):
         """Apply a ``DISTINCT`` to the query and return the newly resulting
         ``Query``.
 
+
+        .. note::
+
+            The :meth:`.distinct` call includes logic that will automatically
+            add columns from the ORDER BY of the query to the columns
+            clause of the SELECT statement, to satisfy the common need
+            of the database backend that ORDER BY columns be part of the
+            SELECT list when DISTINCT is used.   These columns *are not*
+            added to the list of columns actually fetched by the
+            :class:`.Query`, however, so would not affect results.
+            The columns are passed through when using the
+            :attr:`.Query.statement` accessor, however.
+
         :param \*expr: optional column expressions.  When present,
          the Postgresql dialect will render a ``DISTINCT ON (<expressions>>)``
          construct.