Implement placeholders for CUBE, ROLLUP, GROUPING SETSreview/mike_bayer/pr_github_383

Fixes: #3429

Co-authored-by: Mike Bayer <mike_mp@zzzcomputing.com>
Change-Id: I870ee7dc801d553c5309c291402ec468b671e9a9
Pull-request: https://github.com/zzzeek/sqlalchemy/pull/383

5 files changed, 131 insertions, 2 deletions

diff --git a/doc/build/changelog/migration_12.rst b/doc/build/changelog/migration_12.rst
index a670bb394..e9deb75c4 100644
--- a/doc/build/changelog/migration_12.rst
+++ b/doc/build/changelog/migration_12.rst
@@ -812,6 +812,34 @@ if the application is working with plain floats.
 
 :ticket:`4020`
 
+
+.. change_3249:
+
+Support for GROUPING SETS, CUBE, ROLLUP
+---------------------------------------
+
+All three of GROUPING SETS, CUBE, ROLLUP are available via the
+:attr:`.func` namespace.  In the case of CUBE and ROLLUP, these functions
+already work in previous versions, however for GROUPING SETS, a placeholder
+is added to the compiler to allow for the space.  All three functions
+are named in the documentation now::
+
+    >>> from sqlalchemy import select, table, column, func, tuple_
+    >>> t = table('t',
+    ...           column('value'), column('x'),
+    ...           column('y'), column('z'), column('q'))
+    >>> stmt = select([func.sum(t.c.value)]).group_by(
+    ...     func.grouping_sets(
+    ...         tuple_(t.c.x, t.c.y),
+    ...         tuple_(t.c.z, t.c.q),
+    ...     )
+    ... )
+    >>> print(stmt)
+    SELECT sum(t.value) AS sum_1
+    FROM t GROUP BY GROUPING SETS((t.x, t.y), (t.z, t.q))
+
+:ticket:`3429`
+
 Key Behavioral Changes - ORM
 ============================
 
diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py
index 2dec3a5c3..b0f0807d6 100644
--- a/lib/sqlalchemy/sql/compiler.py
+++ b/lib/sqlalchemy/sql/compiler.py
@@ -121,7 +121,10 @@ FUNCTIONS = {
     functions.random: 'random%(expr)s',
     functions.sysdate: 'sysdate',
     functions.session_user: 'SESSION_USER',
-    functions.user: 'USER'
+    functions.user: 'USER',
+    functions.cube: 'CUBE%(expr)s',
+    functions.rollup: 'ROLLUP%(expr)s',
+    functions.grouping_sets: 'GROUPING SETS%(expr)s',
 }
 
 EXTRACT_MAP = {
diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 36a6a6557..9213d616c 100644
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -3293,7 +3293,7 @@ class WithinGroup(ColumnElement):
     """Represent a WITHIN GROUP (ORDER BY) clause.
 
     This is a special operator against so-called
-    so-called "ordered set aggregate" and "hypothetical
+    "ordered set aggregate" and "hypothetical
     set aggregate" functions, including ``percentile_cont()``,
     ``rank()``, ``dense_rank()``, etc.
 
diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py
index 08f1d32a5..9a9396fec 100644
--- a/lib/sqlalchemy/sql/functions.py
+++ b/lib/sqlalchemy/sql/functions.py
@@ -811,3 +811,65 @@ class cume_dist(GenericFunction):
 
     """
     type = sqltypes.Numeric()
+
+
+class cube(GenericFunction):
+    r"""Implement the ``CUBE`` grouping operation.
+
+    This function is used as part of the GROUP BY of a statement,
+    e.g. :meth:`.Select.group_by`::
+
+        stmt = select(
+            [func.sum(table.c.value), table.c.col_1, table.c.col_2]
+            ).group_by(func.cube(table.c.col_1, table.c.col_2))
+
+    .. versionadded:: 1.2
+
+    """
+
+
+class rollup(GenericFunction):
+    r"""Implement the ``ROLLUP`` grouping operation.
+
+    This function is used as part of the GROUP BY of a statement,
+    e.g. :meth:`.Select.group_by`::
+
+        stmt = select(
+            [func.sum(table.c.value), table.c.col_1, table.c.col_2]
+        ).group_by(func.rollup(table.c.col_1, table.c.col_2))
+
+    .. versionadded:: 1.2
+
+    """
+
+
+class grouping_sets(GenericFunction):
+    r"""Implement the ``GROUPING SETS`` grouping operation.
+
+    This function is used as part of the GROUP BY of a statement,
+    e.g. :meth:`.Select.group_by`::
+
+        stmt = select(
+            [func.sum(table.c.value), table.c.col_1, table.c.col_2]
+        ).group_by(func.grouping_sets(table.c.col_1, table.c.col_2))
+
+    In order to group by multiple sets, use the :func:`.tuple_` construct::
+
+        from sqlalchemy import tuple_
+
+        stmt = select(
+            [
+                func.sum(table.c.value),
+                table.c.col_1, table.c.col_2,
+                table.c.col_3]
+        ).group_by(
+            func.grouping_sets(
+                tuple_(table.c.col_1, table.c.col_2),
+                tuple_(table.c.value, table.c.col_3),
+            )
+        )
+
+
+    .. versionadded:: 1.2
+
+    """
diff --git a/test/sql/test_functions.py b/test/sql/test_functions.py
index 272bd876e..a7dfd2beb 100644
--- a/test/sql/test_functions.py
+++ b/test/sql/test_functions.py
@@ -86,6 +86,42 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         ]:
             self.assert_compile(func.random(), ret, dialect=dialect)
 
+    def test_cube_operators(self):
+
+        t = table('t', column('value'),
+                  column('x'), column('y'), column('z'), column('q'))
+
+        stmt = select([func.sum(t.c.value)])
+
+        self.assert_compile(
+            stmt.group_by(func.cube(t.c.x, t.c.y)),
+            "SELECT sum(t.value) AS sum_1 FROM t GROUP BY CUBE(t.x, t.y)"
+        )
+
+        self.assert_compile(
+            stmt.group_by(func.rollup(t.c.x, t.c.y)),
+            "SELECT sum(t.value) AS sum_1 FROM t GROUP BY ROLLUP(t.x, t.y)"
+        )
+
+        self.assert_compile(
+            stmt.group_by(
+                func.grouping_sets(t.c.x, t.c.y)
+            ),
+            "SELECT sum(t.value) AS sum_1 FROM t "
+            "GROUP BY GROUPING SETS(t.x, t.y)"
+        )
+
+        self.assert_compile(
+            stmt.group_by(
+                func.grouping_sets(
+                    sql.tuple_(t.c.x, t.c.y),
+                    sql.tuple_(t.c.z, t.c.q),
+                )
+            ),
+            "SELECT sum(t.value) AS sum_1 FROM t GROUP BY "
+            "GROUPING SETS((t.x, t.y), (t.z, t.q))"
+        )
+
     def test_generic_annotation(self):
         fn = func.coalesce('x', 'y')._annotate({"foo": "bar"})
         self.assert_compile(