- add a note about query.order_by(None) with union etc. clarifies [ticket:2022]

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index d5f0ef0ca5799726781cb9fcf8c32cd4723717f8..59644591821966dfe6ec06430bff47d8a0fcecab 100644 (file)
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1073,7 +1073,14 @@ class Query(object):
 
             SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y UNION 
                             SELECT * FROM Z)
-
+        
+        Note that many database backends do not allow ORDER BY to
+        be rendered on a query called within UNION, EXCEPT, etc.
+        To disable all ORDER BY clauses including those configured
+        on mappers, issue ``query.order_by(None)`` - the resulting
+        :class:`.Query` object will not render ORDER BY within 
+        its SELECT statement.
+        
         """