PostgreSQL 13 Documentation: 9.20. Range Functions and Operators

9.20. Range Functions and Operators
Prev	Up	Chapter 9. Functions and Operators	Home	Next

9.20. Range Functions and Operators

See Section 8.17 for an overview of range types.

Table 9.53 shows the specialized operators available for range types. In addition to those, the usual comparison operators shown in Table 9.1 are available for range types. The comparison operators order first by the range lower bounds, and only if those are equal do they compare the upper bounds. This does not usually result in a useful overall ordering, but the operators are provided to allow unique indexes to be constructed on ranges.

Table 9.53. Range Operators

Operator Description Example(s)
`anyrange` `@>` `anyrange` → `boolean` Does the first range contain the second? `int4range(2,4) @> int4range(2,3)` → `t`
`anyrange` `@>` `anyelement` → `boolean` Does the range contain the element? `'[2011-01-01,2011-03-01)'::tsrange @> '2011-01-10'::timestamp` → `t`
`anyrange` `<@` `anyrange` → `boolean` Is the first range contained by the second? `int4range(2,4) <@ int4range(1,7)` → `t`
`anyelement` `<@` `anyrange` → `boolean` Is the element contained in the range? `42 <@ int4range(1,7)` → `f`
`anyrange` `&&` `anyrange` → `boolean` Do the ranges overlap, that is, have any elements in common? `int8range(3,7) && int8range(4,12)` → `t`
`anyrange` `<<` `anyrange` → `boolean` Is the first range strictly left of the second? `int8range(1,10) << int8range(100,110)` → `t`
`anyrange` `>>` `anyrange` → `boolean` Is the first range strictly right of the second? `int8range(50,60) >> int8range(20,30)` → `t`
`anyrange` `&<` `anyrange` → `boolean` Does the first range not extend to the right of the second? `int8range(1,20) &< int8range(18,20)` → `t`
`anyrange` `&>` `anyrange` → `boolean` Does the first range not extend to the left of the second? `int8range(7,20) &> int8range(5,10)` → `t`
`anyrange` `-\|-` `anyrange` → `boolean` Are the ranges adjacent? `numrange(1.1,2.2) -\|- numrange(2.2,3.3)` → `t`
`anyrange` `+` `anyrange` → `anyrange` Computes the union of the ranges. The ranges must overlap or be adjacent, so that the union is a single range (but see `range_merge()`). `numrange(5,15) + numrange(10,20)` → `[5,20)`
`anyrange` `` `anyrange` → `anyrange` Computes the intersection of the ranges. `int8range(5,15) int8range(10,20)` → `[10,15)`
`anyrange` `-` `anyrange` → `anyrange` Computes the difference of the ranges. The second range must not be contained in the first in such a way that the difference would not be a single range. `int8range(5,15) - int8range(10,20)` → `[5,10)`

Operator

Description

Example(s)

anyrange @> anyrange → boolean

Does the first range contain the second?

int4range(2,4) @> int4range(2,3) → t

anyrange @> anyelement → boolean

Does the range contain the element?

'[2011-01-01,2011-03-01)'::tsrange @> '2011-01-10'::timestamp → t

anyrange <@ anyrange → boolean

Is the first range contained by the second?

int4range(2,4) <@ int4range(1,7) → t

anyelement <@ anyrange → boolean

Is the element contained in the range?

42 <@ int4range(1,7) → f

anyrange && anyrange → boolean

Do the ranges overlap, that is, have any elements in common?

int8range(3,7) && int8range(4,12) → t

anyrange << anyrange → boolean

Is the first range strictly left of the second?

int8range(1,10) << int8range(100,110) → t

anyrange >> anyrange → boolean

Is the first range strictly right of the second?

int8range(50,60) >> int8range(20,30) → t

anyrange &< anyrange → boolean

Does the first range not extend to the right of the second?

int8range(1,20) &< int8range(18,20) → t

anyrange &> anyrange → boolean

Does the first range not extend to the left of the second?

int8range(7,20) &> int8range(5,10) → t

anyrange -|- anyrange → boolean

Are the ranges adjacent?

numrange(1.1,2.2) -|- numrange(2.2,3.3) → t

anyrange + anyrange → anyrange

Computes the union of the ranges. The ranges must overlap or be adjacent, so that the union is a single range (but see range_merge()).

numrange(5,15) + numrange(10,20) → [5,20)

anyrange * anyrange → anyrange

Computes the intersection of the ranges.

int8range(5,15) * int8range(10,20) → [10,15)

anyrange - anyrange → anyrange

Computes the difference of the ranges. The second range must not be contained in the first in such a way that the difference would not be a single range.

int8range(5,15) - int8range(10,20) → [5,10)

The left-of/right-of/adjacent operators always return false when an empty range is involved; that is, an empty range is not considered to be either before or after any other range.

Table 9.54 shows the functions available for use with range types.

Table 9.54. Range Functions

Function Description Example(s)
`lower` ( `anyrange` ) → `anyelement` Extracts the lower bound of the range (`NULL` if the range is empty or the lower bound is infinite). `lower(numrange(1.1,2.2))` → `1.1`
`upper` ( `anyrange` ) → `anyelement` Extracts the upper bound of the range (`NULL` if the range is empty or the upper bound is infinite). `upper(numrange(1.1,2.2))` → `2.2`
`isempty` ( `anyrange` ) → `boolean` Is the range empty? `isempty(numrange(1.1,2.2))` → `f`
`lower_inc` ( `anyrange` ) → `boolean` Is the range's lower bound inclusive? `lower_inc(numrange(1.1,2.2))` → `t`
`upper_inc` ( `anyrange` ) → `boolean` Is the range's upper bound inclusive? `upper_inc(numrange(1.1,2.2))` → `f`
`lower_inf` ( `anyrange` ) → `boolean` Is the range's lower bound infinite? `lower_inf('(,)'::daterange)` → `t`
`upper_inf` ( `anyrange` ) → `boolean` Is the range's upper bound infinite? `upper_inf('(,)'::daterange)` → `t`
`range_merge` ( `anyrange`, `anyrange` ) → `anyrange` Computes the smallest range that includes both of the given ranges. `range_merge('[1,2)'::int4range, '[3,4)'::int4range)` → `[1,4)`

Function

Description

Example(s)

lower ( anyrange ) → anyelement

Extracts the lower bound of the range (NULL if the range is empty or the lower bound is infinite).

lower(numrange(1.1,2.2)) → 1.1

upper ( anyrange ) → anyelement

Extracts the upper bound of the range (NULL if the range is empty or the upper bound is infinite).

upper(numrange(1.1,2.2)) → 2.2

isempty ( anyrange ) → boolean

Is the range empty?

isempty(numrange(1.1,2.2)) → f

lower_inc ( anyrange ) → boolean

Is the range's lower bound inclusive?

lower_inc(numrange(1.1,2.2)) → t

upper_inc ( anyrange ) → boolean

Is the range's upper bound inclusive?

upper_inc(numrange(1.1,2.2)) → f

lower_inf ( anyrange ) → boolean

Is the range's lower bound infinite?

lower_inf('(,)'::daterange) → t

upper_inf ( anyrange ) → boolean

Is the range's upper bound infinite?

upper_inf('(,)'::daterange) → t

range_merge ( anyrange, anyrange ) → anyrange

Computes the smallest range that includes both of the given ranges.

range_merge('[1,2)'::int4range, '[3,4)'::int4range) → [1,4)

The lower_inc, upper_inc, lower_inf, and upper_inf functions all return false for an empty range.

Prev	Up	Next
9.19. Array Functions and Operators	Home	9.21. Aggregate Functions