- Added support for "set-aggregate" functions of the formticket_3516

``<function> WITHIN GROUP (ORDER BY <criteria>)``, using the
method :class:`.FunctionElement.within_group`.  A series of common
set-aggregate functions with return types derived from the set have
been added. This includes functions like :class:`.percentile_cont`,
:class:`.dense_rank` and others.
fixes #1370
- make sure we use func.name for all _literal_as_binds in functions.py
so we get consistent naming behavior for parameters.

3 files changed, 62 insertions, 1 deletions

diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst
index 0a6543575..350a7c4d2 100644
--- a/doc/build/changelog/changelog_11.rst
+++ b/doc/build/changelog/changelog_11.rst
@@ -22,6 +22,21 @@
     :version: 1.1.0b1
 
     .. change::
+        :tags: feature, sql
+        :tickets: 1370
+
+        Added support for "set-aggregate" functions of the form
+        ``<function> WITHIN GROUP (ORDER BY <criteria>)``, using the
+        method :meth:`.FunctionElement.within_group`.  A series of common
+        set-aggregate functions with return types derived from the set have
+        been added. This includes functions like :class:`.percentile_cont`,
+        :class:`.dense_rank` and others.
+
+        .. seealso::
+
+            :ref:`change_3132`
+
+    .. change::
         :tags: feature, sql, postgresql
         :tickets: 3132
 
@@ -31,6 +46,10 @@
         supported on Postgresql at the moment, only actually works on
         Postgresql.
 
+        .. seealso::
+
+            :ref:`change_3132`
+
     .. change::
         :tags: feature, sql
         :tickets: 3516
diff --git a/doc/build/changelog/migration_11.rst b/doc/build/changelog/migration_11.rst
index f4cadeea5..c146e2443 100644
--- a/doc/build/changelog/migration_11.rst
+++ b/doc/build/changelog/migration_11.rst
@@ -16,7 +16,7 @@ What's New in SQLAlchemy 1.1?
     some issues may be moved to later milestones in order to allow
     for a timely release.
 
-    Document last updated: July 24, 2015.
+    Document last updated: August 26, 2015
 
 Introduction
 ============
@@ -263,6 +263,43 @@ such as::
 
 :ticket:`3516`
 
+.. _change_3132:
+
+New Function features, "WITHIN GROUP", array_agg and set aggregate functions
+----------------------------------------------------------------------------
+
+With the new :class:`.Array` type we can also implement a pre-typed
+function for the ``array_agg()`` SQL function that returns an array,
+which is now available using :class:`.array_agg`::
+
+    from sqlalchemy import func
+    stmt = select([func.array_agg(table.c.value)])
+
+Additionally, functions like ``percentile_cont()``, ``percentile_disc()``,
+``rank()``, ``dense_rank()`` and others that require an ordering via
+``WITHIN GROUP (ORDER BY <expr>)`` are now available via the
+:meth:`.FunctionElement.within_group` modifier::
+
+    from sqlalchemy import func
+    stmt = select([
+        department.c.id,
+        func.percentile_cont(0.5).within_group(
+            department.c.salary.desc()
+        )
+    ])
+
+The above statement would produce SQL similar to::
+
+  SELECT department.id, percentile_cont(0.5)
+  WITHIN GROUP (ORDER BY department.salary DESC)
+
+Placeholders with correct return types are now provided for these functions,
+and include :class:`.percentile_cont`, :class:`.percentile_disc`,
+:class:`.rank`, :class:`.dense_rank`, :class:`.mode`, :class:`.percent_rank`,
+and :class:`.cume_dist`.
+
+:ticket:`3132` :ticket:`1370`
+
 Key Behavioral Changes - ORM
 ============================
 
diff --git a/doc/build/core/sqlelement.rst b/doc/build/core/sqlelement.rst
index d2019f71e..30a6ed568 100644
--- a/doc/build/core/sqlelement.rst
+++ b/doc/build/core/sqlelement.rst
@@ -69,6 +69,8 @@ used to construct any kind of typed SQL expression.
 
 .. autofunction:: type_coerce
 
+.. autofunction:: within_group
+
 .. autoclass:: BinaryExpression
    :members:
 
@@ -133,6 +135,9 @@ used to construct any kind of typed SQL expression.
 .. autoclass:: Tuple
    :members:
 
+.. autoclass:: WithinGroup
+   :members:
+
 .. autoclass:: sqlalchemy.sql.elements.True_
    :members: