2011-11-03 12:16:28 +01:00
|
|
|
<!-- doc/src/sgml/rangetypes.sgml -->
|
|
|
|
|
|
|
|
<sect1 id="rangetypes">
|
|
|
|
<title>Range Types</title>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>range type</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2021-05-03 20:14:03 +02:00
|
|
|
<indexterm>
|
|
|
|
<primary>multirange type</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
Range types are data types representing a range of values of some
|
2017-10-09 03:44:17 +02:00
|
|
|
element type (called the range's <firstterm>subtype</firstterm>).
|
2011-11-19 00:23:55 +01:00
|
|
|
For instance, ranges
|
2011-11-03 12:16:28 +01:00
|
|
|
of <type>timestamp</type> might be used to represent the ranges of
|
|
|
|
time that a meeting room is reserved. In this case the data type
|
2011-11-19 00:23:55 +01:00
|
|
|
is <type>tsrange</type> (short for <quote>timestamp range</quote>),
|
|
|
|
and <type>timestamp</type> is the subtype. The subtype must have
|
|
|
|
a total order so that it is well-defined whether element values are
|
|
|
|
within, before, or after a range of values.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
Range types are useful because they represent many element values in a
|
|
|
|
single range value, and because concepts such as overlapping ranges can
|
|
|
|
be expressed clearly. The use of time and date ranges for scheduling
|
2011-11-03 12:16:28 +01:00
|
|
|
purposes is the clearest example; but price ranges, measurement
|
2011-11-19 00:23:55 +01:00
|
|
|
ranges from an instrument, and so forth can also be useful.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
<para>
|
|
|
|
Every range type has a corresponding multirange type. A multirange is
|
2020-12-24 09:05:49 +01:00
|
|
|
an ordered list of non-contiguous, non-empty, non-null ranges. Most
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
range operators also work on multiranges, and they have a few functions
|
|
|
|
of their own.
|
|
|
|
</para>
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<sect2 id="rangetypes-builtin">
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
<title>Built-in Range and Multirange Types</title>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
|
|
|
PostgreSQL comes with the following built-in range types:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
<type>int4range</type> — Range of <type>integer</type>,
|
|
|
|
<type>int4multirange</type> — corresponding Multirange
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
<type>int8range</type> — Range of <type>bigint</type>,
|
|
|
|
<type>int8multirange</type> — corresponding Multirange
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
<type>numrange</type> — Range of <type>numeric</type>,
|
|
|
|
<type>nummultirange</type> — corresponding Multirange
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
<type>tsrange</type> — Range of <type>timestamp without time zone</type>,
|
|
|
|
<type>tsmultirange</type> — corresponding Multirange
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
<type>tstzrange</type> — Range of <type>timestamp with time zone</type>,
|
|
|
|
<type>tstzmultirange</type> — corresponding Multirange
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
<type>daterange</type> — Range of <type>date</type>,
|
|
|
|
<type>datemultirange</type> — corresponding Multirange
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
2011-11-19 00:23:55 +01:00
|
|
|
In addition, you can define your own range types;
|
2017-11-23 15:39:47 +01:00
|
|
|
see <xref linkend="sql-createtype"/> for more information.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="rangetypes-examples">
|
|
|
|
<title>Examples</title>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
|
|
|
<programlisting>
|
2012-06-08 09:28:32 +02:00
|
|
|
CREATE TABLE reservation (room int, during tsrange);
|
2011-11-19 00:23:55 +01:00
|
|
|
INSERT INTO reservation VALUES
|
2012-06-08 09:28:32 +02:00
|
|
|
(1108, '[2010-01-01 14:30, 2010-01-01 15:30)');
|
2011-11-03 12:16:28 +01:00
|
|
|
|
|
|
|
-- Containment
|
2015-10-07 15:42:26 +02:00
|
|
|
SELECT int4range(10, 20) @> 3;
|
2011-11-03 12:16:28 +01:00
|
|
|
|
|
|
|
-- Overlaps
|
2011-11-19 00:23:55 +01:00
|
|
|
SELECT numrange(11.1, 22.2) && numrange(20.0, 30.0);
|
2011-11-03 12:16:28 +01:00
|
|
|
|
2011-11-19 00:23:55 +01:00
|
|
|
-- Extract the upper bound
|
2011-11-03 12:16:28 +01:00
|
|
|
SELECT upper(int8range(15, 25));
|
|
|
|
|
2011-11-19 00:23:55 +01:00
|
|
|
-- Compute the intersection
|
2011-11-03 12:16:28 +01:00
|
|
|
SELECT int4range(10, 20) * int4range(15, 25);
|
|
|
|
|
2012-08-23 10:57:34 +02:00
|
|
|
-- Is the range empty?
|
2011-11-08 08:40:37 +01:00
|
|
|
SELECT isempty(numrange(1, 5));
|
2011-11-03 12:16:28 +01:00
|
|
|
</programlisting>
|
|
|
|
|
2017-11-23 15:39:47 +01:00
|
|
|
See <xref linkend="range-operators-table"/>
|
|
|
|
and <xref linkend="range-functions-table"/> for complete lists of
|
2011-11-24 01:13:56 +01:00
|
|
|
operators and functions on range types.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="rangetypes-inclusivity">
|
|
|
|
<title>Inclusive and Exclusive Bounds</title>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
Every non-empty range has two bounds, the lower bound and the upper
|
|
|
|
bound. All points between these values are included in the range. An
|
|
|
|
inclusive bound means that the boundary point itself is included in
|
|
|
|
the range as well, while an exclusive bound means that the boundary
|
|
|
|
point is not included in the range.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
In the text form of a range, an inclusive lower bound is represented by
|
|
|
|
<quote><literal>[</literal></quote> while an exclusive lower bound is
|
|
|
|
represented by <quote><literal>(</literal></quote>. Likewise, an inclusive upper bound is represented by
|
|
|
|
<quote><literal>]</literal></quote>, while an exclusive upper bound is
|
|
|
|
represented by <quote><literal>)</literal></quote>.
|
2017-11-23 15:39:47 +01:00
|
|
|
(See <xref linkend="rangetypes-io"/> for more details.)
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
The functions <literal>lower_inc</literal>
|
|
|
|
and <literal>upper_inc</literal> test the inclusivity of the lower
|
|
|
|
and upper bounds of a range value, respectively.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="rangetypes-infinite">
|
2011-11-19 00:23:55 +01:00
|
|
|
<title>Infinite (Unbounded) Ranges</title>
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2019-12-27 20:33:30 +01:00
|
|
|
The lower bound of a range can be omitted, meaning that all
|
|
|
|
values less than the upper bound are included in the range, e.g.,
|
|
|
|
<literal>(,3]</literal>. Likewise, if the upper bound of the range
|
|
|
|
is omitted, then all values greater than the lower bound are included
|
|
|
|
in the range. If both lower and upper bounds are omitted, all values
|
|
|
|
of the element type are considered to be in the range. Specifying a
|
|
|
|
missing bound as inclusive is automatically converted to exclusive,
|
|
|
|
e.g., <literal>[,]</literal> is converted to <literal>(,)</literal>.
|
|
|
|
You can think of these missing values as +/-infinity, but they are
|
|
|
|
special range type values and are considered to be beyond any range
|
|
|
|
element type's +/-infinity values.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
|
|
|
<para>
|
2019-12-27 20:33:30 +01:00
|
|
|
Element types that have the notion of <quote>infinity</quote> can
|
|
|
|
use them as explicit bound values. For example, with timestamp
|
|
|
|
ranges, <literal>[today,infinity)</literal> excludes the special
|
|
|
|
<type>timestamp</type> value <literal>infinity</literal>,
|
|
|
|
while <literal>[today,infinity]</literal> include it, as does
|
|
|
|
<literal>[today,)</literal> and <literal>[today,]</literal>.
|
2011-11-19 00:23:55 +01:00
|
|
|
</para>
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
The functions <literal>lower_inf</literal>
|
|
|
|
and <literal>upper_inf</literal> test for infinite lower
|
|
|
|
and upper bounds of a range, respectively.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="rangetypes-io">
|
2011-11-19 00:23:55 +01:00
|
|
|
<title>Range Input/Output</title>
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
The input for a range value must follow one of the following patterns:
|
2011-11-03 12:16:28 +01:00
|
|
|
<synopsis>
|
|
|
|
(<replaceable>lower-bound</replaceable>,<replaceable>upper-bound</replaceable>)
|
|
|
|
(<replaceable>lower-bound</replaceable>,<replaceable>upper-bound</replaceable>]
|
|
|
|
[<replaceable>lower-bound</replaceable>,<replaceable>upper-bound</replaceable>)
|
|
|
|
[<replaceable>lower-bound</replaceable>,<replaceable>upper-bound</replaceable>]
|
|
|
|
empty
|
|
|
|
</synopsis>
|
2011-11-19 00:23:55 +01:00
|
|
|
The parentheses or brackets indicate whether the lower and upper bounds
|
|
|
|
are exclusive or inclusive, as described previously.
|
|
|
|
Notice that the final pattern is <literal>empty</literal>, which
|
|
|
|
represents an empty range (a range that contains no points).
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
The <replaceable>lower-bound</replaceable> may be either a string
|
|
|
|
that is valid input for the subtype, or empty to indicate no
|
|
|
|
lower bound. Likewise, <replaceable>upper-bound</replaceable> may be
|
|
|
|
either a string that is valid input for the subtype, or empty to
|
|
|
|
indicate no upper bound.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
Each bound value can be quoted using <literal>"</literal> (double quote)
|
|
|
|
characters. This is necessary if the bound value contains parentheses,
|
|
|
|
brackets, commas, double quotes, or backslashes, since these characters
|
|
|
|
would otherwise be taken as part of the range syntax. To put a double
|
|
|
|
quote or backslash in a quoted bound value, precede it with a
|
|
|
|
backslash. (Also, a pair of double quotes within a double-quoted bound
|
|
|
|
value is taken to represent a double quote character, analogously to the
|
|
|
|
rules for single quotes in SQL literal strings.) Alternatively, you can
|
|
|
|
avoid quoting and use backslash-escaping to protect all data characters
|
|
|
|
that would otherwise be taken as range syntax. Also, to write a bound
|
|
|
|
value that is an empty string, write <literal>""</literal>, since writing
|
|
|
|
nothing means an infinite bound.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
Whitespace is allowed before and after the range value, but any whitespace
|
|
|
|
between the parentheses or brackets is taken as part of the lower or upper
|
|
|
|
bound value. (Depending on the element type, it might or might not be
|
|
|
|
significant.)
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
These rules are very similar to those for writing field values in
|
2017-11-23 15:39:47 +01:00
|
|
|
composite-type literals. See <xref linkend="rowtypes-io-syntax"/> for
|
2011-11-19 00:23:55 +01:00
|
|
|
additional commentary.
|
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
|
|
|
Examples:
|
|
|
|
<programlisting>
|
2011-11-19 00:23:55 +01:00
|
|
|
-- includes 3, does not include 7, and does include all points in between
|
2012-06-08 09:28:32 +02:00
|
|
|
SELECT '[3,7)'::int4range;
|
2011-11-03 12:16:28 +01:00
|
|
|
|
|
|
|
-- does not include either 3 or 7, but includes all points in between
|
2012-06-08 09:28:32 +02:00
|
|
|
SELECT '(3,7)'::int4range;
|
2011-11-03 12:16:28 +01:00
|
|
|
|
|
|
|
-- includes only the single point 4
|
2012-06-08 09:28:32 +02:00
|
|
|
SELECT '[4,4]'::int4range;
|
2011-11-24 01:13:56 +01:00
|
|
|
|
|
|
|
-- includes no points (and will be normalized to 'empty')
|
2012-06-08 09:28:32 +02:00
|
|
|
SELECT '[4,4)'::int4range;
|
2011-11-03 12:16:28 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
The input for a multirange is curly brackets (<literal>{</literal> and
|
|
|
|
<literal>}</literal>) containing zero or more valid ranges,
|
|
|
|
separated by commas. Whitespace is permitted around the brackets and
|
|
|
|
commas. This is intended to be reminiscent of array syntax, although
|
|
|
|
multiranges are much simpler: they have just one dimension and there is
|
|
|
|
no need to quote their contents. (The bounds of their ranges may be
|
|
|
|
quoted as above however.)
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Examples:
|
|
|
|
<programlisting>
|
|
|
|
SELECT '{}'::int4multirange;
|
|
|
|
SELECT '{[3,7)}'::int4multirange;
|
|
|
|
SELECT '{[3,7), [8,9)}'::int4multirange;
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="rangetypes-construct">
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
<title>Constructing Ranges and Multiranges</title>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
Each range type has a constructor function with the same name as the range
|
|
|
|
type. Using the constructor function is frequently more convenient than
|
|
|
|
writing a range literal constant, since it avoids the need for extra
|
|
|
|
quoting of the bound values. The constructor function
|
2011-11-23 02:45:05 +01:00
|
|
|
accepts two or three arguments. The two-argument form constructs a range
|
|
|
|
in standard form (lower bound inclusive, upper bound exclusive), while
|
|
|
|
the three-argument form constructs a range with bounds of the form
|
|
|
|
specified by the third argument.
|
|
|
|
The third argument must be one of the strings
|
2011-11-19 00:23:55 +01:00
|
|
|
<quote><literal>()</literal></quote>,
|
|
|
|
<quote><literal>(]</literal></quote>,
|
|
|
|
<quote><literal>[)</literal></quote>, or
|
|
|
|
<quote><literal>[]</literal></quote>.
|
|
|
|
For example:
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<programlisting>
|
2011-11-23 02:45:05 +01:00
|
|
|
-- The full form is: lower bound, upper bound, and text argument indicating
|
2011-11-19 00:23:55 +01:00
|
|
|
-- inclusivity/exclusivity of bounds.
|
2011-11-03 12:16:28 +01:00
|
|
|
SELECT numrange(1.0, 14.0, '(]');
|
|
|
|
|
2011-11-19 00:23:55 +01:00
|
|
|
-- If the third argument is omitted, '[)' is assumed.
|
|
|
|
SELECT numrange(1.0, 14.0);
|
|
|
|
|
|
|
|
-- Although '(]' is specified here, on display the value will be converted to
|
|
|
|
-- canonical form, since int8range is a discrete range type (see below).
|
2011-11-03 12:16:28 +01:00
|
|
|
SELECT int8range(1, 14, '(]');
|
|
|
|
|
2011-11-19 00:23:55 +01:00
|
|
|
-- Using NULL for either bound causes the range to be unbounded on that side.
|
|
|
|
SELECT numrange(NULL, 2.2);
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Each range type also has a multirange constructor with the same name as the
|
|
|
|
multirange type. The constructor function takes zero or more arguments
|
|
|
|
which are all ranges of the appropriate type.
|
|
|
|
For example:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
SELECT nummultirange();
|
|
|
|
SELECT nummultirange(numrange(1.0, 14.0));
|
|
|
|
SELECT nummultirange(numrange(1.0, 14.0), numrange(20.0, 25.0));
|
2011-11-03 12:16:28 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="rangetypes-discrete">
|
|
|
|
<title>Discrete Range Types</title>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
A discrete range is one whose element type has a well-defined
|
2012-06-08 09:28:32 +02:00
|
|
|
<quote>step</quote>, such as <type>integer</type> or <type>date</type>.
|
2011-11-24 01:13:56 +01:00
|
|
|
In these types two elements can be said to be adjacent, when there are
|
2011-11-19 00:23:55 +01:00
|
|
|
no valid values between them. This contrasts with continuous ranges,
|
|
|
|
where it's always (or almost always) possible to identify other element
|
|
|
|
values between two given values. For example, a range over the
|
2017-10-09 03:44:17 +02:00
|
|
|
<type>numeric</type> type is continuous, as is a range over <type>timestamp</type>.
|
|
|
|
(Even though <type>timestamp</type> has limited precision, and so could
|
2011-11-19 00:23:55 +01:00
|
|
|
theoretically be treated as discrete, it's better to consider it continuous
|
|
|
|
since the step size is normally not of interest.)
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
Another way to think about a discrete range type is that there is a clear
|
2017-10-09 03:44:17 +02:00
|
|
|
idea of a <quote>next</quote> or <quote>previous</quote> value for each element value.
|
2011-11-19 00:23:55 +01:00
|
|
|
Knowing that, it is possible to convert between inclusive and exclusive
|
|
|
|
representations of a range's bounds, by choosing the next or previous
|
|
|
|
element value instead of the one originally given.
|
2017-10-09 03:44:17 +02:00
|
|
|
For example, in an integer range type <literal>[4,8]</literal> and
|
|
|
|
<literal>(3,9)</literal> denote the same set of values; but this would not be so
|
2011-11-19 00:23:55 +01:00
|
|
|
for a range over numeric.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
A discrete range type should have a <firstterm>canonicalization</firstterm>
|
2011-11-19 00:23:55 +01:00
|
|
|
function that is aware of the desired step size for the element type.
|
2011-11-24 01:13:56 +01:00
|
|
|
The canonicalization function is charged with converting equivalent values
|
|
|
|
of the range type to have identical representations, in particular
|
|
|
|
consistently inclusive or exclusive bounds.
|
|
|
|
If a canonicalization function is not specified, then ranges with different
|
|
|
|
formatting will always be treated as unequal, even though they might
|
|
|
|
represent the same set of values in reality.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2012-06-08 09:28:32 +02:00
|
|
|
The built-in range types <type>int4range</type>, <type>int8range</type>,
|
|
|
|
and <type>daterange</type> all use a canonical form that includes
|
2011-11-19 00:23:55 +01:00
|
|
|
the lower bound and excludes the upper bound; that is,
|
|
|
|
<literal>[)</literal>. User-defined range types can use other conventions,
|
|
|
|
however.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="rangetypes-defining">
|
|
|
|
<title>Defining New Range Types</title>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2011-11-19 00:23:55 +01:00
|
|
|
Users can define their own range types. The most common reason to do
|
|
|
|
this is to use ranges over subtypes not provided among the built-in
|
|
|
|
range types.
|
2011-11-24 01:13:56 +01:00
|
|
|
For example, to define a new range type of subtype <type>float8</type>:
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<programlisting>
|
2011-11-24 01:13:56 +01:00
|
|
|
CREATE TYPE floatrange AS RANGE (
|
2012-06-08 09:28:32 +02:00
|
|
|
subtype = float8,
|
|
|
|
subtype_diff = float8mi
|
2011-11-03 12:16:28 +01:00
|
|
|
);
|
|
|
|
|
|
|
|
SELECT '[1.234, 5.678]'::floatrange;
|
|
|
|
</programlisting>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-24 01:13:56 +01:00
|
|
|
Because <type>float8</type> has no meaningful
|
2011-11-19 00:23:55 +01:00
|
|
|
<quote>step</quote>, we do not define a canonicalization
|
2011-11-24 01:13:56 +01:00
|
|
|
function in this example.
|
|
|
|
</para>
|
|
|
|
|
Multirange datatypes
Multiranges are basically sorted arrays of non-overlapping ranges with
set-theoretic operations defined over them.
Since v14, each range type automatically gets a corresponding multirange
datatype. There are both manual and automatic mechanisms for naming multirange
types. Once can specify multirange type name using multirange_type_name
attribute in CREATE TYPE. Otherwise, a multirange type name is generated
automatically. If the range type name contains "range" then we change that to
"multirange". Otherwise, we add "_multirange" to the end.
Implementation of multiranges comes with a space-efficient internal
representation format, which evades extra paddings and duplicated storage of
oids. Altogether this format allows fetching a particular range by its index
in O(n).
Statistic gathering and selectivity estimation are implemented for multiranges.
For this purpose, stored multirange is approximated as union range without gaps.
This field will likely need improvements in the future.
Catversion is bumped.
Discussion: https://postgr.es/m/CALNJ-vSUpQ_Y%3DjXvTxt1VYFztaBSsWVXeF1y6gTYQ4bOiWDLgQ%40mail.gmail.com
Discussion: https://postgr.es/m/a0b8026459d1e6167933be2104a6174e7d40d0ab.camel%40j-davis.com#fe7218c83b08068bfffb0c5293eceda0
Author: Paul Jungwirth, revised by me
Reviewed-by: David Fetter, Corey Huinker, Jeff Davis, Pavel Stehule
Reviewed-by: Alvaro Herrera, Tom Lane, Isaac Morland, David G. Johnston
Reviewed-by: Zhihong Yu, Alexander Korotkov
2020-12-20 05:20:33 +01:00
|
|
|
<para>
|
|
|
|
When you define your own range you automatically get a corresponding
|
|
|
|
multirange type.
|
|
|
|
</para>
|
|
|
|
|
2015-10-02 18:20:01 +02:00
|
|
|
<para>
|
|
|
|
Defining your own range type also allows you to specify a different
|
|
|
|
subtype B-tree operator class or collation to use, so as to change the sort
|
|
|
|
ordering that determines which values fall into a given range.
|
|
|
|
</para>
|
|
|
|
|
2011-11-24 01:13:56 +01:00
|
|
|
<para>
|
|
|
|
If the subtype is considered to have discrete rather than continuous
|
2017-10-09 03:44:17 +02:00
|
|
|
values, the <command>CREATE TYPE</command> command should specify a
|
|
|
|
<literal>canonical</literal> function.
|
2011-11-24 01:13:56 +01:00
|
|
|
The canonicalization function takes an input range value, and must return
|
|
|
|
an equivalent range value that may have different bounds and formatting.
|
|
|
|
The canonical output for two ranges that represent the same set of values,
|
|
|
|
for example the integer ranges <literal>[1, 7]</literal> and <literal>[1,
|
|
|
|
8)</literal>, must be identical. It doesn't matter which representation
|
|
|
|
you choose to be the canonical one, so long as two equivalent values with
|
|
|
|
different formattings are always mapped to the same value with the same
|
|
|
|
formatting. In addition to adjusting the inclusive/exclusive bounds
|
|
|
|
format, a canonicalization function might round off boundary values, in
|
|
|
|
case the desired step size is larger than what the subtype is capable of
|
2017-10-09 03:44:17 +02:00
|
|
|
storing. For instance, a range type over <type>timestamp</type> could be
|
2011-11-24 01:13:56 +01:00
|
|
|
defined to have a step size of an hour, in which case the canonicalization
|
|
|
|
function would need to round off bounds that weren't a multiple of an hour,
|
|
|
|
or perhaps throw an error instead.
|
2011-11-19 00:23:55 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2015-10-02 18:20:01 +02:00
|
|
|
In addition, any range type that is meant to be used with GiST or SP-GiST
|
2017-10-09 03:44:17 +02:00
|
|
|
indexes should define a subtype difference, or <literal>subtype_diff</literal>,
|
|
|
|
function. (The index will still work without <literal>subtype_diff</literal>,
|
2015-10-02 18:20:01 +02:00
|
|
|
but it is likely to be considerably less efficient than if a difference
|
|
|
|
function is provided.) The subtype difference function takes two input
|
|
|
|
values of the subtype, and returns their difference
|
2017-10-09 03:44:17 +02:00
|
|
|
(i.e., <replaceable>X</replaceable> minus <replaceable>Y</replaceable>) represented as
|
|
|
|
a <type>float8</type> value. In our example above, the
|
|
|
|
function <function>float8mi</function> that underlies the regular <type>float8</type>
|
2015-10-02 18:20:01 +02:00
|
|
|
minus operator can be used; but for any other subtype, some type
|
|
|
|
conversion would be necessary. Some creative thought about how to
|
|
|
|
represent differences as numbers might be needed, too. To the greatest
|
2017-10-09 03:44:17 +02:00
|
|
|
extent possible, the <literal>subtype_diff</literal> function should agree with
|
2015-10-02 18:20:01 +02:00
|
|
|
the sort ordering implied by the selected operator class and collation;
|
|
|
|
that is, its result should be positive whenever its first argument is
|
|
|
|
greater than its second according to the sort ordering.
|
2011-11-24 01:13:56 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
A less-oversimplified example of a <literal>subtype_diff</literal> function is:
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2015-10-02 18:20:01 +02:00
|
|
|
<programlisting>
|
|
|
|
CREATE FUNCTION time_subtype_diff(x time, y time) RETURNS float8 AS
|
|
|
|
'SELECT EXTRACT(EPOCH FROM (x - y))' LANGUAGE sql STRICT IMMUTABLE;
|
|
|
|
|
|
|
|
CREATE TYPE timerange AS RANGE (
|
|
|
|
subtype = time,
|
|
|
|
subtype_diff = time_subtype_diff
|
|
|
|
);
|
|
|
|
|
|
|
|
SELECT '[11:10, 23:00]'::timerange;
|
|
|
|
</programlisting>
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2017-11-23 15:39:47 +01:00
|
|
|
See <xref linkend="sql-createtype"/> for more information about creating
|
2011-11-19 00:23:55 +01:00
|
|
|
range types.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
2013-04-22 20:51:14 +02:00
|
|
|
<sect2 id="rangetypes-indexing">
|
2011-11-19 00:23:55 +01:00
|
|
|
<title>Indexing</title>
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<indexterm>
|
|
|
|
<primary>range type</primary>
|
2011-11-24 01:13:56 +01:00
|
|
|
<secondary>indexes on</secondary>
|
2011-11-03 12:16:28 +01:00
|
|
|
</indexterm>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2013-04-22 20:51:14 +02:00
|
|
|
GiST and SP-GiST indexes can be created for table columns of range types.
|
2020-12-29 21:36:43 +01:00
|
|
|
GiST indexes can be also created for table columns of multirange types.
|
2013-04-22 20:51:14 +02:00
|
|
|
For instance, to create a GiST index:
|
2011-11-03 12:16:28 +01:00
|
|
|
<programlisting>
|
2015-05-15 17:42:29 +02:00
|
|
|
CREATE INDEX reservation_idx ON reservation USING GIST (during);
|
2011-11-03 12:16:28 +01:00
|
|
|
</programlisting>
|
2020-12-29 21:36:43 +01:00
|
|
|
A GiST or SP-GiST index on ranges can accelerate queries involving these
|
|
|
|
range operators:
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>=</literal>,
|
|
|
|
<literal>&&</literal>,
|
|
|
|
<literal><@</literal>,
|
|
|
|
<literal>@></literal>,
|
|
|
|
<literal><<</literal>,
|
|
|
|
<literal>>></literal>,
|
|
|
|
<literal>-|-</literal>,
|
|
|
|
<literal>&<</literal>, and
|
2020-12-29 21:36:43 +01:00
|
|
|
<literal>&></literal>.
|
|
|
|
A GiST index on multiranges can accelerate queries involving the same
|
|
|
|
set of multirange operators.
|
|
|
|
A GiST index on ranges and GiST index on multiranges can also accelerate
|
|
|
|
queries involving these cross-type range to multirange and multirange to
|
|
|
|
range operators correspondingly:
|
|
|
|
<literal>&&</literal>,
|
|
|
|
<literal><@</literal>,
|
|
|
|
<literal>@></literal>,
|
|
|
|
<literal><<</literal>,
|
|
|
|
<literal>>></literal>,
|
|
|
|
<literal>-|-</literal>,
|
|
|
|
<literal>&<</literal>, and
|
|
|
|
<literal>&></literal>.
|
|
|
|
See <xref linkend="range-operators-table"/> for more information.
|
2011-11-24 01:13:56 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
In addition, B-tree and hash indexes can be created for table columns of
|
|
|
|
range types. For these index types, basically the only useful range
|
|
|
|
operation is equality. There is a B-tree sort ordering defined for range
|
2017-10-09 03:44:17 +02:00
|
|
|
values, with corresponding <literal><</literal> and <literal>></literal> operators,
|
2011-11-24 01:13:56 +01:00
|
|
|
but the ordering is rather arbitrary and not usually useful in the real
|
|
|
|
world. Range types' B-tree and hash support is primarily meant to
|
|
|
|
allow sorting and hashing internally in queries, rather than creation of
|
|
|
|
actual indexes.
|
2011-11-03 12:16:28 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="rangetypes-constraint">
|
2011-11-19 00:23:55 +01:00
|
|
|
<title>Constraints on Ranges</title>
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<indexterm>
|
|
|
|
<primary>range type</primary>
|
|
|
|
<secondary>exclude</secondary>
|
|
|
|
</indexterm>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
|
|
|
While <literal>UNIQUE</literal> is a natural constraint for scalar
|
|
|
|
values, it is usually unsuitable for range types. Instead, an
|
|
|
|
exclusion constraint is often more appropriate
|
2017-10-20 03:16:39 +02:00
|
|
|
(see <link linkend="sql-createtable-exclude">CREATE TABLE
|
2011-11-03 12:16:28 +01:00
|
|
|
... CONSTRAINT ... EXCLUDE</link>). Exclusion constraints allow the
|
2011-11-19 00:23:55 +01:00
|
|
|
specification of constraints such as <quote>non-overlapping</quote> on a
|
|
|
|
range type. For example:
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<programlisting>
|
2013-09-05 08:30:27 +02:00
|
|
|
CREATE TABLE reservation (
|
|
|
|
during tsrange,
|
2015-05-15 17:42:29 +02:00
|
|
|
EXCLUDE USING GIST (during WITH &&)
|
2013-09-05 08:30:27 +02:00
|
|
|
);
|
2011-11-03 12:16:28 +01:00
|
|
|
</programlisting>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
That constraint will prevent any overlapping values from existing
|
|
|
|
in the table at the same time:
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<programlisting>
|
2011-11-19 00:23:55 +01:00
|
|
|
INSERT INTO reservation VALUES
|
2013-09-05 08:30:27 +02:00
|
|
|
('[2010-01-01 11:30, 2010-01-01 15:00)');
|
2011-11-19 00:23:55 +01:00
|
|
|
INSERT 0 1
|
|
|
|
|
|
|
|
INSERT INTO reservation VALUES
|
2013-09-05 08:30:27 +02:00
|
|
|
('[2010-01-01 14:45, 2010-01-01 15:45)');
|
2011-11-19 00:23:55 +01:00
|
|
|
ERROR: conflicting key value violates exclusion constraint "reservation_during_excl"
|
2013-09-05 08:30:27 +02:00
|
|
|
DETAIL: Key (during)=(["2010-01-01 14:45:00","2010-01-01 15:45:00")) conflicts
|
|
|
|
with existing key (during)=(["2010-01-01 11:30:00","2010-01-01 15:00:00")).
|
2011-11-03 12:16:28 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
You can use the <link linkend="btree-gist"><literal>btree_gist</literal></link>
|
2012-06-07 23:06:20 +02:00
|
|
|
extension to define exclusion constraints on plain scalar data types, which
|
2011-11-19 00:23:55 +01:00
|
|
|
can then be combined with range exclusions for maximum flexibility. For
|
|
|
|
example, after <literal>btree_gist</literal> is installed, the following
|
|
|
|
constraint will reject overlapping ranges only if the meeting room numbers
|
|
|
|
are equal:
|
2011-11-03 12:16:28 +01:00
|
|
|
|
2011-11-19 00:23:55 +01:00
|
|
|
<programlisting>
|
2013-09-05 08:30:27 +02:00
|
|
|
CREATE EXTENSION btree_gist;
|
2012-06-08 09:28:32 +02:00
|
|
|
CREATE TABLE room_reservation (
|
|
|
|
room text,
|
|
|
|
during tsrange,
|
2015-05-15 17:42:29 +02:00
|
|
|
EXCLUDE USING GIST (room WITH =, during WITH &&)
|
2011-11-03 12:16:28 +01:00
|
|
|
);
|
|
|
|
|
|
|
|
INSERT INTO room_reservation VALUES
|
2012-06-08 09:28:32 +02:00
|
|
|
('123A', '[2010-01-01 14:00, 2010-01-01 15:00)');
|
2011-11-19 00:23:55 +01:00
|
|
|
INSERT 0 1
|
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
INSERT INTO room_reservation VALUES
|
2012-06-08 09:28:32 +02:00
|
|
|
('123A', '[2010-01-01 14:30, 2010-01-01 15:30)');
|
2011-11-19 00:23:55 +01:00
|
|
|
ERROR: conflicting key value violates exclusion constraint "room_reservation_room_during_excl"
|
2013-09-05 08:30:27 +02:00
|
|
|
DETAIL: Key (room, during)=(123A, ["2010-01-01 14:30:00","2010-01-01 15:30:00")) conflicts
|
|
|
|
with existing key (room, during)=(123A, ["2010-01-01 14:00:00","2010-01-01 15:00:00")).
|
2011-11-19 00:23:55 +01:00
|
|
|
|
2011-11-03 12:16:28 +01:00
|
|
|
INSERT INTO room_reservation VALUES
|
2012-06-08 09:28:32 +02:00
|
|
|
('123B', '[2010-01-01 14:30, 2010-01-01 15:30)');
|
2011-11-19 00:23:55 +01:00
|
|
|
INSERT 0 1
|
2011-11-03 12:16:28 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|