Annotation Type Aggregate.Plan
-
@Documented @Target({}) @Retention(CLASS) public static @interface Aggregate.Plan
Specifies one "plan" for evaluating the aggregate; one must always be specified (asplan
), and a second may be specified (asmovingPlan
).A plan must specify a data type
stateType
to hold the accumulating state, optionally an estimate of its expected size in bytes, and optionally its initial contents. The plan also specifies up to four functionsaccumulate
,combine
,finish
, andremove
. Onlyaccumulate
is always required;remove
is required in amovingPlan
, and otherwise not allowed.Each of the four functions may be specified as a single string "name", which will be leniently parsed as an optionally schema-qualified name, or as two strings
{"schema","local"}
with the schema made explicit. The two-string form with""
as the schema represents an explicitly non-schema-qualified name.
-
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description String[]
accumulate
Name of the function that will be called for each row being aggregated.String[]
combine
Name of an optional function to combine two instances of the state type.String[]
deserialize
Name of a deserializing function ((bytea
,internal
) tointernal
), usable only if aserialize
function is also specified.String[]
finish
Name of an optional function to produce the aggregate's result from the final value of the state; without this function, the aggregate's result type is the state type, and the result is simply the final value of the state.Aggregate.FinishEffect
finishEffect
The effect of thefinish
function in thisPlan
.String
initialState
An optional initial value for the state (which will otherwise be initially null).boolean
polymorphic
Whether the argument list forfinish
should be extended with slots corresponding to the aggregatedarguments
, all nulls at runtime but with their resolved runtime types.String[]
remove
Name of an optional function that can reverse the effect on the state of a row previously passed toaccumulate
.String[]
serialize
Name of a serializing function (internal
tobytea
), usable only if acombine
function is specified and the aggregate's state type isinternal
.int
stateSize
An optional estimate of the size in bytes that the state may grow to occupy.String
stateType
The data type to be used to hold the accumulating state.
-
-
-
Element Detail
-
stateType
String stateType
The data type to be used to hold the accumulating state.This will be the first argument type for all of the support functions except
deserialize
(both argument types forcombine
) and also, if there is nofinish
function, the result type of the aggregate.- Default:
- ""
-
-
-
initialState
String initialState
An optional initial value for the state (which will otherwise be initially null).Must be a string the state type's text-input conversion would accept.
Omitting the initial value only works if the
accumulate
function isonNullInput=CALLED
, or if the aggregate's first argument type is the same as the state type.- Default:
- ""
-
-
-
accumulate
String[] accumulate
Name of the function that will be called for each row being aggregated.The function named here must have an argument list that starts with one argument of the state type, followed by all of this aggregate's
arguments
. It does not receive thedirectArguments
, if any.- Default:
- {}
-
-
-
combine
String[] combine
Name of an optional function to combine two instances of the state type.The function named here should be one that has two arguments, both of the state type, and returns the state type.
- Default:
- {}
-
-
-
finish
String[] finish
Name of an optional function to produce the aggregate's result from the final value of the state; without this function, the aggregate's result type is the state type, and the result is simply the final value of the state.When this function is specified, its result type determines the result type of the aggregate. Its argument list signature is a single argument of the state type, followed by all the
directArguments
if any, followed (only ifpolymorphic
is true) byarguments.length
additional arguments for which nulls will be passed at runtime but with their resolved runtime types.- Default:
- {}
-
-
-
remove
String[] remove
Name of an optional function that can reverse the effect on the state of a row previously passed toaccumulate
.The function named here should have the same argument list signature as the
accumulate
function.Required in a
movingPlan
; not allowed otherwise.- Default:
- {}
-
-
-
finishEffect
Aggregate.FinishEffect finishEffect
The effect of thefinish
function in thisPlan
.If
READ_ONLY
, PostgreSQL can continue updating the same state with additional rows, and call the finisher again for updated results.If
SHAREABLE
, the state cannot be further updated after a finisher call, but finishers for other aggregates that use the same state representation (and are alsoSHAREABLE
) can be called to produce the results for those aggregates. An example could be the several linear-regression-related aggregates, all of which can work from a state that contains the count of values, sum of values, and sum of squares.If
READ_WRITE
, no further use can be made of the state after the finisher has run.Leaving this to default is not exactly equivalent to specifying the default value shown here. If left to default, it will be left unspecified in the generated
CREATE AGGREGATE
, and PostgreSQL will apply its default, which isREAD_ONLY
in the case of an ordinary aggregate, butREAD_WRITE
for an ordered-set or hypothetical-set aggregate.- Default:
- org.postgresql.pljava.annotation.Aggregate.FinishEffect.READ_ONLY
-
-
-
deserialize
String[] deserialize
Name of a deserializing function ((bytea
,internal
) tointernal
), usable only if aserialize
function is also specified.Not allowed in a
movingPlan
.- Default:
- {}
-
-