From 0d3f4406dfa00d848711fdb4af53be663ffc7d0f Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 3 Sep 2013 17:08:38 -0400 Subject: Allow aggregate functions to be VARIADIC. There's no inherent reason why an aggregate function can't be variadic (even VARIADIC ANY) if its transition function can handle the case. Indeed, this patch to add the feature touches none of the planner or executor, and little of the parser; the main missing stuff was DDL and pg_dump support. It is true that variadic aggregates can create the same sort of ambiguity about parameters versus ORDER BY keys that was complained of when we (briefly) had both one- and two-argument forms of string_agg(). However, the policy formed in response to that discussion only said that we'd not create any built-in aggregates with varying numbers of arguments, not that we shouldn't allow users to do it. So the logical extension of that is we can allow users to make variadic aggregates as long as we're wary about shipping any such in core. In passing, this patch allows aggregate function arguments to be named, to the extent of remembering the names in pg_proc and dumping them in pg_dump. You can't yet call an aggregate using named-parameter notation. That seems like a likely future extension, but it'll take some work, and it's not what this patch is really about. Likewise, there's still some work needed to make window functions handle VARIADIC fully, but I left that for another day. initdb forced because of new aggvariadic field in Aggref parse nodes. --- doc/src/sgml/ref/alter_aggregate.sgml | 37 +++++++++++++++++++++++++++++----- doc/src/sgml/ref/alter_extension.sgml | 4 ++-- doc/src/sgml/ref/comment.sgml | 8 ++++---- doc/src/sgml/ref/create_aggregate.sgml | 36 +++++++++++++++++++++++++++------ doc/src/sgml/ref/drop_aggregate.sgml | 32 ++++++++++++++++++++++++++--- doc/src/sgml/ref/security_label.sgml | 10 ++++----- doc/src/sgml/syntax.sgml | 7 +++++++ doc/src/sgml/xaggr.sgml | 36 +++++++++++++++++++++++++++++++++ 8 files changed, 145 insertions(+), 25 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/ref/alter_aggregate.sgml b/doc/src/sgml/ref/alter_aggregate.sgml index 571a50a502e..aab5b2b695e 100644 --- a/doc/src/sgml/ref/alter_aggregate.sgml +++ b/doc/src/sgml/ref/alter_aggregate.sgml @@ -21,9 +21,12 @@ PostgreSQL documentation -ALTER AGGREGATE name ( argtype [ , ... ] ) RENAME TO new_name -ALTER AGGREGATE name ( argtype [ , ... ] ) OWNER TO new_owner -ALTER AGGREGATE name ( argtype [ , ... ] ) SET SCHEMA new_schema +ALTER AGGREGATE name ( [ argmode ] [ arg_name ] arg_data_type [ , ... ] ) + RENAME TO new_name +ALTER AGGREGATE name ( [ argmode ] [ arg_name ] arg_data_type [ , ... ] ) + OWNER TO new_owner +ALTER AGGREGATE name ( [ argmode ] [ arg_name ] arg_data_type [ , ... ] ) + SET SCHEMA new_schema @@ -62,12 +65,36 @@ ALTER AGGREGATE name ( argtype - argtype + argmode + + + + The mode of an argument: IN or VARIADIC. + If omitted, the default is IN. + + + + + + arg_name + + + + The name of an argument. + Note that ALTER AGGREGATE does not actually pay + any attention to argument names, since only the argument data + types are needed to determine the aggregate function's identity. + + + + + + arg_data_type An input data type on which the aggregate function operates. To reference a zero-argument aggregate function, write * - in place of the list of input data types. + in place of the list of argument specifications. diff --git a/doc/src/sgml/ref/alter_extension.sgml b/doc/src/sgml/ref/alter_extension.sgml index 2dbba0c0bbb..a14fcb48683 100644 --- a/doc/src/sgml/ref/alter_extension.sgml +++ b/doc/src/sgml/ref/alter_extension.sgml @@ -30,7 +30,7 @@ ALTER EXTENSION name DROP where member_object is: - AGGREGATE agg_name (agg_type [, ...] ) | + AGGREGATE agg_name ( [ argmode ] [ argname ] agg_type [, ...] ) | CAST (source_type AS target_type) | COLLATION object_name | CONVERSION object_name | @@ -179,7 +179,7 @@ ALTER EXTENSION name DROP An input data type on which the aggregate function operates. To reference a zero-argument aggregate function, write * - in place of the list of input data types. + in place of the list of argument specifications. diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml index e94dd4b8ded..e55050042a8 100644 --- a/doc/src/sgml/ref/comment.sgml +++ b/doc/src/sgml/ref/comment.sgml @@ -23,7 +23,7 @@ PostgreSQL documentation COMMENT ON { - AGGREGATE agg_name (agg_type [, ...] ) | + AGGREGATE agg_name ( [ argmode ] [ argname ] agg_type [, ...] ) | CAST (source_type AS target_type) | COLLATION object_name | COLUMN relation_name.column_name | @@ -126,7 +126,7 @@ COMMENT ON An input data type on which the aggregate function operates. To reference a zero-argument aggregate function, write * - in place of the list of input data types. + in place of the list of argument specifications. @@ -156,7 +156,7 @@ COMMENT ON The mode of a function argument: IN, OUT, INOUT, or VARIADIC. If omitted, the default is IN. - Note that COMMENT ON FUNCTION does not actually pay + Note that COMMENT does not actually pay any attention to OUT arguments, since only the input arguments are needed to determine the function's identity. So it is sufficient to list the IN, INOUT, @@ -170,7 +170,7 @@ COMMENT ON The name of a function argument. - Note that COMMENT ON FUNCTION does not actually pay + Note that COMMENT does not actually pay any attention to argument names, since only the argument data types are needed to determine the function's identity. diff --git a/doc/src/sgml/ref/create_aggregate.sgml b/doc/src/sgml/ref/create_aggregate.sgml index d5e4e272fce..2b35fa4d522 100644 --- a/doc/src/sgml/ref/create_aggregate.sgml +++ b/doc/src/sgml/ref/create_aggregate.sgml @@ -21,7 +21,7 @@ PostgreSQL documentation -CREATE AGGREGATE name ( input_data_type [ , ... ] ) ( +CREATE AGGREGATE name ( [ argmode ] [ arg_name ] arg_data_type [ , ... ] ) ( SFUNC = sfunc, STYPE = state_data_type [ , FINALFUNC = ffunc ] @@ -118,7 +118,7 @@ CREATE AGGREGATE name ( Note that this behavior is only available when state_data_type is the same as the first - input_data_type. + arg_data_type. When these types are different, you must supply a nonnull initial condition or use a nonstrict transition function. @@ -187,12 +187,36 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; - input_data_type + argmode + + + + The mode of an argument: IN or VARIADIC. + (Aggregate functions do not support OUT arguments.) + If omitted, the default is IN. Only the last argument + can be marked VARIADIC. + + + + + + arg_name + + + + The name of an argument. This is currently only useful for + documentation purposes. If omitted, the argument has no name. + + + + + + arg_data_type An input data type on which this aggregate function operates. To create a zero-argument aggregate function, write * - in place of the list of input data types. (An example of such an + in place of the list of argument specifications. (An example of such an aggregate is count(*).) @@ -205,8 +229,8 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; In the old syntax for CREATE AGGREGATE, the input data type is specified by a basetype parameter rather than being written next to the aggregate name. Note that this syntax allows - only one input parameter. To define a zero-argument aggregate function, - specify the basetype as + only one input parameter. To define a zero-argument aggregate function + with this syntax, specify the basetype as "ANY" (not *). diff --git a/doc/src/sgml/ref/drop_aggregate.sgml b/doc/src/sgml/ref/drop_aggregate.sgml index 1ed152f6a05..06060fb4f7b 100644 --- a/doc/src/sgml/ref/drop_aggregate.sgml +++ b/doc/src/sgml/ref/drop_aggregate.sgml @@ -21,7 +21,9 @@ PostgreSQL documentation -DROP AGGREGATE [ IF EXISTS ] name ( argtype [ , ... ] ) [ CASCADE | RESTRICT ] +DROP AGGREGATE [ IF EXISTS ] + name ( [ argmode ] [ arg_name ] arg_data_type [ , ... ] ) + [ CASCADE | RESTRICT ] @@ -60,12 +62,36 @@ DROP AGGREGATE [ IF EXISTS ] name ( - argtype + argmode + + + + The mode of an argument: IN or VARIADIC. + If omitted, the default is IN. + + + + + + arg_name + + + + The name of an argument. + Note that DROP AGGREGATE does not actually pay + any attention to argument names, since only the argument data + types are needed to determine the aggregate function's identity. + + + + + + arg_data_type An input data type on which the aggregate function operates. To reference a zero-argument aggregate function, write * - in place of the list of input data types. + in place of the list of argument specifications. diff --git a/doc/src/sgml/ref/security_label.sgml b/doc/src/sgml/ref/security_label.sgml index 52cb1d16f4c..76c131f94ee 100644 --- a/doc/src/sgml/ref/security_label.sgml +++ b/doc/src/sgml/ref/security_label.sgml @@ -25,7 +25,7 @@ SECURITY LABEL [ FOR provider ] ON { TABLE object_name | COLUMN table_name.column_name | - AGGREGATE agg_name (agg_type [, ...] ) | + AGGREGATE agg_name ( [ argmode ] [ argname ] agg_type [, ...] ) | DATABASE object_name | DOMAIN object_name | EVENT TRIGGER object_name | @@ -107,12 +107,12 @@ SECURITY LABEL [ FOR provider ] ON - arg_type + agg_type An input data type on which the aggregate function operates. To reference a zero-argument aggregate function, write * - in place of the list of input data types. + in place of the list of argument specifications. @@ -125,7 +125,7 @@ SECURITY LABEL [ FOR provider ] ON The mode of a function argument: IN, OUT, INOUT, or VARIADIC. If omitted, the default is IN. - Note that SECURITY LABEL ON FUNCTION does not actually + Note that SECURITY LABEL does not actually pay any attention to OUT arguments, since only the input arguments are needed to determine the function's identity. So it is sufficient to list the IN, INOUT, @@ -140,7 +140,7 @@ SECURITY LABEL [ FOR provider ] ON The name of a function argument. - Note that SECURITY LABEL ON FUNCTION does not actually + Note that SECURITY LABEL does not actually pay any attention to argument names, since only the argument data types are needed to determine the function's identity. diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 803ed855c82..e3dbc4b5ea5 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -2524,6 +2524,13 @@ SELECT concat_lower_or_upper('Hello', 'World', uppercase := true); having numerous parameters that have default values, named or mixed notation can save a great deal of writing and reduce chances for error. + + + + Named and mixed call notations can currently be used only with regular + functions, not with aggregate functions or window functions. + + diff --git a/doc/src/sgml/xaggr.sgml b/doc/src/sgml/xaggr.sgml index 1822f6d4abd..9ed7d99f7c0 100644 --- a/doc/src/sgml/xaggr.sgml +++ b/doc/src/sgml/xaggr.sgml @@ -169,6 +169,42 @@ SELECT attrelid::regclass, array_accum(atttypid::regtype) + + An aggregate function can be made to accept a varying number of arguments + by declaring its last argument as a VARIADIC array, in much + the same fashion as for regular functions; see + . The aggregate's transition + function must have the same array type as its last argument. The + transition function typically would also be marked VARIADIC, + but this is not strictly required. + + + + + Variadic aggregates are easily misused in connection with + the ORDER BY option (see ), + since the parser cannot tell whether the wrong number of actual arguments + have been given in such a combination. Keep in mind that everything to + the right of ORDER BY is a sort key, not an argument to the + aggregate. For example, in + +SELECT myaggregate(a ORDER BY a, b, c) FROM ... + + the parser will see this as a single aggregate function argument and + three sort keys. However, the user might have intended + +SELECT myaggregate(a, b, c ORDER BY a) FROM ... + + If myaggregate is variadic, both these calls could be + perfectly valid. + + + + For the same reason, it's wise to think twice before creating aggregate + functions with the same names and different numbers of regular arguments. + + + A function written in C can detect that it is being called as an aggregate transition or final function by calling -- cgit v1.2.3