begriffs open source - ai-pg/blob - full-docs/html/seg.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.39. seg — a datatype for line segments or floating point intervals</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="postgres-fdw.html" title="F.38. postgres_fdw — access data stored in external PostgreSQL servers" /><link rel="next" href="sepgsql.html" title="F.40. sepgsql — SELinux-, label-based mandatory access control (MAC) security module" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.39. seg — a datatype for line segments or floating point intervals</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="postgres-fdw.html" title="F.38. postgres_fdw —&#10;   access data stored in external PostgreSQL&#10;   servers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules and Extensions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sepgsql.html" title="F.40. sepgsql —&#10;   SELinux-, label-based mandatory access control (MAC) security module">Next</a></td></tr></table><hr /></div><div class="sect1" id="SEG"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.39. seg — a datatype for line segments or floating point intervals <a href="#SEG" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="seg.html#SEG-RATIONALE">F.39.1. Rationale</a></span></dt><dt><span class="sect2"><a href="seg.html#SEG-SYNTAX">F.39.2. Syntax</a></span></dt><dt><span class="sect2"><a href="seg.html#SEG-PRECISION">F.39.3. Precision</a></span></dt><dt><span class="sect2"><a href="seg.html#SEG-USAGE">F.39.4. Usage</a></span></dt><dt><span class="sect2"><a href="seg.html#SEG-NOTES">F.39.5. Notes</a></span></dt><dt><span class="sect2"><a href="seg.html#SEG-CREDITS">F.39.6. Credits</a></span></dt></dl></div><a id="id-1.11.7.49.2" class="indexterm"></a><p>
   3   This module implements a data type <code class="type">seg</code> for
   4   representing line segments, or floating point intervals.
   5   <code class="type">seg</code> can represent uncertainty in the interval endpoints,
   6   making it especially useful for representing laboratory measurements.
   7  </p><p>
   8   This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
   9   installed by non-superusers who have <code class="literal">CREATE</code> privilege
  10   on the current database.
  11  </p><div class="sect2" id="SEG-RATIONALE"><div class="titlepage"><div><div><h3 class="title">F.39.1. Rationale <a href="#SEG-RATIONALE" class="id_link">#</a></h3></div></div></div><p>
  12    The geometry of measurements is usually more complex than that of a
  13    point in a numeric continuum. A measurement is usually a segment of
  14    that continuum with somewhat fuzzy limits. The measurements come out
  15    as intervals because of uncertainty and randomness, as well as because
  16    the value being measured may naturally be an interval indicating some
  17    condition, such as the temperature range of stability of a protein.
  18   </p><p>
  19    Using just common sense, it appears more convenient to store such data
  20    as intervals, rather than pairs of numbers. In practice, it even turns
  21    out more efficient in most applications.
  22   </p><p>
  23    Further along the line of common sense, the fuzziness of the limits
  24    suggests that the use of traditional numeric data types leads to a
  25    certain loss of information. Consider this: your instrument reads
  26    6.50, and you input this reading into the database. What do you get
  27    when you fetch it? Watch:
  28
  29 </p><pre class="screen">
  30 test=&gt; select 6.50 :: float8 as "pH";
  31  pH
  32 ---
  33 6.5
  34 (1 row)
  35 </pre><p>
  36
  37    In the world of measurements, 6.50 is not the same as 6.5. It may
  38    sometimes be critically different. The experimenters usually write
  39    down (and publish) the digits they trust. 6.50 is actually a fuzzy
  40    interval contained within a bigger and even fuzzier interval, 6.5,
  41    with their center points being (probably) the only common feature they
  42    share. We definitely do not want such different data items to appear the
  43    same.
  44   </p><p>
  45    Conclusion? It is nice to have a special data type that can record the
  46    limits of an interval with arbitrarily variable precision. Variable in
  47    the sense that each data element records its own precision.
  48   </p><p>
  49    Check this out:
  50
  51 </p><pre class="screen">
  52 test=&gt; select '6.25 .. 6.50'::seg as "pH";
  53           pH
  54 ------------
  55 6.25 .. 6.50
  56 (1 row)
  57 </pre><p>
  58   </p></div><div class="sect2" id="SEG-SYNTAX"><div class="titlepage"><div><div><h3 class="title">F.39.2. Syntax <a href="#SEG-SYNTAX" class="id_link">#</a></h3></div></div></div><p>
  59    The external representation of an interval is formed using one or two
  60    floating-point numbers joined by the range operator (<code class="literal">..</code>
  61    or <code class="literal">...</code>).  Alternatively, it can be specified as a
  62    center point plus or minus a deviation.
  63    Optional certainty indicators (<code class="literal">&lt;</code>,
  64    <code class="literal">&gt;</code> or <code class="literal">~</code>) can be stored as well.
  65    (Certainty indicators are ignored by all the built-in operators, however.)
  66    <a class="xref" href="seg.html#SEG-REPR-TABLE" title="Table F.29. seg External Representations">Table F.29</a> gives an overview of allowed
  67    representations; <a class="xref" href="seg.html#SEG-INPUT-EXAMPLES" title="Table F.30. Examples of Valid seg Input">Table F.30</a> shows some
  68    examples.
  69   </p><p>
  70    In <a class="xref" href="seg.html#SEG-REPR-TABLE" title="Table F.29. seg External Representations">Table F.29</a>, <em class="replaceable"><code>x</code></em>, <em class="replaceable"><code>y</code></em>, and
  71    <em class="replaceable"><code>delta</code></em> denote
  72    floating-point numbers.  <em class="replaceable"><code>x</code></em> and <em class="replaceable"><code>y</code></em>, but
  73    not <em class="replaceable"><code>delta</code></em>, can be preceded by a certainty indicator.
  74   </p><div class="table" id="SEG-REPR-TABLE"><p class="title"><strong>Table F.29. <code class="type">seg</code> External Representations</strong></p><div class="table-contents"><table class="table" summary="seg External Representations" border="1"><colgroup><col /><col /></colgroup><tbody><tr><td><code class="literal"><em class="replaceable"><code>x</code></em></code></td><td>Single value (zero-length interval)
  75       </td></tr><tr><td><code class="literal"><em class="replaceable"><code>x</code></em> .. <em class="replaceable"><code>y</code></em></code></td><td>Interval from <em class="replaceable"><code>x</code></em> to <em class="replaceable"><code>y</code></em>
  76       </td></tr><tr><td><code class="literal"><em class="replaceable"><code>x</code></em> (+-) <em class="replaceable"><code>delta</code></em></code></td><td>Interval from <em class="replaceable"><code>x</code></em> - <em class="replaceable"><code>delta</code></em> to
  77       <em class="replaceable"><code>x</code></em> + <em class="replaceable"><code>delta</code></em>
  78       </td></tr><tr><td><code class="literal"><em class="replaceable"><code>x</code></em> ..</code></td><td>Open interval with lower bound <em class="replaceable"><code>x</code></em>
  79       </td></tr><tr><td><code class="literal">.. <em class="replaceable"><code>x</code></em></code></td><td>Open interval with upper bound <em class="replaceable"><code>x</code></em>
  80       </td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="SEG-INPUT-EXAMPLES"><p class="title"><strong>Table F.30. Examples of Valid <code class="type">seg</code> Input</strong></p><div class="table-contents"><table class="table" summary="Examples of Valid seg Input" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><tbody><tr><td><code class="literal">5.0</code></td><td>
  81        Creates a zero-length segment (a point, if you will)
  82       </td></tr><tr><td><code class="literal">~5.0</code></td><td>
  83        Creates a zero-length segment and records
  84        <code class="literal">~</code> in the data.  <code class="literal">~</code> is ignored
  85        by <code class="type">seg</code> operations, but
  86        is preserved as a comment.
  87       </td></tr><tr><td><code class="literal">&lt;5.0</code></td><td>
  88        Creates a point at 5.0.  <code class="literal">&lt;</code> is ignored but
  89        is preserved as a comment.
  90       </td></tr><tr><td><code class="literal">&gt;5.0</code></td><td>
  91        Creates a point at 5.0.  <code class="literal">&gt;</code> is ignored but
  92        is preserved as a comment.
  93       </td></tr><tr><td><code class="literal">5(+-)0.3</code></td><td>
  94         Creates an interval <code class="literal">4.7 .. 5.3</code>.
  95         Note that the <code class="literal">(+-)</code> notation isn't preserved.
  96       </td></tr><tr><td><code class="literal">50 .. </code></td><td>Everything that is greater than or equal to 50</td></tr><tr><td><code class="literal">.. 0</code></td><td>Everything that is less than or equal to 0</td></tr><tr><td><code class="literal">1.5e-2 .. 2E-2 </code></td><td>Creates an interval <code class="literal">0.015 .. 0.02</code></td></tr><tr><td><code class="literal">1 ... 2</code></td><td>
  97        The same as <code class="literal">1...2</code>, or <code class="literal">1 .. 2</code>,
  98        or <code class="literal">1..2</code>
  99        (spaces around the range operator are ignored)
 100       </td></tr></tbody></table></div></div><br class="table-break" /><p>
 101    Because the <code class="literal">...</code> operator is widely used in data sources, it is allowed
 102    as an alternative spelling of the <code class="literal">..</code> operator.  Unfortunately, this
 103    creates a parsing ambiguity: it is not clear whether the upper bound
 104    in <code class="literal">0...23</code> is meant to be <code class="literal">23</code> or <code class="literal">0.23</code>.
 105    This is resolved by requiring at least one digit before the decimal
 106    point in all numbers in <code class="type">seg</code> input.
 107   </p><p>
 108    As a sanity check, <code class="type">seg</code> rejects intervals with the lower bound
 109    greater than the upper, for example <code class="literal">5 .. 2</code>.
 110   </p></div><div class="sect2" id="SEG-PRECISION"><div class="titlepage"><div><div><h3 class="title">F.39.3. Precision <a href="#SEG-PRECISION" class="id_link">#</a></h3></div></div></div><p>
 111    <code class="type">seg</code> values are stored internally as pairs of 32-bit floating point
 112    numbers. This means that numbers with more than 7 significant digits
 113    will be truncated.
 114   </p><p>
 115    Numbers with 7 or fewer significant digits retain their
 116    original precision. That is, if your query returns 0.00, you will be
 117    sure that the trailing zeroes are not the artifacts of formatting: they
 118    reflect the precision of the original data. The number of leading
 119    zeroes does not affect precision: the value 0.0067 is considered to
 120    have just 2 significant digits.
 121   </p></div><div class="sect2" id="SEG-USAGE"><div class="titlepage"><div><div><h3 class="title">F.39.4. Usage <a href="#SEG-USAGE" class="id_link">#</a></h3></div></div></div><p>
 122    The <code class="filename">seg</code> module includes a GiST index operator class for
 123    <code class="type">seg</code> values.
 124    The operators supported by the GiST operator class are shown in <a class="xref" href="seg.html#SEG-GIST-OPERATORS" title="Table F.31. Seg GiST Operators">Table F.31</a>.
 125   </p><div class="table" id="SEG-GIST-OPERATORS"><p class="title"><strong>Table F.31. Seg GiST Operators</strong></p><div class="table-contents"><table class="table" summary="Seg GiST Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
 126         Operator
 127        </p>
 128        <p>
 129         Description
 130        </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
 131         <code class="type">seg</code> <code class="literal">&lt;&lt;</code> <code class="type">seg</code>
 132         → <code class="returnvalue">boolean</code>
 133        </p>
 134        <p>
 135         Is the first <code class="type">seg</code> entirely to the left of the second?
 136         [a, b] &lt;&lt; [c, d] is true if b &lt; c.
 137        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 138         <code class="type">seg</code> <code class="literal">&gt;&gt;</code> <code class="type">seg</code>
 139         → <code class="returnvalue">boolean</code>
 140        </p>
 141        <p>
 142         Is the first <code class="type">seg</code> entirely to the right of the second?
 143         [a, b] &gt;&gt; [c, d] is true if a &gt; d.
 144        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 145         <code class="type">seg</code> <code class="literal">&amp;&lt;</code> <code class="type">seg</code>
 146         → <code class="returnvalue">boolean</code>
 147        </p>
 148        <p>
 149         Does the first <code class="type">seg</code> not extend to the right of the
 150         second?
 151         [a, b] &amp;&lt; [c, d] is true if b &lt;= d.
 152        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 153         <code class="type">seg</code> <code class="literal">&amp;&gt;</code> <code class="type">seg</code>
 154         → <code class="returnvalue">boolean</code>
 155        </p>
 156        <p>
 157         Does the first <code class="type">seg</code> not extend to the left of the
 158         second?
 159         [a, b] &amp;&gt; [c, d] is true if a &gt;= c.
 160        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 161         <code class="type">seg</code> <code class="literal">=</code> <code class="type">seg</code>
 162         → <code class="returnvalue">boolean</code>
 163        </p>
 164        <p>
 165         Are the two <code class="type">seg</code>s equal?
 166        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 167         <code class="type">seg</code> <code class="literal">&amp;&amp;</code> <code class="type">seg</code>
 168         → <code class="returnvalue">boolean</code>
 169        </p>
 170        <p>
 171         Do the two <code class="type">seg</code>s overlap?
 172        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 173         <code class="type">seg</code> <code class="literal">@&gt;</code> <code class="type">seg</code>
 174         → <code class="returnvalue">boolean</code>
 175        </p>
 176        <p>
 177         Does the first <code class="type">seg</code> contain the second?
 178        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 179         <code class="type">seg</code> <code class="literal">&lt;@</code> <code class="type">seg</code>
 180         → <code class="returnvalue">boolean</code>
 181        </p>
 182        <p>
 183         Is the first <code class="type">seg</code> contained in the second?
 184        </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
 185    In addition to the above operators, the usual comparison
 186    operators shown in <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a> are
 187    available for type <code class="type">seg</code>.  These operators
 188    first compare (a) to (c),
 189    and if these are equal, compare (b) to (d). That results in
 190    reasonably good sorting in most cases, which is useful if
 191    you want to use ORDER BY with this type.
 192   </p></div><div class="sect2" id="SEG-NOTES"><div class="titlepage"><div><div><h3 class="title">F.39.5. Notes <a href="#SEG-NOTES" class="id_link">#</a></h3></div></div></div><p>
 193    For examples of usage, see the regression test <code class="filename">sql/seg.sql</code>.
 194   </p><p>
 195    The mechanism that converts <code class="literal">(+-)</code> to regular ranges
 196    isn't completely accurate in determining the number of significant digits
 197    for the boundaries.  For example, it adds an extra digit to the lower
 198    boundary if the resulting interval includes a power of ten:
 199
 200 </p><pre class="screen">
 201 postgres=&gt; select '10(+-)1'::seg as seg;
 202       seg
 203 ---------
 204 9.0 .. 11             -- should be: 9 .. 11
 205 </pre><p>
 206   </p><p>
 207    The performance of an R-tree index can largely depend on the initial
 208    order of input values. It may be very helpful to sort the input table
 209    on the <code class="type">seg</code> column; see the script <code class="filename">sort-segments.pl</code>
 210    for an example.
 211   </p></div><div class="sect2" id="SEG-CREDITS"><div class="titlepage"><div><div><h3 class="title">F.39.6. Credits <a href="#SEG-CREDITS" class="id_link">#</a></h3></div></div></div><p>
 212    Original author: Gene Selkov, Jr. <code class="email">&lt;<a class="email" href="mailto:selkovjr@mcs.anl.gov">selkovjr@mcs.anl.gov</a>&gt;</code>,
 213    Mathematics and Computer Science Division, Argonne National Laboratory.
 214   </p><p>
 215    My thanks are primarily to Prof. Joe Hellerstein
 216    (<a class="ulink" href="https://dsf.berkeley.edu/jmh/" target="_top">https://dsf.berkeley.edu/jmh/</a>) for elucidating the
 217    gist of the GiST (<a class="ulink" href="http://gist.cs.berkeley.edu/" target="_top">http://gist.cs.berkeley.edu/</a>). I am
 218    also grateful to all Postgres developers, present and past, for enabling
 219    myself to create my own world and live undisturbed in it. And I would like
 220    to acknowledge my gratitude to Argonne Lab and to the U.S. Department of
 221    Energy for the years of faithful support of my database research.
 222   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="postgres-fdw.html" title="F.38. postgres_fdw —&#10;   access data stored in external PostgreSQL&#10;   servers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sepgsql.html" title="F.40. sepgsql —&#10;   SELinux-, label-based mandatory access control (MAC) security module">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.38. postgres_fdw —
 223    access data stored in external <span class="productname">PostgreSQL</span>
 224    servers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.40. sepgsql —
 225    SELinux-, label-based mandatory access control (MAC) security module</td></tr></table></div></body></html>