mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-15 21:00:20 +02:00
3c49c6facb
Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
398 lines
13 KiB
Plaintext
398 lines
13 KiB
Plaintext
<!-- doc/src/sgml/seg.sgml -->
|
|
|
|
<sect1 id="seg" xreflabel="seg">
|
|
<title>seg</title>
|
|
|
|
<indexterm zone="seg">
|
|
<primary>seg</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
This module implements a data type <type>seg</type> for
|
|
representing line segments, or floating point intervals.
|
|
<type>seg</type> can represent uncertainty in the interval endpoints,
|
|
making it especially useful for representing laboratory measurements.
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>Rationale</title>
|
|
|
|
<para>
|
|
The geometry of measurements is usually more complex than that of a
|
|
point in a numeric continuum. A measurement is usually a segment of
|
|
that continuum with somewhat fuzzy limits. The measurements come out
|
|
as intervals because of uncertainty and randomness, as well as because
|
|
the value being measured may naturally be an interval indicating some
|
|
condition, such as the temperature range of stability of a protein.
|
|
</para>
|
|
|
|
<para>
|
|
Using just common sense, it appears more convenient to store such data
|
|
as intervals, rather than pairs of numbers. In practice, it even turns
|
|
out more efficient in most applications.
|
|
</para>
|
|
|
|
<para>
|
|
Further along the line of common sense, the fuzziness of the limits
|
|
suggests that the use of traditional numeric data types leads to a
|
|
certain loss of information. Consider this: your instrument reads
|
|
6.50, and you input this reading into the database. What do you get
|
|
when you fetch it? Watch:
|
|
|
|
<screen>
|
|
test=> select 6.50 :: float8 as "pH";
|
|
pH
|
|
---
|
|
6.5
|
|
(1 row)
|
|
</screen>
|
|
|
|
In the world of measurements, 6.50 is not the same as 6.5. It may
|
|
sometimes be critically different. The experimenters usually write
|
|
down (and publish) the digits they trust. 6.50 is actually a fuzzy
|
|
interval contained within a bigger and even fuzzier interval, 6.5,
|
|
with their center points being (probably) the only common feature they
|
|
share. We definitely do not want such different data items to appear the
|
|
same.
|
|
</para>
|
|
|
|
<para>
|
|
Conclusion? It is nice to have a special data type that can record the
|
|
limits of an interval with arbitrarily variable precision. Variable in
|
|
the sense that each data element records its own precision.
|
|
</para>
|
|
|
|
<para>
|
|
Check this out:
|
|
|
|
<screen>
|
|
test=> select '6.25 .. 6.50'::seg as "pH";
|
|
pH
|
|
------------
|
|
6.25 .. 6.50
|
|
(1 row)
|
|
</screen>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Syntax</title>
|
|
|
|
<para>
|
|
The external representation of an interval is formed using one or two
|
|
floating-point numbers joined by the range operator (<literal>..</literal>
|
|
or <literal>...</literal>). Alternatively, it can be specified as a
|
|
center point plus or minus a deviation.
|
|
Optional certainty indicators (<literal><</literal>,
|
|
<literal>></literal> or <literal>~</literal>) can be stored as well.
|
|
(Certainty indicators are ignored by all the built-in operators, however.)
|
|
<xref linkend="seg-repr-table"/> gives an overview of allowed
|
|
representations; <xref linkend="seg-input-examples"/> shows some
|
|
examples.
|
|
</para>
|
|
|
|
<para>
|
|
In <xref linkend="seg-repr-table"/>, <replaceable>x</replaceable>, <replaceable>y</replaceable>, and
|
|
<replaceable>delta</replaceable> denote
|
|
floating-point numbers. <replaceable>x</replaceable> and <replaceable>y</replaceable>, but
|
|
not <replaceable>delta</replaceable>, can be preceded by a certainty indicator.
|
|
</para>
|
|
|
|
<table id="seg-repr-table">
|
|
<title><type>seg</type> External Representations</title>
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry><literal><replaceable>x</replaceable></literal></entry>
|
|
<entry>Single value (zero-length interval)
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal><replaceable>x</replaceable> .. <replaceable>y</replaceable></literal></entry>
|
|
<entry>Interval from <replaceable>x</replaceable> to <replaceable>y</replaceable>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal><replaceable>x</replaceable> (+-) <replaceable>delta</replaceable></literal></entry>
|
|
<entry>Interval from <replaceable>x</replaceable> - <replaceable>delta</replaceable> to
|
|
<replaceable>x</replaceable> + <replaceable>delta</replaceable>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal><replaceable>x</replaceable> ..</literal></entry>
|
|
<entry>Open interval with lower bound <replaceable>x</replaceable>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>.. <replaceable>x</replaceable></literal></entry>
|
|
<entry>Open interval with upper bound <replaceable>x</replaceable>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<table id="seg-input-examples">
|
|
<title>Examples of Valid <type>seg</type> Input</title>
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>5.0</literal></entry>
|
|
<entry>
|
|
Creates a zero-length segment (a point, if you will)
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>~5.0</literal></entry>
|
|
<entry>
|
|
Creates a zero-length segment and records
|
|
<literal>~</literal> in the data. <literal>~</literal> is ignored
|
|
by <type>seg</type> operations, but
|
|
is preserved as a comment.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal><5.0</literal></entry>
|
|
<entry>
|
|
Creates a point at 5.0. <literal><</literal> is ignored but
|
|
is preserved as a comment.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>>5.0</literal></entry>
|
|
<entry>
|
|
Creates a point at 5.0. <literal>></literal> is ignored but
|
|
is preserved as a comment.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>5(+-)0.3</literal></entry>
|
|
<entry>
|
|
Creates an interval <literal>4.7 .. 5.3</literal>.
|
|
Note that the <literal>(+-)</literal> notation isn't preserved.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>50 .. </literal></entry>
|
|
<entry>Everything that is greater than or equal to 50</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>.. 0</literal></entry>
|
|
<entry>Everything that is less than or equal to 0</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>1.5e-2 .. 2E-2 </literal></entry>
|
|
<entry>Creates an interval <literal>0.015 .. 0.02</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>1 ... 2</literal></entry>
|
|
<entry>
|
|
The same as <literal>1...2</literal>, or <literal>1 .. 2</literal>,
|
|
or <literal>1..2</literal>
|
|
(spaces around the range operator are ignored)
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<para>
|
|
Because <literal>...</literal> is widely used in data sources, it is allowed
|
|
as an alternative spelling of <literal>..</literal>. Unfortunately, this
|
|
creates a parsing ambiguity: it is not clear whether the upper bound
|
|
in <literal>0...23</literal> is meant to be <literal>23</literal> or <literal>0.23</literal>.
|
|
This is resolved by requiring at least one digit before the decimal
|
|
point in all numbers in <type>seg</type> input.
|
|
</para>
|
|
|
|
<para>
|
|
As a sanity check, <type>seg</type> rejects intervals with the lower bound
|
|
greater than the upper, for example <literal>5 .. 2</literal>.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Precision</title>
|
|
|
|
<para>
|
|
<type>seg</type> values are stored internally as pairs of 32-bit floating point
|
|
numbers. This means that numbers with more than 7 significant digits
|
|
will be truncated.
|
|
</para>
|
|
|
|
<para>
|
|
Numbers with 7 or fewer significant digits retain their
|
|
original precision. That is, if your query returns 0.00, you will be
|
|
sure that the trailing zeroes are not the artifacts of formatting: they
|
|
reflect the precision of the original data. The number of leading
|
|
zeroes does not affect precision: the value 0.0067 is considered to
|
|
have just 2 significant digits.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Usage</title>
|
|
|
|
<para>
|
|
The <filename>seg</filename> module includes a GiST index operator class for
|
|
<type>seg</type> values.
|
|
The operators supported by the GiST operator class are shown in <xref linkend="seg-gist-operators"/>.
|
|
</para>
|
|
|
|
<table id="seg-gist-operators">
|
|
<title>Seg GiST Operators</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Operator</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>[a, b] << [c, d]</literal></entry>
|
|
<entry>[a, b] is entirely to the left of [c, d]. That is, [a,
|
|
b] << [c, d] is true if b < c and false otherwise.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>[a, b] >> [c, d]</literal></entry>
|
|
<entry>[a, b] is entirely to the right of [c, d]. That is, [a,
|
|
b] >> [c, d] is true if a > d and false otherwise.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>[a, b] &< [c, d]</literal></entry>
|
|
<entry>Overlaps or is left of — This might be better read
|
|
as <quote>does not extend to right of</quote>. It is true when
|
|
b <= d.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>[a, b] &> [c, d]</literal></entry>
|
|
<entry>Overlaps or is right of — This might be better read
|
|
as <quote>does not extend to left of</quote>. It is true when
|
|
a >= c.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>[a, b] = [c, d]</literal></entry>
|
|
<entry>Same as — The segments [a, b] and [c, d] are
|
|
identical, that is, a = c and b = d.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>[a, b] && [c, d]</literal></entry>
|
|
<entry>The segments [a, b] and [c, d] overlap.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>[a, b] @> [c, d]</literal></entry>
|
|
<entry>The segment [a, b] contains the segment [c, d], that is,
|
|
a <= c and b >= d.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>[a, b] <@ [c, d]</literal></entry>
|
|
<entry>The segment [a, b] is contained in [c, d], that is, a
|
|
>= c and b <= d.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<para>
|
|
(Before PostgreSQL 8.2, the containment operators <literal>@></literal> and <literal><@</literal> were
|
|
respectively called <literal>@</literal> and <literal>~</literal>. These names are still available, but are
|
|
deprecated and will eventually be retired. Notice that the old names
|
|
are reversed from the convention formerly followed by the core geometric
|
|
data types!)
|
|
</para>
|
|
|
|
<para>
|
|
The standard B-tree operators are also provided, for example
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Operator</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>[a, b] < [c, d]</literal></entry>
|
|
<entry>Less than</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>[a, b] > [c, d]</literal></entry>
|
|
<entry>Greater than</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
These operators do not make a lot of sense for any practical
|
|
purpose but sorting. These operators first compare (a) to (c),
|
|
and if these are equal, compare (b) to (d). That results in
|
|
reasonably good sorting in most cases, which is useful if
|
|
you want to use ORDER BY with this type.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
For examples of usage, see the regression test <filename>sql/seg.sql</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
The mechanism that converts <literal>(+-)</literal> to regular ranges
|
|
isn't completely accurate in determining the number of significant digits
|
|
for the boundaries. For example, it adds an extra digit to the lower
|
|
boundary if the resulting interval includes a power of ten:
|
|
|
|
<screen>
|
|
postgres=> select '10(+-)1'::seg as seg;
|
|
seg
|
|
---------
|
|
9.0 .. 11 -- should be: 9 .. 11
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
The performance of an R-tree index can largely depend on the initial
|
|
order of input values. It may be very helpful to sort the input table
|
|
on the <type>seg</type> column; see the script <filename>sort-segments.pl</filename>
|
|
for an example.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Credits</title>
|
|
|
|
<para>
|
|
Original author: Gene Selkov, Jr. <email>selkovjr@mcs.anl.gov</email>,
|
|
Mathematics and Computer Science Division, Argonne National Laboratory.
|
|
</para>
|
|
|
|
<para>
|
|
My thanks are primarily to Prof. Joe Hellerstein
|
|
(<ulink url="http://db.cs.berkeley.edu/jmh/"></ulink>) for elucidating the
|
|
gist of the GiST (<ulink url="http://gist.cs.berkeley.edu/"></ulink>). I am
|
|
also grateful to all Postgres developers, present and past, for enabling
|
|
myself to create my own world and live undisturbed in it. And I would like
|
|
to acknowledge my gratitude to Argonne Lab and to the U.S. Department of
|
|
Energy for the years of faithful support of my database research.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|