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 (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 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 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

        Aggregate.FinishEffect 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:
        org.postgresql.pljava.annotation.Aggregate.FinishEffect.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:
        {}