Annotation Type Aggregate.Plan

Enclosing class:
Aggregate

@Documented
@Target({})
@Retention(CLASS)
public static @interface Aggregate.Plan
Specifies one "plan" for evaluating the aggregate; one must always be specified (as 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

    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) to internal), usable only if a serialize 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 the finish function in this Plan.
    String initialState
    An optional initial value for the state (which will otherwise be initially null).
    boolean polymorphic
    Whether the argument list for finish should be extended with slots corresponding to the aggregated arguments, 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 to accumulate.
    String[] serialize
    Name of a serializing function (internal to bytea), usable only if a combine function is specified and the aggregate's state type is internal.
    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 Details

    • 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 for combine) and also, if there is no finish function, the result type of the aggregate.

      Default:
      ""
    • stateSize

      int stateSize
      An optional estimate of the size in bytes that the state may grow to occupy.
      Default:
      0
    • 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 is onNullInput=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 the directArguments, 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 if polymorphic is true) by arguments.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 to accumulate.

      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 polymorphic
      Whether the argument list for finish should be extended with slots corresponding to the aggregated arguments, all nulls at runtime but with their resolved runtime types.
      Default:
      false
    • finishEffect

      The effect of the finish function in this Plan.

      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 also SHAREABLE) 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 is READ_ONLY in the case of an ordinary aggregate, but READ_WRITE for an ordered-set or hypothetical-set aggregate.

      Default:
      READ_ONLY
    • serialize

      String[] serialize
      Name of a serializing function (internal to bytea), usable only if a combine function is specified and the aggregate's state type is internal.

      Not allowed in a movingPlan. Not allowed without deserialize.

      Default:
      {}
    • deserialize

      String[] deserialize
      Name of a deserializing function ((bytea, internal) to internal), usable only if a serialize function is also specified.

      Not allowed in a movingPlan.

      Default:
      {}