Annotation Type Operator

    • Field Summary

      Fields 
      Modifier and Type Fields Description
      static String SELF
      Distinguished value usable for commutator= to indicate that an operator is its own commutator without having to repeat its schema and name.
      static String TWIN
      Distinguished value usable for commutator= to indicate that an operator's commutator is another operator with the same schema and name, without having to repeat them.
    • Required Element Summary

      Required Elements 
      Modifier and Type Required Element Description
      String[] name
      Name for this operator.
    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      String comment
      A comment to be associated with the operator.
      String[] commutator
      Name of an operator that is the commutator of this one.
      String[] function
      Name of the function backing the operator; may be omitted if this annotation appears on a method.
      boolean hashes
      Whether this operator can be used in computing a hash join.
      String implementor
      The <implementor name> to be used around SQL code generated for this operator.
      String[] join
      Name of a function that can estimate the selectivity of this operator when used in a join.
      String left
      The type of the operator's left operand, if any.
      boolean merges
      Whether this operator can be used in computing a merge join.
      String[] negator
      Name of an operator that is the negator of this one.
      String[] provides
      One or more arbitrary labels that will be considered 'provided' by the object carrying this annotation.
      String[] requires
      One or more arbitrary labels that will be considered 'required' by the object carrying this annotation.
      String[] restrict
      Name of a function that can estimate the selectivity of this operator when used in a WHERE clause.
      String right
      The type of the operator's right operand, if any.
      String[] synthetic
      Name of a function to be synthesized by PL/Java based on the method this annotation appears on and this operator's commutator or negator relationship to another operator declared on the same method.
    • Field Detail

      • SELF

        static final String SELF
        Distinguished value usable for commutator= to indicate that an operator is its own commutator without having to repeat its schema and name.

        This value strictly declares that the operator is its own commutator, and therefore is only allowed for an operator with two operands of the same type. If the types are different, a commutator with the same name would in fact be a different operator with the operand types exchanged; use TWIN for that.

      • TWIN

        static final String TWIN
        Distinguished value usable for commutator= to indicate that an operator's commutator is another operator with the same schema and name, without having to repeat them.

        This value strictly declares that the commutator is a different operator, and therefore is only allowed for an operator with two operands of different types. As commutators, this operator and its twin will have those operand types in opposite orders, so PostgreSQL overloading will allow them to have the same name.

        This value may also be used with synthetic= to give the synthesized function the same schema and name as the one it is based on; this also is possible only for a function synthesized by commutation where the commuted parameter types differ.

    • Element Detail

      • name

        String[] name
        Name for this operator.

        May be specified in explicit {"schema","operatorname"} form, or as a single string that will be leniently parsed as an optionally schema-qualified name. In the explicit form, "" as the schema will make the name explicitly unqualified.

      • left

        String left
        The type of the operator's left operand, if any. Will default to the first parameter type of an associated two-parameter function, or none for an associated one-parameter function.
        Default:
        ""
      • right

        String right
        The type of the operator's right operand, if any. Will default to the second parameter type of an associated two-parameter function, or the parameter type for an associated one-parameter function.
        Default:
        ""
      • function

        String[] function
        Name of the function backing the operator; may be omitted if this annotation appears on a method.

        The function named here must take one parameter of the matching type if only one of left or right is specified, or the left and right types in that order if both are present.

        Default:
        {}
      • synthetic

        String[] synthetic
        Name of a function to be synthesized by PL/Java based on the method this annotation appears on and this operator's commutator or negator relationship to another operator declared on the same method.

        Only allowed in an annotation on a Java method, and where function is not specified.

        The special value TWIN is allowed, to avoid repeating the schema and name when the desired name for the synthesized function is the same as the one it is derived from (which is only possible if the derivation involves commuting the arguments and their types are different, so the two functions can be distinguished by overloading). A typical case would be the twin of a cross-type function like add that is commutative, so using the same name makes sense.

        Default:
        {}
      • commutator

        String[] commutator
        Name of an operator that is the commutator of this one.

        Specified in the same ways as name. The value SELF can be used to avoid repeating the schema and name for the common case of an operator that is its own commutator. The value TWIN can likewise declare that the commutator is the different operator with the same name and schema but the operand types (which must be different) reversed. A typical case would be the twin of a cross-type operator like + that is commutative, so using the same name makes sense.

        When derived by commutation, the synthetic function simply calls the base function with the parameters swapped. For negation, the base function must return boolean or Boolean, and the synthetic function returns true for false, false for true, and null for null. This will give familiar SQL behavior in many cases. For a base function with onNullInput=CALLED, if it can return non-null boolean results on some null inputs, it may be necessary to code a negator or commutator by hand if the synthetic one would not have the intended semantics.

        Default:
        {}
      • negator

        String[] negator
        Name of an operator that is the negator of this one.

        Specified in the same ways as name.

        Default:
        {}
      • hashes

        boolean hashes
        Whether this operator can be used in computing a hash join.

        Only sensible for a boolean-valued binary operator, which must have a commutator in the same hash index operator family, with the underlying functions marked Function.Effects.IMMUTABLE or Function.Effects.STABLE.

        Default:
        false
      • merges

        boolean merges
        Whether this operator can be used in computing a merge join.

        Only sensible for a boolean-valued binary operator, which must have a commutator also appearing as an equality member in the same btree index operator family, with the underlying functions marked Function.Effects.IMMUTABLE or Function.Effects.STABLE.

        Default:
        false
      • restrict

        String[] restrict
        Name of a function that can estimate the selectivity of this operator when used in a WHERE clause.

        Specified in the same ways as function.

        A custom estimator is a complex undertaking (and, at present, requires a language other than Java), but several predefined ones can be found in Operator.SelectivityEstimators.

        Default:
        {}
      • join

        String[] join
        Name of a function that can estimate the selectivity of this operator when used in a join.

        Specified in the same ways as function.

        A custom estimator is a complex undertaking (and, at present, requires a language other than Java), but several predefined ones can be found in Operator.SelectivityEstimators.

        Default:
        {}
      • provides

        String[] provides
        One or more arbitrary labels that will be considered 'provided' by the object carrying this annotation. The deployment descriptor will be generated in such an order that other objects that 'require' labels 'provided' by this come later in the output for install actions, and earlier for remove actions.
        Default:
        {}
      • requires

        String[] requires
        One or more arbitrary labels that will be considered 'required' by the object carrying this annotation. The deployment descriptor will be generated in such an order that other objects that 'provide' labels 'required' by this come earlier in the output for install actions, and later for remove actions.
        Default:
        {}
      • implementor

        String implementor
        The <implementor name> to be used around SQL code generated for this operator. Defaults to PostgreSQL. Set explicitly to "" to emit code not wrapped in an <implementor block>.
        Default:
        ""
      • comment

        String comment
        A comment to be associated with the operator. If left to default, and the annotated Java construct has a doc comment, its first sentence will be used. If an empty string is explicitly given, no comment will be set.
        Default:
        ""