Annotation Interface Aggregate.Plan
- Enclosing class:
Aggregate
plan
), and a second may be specified (as
movingPlan
).
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
functions accumulate
, combine
, finish
, and
remove
. Only accumulate
is always required;
remove
is required in a movingPlan
, 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
Modifier and TypeOptional ElementDescriptionString[]
Name of the function that will be called for each row being aggregated.String[]
Name of an optional function to combine two instances of the state type.String[]
Name of a deserializing function ((bytea
,internal
) tointernal
), usable only if aserialize
function is also specified.String[]
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.The effect of thefinish
function in thisPlan
.An optional initial value for the state (which will otherwise be initially null).boolean
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[]
Name of an optional function that can reverse the effect on the state of a row previously passed toaccumulate
.String[]
Name of a serializing function (internal
tobytea
), usable only if acombine
function is specified and the aggregate's state type isinternal
.int
An optional estimate of the size in bytes that the state may grow to occupy.The data type to be used to hold the accumulating state.
-
Element Details
-
stateType
String stateTypeThe 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:
""
-
stateSize
int stateSizeAn optional estimate of the size in bytes that the state may grow to occupy.- Default:
0
-
initialState
String initialStateAn 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[] accumulateName 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[] combineName 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[] finishName 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[] removeName 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:
{}
-
polymorphic
boolean polymorphicWhether the argument list forfinish
should be extended with slots corresponding to the aggregatedarguments
, all nulls at runtime but with their resolved runtime types.- Default:
false
-
finishEffect
Aggregate.FinishEffect finishEffectThe 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:
READ_ONLY
-
serialize
String[] serializeName of a serializing function (internal
tobytea
), usable only if acombine
function is specified and the aggregate's state type isinternal
.Not allowed in a
movingPlan
. Not allowed withoutdeserialize
.- Default:
{}
-
deserialize
String[] deserializeName of a deserializing function ((bytea
,internal
) tointernal
), usable only if aserialize
function is also specified.Not allowed in a
movingPlan
.- Default:
{}
-