diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 7195df8..655587e 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -12006,7 +12006,9 @@ NULL baz(3 rows) . The built-in ordered-set aggregate functions are listed in and - . + . Grouping operations, + which are closely related to aggregate functions, are listed in + . The special syntax considerations for aggregate functions are explained in . Consult for additional introductory @@ -13052,6 +13054,72 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; to the rule specified in the ORDER BY clause. + + Grouping Operations + + + + + Function + Return Type + Description + + + + + + + + + GROUPING + + GROUPING(args...) + + + integer + + + Integer bitmask indicating which arguments are not being included in the current + grouping set + + + + +
+ + + Grouping operations are used in conjunction with grouping sets (see + ) to distinguish result rows. The + arguments to the GROUPING operation are not actually evaluated, + but they must match exactly expressions given in the GROUP BY + clause of the current query level. Bits are assigned with the rightmost + argument being the least-significant bit; each bit is 0 if the corresponding + expression is included in the grouping criteria of the grouping set generating + the result row, and 1 if it is not. For example: + +=> SELECT * FROM items_sold; + make | model | sales +-------+-------+------- + Foo | GT | 10 + Foo | Tour | 20 + Bar | City | 15 + Bar | Sport | 5 +(4 rows) + +=> SELECT make, model, GROUPING(make,model), sum(sales) FROM items_sold GROUP BY ROLLUP(make,model); + make | model | grouping | sum +-------+-------+----------+----- + Foo | GT | 0 | 10 + Foo | Tour | 0 | 20 + Bar | City | 0 | 15 + Bar | Sport | 0 | 5 + Foo | | 1 | 30 + Bar | | 1 | 20 + | | 3 | 50 +(7 rows) + + + diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index 9bf3136..1ff920f 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -1141,6 +1141,184 @@ SELECT product_id, p.name, (sum(s.units) * (p.price - p.cost)) AS profit + + <literal>GROUPING SETS</>, <literal>CUBE</>, and <literal>ROLLUP</> + + + GROUPING SETS + + + CUBE + + + ROLLUP + + + grouping sets + + + + More complex grouping operations than those described above are possible + using the concept of grouping sets. The data selected by + the FROM and WHERE clauses is grouped separately + by each specified grouping set, aggregates computed for each group just as + for simple GROUP BY clauses, and then the results returned. + For example: + +=> SELECT * FROM items_sold; + brand | size | sales +-------+------+------- + Foo | L | 10 + Foo | M | 20 + Bar | M | 15 + Bar | L | 5 +(4 rows) + +=> SELECT brand, size, sum(sales) FROM items_sold GROUP BY GROUPING SETS ((brand), (size), ()); + brand | size | sum +-------+------+----- + Foo | | 30 + Bar | | 20 + | L | 15 + | M | 35 + | | 50 +(5 rows) + + + + + Each sublist of GROUPING SETS may specify zero or more columns + or expressions and is interpreted the same way as though it were directly + in the GROUP BY clause. An empty grouping set means that all + rows are aggregated down to a single group (which is output even if no + input rows were present), as described above for the case of aggregate + functions with no GROUP BY clause. + + + + References to the grouping columns or expressions are replaced + by NULL values in result rows for grouping sets in which those + columns do not appear. To distinguish which grouping a particular output + row resulted from, see . + + + + A shorthand notation is provided for specifying two common types of grouping set. + A clause of the form + +ROLLUP ( e1, e2, e3, ... ) + + represents the given list of expressions and all prefixes of the list including + the empty list; thus it is equivalent to + +GROUPING SETS ( + ( e1, e2, e3, ... ), + ... + ( e1, e2 ) + ( e1 ) + ( ) +) + + This is commonly used for analysis over hierarchical data; e.g. total + salary by department, division, and company-wide total. + + + + A clause of the form + +CUBE ( e1, e2, ... ) + + represents the given list and all of its possible subsets (i.e. the power + set). Thus + +CUBE ( a, b, c ) + + is equivalent to + +GROUPING SETS ( + ( a, b, c ), + ( a, b ), + ( a, c ), + ( a ), + ( b, c ), + ( b ), + ( c ), + ( ), +) + + + + + The individual elements of a CUBE or ROLLUP + clause may be either individual expressions, or sub-lists of elements in + parentheses. In the latter case, the sub-lists are treated as single + units for the purposes of generating the individual grouping sets. + For example: + +CUBE ( (a,b), (c,d) ) + + is equivalent to + +GROUPING SETS ( + ( a, b, c, d ) + ( a, b ) + ( c, d ) + ( ) +) + + and + +ROLLUP ( a, (b,c), d ) + + is equivalent to + +GROUPING SETS ( + ( a, b, c, d ) + ( a, b, c ) + ( a ) + ( ) +) + + + + + The CUBE and ROLLUP constructs can be used either + directly in the GROUP BY clause, or nested inside a + GROUPING SETS clause. If one GROUPING SETS clause + is nested inside another, the effect is the same as if all the elements of + the inner clause had been written directly in the outer clause. + + + + If multiple grouping items are specified in a single GROUP BY + clause, then the final list of grouping sets is the cross product of the + individual items. For example: + +GROUP BY a, CUBE(b,c), GROUPING SETS ((d), (e)) + + is equivalent to + +GROUP BY GROUPING SETS ( + (a,b,c,d), (a,b,c,e), + (a,b,d), (a,b,e), + (a,c,d), (a,c,e), + (a,d), (a,e) +) + + + + + + The construct (a,b) is normally recognized in expressions as + a row constructor. + Within the GROUP BY clause, this does not apply at the top + levels of expressions, and (a,b) is parsed as a list of + expressions as described above. If for some reason you need + a row constructor in a grouping expression, use ROW(a,b). + + + + Window Function Processing diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index 940d1aa..7d10dbe 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -37,7 +37,7 @@ SELECT [ ALL | DISTINCT [ ON ( expressionexpression [ [ AS ] output_name ] [, ...] ] [ FROM from_item [, ...] ] [ WHERE condition ] - [ GROUP BY expression [, ...] ] + [ GROUP BY grouping_element [, ...] ] [ HAVING condition [, ...] ] [ WINDOW window_name AS ( window_definition ) [, ...] ] [ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] select ] @@ -60,6 +60,15 @@ SELECT [ ALL | DISTINCT [ ON ( expressionalias [ ( column_alias [, ...] ) ] ] from_item [ NATURAL ] join_type from_item [ ON join_condition | USING ( join_column [, ...] ) ] +and grouping_element can be one of: + + ( ) + expression + ( expression [, ...] ) + ROLLUP ( { expression | ( expression [, ...] ) } [, ...] ) + CUBE ( { expression | ( expression [, ...] ) } [, ...] ) + GROUPING SETS ( grouping_element [, ...] ) + and with_query is: with_query_name [ ( column_name [, ...] ) ] AS ( select | values | insert | update | delete ) @@ -619,23 +628,35 @@ WHERE condition The optional GROUP BY clause has the general form -GROUP BY expression [, ...] +GROUP BY grouping_element [, ...] GROUP BY will condense into a single row all selected rows that share the same values for the grouped - expressions. expression can be an input column - name, or the name or ordinal number of an output column - (SELECT list item), or an arbitrary + expressions. An expression used inside a + grouping_element + can be an input column name, or the name or ordinal number of an + output column (SELECT list item), or an arbitrary expression formed from input-column values. In case of ambiguity, a GROUP BY name will be interpreted as an input-column name rather than an output column name. + If any of GROUPING SETS, ROLLUP or + CUBE are present as grouping elements, then the + GROUP BY clause as a whole defines some number of + independent grouping sets. The effect of this is + equivalent to constructing a UNION ALL between + subqueries with the individual grouping sets as their + GROUP BY clauses. For further details on the handling + of grouping sets see . + + + Aggregate functions, if any are used, are computed across all rows making up each group, producing a separate value for each group (whereas without GROUP BY, an aggregate