+ linkend="syntax-window-functions"/>). Fundamentally, the extra
+ information provided is how to add or subtract an
+ offset value in a way that is
+ compatible with the family's data ordering.
-
-
- Before doing so, the function should check the sign
- of offset: if it is less than zero, raise
- error ERRCODE_INVALID_PRECEDING_OR_FOLLOWING_SIZE (22013)
- with error text like invalid preceding or following size in window
- function. (This is required by the SQL standard, although
- nonstandard operator families might perhaps choose to ignore this
- restriction, since there seems to be little semantic necessity for it.)
- This requirement is delegated to the in_range
- function so that the core code needn't understand what less than
- zero means for a particular data type.
-
- An additional expectation is that in_range functions
- should, if practical, avoid throwing an error
- if base +
- offset
- or base -
- offset would overflow.
- The correct comparison result can be determined even if that value would
- be out of the data type's range. Note that if the data type includes
- concepts such as infinity
or NaN
, extra care
- may be needed to ensure that in_range's results agree
- with the normal sort order of the operator family.
-
-
- The results of the in_range function must be
- consistent with the sort ordering imposed by the operator family.
- To be precise, given any fixed values of offset
- and sub, then:
-
-
- If in_range with less =
- true is true for some val1
- and base, it must be true for
- every val2 <=
- val1 with the
- same base.
+ An in_range function must have the signature
+
+in_range(val type1, base type1, offset type2, sub bool, less bool)
+returns bool
+
+ val and
+ base must be of the same type, which
+ is one of the types supported by the operator family (i.e., a
+ type for which it provides an ordering). However,
+ offset could be of a different type,
+ which might be one otherwise unsupported by the family. An
+ example is that the built-in time_ops family
+ provides an in_range function that has
+ offset of type interval.
+ A family can provide in_range functions for
+ any of its supported types and one or more
+ offset types. Each
+ in_range function should be entered in
+ pg_amproc with
+ amproclefttype equal to
+ type1 and amprocrighttype
+ equal to type2.
-
-
+
- If in_range with less =
- true is false for some val1
- and base, it must be false for
- every val2 >=
- val1 with the
- same base.
+ The essential semantics of an in_range
+ function depend on the two Boolean flag parameters. It should
+ add or subtract base and
+ offset, then compare
+ val to the result, as follows:
+
+
+ if !sub and
+ !less, return
+ val >=
+ (base +
+ offset)
+
+
+
+ if !sub and
+ less, return
+ val <=
+ (base +
+ offset)
+
+
+
+ if sub and
+ !less, return
+ val >=
+ (base -
+ offset)
+
+
+
+ if sub and
+ less, return
+ val <=
+ (base -
+ offset)
+
+
+
+ Before doing so, the function should check the sign of
+ offset: if it is less than zero, raise
+ error
+ ERRCODE_INVALID_PRECEDING_OR_FOLLOWING_SIZE
+ (22013) with error text like invalid preceding or
+ following size in window function. (This is required by
+ the SQL standard, although nonstandard operator families might
+ perhaps choose to ignore this restriction, since there seems to
+ be little semantic necessity for it.) This requirement is
+ delegated to the in_range function so that
+ the core code needn't understand what less than
+ zero means for a particular data type.
-
-
+
- If in_range with less =
- true is true for some val
- and base1, it must be true for
- every base2 >=
- base1 with the
- same val.
+ An additional expectation is that in_range
+ functions should, if practical, avoid throwing an error if
+ base +
+ offset or
+ base -
+ offset would overflow. The correct
+ comparison result can be determined even if that value would be
+ out of the data type's range. Note that if the data type
+ includes concepts such as infinity
or
+ NaN
, extra care may be needed to ensure that
+ in_range's results agree with the normal
+ sort order of the operator family.
-
-
+
- If in_range with less =
- true is false for some val
- and base1, it must be false for
- every base2 <=
- base1 with the
- same val.
+ The results of the in_range function must be
+ consistent with the sort ordering imposed by the operator family.
+ To be precise, given any fixed values of
+ offset and
+ sub, then:
+
+
+ If in_range with
+ less = true is true for some
+ val1 and
+ base, it must be true for every
+ val2 <=
+ val1 with the same
+ base.
+
+
+
+ If in_range with
+ less = true is false for some
+ val1 and
+ base, it must be false for every
+ val2 >=
+ val1 with the same
+ base.
+
+
+
+ If in_range with
+ less = true is true for some
+ val and
+ base1, it must be true for every
+ base2 >=
+ base1 with the same
+ val.
+
+
+
+ If in_range with
+ less = true is false for some
+ val and
+ base1, it must be false for every
+ base2 <=
+ base1 with the same
+ val.
+
+
+
+ Analogous statements with inverted conditions hold when
+ less = false.
-
-
- Analogous statements with inverted conditions hold
- when less = false.
-
- If the type being ordered (type1) is collatable,
- the appropriate collation OID will be passed to
- the in_range function, using the standard
- PG_GET_COLLATION() mechanism.
-
+ If the type being ordered (type1) is collatable, the
+ appropriate collation OID will be passed to the
+ in_range function, using the standard
+ PG_GET_COLLATION() mechanism.
+
- in_range functions need not handle NULL inputs, and
- typically will be marked strict.
-
+ in_range functions need not handle NULL
+ inputs, and typically will be marked strict.
+
+
+
+
projects / postgresql.git / commitdiff