performance_tips.xml \
postgis.xml \
reference_accessor.xml \
+ reference_bbox.xml \
reference_constructor.xml \
reference_editor.xml \
reference_guc.xml \
reference_management.xml \
reference_measure.xml \
reference_sfcgal.xml \
- reference_misc.xml \
reference_operator.xml \
reference_output.xml \
reference_processing.xml \
reference_raster.xml \
- reference_temporal.xml \
+ reference_trajectory.xml \
reference_transaction.xml \
reference_troubleshooting.xml \
reference_type.xml \
<!ENTITY reference_management SYSTEM "reference_management.xml">
<!ENTITY reference_constructor SYSTEM "reference_constructor.xml">
<!ENTITY reference_accessor SYSTEM "reference_accessor.xml">
+<!ENTITY reference_bbox SYSTEM "reference_bbox.xml">
<!ENTITY reference_editor SYSTEM "reference_editor.xml">
<!ENTITY reference_output SYSTEM "reference_output.xml">
<!ENTITY reference_operator SYSTEM "reference_operator.xml">
<!ENTITY reference_sfcgal SYSTEM "reference_sfcgal.xml">
<!ENTITY reference_processing SYSTEM "reference_processing.xml">
<!ENTITY reference_lrs SYSTEM "reference_lrs.xml">
-<!ENTITY reference_temporal SYSTEM "reference_temporal.xml">
+<!ENTITY reference_trajectory SYSTEM "reference_trajectory.xml">
<!ENTITY reference_transaction SYSTEM "reference_transaction.xml">
<!ENTITY reference_misc SYSTEM "reference_misc.xml">
<!ENTITY reference_troubleshooting SYSTEM "reference_troubleshooting.xml">
&reference_output;
&reference_operator;
&reference_measure;
- &reference_sfcgal;
&reference_processing;
+ &reference_bbox;
&reference_lrs;
- &reference_temporal;
+ &reference_trajectory;
+ &reference_sfcgal;
&reference_transaction;
- &reference_misc;
+ <!-- &reference_misc; -->
&reference_version;
&reference_guc;
&reference_troubleshooting;
</refsection>
</refentry>
- <refentry id="ST_XMax">
- <refnamediv>
- <refname>ST_XMax</refname>
-
- <refpurpose>Returns X maxima of a bounding box 2d or 3d or a geometry.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float <function>ST_XMax</function></funcdef>
- <paramdef><type>box3d </type> <parameter>aGeomorBox2DorBox3D</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns X maxima of a bounding box 2d or 3d or a geometry.</para>
-
- <note>
- <para>Although this function is only defined for box3d, it will work for box2d and geometry because of the auto-casting behavior
- defined for geometries and box2d. However you can not feed it a geometry or box2d text representation, since that will not auto-cast.</para>
- </note>
-
- <para>&Z_support;</para>
- <para>&curve_support;</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT ST_XMax('BOX3D(1 2 3, 4 5 6)');
-st_xmax
--------
-4
-
-SELECT ST_XMax(ST_GeomFromText('LINESTRING(1 3 4, 5 6 7)'));
-st_xmax
--------
-5
-
-SELECT ST_XMax(CAST('BOX(-3 2, 3 4)' As box2d));
-st_xmax
--------
-3
---Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
-SELECT ST_XMax('LINESTRING(1 3, 5 6)');
-
---ERROR: BOX3D parser - doesn't start with BOX3D(
-
-SELECT ST_XMax(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
-st_xmax
---------
-220288.248780547
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_XMin" />, <xref linkend="ST_YMax" />, <xref linkend="ST_YMin" />, <xref linkend="ST_ZMax" />, <xref linkend="ST_ZMin" /></para>
- </refsection>
- </refentry>
-
- <refentry id="ST_XMin">
- <refnamediv>
- <refname>ST_XMin</refname>
-
- <refpurpose>Returns X minima of a bounding box 2d or 3d or a geometry.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float <function>ST_XMin</function></funcdef>
- <paramdef><type>box3d </type> <parameter>aGeomorBox2DorBox3D</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns X minima of a bounding box 2d or 3d or a geometry.</para>
-
- <note>
- <para>Although this function is only defined for box3d, it will work for box2d and geometry because of the auto-casting behavior
- defined for geometries and box2d. However you can not feed it a geometry or box2d text representation, since that will not auto-cast.</para>
- </note>
-
- <para>&Z_support;</para>
- <para>&curve_support;</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT ST_XMin('BOX3D(1 2 3, 4 5 6)');
-st_xmin
--------
-1
-
-SELECT ST_XMin(ST_GeomFromText('LINESTRING(1 3 4, 5 6 7)'));
-st_xmin
--------
-1
-
-SELECT ST_XMin(CAST('BOX(-3 2, 3 4)' As box2d));
-st_xmin
--------
--3
---Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
-SELECT ST_XMin('LINESTRING(1 3, 5 6)');
-
---ERROR: BOX3D parser - doesn't start with BOX3D(
-
-SELECT ST_XMin(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
-st_xmin
---------
-220186.995121892
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_XMax" />, <xref linkend="ST_YMax" />, <xref linkend="ST_YMin" />, <xref linkend="ST_ZMax" />, <xref linkend="ST_ZMin" /></para>
- </refsection>
- </refentry>
-
<refentry id="ST_Y">
<refnamediv>
<refname>ST_Y</refname>
</refsection>
</refentry>
- <refentry id="ST_YMax">
- <refnamediv>
- <refname>ST_YMax</refname>
-
- <refpurpose>Returns Y maxima of a bounding box 2d or 3d or a geometry.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float <function>ST_YMax</function></funcdef>
- <paramdef><type>box3d </type> <parameter>aGeomorBox2DorBox3D</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns Y maxima of a bounding box 2d or 3d or a geometry.</para>
-
- <note>
- <para>Although this function is only defined for box3d, it will work for box2d and geometry because of the auto-casting behavior
- defined for geometries and box2d. However you can not feed it a geometry or box2d text representation, since that will not auto-cast.</para>
- </note>
-
- <para>&Z_support;</para>
- <para>&curve_support;</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT ST_YMax('BOX3D(1 2 3, 4 5 6)');
-st_ymax
--------
-5
-
-SELECT ST_YMax(ST_GeomFromText('LINESTRING(1 3 4, 5 6 7)'));
-st_ymax
--------
-6
-
-SELECT ST_YMax(CAST('BOX(-3 2, 3 4)' As box2d));
-st_ymax
--------
-4
---Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
-SELECT ST_YMax('LINESTRING(1 3, 5 6)');
-
---ERROR: BOX3D parser - doesn't start with BOX3D(
-
-SELECT ST_YMax(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
-st_ymax
---------
-150506.126829327
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_XMin" />, <xref linkend="ST_XMax" />, <xref linkend="ST_YMin" />, <xref linkend="ST_ZMax" />, <xref linkend="ST_ZMin" /></para>
- </refsection>
- </refentry>
-
- <refentry id="ST_YMin">
- <refnamediv>
- <refname>ST_YMin</refname>
-
- <refpurpose>Returns Y minima of a bounding box 2d or 3d or a geometry.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float <function>ST_YMin</function></funcdef>
- <paramdef><type>box3d </type> <parameter>aGeomorBox2DorBox3D</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns Y minima of a bounding box 2d or 3d or a geometry.</para>
-
- <note>
- <para>Although this function is only defined for box3d, it will work for box2d and geometry because of the auto-casting behavior
- defined for geometries and box2d. However you can not feed it a geometry or box2d text representation, since that will not auto-cast.</para>
- </note>
-
- <para>&Z_support;</para>
- <para>&curve_support;</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT ST_YMin('BOX3D(1 2 3, 4 5 6)');
-st_ymin
--------
-2
-
-SELECT ST_YMin(ST_GeomFromText('LINESTRING(1 3 4, 5 6 7)'));
-st_ymin
--------
-3
-
-SELECT ST_YMin(CAST('BOX(-3 2, 3 4)' As box2d));
-st_ymin
--------
-2
---Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
-SELECT ST_YMin('LINESTRING(1 3, 5 6)');
-
---ERROR: BOX3D parser - doesn't start with BOX3D(
-
-SELECT ST_YMin(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
-st_ymin
---------
-150406
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_XMin" />, <xref linkend="ST_XMax" />, <xref linkend="ST_YMax" />, <xref linkend="ST_ZMax" />, <xref linkend="ST_ZMin" /></para>
- </refsection>
- </refentry>
-
<refentry id="ST_Z">
<refnamediv>
<refname>ST_Z</refname>
</refsection>
</refentry>
- <refentry id="ST_ZMax">
- <refnamediv>
- <refname>ST_ZMax</refname>
-
- <refpurpose>Returns Z minima of a bounding box 2d or 3d or a geometry.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float <function>ST_ZMax</function></funcdef>
- <paramdef><type>box3d </type> <parameter>aGeomorBox2DorBox3D</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns Z maxima of a bounding box 2d or 3d or a geometry.</para>
-
- <note>
- <para>Although this function is only defined for box3d, it will work for box2d and geometry because of the auto-casting behavior
- defined for geometries and box2d. However you can not feed it a geometry or box2d text representation, since that will not auto-cast.</para>
- </note>
-
- <para>&Z_support;</para>
- <para>&curve_support;</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT ST_ZMax('BOX3D(1 2 3, 4 5 6)');
-st_zmax
--------
-6
-
-SELECT ST_ZMax(ST_GeomFromEWKT('LINESTRING(1 3 4, 5 6 7)'));
-st_zmax
--------
-7
-
-SELECT ST_ZMax('BOX3D(-3 2 1, 3 4 1)' );
-st_zmax
--------
-1
---Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
-SELECT ST_ZMax('LINESTRING(1 3 4, 5 6 7)');
-
---ERROR: BOX3D parser - doesn't start with BOX3D(
-
-SELECT ST_ZMax(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
-st_zmax
---------
-3
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_XMin" />, <xref linkend="ST_XMax" />, <xref linkend="ST_YMax" />, <xref linkend="ST_YMin" />, <xref linkend="ST_ZMax" /></para>
- </refsection>
- </refentry>
-
<refentry id="ST_Zmflag">
<refnamediv>
<refname>ST_Zmflag</refname>
</refsection>
</refentry>
- <refentry id="ST_ZMin">
- <refnamediv>
- <refname>ST_ZMin</refname>
-
- <refpurpose>Returns Z minima of a bounding box 2d or 3d or a geometry.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float <function>ST_ZMin</function></funcdef>
- <paramdef><type>box3d </type> <parameter>aGeomorBox2DorBox3D</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns Z minima of a bounding box 2d or 3d or a geometry.</para>
-
- <note>
- <para>Although this function is only defined for box3d, it will work for box2d and geometry because of the auto-casting behavior
- defined for geometries and box2d. However you can not feed it a geometry or box2d text representation, since that will not auto-cast.</para>
- </note>
-
- <para>&Z_support;</para>
- <para>&curve_support;</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT ST_ZMin('BOX3D(1 2 3, 4 5 6)');
-st_zmin
--------
-3
-
-SELECT ST_ZMin(ST_GeomFromEWKT('LINESTRING(1 3 4, 5 6 7)'));
-st_zmin
--------
-4
-
-SELECT ST_ZMin('BOX3D(-3 2 1, 3 4 1)' );
-st_zmin
--------
-1
---Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
-SELECT ST_ZMin('LINESTRING(1 3 4, 5 6 7)');
-
---ERROR: BOX3D parser - doesn't start with BOX3D(
-
-SELECT ST_ZMin(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
-st_zmin
---------
-1
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_GeomFromText" />, <xref linkend="ST_XMin" />, <xref linkend="ST_XMax" />, <xref linkend="ST_YMax" />, <xref linkend="ST_YMin" />, <xref linkend="ST_ZMax" /></para>
- </refsection>
- </refentry>
-
-
</sect1>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+ <sect1 id="BBox_Functions">
+ <sect1info>
+ <abstract>
+ <para>These functions produce or operate on bounding boxes.
+ They can also provide and accept geometry values, by using automatic or explicit casts.
+ </para>
+ <para>See also <xref linkend="PostGIS_BoxFunctions" />.</para>
+ </abstract>
+ </sect1info>
+
+ <title>Bounding Box Functions</title>
+
+ <refentry id="Box2D">
+ <refnamediv>
+ <refname>Box2D</refname>
+
+ <refpurpose>Returns a BOX2D representing the 2D extent of the geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>box2d <function>Box2D</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns a BOX2D representing the 2D extent of the geometry.</para>
+
+ <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
+ <para>&curve_support;</para>
+ <para>&P_support;</para>
+ <para>&T_support;</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT Box2D(ST_GeomFromText('LINESTRING(1 2, 3 4, 5 6)'));
+ box2d
+ ---------
+ BOX(1 2,5 6)
+
+ SELECT Box2D(ST_GeomFromText('CIRCULARSTRING(220268 150415,220227 150505,220227 150406)'));
+ box2d
+ --------
+ BOX(220186.984375 150406,220288.25 150506.140625)
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="Box3D" />, <xref linkend="ST_GeomFromText" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="Box3D">
+ <refnamediv>
+ <refname>Box3D</refname>
+
+ <refpurpose>Returns a BOX3D representing the 3D extent of the geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>box3d <function>Box3D</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns a BOX3D representing the 3D extent of the geometry.</para>
+ <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
+ <para>&curve_support;</para>
+ <para>&P_support;</para>
+ <para>&T_support;</para>
+ <para>&Z_support;</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT Box3D(ST_GeomFromEWKT('LINESTRING(1 2 3, 3 4 5, 5 6 5)'));
+ Box3d
+ ---------
+ BOX3D(1 2 3,5 6 5)
+
+ SELECT Box3D(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 1,220227 150406 1)'));
+ Box3d
+ --------
+ BOX3D(220227 150406 1,220268 150415 1)
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="Box2D" />, <xref linkend="ST_GeomFromEWKT" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_EstimatedExtent">
+ <refnamediv>
+ <refname>ST_EstimatedExtent</refname>
+
+ <refpurpose>Return the 'estimated' extent of a spatial table.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>box2d <function>ST_EstimatedExtent</function></funcdef>
+ <paramdef><type>text </type> <parameter>schema_name</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>table_name</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>geocolumn_name</parameter></paramdef>
+ <paramdef><type>boolean </type> <parameter>parent_only</parameter></paramdef>
+ </funcprototype>
+
+
+ <funcprototype>
+ <funcdef>box2d <function>ST_EstimatedExtent</function></funcdef>
+ <paramdef><type>text </type> <parameter>schema_name</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>table_name</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>geocolumn_name</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>box2d <function>ST_EstimatedExtent</function></funcdef>
+ <paramdef><type>text </type> <parameter>table_name</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>geocolumn_name</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Return the 'estimated' extent of the given spatial table.
+ The estimated is taken from the geometry column's statistics. The
+ current schema will be used if not specified. The default behavior
+ is to also use statistics collected from child tables (tables
+ with INHERITS) if available. If 'parent_only' is set to TRUE, only
+ statistics for the given table are used and child tables are
+ ignored.
+ </para>
+
+ <para>For PostgreSQL>=8.0.0 statistics are gathered by VACUUM
+ ANALYZE and resulting extent will be about 95% of the real
+ one.</para>
+
+ <note>
+ <para>
+In absence of statistics (empty table or no ANALYZE called) this function
+returns NULL. Prior to version 1.5.4 an exception was thrown
+instead.
+ </para>
+ </note>
+
+
+ <para>For PostgreSQL<8.0.0 statistics are gathered by
+ update_geometry_stats() and resulting extent will be exact.</para>
+
+ <para>Availability: 1.0.0</para>
+ <para>Changed: 2.1.0. Up to 2.0.x this was called ST_Estimated_Extent.</para>
+
+ <para>&curve_support;</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT ST_EstimatedExtent('ny', 'edges', 'the_geom');
+--result--
+BOX(-8877653 4912316,-8010225.5 5589284)
+
+SELECT ST_EstimatedExtent('feature_poly', 'the_geom');
+--result--
+BOX(-124.659652709961 24.6830825805664,-67.7798080444336 49.0012092590332)
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_Extent" /></para>
+ </refsection>
+ </refentry>
+ <refentry id="ST_Expand">
+ <refnamediv>
+ <refname>ST_Expand</refname>
+ <refpurpose>Returns a bounding box expanded from another bounding box or a geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Expand</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>units_to_expand</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>geometry <function>ST_Expand</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>dx</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>dy</parameter></paramdef>
+ <paramdef choice="opt"><type>float</type> <parameter>dz=0</parameter></paramdef>
+ <paramdef choice="opt"><type>float</type> <parameter>dm=0</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>box2d <function>ST_Expand</function></funcdef>
+ <paramdef><type>box2d </type> <parameter>box</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>units_to_expand</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>box2d <function>ST_Expand</function></funcdef>
+ <paramdef><type>box2d </type> <parameter>box</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>dx</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>dy</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>box3d <function>ST_Expand</function></funcdef>
+ <paramdef><type>box3d </type> <parameter>box</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>units_to_expand</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>box3d <function>ST_Expand</function></funcdef>
+ <paramdef><type>box3d </type> <parameter>box</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>dx</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>dy</parameter></paramdef>
+ <paramdef choice="opt"><type>float</type> <parameter>dz=0</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>This function returns a bounding box expanded from the bounding box of the input,
+ either by specifying a single distance with which the box should be expanded in all
+ directions, or by specifying an expansion distance for each direction.
+
+ Uses double-precision. Can be very useful for distance queries, or to add a bounding box
+ filter to a query to take advantage of a spatial index.</para>
+ <para>In addition to the geometry version of ST_Expand, which is the most commonly used, variants
+ are provided that accept and produce internal BOX2D and BOX3D data types.
+ </para>
+ <para>ST_Expand is similar in concept to <xref linkend="ST_Buffer" />,
+ except while buffer expands the geometry in all directions,
+ ST_Expand expands the bounding box along each axis.</para>
+ <para>Units are in the units of the spatial reference system in use denoted by the SRID.</para>
+
+ <note>
+ <para>Pre version 1.3, ST_Expand was used in conjunction with <xref linkend="ST_Distance" /> to do indexable distance queries. For example,
+ <code>the_geom && ST_Expand('POINT(10 20)', 10) AND ST_Distance(the_geom, 'POINT(10 20)') < 10</code>.
+ This has been replaced by the easier <xref linkend="ST_DWithin" /> construct.</para>
+ </note>
+
+ <note>
+ <para>Availability: 1.5.0 behavior changed to output double precision instead of float4 coordinates.</para>
+ <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
+ <para>Enhanced: 2.3.0 support was added to expand a box by different amounts in different dimensions.</para>
+ </note>
+
+ <para>&P_support;</para>
+ <para>&T_support;</para>
+
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <note><para>Examples below use US National Atlas Equal Area (SRID=2163) which is a meter projection</para></note>
+ <programlisting>
+ <!-- TODO: fix results of documentation to reflect new behavior -->
+--10 meter expanded box around bbox of a linestring
+SELECT CAST(ST_Expand(ST_GeomFromText('LINESTRING(2312980 110676,2312923 110701,2312892 110714)', 2163),10) As box2d);
+ st_expand
+------------------------------------
+ BOX(2312882 110666,2312990 110724)
+
+--10 meter expanded 3D box of a 3D box
+SELECT ST_Expand(CAST('BOX3D(778783 2951741 1,794875 2970042.61545891 10)' As box3d),10)
+ st_expand
+-----------------------------------------------------
+ BOX3D(778773 2951731 -9,794885 2970052.61545891 20)
+
+ --10 meter geometry astext rep of a expand box around a point geometry
+ SELECT ST_AsEWKT(ST_Expand(ST_GeomFromEWKT('SRID=2163;POINT(2312980 110676)'),10));
+ st_asewkt
+-------------------------------------------------------------------------------------------------
+ SRID=2163;POLYGON((2312970 110666,2312970 110686,2312990 110686,2312990 110666,2312970 110666))
+
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para><xref linkend="ST_AsEWKT" />, <xref linkend="ST_Buffer" />, <xref linkend="ST_DWithin" />, <xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_GeomFromText" />, <xref linkend="ST_SRID" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_Extent">
+ <refnamediv>
+ <refname>ST_Extent</refname>
+ <refpurpose>an aggregate function that returns the bounding box that bounds rows of geometries.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>box2d <function>ST_Extent</function></funcdef>
+ <paramdef><type>geometry set</type> <parameter>geomfield</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>ST_Extent returns a bounding box that encloses a set of geometries. The ST_Extent function is an "aggregate" function in the
+ terminology of SQL. That means that it operates on lists
+ of data, in the same way the SUM() and AVG() functions do.</para>
+ <para>Since it returns a bounding box, the spatial Units are in the units of the spatial reference system in use denoted by the SRID</para>
+ <para>ST_Extent is similar in concept to Oracle Spatial/Locator's SDO_AGGR_MBR</para>
+ <note>
+ <para>Since ST_Extent returns a bounding box, the SRID meta-data is lost. Use ST_SetSRID to force it back into
+ a geometry with SRID meta data. The coordinates are in the units of the spatial ref of the orginal geometries.</para>
+ </note>
+
+ <note>
+ <para>ST_Extent will return boxes with only an x and y component even with (x,y,z) coordinate geometries. To maintain x,y,z use ST_3DExtent instead.</para>
+ </note>
+
+ <note>
+ <para>Availability: 1.4.0</para>
+ </note>
+
+ <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
+ <para>&P_support;</para>
+ <para>&T_support;</para>
+
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <note><para>Examples below use Massachusetts State Plane ft (SRID=2249)</para></note>
+ <programlisting>
+
+SELECT ST_Extent(the_geom) as bextent FROM sometable;
+ st_bextent
+------------------------------------
+BOX(739651.875 2908247.25,794875.8125 2970042.75)
+
+
+--Return extent of each category of geometries
+SELECT ST_Extent(the_geom) as bextent
+FROM sometable
+GROUP BY category ORDER BY category;
+
+ bextent | name
+----------------------------------------------------+----------------
+ BOX(778783.5625 2951741.25,794875.8125 2970042.75) | A
+ BOX(751315.8125 2919164.75,765202.6875 2935417.25) | B
+ BOX(739651.875 2917394.75,756688.375 2935866) | C
+
+ --Force back into a geometry
+ -- and render the extended text representation of that geometry
+SELECT ST_SetSRID(ST_Extent(the_geom),2249) as bextent FROM sometable;
+
+ bextent
+--------------------------------------------------------------------------------
+ SRID=2249;POLYGON((739651.875 2908247.25,739651.875 2970042.75,794875.8125 2970042.75,
+ 794875.8125 2908247.25,739651.875 2908247.25))
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para><xref linkend="ST_AsEWKT" />, <xref linkend="ST_3DExtent" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_SRID" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_3DExtent">
+ <refnamediv>
+ <refname>ST_3DExtent</refname>
+ <refpurpose>an aggregate function that returns the 3D bounding box that bounds rows of geometries.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>box3d <function>ST_3DExtent</function></funcdef>
+ <paramdef><type>geometry set</type> <parameter>geomfield</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>ST_3DExtent returns a box3d (includes Z coordinate) bounding box that encloses a set of geometries. The ST_3DExtent function is an "aggregate" function in the
+ terminology of SQL. That means that it operates on lists
+ of data, in the same way the SUM() and AVG() functions do.</para>
+ <para>Since it returns a bounding box, the spatial Units are in the units of the spatial reference system in use denoted by the SRID</para>
+
+ <note>
+ <para>Since ST_3DExtent returns a bounding box, the SRID meta-data is lost. Use ST_SetSRID to force it back into
+ a geometry with SRID meta data. The coordinates are in the units of the spatial ref of the orginal geometries.</para>
+ </note>
+
+ <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
+ <para>Changed: 2.0.0 In prior versions this used to be called ST_Extent3D</para>
+ <para>&Z_support;</para>
+ <para>&curve_support;</para>
+ <para>&P_support;</para>
+ <para>&T_support;</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
+SELECT ST_3DExtent(foo.the_geom) As b3extent
+FROM (SELECT ST_MakePoint(x,y,z) As the_geom
+ FROM generate_series(1,3) As x
+ CROSS JOIN generate_series(1,2) As y
+ CROSS JOIN generate_series(0,2) As Z) As foo;
+ b3extent
+--------------------
+ BOX3D(1 1 0,3 2 2)
+
+--Get the extent of various elevated circular strings
+SELECT ST_3DExtent(foo.the_geom) As b3extent
+FROM (SELECT ST_Translate(ST_Force_3DZ(ST_LineToCurve(ST_Buffer(ST_MakePoint(x,y),1))),0,0,z) As the_geom
+ FROM generate_series(1,3) As x
+ CROSS JOIN generate_series(1,2) As y
+ CROSS JOIN generate_series(0,2) As Z) As foo;
+
+ b3extent
+--------------------
+ BOX3D(1 0 0,4 2 2)
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para><xref linkend="ST_Extent" />, <xref linkend="ST_Force_3DZ" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_MakeBox2D">
+ <refnamediv>
+ <refname>ST_MakeBox2D</refname>
+
+ <refpurpose>Creates a BOX2D defined by two 2D point geometries.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>box2d <function>ST_MakeBox2D</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>pointLowLeft</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>pointUpRight</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Creates a BOX2D defined by the given two point
+ geometries. This is useful for doing range queries</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>
+--Return all features that fall reside or partly reside in a US national atlas coordinate bounding box
+--It is assumed here that the geometries are stored with SRID = 2163 (US National atlas equal area)
+SELECT feature_id, feature_name, the_geom
+FROM features
+WHERE the_geom && ST_SetSRID(ST_MakeBox2D(ST_Point(-989502.1875, 528439.5625),
+ ST_Point(-987121.375 ,529933.1875)),2163)</programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_MakePoint" />, <xref linkend="ST_Point" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_SRID" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_3DMakeBox">
+ <refnamediv>
+ <refname>ST_3DMakeBox</refname>
+
+ <refpurpose>Creates a BOX3D defined by two 3D point geometries.</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>box3d <function>ST_3DMakeBox</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>point3DLowLeftBottom</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>point3DUpRightTop</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Creates a BOX3D defined by the given two 3D point
+ geometries. </para>
+
+ <!-- Optionally mention 3D support -->
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/check.png" />
+ </imageobject>
+ </inlinemediaobject> This function supports 3D and will not drop the z-index.</para>
+ <para>Changed: 2.0.0 In prior versions this used to be called ST_MakeBox3D</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>
+SELECT ST_3DMakeBox(ST_MakePoint(-989502.1875, 528439.5625, 10),
+ ST_MakePoint(-987121.375 ,529933.1875, 10)) As abb3d
+
+--bb3d--
+--------
+BOX3D(-989502.1875 528439.5625 10,-987121.375 529933.1875 10)
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_MakePoint" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_SRID" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_XMax">
+ <refnamediv>
+ <refname>ST_XMax</refname>
+
+ <refpurpose>Returns the X maxima of a 2D or 3D bounding box or a geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float <function>ST_XMax</function></funcdef>
+ <paramdef><type>box3d </type> <parameter>aGeomorBox2DorBox3D</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns the X maxima of a 2D or 3D bounding box or a geometry.</para>
+
+ <note>
+ <para>Although this function is only defined for box3d, it also works for box2d and geometry values due to automatic casting.
+ However it will not accept a geometry or box2d text representation, since those do not auto-cast.</para>
+ </note>
+
+ <para>&Z_support;</para>
+ <para>&curve_support;</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT ST_XMax('BOX3D(1 2 3, 4 5 6)');
+st_xmax
+-------
+4
+
+SELECT ST_XMax(ST_GeomFromText('LINESTRING(1 3 4, 5 6 7)'));
+st_xmax
+-------
+5
+
+SELECT ST_XMax(CAST('BOX(-3 2, 3 4)' As box2d));
+st_xmax
+-------
+3
+--Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
+SELECT ST_XMax('LINESTRING(1 3, 5 6)');
+
+--ERROR: BOX3D parser - doesn't start with BOX3D(
+
+SELECT ST_XMax(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
+st_xmax
+--------
+220288.248780547
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_XMin" />, <xref linkend="ST_YMax" />, <xref linkend="ST_YMin" />, <xref linkend="ST_ZMax" />, <xref linkend="ST_ZMin" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_XMin">
+ <refnamediv>
+ <refname>ST_XMin</refname>
+
+ <refpurpose>Returns the X minima of a 2D or 3D bounding box or a geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float <function>ST_XMin</function></funcdef>
+ <paramdef><type>box3d </type> <parameter>aGeomorBox2DorBox3D</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns the X minima of a 2D or 3D bounding box or a geometry.</para>
+
+ <note>
+ <para>Although this function is only defined for box3d, it also works for box2d and geometry values due to automatic casting.
+ However it will not accept a geometry or box2d text representation, since those do not auto-cast.</para>
+ </note>
+
+ <para>&Z_support;</para>
+ <para>&curve_support;</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT ST_XMin('BOX3D(1 2 3, 4 5 6)');
+st_xmin
+-------
+1
+
+SELECT ST_XMin(ST_GeomFromText('LINESTRING(1 3 4, 5 6 7)'));
+st_xmin
+-------
+1
+
+SELECT ST_XMin(CAST('BOX(-3 2, 3 4)' As box2d));
+st_xmin
+-------
+-3
+--Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
+SELECT ST_XMin('LINESTRING(1 3, 5 6)');
+
+--ERROR: BOX3D parser - doesn't start with BOX3D(
+
+SELECT ST_XMin(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
+st_xmin
+--------
+220186.995121892
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_XMax" />, <xref linkend="ST_YMax" />, <xref linkend="ST_YMin" />, <xref linkend="ST_ZMax" />, <xref linkend="ST_ZMin" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_YMax">
+ <refnamediv>
+ <refname>ST_YMax</refname>
+
+ <refpurpose>Returns the Y maxima of a 2D or 3D bounding box or a geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float <function>ST_YMax</function></funcdef>
+ <paramdef><type>box3d </type> <parameter>aGeomorBox2DorBox3D</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns the Y maxima of a 2D or 3D bounding box or a geometry.</para>
+
+ <note>
+ <para>Although this function is only defined for box3d, it also works for box2d and geometry values due to automatic casting.
+ However it will not accept a geometry or box2d text representation, since those do not auto-cast.</para>
+ </note>
+
+ <para>&Z_support;</para>
+ <para>&curve_support;</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT ST_YMax('BOX3D(1 2 3, 4 5 6)');
+st_ymax
+-------
+5
+
+SELECT ST_YMax(ST_GeomFromText('LINESTRING(1 3 4, 5 6 7)'));
+st_ymax
+-------
+6
+
+SELECT ST_YMax(CAST('BOX(-3 2, 3 4)' As box2d));
+st_ymax
+-------
+4
+--Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
+SELECT ST_YMax('LINESTRING(1 3, 5 6)');
+
+--ERROR: BOX3D parser - doesn't start with BOX3D(
+
+SELECT ST_YMax(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
+st_ymax
+--------
+150506.126829327
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_XMin" />, <xref linkend="ST_XMax" />, <xref linkend="ST_YMin" />, <xref linkend="ST_ZMax" />, <xref linkend="ST_ZMin" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_YMin">
+ <refnamediv>
+ <refname>ST_YMin</refname>
+
+ <refpurpose>Returns the Y minima of a 2D or 3D bounding box or a geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float <function>ST_YMin</function></funcdef>
+ <paramdef><type>box3d </type> <parameter>aGeomorBox2DorBox3D</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns the Y minima of a 2D or 3D bounding box or a geometry.</para>
+
+ <note>
+ <para>Although this function is only defined for box3d, it also works for box2d and geometry values due to automatic casting.
+ However it will not accept a geometry or box2d text representation, since those do not auto-cast.</para>
+ </note>
+
+ <para>&Z_support;</para>
+ <para>&curve_support;</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT ST_YMin('BOX3D(1 2 3, 4 5 6)');
+st_ymin
+-------
+2
+
+SELECT ST_YMin(ST_GeomFromText('LINESTRING(1 3 4, 5 6 7)'));
+st_ymin
+-------
+3
+
+SELECT ST_YMin(CAST('BOX(-3 2, 3 4)' As box2d));
+st_ymin
+-------
+2
+--Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
+SELECT ST_YMin('LINESTRING(1 3, 5 6)');
+
+--ERROR: BOX3D parser - doesn't start with BOX3D(
+
+SELECT ST_YMin(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
+st_ymin
+--------
+150406
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_XMin" />, <xref linkend="ST_XMax" />, <xref linkend="ST_YMax" />, <xref linkend="ST_ZMax" />, <xref linkend="ST_ZMin" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_ZMax">
+ <refnamediv>
+ <refname>ST_ZMax</refname>
+
+ <refpurpose>Returns the Z maxima of a 2D or 3D bounding box or a geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float <function>ST_ZMax</function></funcdef>
+ <paramdef><type>box3d </type> <parameter>aGeomorBox2DorBox3D</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns the Z maxima of a 2D or 3D bounding box or a geometry.</para>
+
+ <note>
+ <para>Although this function is only defined for box3d, it also works for box2d and geometry values due to automatic casting.
+ However it will not accept a geometry or box2d text representation, since those do not auto-cast.</para>
+ </note>
+
+ <para>&Z_support;</para>
+ <para>&curve_support;</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT ST_ZMax('BOX3D(1 2 3, 4 5 6)');
+st_zmax
+-------
+6
+
+SELECT ST_ZMax(ST_GeomFromEWKT('LINESTRING(1 3 4, 5 6 7)'));
+st_zmax
+-------
+7
+
+SELECT ST_ZMax('BOX3D(-3 2 1, 3 4 1)' );
+st_zmax
+-------
+1
+--Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
+SELECT ST_ZMax('LINESTRING(1 3 4, 5 6 7)');
+
+--ERROR: BOX3D parser - doesn't start with BOX3D(
+
+SELECT ST_ZMax(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
+st_zmax
+--------
+3
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_XMin" />, <xref linkend="ST_XMax" />, <xref linkend="ST_YMax" />, <xref linkend="ST_YMin" />, <xref linkend="ST_ZMax" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_ZMin">
+ <refnamediv>
+ <refname>ST_ZMin</refname>
+
+ <refpurpose>Returns the Z minima of a 2D or 3D bounding box or a geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float <function>ST_ZMin</function></funcdef>
+ <paramdef><type>box3d </type> <parameter>aGeomorBox2DorBox3D</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns the Z minima of a 2D or 3D bounding box or a geometry.</para>
+
+ <note>
+ <para>Although this function is only defined for box3d, it also works for box2d and geometry values due to automatic casting.
+ However it will not accept a geometry or box2d text representation, since those do not auto-cast.</para>
+ </note>
+
+ <para>&Z_support;</para>
+ <para>&curve_support;</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT ST_ZMin('BOX3D(1 2 3, 4 5 6)');
+st_zmin
+-------
+3
+
+SELECT ST_ZMin(ST_GeomFromEWKT('LINESTRING(1 3 4, 5 6 7)'));
+st_zmin
+-------
+4
+
+SELECT ST_ZMin('BOX3D(-3 2 1, 3 4 1)' );
+st_zmin
+-------
+1
+--Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
+SELECT ST_ZMin('LINESTRING(1 3 4, 5 6 7)');
+
+--ERROR: BOX3D parser - doesn't start with BOX3D(
+
+SELECT ST_ZMin(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
+st_zmin
+--------
+1
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_GeomFromText" />, <xref linkend="ST_XMin" />, <xref linkend="ST_XMax" />, <xref linkend="ST_YMax" />, <xref linkend="ST_YMin" />, <xref linkend="ST_ZMax" /></para>
+ </refsection>
+ </refentry>
+
+ </sect1>
</refsection>
</refentry>
- <refentry id="ST_MakeBox2D">
- <refnamediv>
- <refname>ST_MakeBox2D</refname>
-
- <refpurpose>Creates a BOX2D defined by the given point
- geometries.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>box2d <function>ST_MakeBox2D</function></funcdef>
- <paramdef><type>geometry </type> <parameter>pointLowLeft</parameter></paramdef>
- <paramdef><type>geometry </type> <parameter>pointUpRight</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Creates a BOX2D defined by the given point
- geometries. This is useful for doing range queries</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>
---Return all features that fall reside or partly reside in a US national atlas coordinate bounding box
---It is assumed here that the geometries are stored with SRID = 2163 (US National atlas equal area)
-SELECT feature_id, feature_name, the_geom
-FROM features
-WHERE the_geom && ST_SetSRID(ST_MakeBox2D(ST_Point(-989502.1875, 528439.5625),
- ST_Point(-987121.375 ,529933.1875)),2163)</programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_MakePoint" />, <xref linkend="ST_Point" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_SRID" /></para>
- </refsection>
- </refentry>
-
- <refentry id="ST_3DMakeBox">
- <refnamediv>
- <refname>ST_3DMakeBox</refname>
-
- <refpurpose>Creates a BOX3D defined by the given 3d point
- geometries.</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>box3d <function>ST_3DMakeBox</function></funcdef>
- <paramdef><type>geometry </type> <parameter>point3DLowLeftBottom</parameter></paramdef>
- <paramdef><type>geometry </type> <parameter>point3DUpRightTop</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Creates a BOX3D defined by the given 2 3D point
- geometries. </para>
-
- <!-- Optionally mention 3d support -->
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/check.png" />
- </imageobject>
- </inlinemediaobject> This function supports 3d and will not drop the z-index.</para>
- <para>Changed: 2.0.0 In prior versions this used to be called ST_MakeBox3D</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>
-SELECT ST_3DMakeBox(ST_MakePoint(-989502.1875, 528439.5625, 10),
- ST_MakePoint(-987121.375 ,529933.1875, 10)) As abb3d
-
---bb3d--
---------
-BOX3D(-989502.1875 528439.5625 10,-987121.375 529933.1875 10)
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_MakePoint" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_SRID" /></para>
- </refsection>
- </refentry>
-
<refentry id="ST_MakeLine">
<refnamediv>
<refname>ST_MakeLine</refname>
<refnamediv>
<refname>AddGeometryColumn</refname>
- <refpurpose>Adds a geometry column to an existing table of
- attributes. By default uses type modifier to define rather than constraints.
- Pass in false for use_typmod to get old check constraint based behavior</refpurpose>
+ <refpurpose>Adds a geometry column to an existing table.</refpurpose>
</refnamediv>
<refsynopsisdiv>
</refsection>
</refentry>
+ <refentry id="Find_SRID">
+ <refnamediv>
+ <refname>Find_SRID</refname>
+
+ <refpurpose>Returns the SRID defined for a geometry column.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>integer <function>Find_SRID</function></funcdef>
+ <paramdef><type>varchar </type> <parameter>a_schema_name</parameter></paramdef>
+ <paramdef><type>varchar </type> <parameter>a_table_name</parameter></paramdef>
+ <paramdef><type>varchar </type> <parameter>a_geomfield_name</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns the integer SRID of the
+ specified geometry column by searching through the GEOMETRY_COLUMNS table.
+ If the geometry column has not been properly added (e.g. with the
+ <xref linkend="AddGeometryColumn" /> function), this function will not work.</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting> SELECT Find_SRID('public', 'tiger_us_state_2007', 'the_geom_4269');
+find_srid
+----------
+4269
+</programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_SRID" /></para>
+ </refsection>
+ </refentry>
+
+
<refentry id="Populate_Geometry_Columns">
<refnamediv>
<refname>Populate_Geometry_Columns</refname>
- <refpurpose>Ensures geometry columns are defined with type modifiers or have appropriate spatial constraints
- This ensures they will be registered correctly in <varname>geometry_columns</varname> view. By default will convert all geometry
- columns with no type modifier to ones with type modifiers. To get old behavior set <varname>use_typmod=false</varname></refpurpose>
+ <refpurpose>Ensures geometry columns are defined with type modifiers or have appropriate spatial constraints.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsection>
<title>Description</title>
- <para>Ensures geometry columns have appropriate type modifiers or spatial constraints to ensure they are registered correctly in <varname>geometry_columns</varname> table.</para>
+ <para>Ensures geometry columns have appropriate type modifiers or spatial constraints to ensure they are registered correctly in the <varname>geometry_columns</varname> view.
+ By default will convert all geometry
+ columns with no type modifier to ones with type modifiers.
+ </para>
<para>For backwards compatibility and for spatial needs such as table inheritance where each child table may have different geometry type, the old check constraint behavior is still supported.
If you need the old behavior, you need to pass in the new optional argument as false <varname>use_typmod=false</varname>. When this is done geometry columns will be created with no type modifiers
<refname>UpdateGeometrySRID</refname>
<refpurpose>Updates the SRID of all features in a geometry
- column, geometry_columns metadata and srid. If it was enforced with constraints, the constraints will be updated with new srid constraint.
- If the old was enforced by type definition, the type definition will be changed.</refpurpose>
+ column, and the table metadata.
+ </refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Description</title>
<para>Updates the SRID of all features in a geometry column, updating
- constraints and reference in geometry_columns. Note: uses
+ constraints and reference in geometry_columns.
+ If the column was enforced by a type definition, the type definition will be changed.
+ Note: uses
current_schema() on schema-aware pgsql installations if schema is not
provided.</para>
<para>&Z_support;</para>
</para>
</refsection>
</refentry>
+
+ <refentry id="ST_MemSize">
+ <refnamediv>
+ <refname>ST_MemSize</refname>
+
+ <refpurpose>Returns the amount of memory space a geometry takes.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>integer <function>ST_MemSize</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns the amount of memory space (in bytes) the geometry takes. </para>
+ <para>This complements the PostgreSQL built-in <ulink url="https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">database object functions</ulink>
+ pg_column_size, pg_size_pretty, pg_relation_size, pg_total_relation_size.</para>
+ <note><para>pg_relation_size which gives the byte size of a table may return byte size lower than ST_MemSize. This is because
+ pg_relation_size does not add toasted table contribution and large geometries are stored in TOAST tables.</para>
+ <para>pg_total_relation_size - includes, the table, the toasted tables, and the indexes.</para>
+ <para>pg_column_size returns how much space a geometry would take in a column considering compression, so may be lower than ST_MemSize</para>
+ </note>
+
+ <para>&Z_support;</para>
+ <para>&curve_support;</para>
+ <para>&P_support;</para>
+ <para>&T_support;</para>
+ <para>Changed: 2.2.0 name changed to ST_MemSize to follow naming convention. In prior versions this function was called ST_Mem_Size, old name deprecated though still available.</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>
+--Return how much byte space Boston takes up in our Mass data set
+SELECT pg_size_pretty(SUM(ST_MemSize(the_geom))) as totgeomsum,
+pg_size_pretty(SUM(CASE WHEN town = 'BOSTON' THEN ST_MemSize(the_geom) ELSE 0 END)) As bossum,
+CAST(SUM(CASE WHEN town = 'BOSTON' THEN ST_MemSize(the_geom) ELSE 0 END)*1.00 /
+ SUM(ST_MemSize(the_geom))*100 As numeric(10,2)) As perbos
+FROM towns;
+
+totgeomsum bossum perbos
+---------- ------ ------
+1522 kB 30 kB 1.99
+
+
+SELECT ST_MemSize(ST_GeomFromText('CIRCULARSTRING(220268 150415,220227 150505,220227 150406)'));
+
+---
+73
+
+--What percentage of our table is taken up by just the geometry
+SELECT pg_total_relation_size('public.neighborhoods') As fulltable_size, sum(ST_MemSize(the_geom)) As geomsize,
+sum(ST_MemSize(the_geom))*1.00/pg_total_relation_size('public.neighborhoods')*100 As pergeom
+FROM neighborhoods;
+fulltable_size geomsize pergeom
+------------------------------------------------
+262144 96238 36.71188354492187500000
+ </programlisting>
+ </refsection>
+
+ </refentry>
+
</sect1>
</refsection>
</refentry>
+ <refentry id="ST_PointInsideCircle">
+ <refnamediv>
+ <refname>ST_PointInsideCircle</refname>
+
+ <refpurpose>Is the point geometry inside the circle defined by center_x, center_y, radius</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>boolean <function>ST_PointInsideCircle</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>a_point</parameter></paramdef>
+ <paramdef><type>float </type> <parameter>center_x</parameter></paramdef>
+ <paramdef><type>float </type> <parameter>center_y</parameter></paramdef>
+ <paramdef><type>float </type> <parameter>radius</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>The syntax for this functions is
+ ST_PointInsideCircle(<geometry>,<circle_center_x>,<circle_center_y>,<radius>).
+ Returns the true if the geometry is a point and is inside the
+ circle. Returns false otherwise.</para>
+ <note><para>This only works for points as the name suggests</para></note>
+
+ <para>Availability: 1.2</para>
+ <para>Changed: 2.2.0 In prior versions this used to be called ST_Point_Inside_Circle</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT ST_PointInsideCircle(ST_Point(1,2), 0.5, 2, 3);
+ st_pointinsidecircle
+------------------------
+ t
+</programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_DWithin" /></para>
+ </refsection>
+ </refentry>
+
<refentry id="ST_PointOnSurface">
<refnamediv>
<refname>ST_PointOnSurface</refname>
<refsection>
<title>See Also</title>
- <para><xref linkend="ST_Centroid" />, <xref linkend="ST_Point_Inside_Circle" /></para>
+ <para><xref linkend="ST_Centroid" />, <xref linkend="ST_PointInsideCircle" /></para>
</refsection>
</refentry>
<sect1 id="Miscellaneous_Functions">
<title>Miscellaneous Functions</title>
- <refentry id="ST_Accum">
- <refnamediv>
- <refname>ST_Accum</refname>
-
- <refpurpose>Aggregate. Constructs an array of geometries.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry[] <function>ST_Accum</function></funcdef>
- <paramdef><type>geometry set</type> <parameter>geomfield</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Aggregate. Constructs an array of geometries.</para>
- <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
- <para>&Z_support;</para>
- <para>&curve_support;</para>
- <para>&P_support;</para>
- <para>&T_support;</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT (ST_Accum(the_geom)) As all_em, ST_AsText((ST_Accum(the_geom))[1]) As grabone,
-(ST_Accum(the_geom))[2:4] as grab_rest
- FROM (SELECT ST_MakePoint(a*CAST(random()*10 As integer), a*CAST(random()*10 As integer), a*CAST(random()*10 As integer)) As the_geom
- FROM generate_series(1,4) a) As foo;
-
-all_em|grabone | grab_rest
-
--------------------------------------------------------------------------------+
-
- {0101000080000000000000144000000000000024400000000000001040:
- 0101000080000000000
-00018400000000000002C400000000000003040:
-0101000080000000000000354000000000000038400000000000001840:
-010100008000000000000040400000000000003C400000000000003040} |
- POINT(5 10) | {010100008000000000000018400000000000002C400000000000003040:
- 0101000080000000000000354000000000000038400000000000001840:
- 010100008000000000000040400000000000003C400000000000003040}
-(1 row)
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_Collect" /></para>
- </refsection>
- </refentry>
-
- <refentry id="Box2D">
- <refnamediv>
- <refname>Box2D</refname>
-
- <refpurpose>Returns a BOX2D representing the maximum extents of the geometry.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>box2d <function>Box2D</function></funcdef>
- <paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns a BOX2D representing the maximum extents of the geometry.</para>
-
- <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
- <para>&curve_support;</para>
- <para>&P_support;</para>
- <para>&T_support;</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT Box2D(ST_GeomFromText('LINESTRING(1 2, 3 4, 5 6)'));
- box2d
- ---------
- BOX(1 2,5 6)
-
- SELECT Box2D(ST_GeomFromText('CIRCULARSTRING(220268 150415,220227 150505,220227 150406)'));
- box2d
- --------
- BOX(220186.984375 150406,220288.25 150506.140625)
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="Box3D" />, <xref linkend="ST_GeomFromText" /></para>
- </refsection>
- </refentry>
-
- <refentry id="Box3D">
- <refnamediv>
- <refname>Box3D</refname>
-
- <refpurpose>Returns a BOX3D representing the maximum extents of the geometry.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>box3d <function>Box3D</function></funcdef>
- <paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns a BOX3D representing the maximum extents of the geometry.</para>
- <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
- <para>&curve_support;</para>
- <para>&P_support;</para>
- <para>&T_support;</para>
- <para>&Z_support;</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT Box3D(ST_GeomFromEWKT('LINESTRING(1 2 3, 3 4 5, 5 6 5)'));
- Box3d
- ---------
- BOX3D(1 2 3,5 6 5)
-
- SELECT Box3D(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 1,220227 150406 1)'));
- Box3d
- --------
- BOX3D(220227 150406 1,220268 150415 1)
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="Box2D" />, <xref linkend="ST_GeomFromEWKT" /></para>
- </refsection>
- </refentry>
-
- <refentry id="ST_EstimatedExtent">
- <refnamediv>
- <refname>ST_EstimatedExtent</refname>
-
- <refpurpose>Return the 'estimated' extent of the given spatial table.
- The estimated is taken from the geometry column's statistics. The
- current schema will be used if not specified.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>box2d <function>ST_EstimatedExtent</function></funcdef>
- <paramdef><type>text </type> <parameter>schema_name</parameter></paramdef>
- <paramdef><type>text </type> <parameter>table_name</parameter></paramdef>
- <paramdef><type>text </type> <parameter>geocolumn_name</parameter></paramdef>
- <paramdef><type>boolean </type> <parameter>parent_ony</parameter></paramdef>
- </funcprototype>
-
-
- <funcprototype>
- <funcdef>box2d <function>ST_EstimatedExtent</function></funcdef>
- <paramdef><type>text </type> <parameter>schema_name</parameter></paramdef>
- <paramdef><type>text </type> <parameter>table_name</parameter></paramdef>
- <paramdef><type>text </type> <parameter>geocolumn_name</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>box2d <function>ST_EstimatedExtent</function></funcdef>
- <paramdef><type>text </type> <parameter>table_name</parameter></paramdef>
- <paramdef><type>text </type> <parameter>geocolumn_name</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Return the 'estimated' extent of the given spatial table.
- The estimated is taken from the geometry column's statistics. The
- current schema will be used if not specified. The default behavior
- is to also use statistics collected from children tables (tables
- with INHERITS) if available. If 'parent_ony' is set to TRUE, only
- statistics for the given table are used and children tables are
- ignored.
- </para>
-
- <para>For PostgreSQL>=8.0.0 statistics are gathered by VACUUM
- ANALYZE and resulting extent will be about 95% of the real
- one.</para>
-
- <note>
- <para>
-In absence of statistics (empty table or no ANALYZE called) this function
-returns NULL. Prior to version 1.5.4 an exception was thrown
-instead.
- </para>
- </note>
-
-
- <para>For PostgreSQL<8.0.0 statistics are gathered by
- update_geometry_stats() and resulting extent will be exact.</para>
-
- <para>Availability: 1.0.0</para>
- <para>Changed: 2.1.0. Up to 2.0.x this was called ST_Estimated_Extent.</para>
-
- <para>&curve_support;</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT ST_EstimatedExtent('ny', 'edges', 'the_geom');
---result--
-BOX(-8877653 4912316,-8010225.5 5589284)
-
-SELECT ST_EstimatedExtent('feature_poly', 'the_geom');
---result--
-BOX(-124.659652709961 24.6830825805664,-67.7798080444336 49.0012092590332)
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_Extent" /></para>
- </refsection>
- </refentry>
- <refentry id="ST_Expand">
- <refnamediv>
- <refname>ST_Expand</refname>
- <refpurpose>Returns bounding box expanded in all directions from the bounding box of the input geometry. Uses double-precision</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_Expand</function></funcdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- <paramdef><type>float</type> <parameter>units_to_expand</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>geometry <function>ST_Expand</function></funcdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- <paramdef><type>float</type> <parameter>dx</parameter></paramdef>
- <paramdef><type>float</type> <parameter>dy</parameter></paramdef>
- <paramdef choice="opt"><type>float</type> <parameter>dz=0</parameter></paramdef>
- <paramdef choice="opt"><type>float</type> <parameter>dm=0</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>box2d <function>ST_Expand</function></funcdef>
- <paramdef><type>box2d </type> <parameter>box</parameter></paramdef>
- <paramdef><type>float</type> <parameter>units_to_expand</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>box2d <function>ST_Expand</function></funcdef>
- <paramdef><type>box2d </type> <parameter>box</parameter></paramdef>
- <paramdef><type>float</type> <parameter>dx</parameter></paramdef>
- <paramdef><type>float</type> <parameter>dy</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>box3d <function>ST_Expand</function></funcdef>
- <paramdef><type>box3d </type> <parameter>box</parameter></paramdef>
- <paramdef><type>float</type> <parameter>units_to_expand</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>box3d <function>ST_Expand</function></funcdef>
- <paramdef><type>box3d </type> <parameter>box</parameter></paramdef>
- <paramdef><type>float</type> <parameter>dx</parameter></paramdef>
- <paramdef><type>float</type> <parameter>dy</parameter></paramdef>
- <paramdef choice="opt"><type>float</type> <parameter>dz=0</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>This function returns a bounding box expanded from the bounding box of the input,
- either by specifying a single distance with which the box should be expanded in all
- directions, or by specifying an expansion distance for each direction.
-
- Uses double-precision. Can be very useful for distance queries, or to add a bounding box
- filter to a query to take advantage of a spatial index.</para>
- <para>In addition to the geometry version of ST_Expand, which is the most commonly used, variants
- are provided that accept and produce internal BOX2D and BOX3D data types.
- </para>
- <para>ST_Expand is similar in concept to ST_Buffer, except while buffer expands the geometry in all directions,
- ST_Expand expands the bounding box an x,y,z unit amount.</para>
- <para>Units are in the units of the spatial reference system in use denoted by the SRID.</para>
-
- <note>
- <para>Pre 1.3, ST_Expand was used in conjunction with distance to do indexable queries. Something of the form
- <code>the_geom && ST_Expand('POINT(10 20)', 10) AND ST_Distance(the_geom, 'POINT(10 20)') < 10</code>
- Post 1.2, this was replaced with the easier ST_DWithin construct.</para>
- </note>
-
- <note>
- <para>Availability: 1.5.0 behavior changed to output double precision instead of float4 coordinates.</para>
- <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
- <para>Enhanced: 2.3.0 support was added to expand a box by different amounts in different dimensions.</para>
- </note>
-
- <para>&P_support;</para>
- <para>&T_support;</para>
-
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <note><para>Examples below use US National Atlas Equal Area (SRID=2163) which is a meter projection</para></note>
- <programlisting>
- <!-- TODO: fix results of documentation to reflect new behavior -->
---10 meter expanded box around bbox of a linestring
-SELECT CAST(ST_Expand(ST_GeomFromText('LINESTRING(2312980 110676,2312923 110701,2312892 110714)', 2163),10) As box2d);
- st_expand
-------------------------------------
- BOX(2312882 110666,2312990 110724)
-
---10 meter expanded 3d box of a 3d box
-SELECT ST_Expand(CAST('BOX3D(778783 2951741 1,794875 2970042.61545891 10)' As box3d),10)
- st_expand
------------------------------------------------------
- BOX3D(778773 2951731 -9,794885 2970052.61545891 20)
-
- --10 meter geometry astext rep of a expand box around a point geometry
- SELECT ST_AsEWKT(ST_Expand(ST_GeomFromEWKT('SRID=2163;POINT(2312980 110676)'),10));
- st_asewkt
--------------------------------------------------------------------------------------------------
- SRID=2163;POLYGON((2312970 110666,2312970 110686,2312990 110686,2312990 110666,2312970 110666))
-
- </programlisting>
- </refsection>
-
- <refsection>
- <title>See Also</title>
- <para><xref linkend="ST_AsEWKT" />, <xref linkend="ST_Buffer" />, <xref linkend="ST_DWithin" />, <xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_GeomFromText" />, <xref linkend="ST_SRID" /></para>
- </refsection>
- </refentry>
-
- <refentry id="ST_Extent">
- <refnamediv>
- <refname>ST_Extent</refname>
- <refpurpose>an aggregate function that returns the bounding box that bounds rows of geometries.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>box2d <function>ST_Extent</function></funcdef>
- <paramdef><type>geometry set</type> <parameter>geomfield</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>ST_Extent returns a bounding box that encloses a set of geometries. The ST_Extent function is an "aggregate" function in the
- terminology of SQL. That means that it operates on lists
- of data, in the same way the SUM() and AVG() functions do.</para>
- <para>Since it returns a bounding box, the spatial Units are in the units of the spatial reference system in use denoted by the SRID</para>
- <para>ST_Extent is similar in concept to Oracle Spatial/Locator's SDO_AGGR_MBR</para>
- <note>
- <para>Since ST_Extent returns a bounding box, the SRID meta-data is lost. Use ST_SetSRID to force it back into
- a geometry with SRID meta data. The coordinates are in the units of the spatial ref of the orginal geometries.</para>
- </note>
-
- <note>
- <para>ST_Extent will return boxes with only an x and y component even with (x,y,z) coordinate geometries. To maintain x,y,z use ST_3DExtent instead.</para>
- </note>
-
- <note>
- <para>Availability: 1.4.0</para>
- </note>
-
- <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
- <para>&P_support;</para>
- <para>&T_support;</para>
-
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <note><para>Examples below use Massachusetts State Plane ft (SRID=2249)</para></note>
- <programlisting>
-
-SELECT ST_Extent(the_geom) as bextent FROM sometable;
- st_bextent
-------------------------------------
-BOX(739651.875 2908247.25,794875.8125 2970042.75)
-
-
---Return extent of each category of geometries
-SELECT ST_Extent(the_geom) as bextent
-FROM sometable
-GROUP BY category ORDER BY category;
-
- bextent | name
-----------------------------------------------------+----------------
- BOX(778783.5625 2951741.25,794875.8125 2970042.75) | A
- BOX(751315.8125 2919164.75,765202.6875 2935417.25) | B
- BOX(739651.875 2917394.75,756688.375 2935866) | C
-
- --Force back into a geometry
- -- and render the extended text representation of that geometry
-SELECT ST_SetSRID(ST_Extent(the_geom),2249) as bextent FROM sometable;
-
- bextent
---------------------------------------------------------------------------------
- SRID=2249;POLYGON((739651.875 2908247.25,739651.875 2970042.75,794875.8125 2970042.75,
- 794875.8125 2908247.25,739651.875 2908247.25))
- </programlisting>
- </refsection>
-
- <refsection>
- <title>See Also</title>
- <para><xref linkend="ST_AsEWKT" />, <xref linkend="ST_3DExtent" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_SRID" /></para>
- </refsection>
- </refentry>
-
- <refentry id="ST_3DExtent">
- <refnamediv>
- <refname>ST_3DExtent</refname>
- <refpurpose>an aggregate function that returns the box3D bounding box that bounds rows of geometries.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>box3d <function>ST_3DExtent</function></funcdef>
- <paramdef><type>geometry set</type> <parameter>geomfield</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>ST_3DExtent returns a box3d (includes Z coordinate) bounding box that encloses a set of geometries. The ST_3DExtent function is an "aggregate" function in the
- terminology of SQL. That means that it operates on lists
- of data, in the same way the SUM() and AVG() functions do.</para>
- <para>Since it returns a bounding box, the spatial Units are in the units of the spatial reference system in use denoted by the SRID</para>
-
- <note>
- <para>Since ST_3DExtent returns a bounding box, the SRID meta-data is lost. Use ST_SetSRID to force it back into
- a geometry with SRID meta data. The coordinates are in the units of the spatial ref of the orginal geometries.</para>
- </note>
-
- <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
- <para>Changed: 2.0.0 In prior versions this used to be called ST_Extent3D</para>
- <para>&Z_support;</para>
- <para>&curve_support;</para>
- <para>&P_support;</para>
- <para>&T_support;</para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <programlisting>
-SELECT ST_3DExtent(foo.the_geom) As b3extent
-FROM (SELECT ST_MakePoint(x,y,z) As the_geom
- FROM generate_series(1,3) As x
- CROSS JOIN generate_series(1,2) As y
- CROSS JOIN generate_series(0,2) As Z) As foo;
- b3extent
---------------------
- BOX3D(1 1 0,3 2 2)
-
---Get the extent of various elevated circular strings
-SELECT ST_3DExtent(foo.the_geom) As b3extent
-FROM (SELECT ST_Translate(ST_Force_3DZ(ST_LineToCurve(ST_Buffer(ST_MakePoint(x,y),1))),0,0,z) As the_geom
- FROM generate_series(1,3) As x
- CROSS JOIN generate_series(1,2) As y
- CROSS JOIN generate_series(0,2) As Z) As foo;
-
- b3extent
---------------------
- BOX3D(1 0 0,4 2 2)
- </programlisting>
- </refsection>
-
- <refsection>
- <title>See Also</title>
- <para><xref linkend="ST_Extent" />, <xref linkend="ST_Force_3DZ" /></para>
- </refsection>
- </refentry>
-
-
- <refentry id="Find_SRID">
- <refnamediv>
- <refname>Find_SRID</refname>
-
- <refpurpose>The syntax is find_srid(a_db_schema, a_table,
- a_column) and the function returns the integer SRID of the
- specified column by searching through the GEOMETRY_COLUMNS table.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>integer <function>Find_SRID</function></funcdef>
- <paramdef><type>varchar </type> <parameter>a_schema_name</parameter></paramdef>
- <paramdef><type>varchar </type> <parameter>a_table_name</parameter></paramdef>
- <paramdef><type>varchar </type> <parameter>a_geomfield_name</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>The syntax is find_srid(<db/schema>, <table>,
- <column>) and the function returns the integer SRID of the
- specified column by searching through the GEOMETRY_COLUMNS table.
- If the geometry column has not been properly added with the
- AddGeometryColumns() function, this function will not work
- either.</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting> SELECT Find_SRID('public', 'tiger_us_state_2007', 'the_geom_4269');
-find_srid
-----------
-4269
-</programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_SRID" /></para>
- </refsection>
- </refentry>
-
- <refentry id="ST_MemSize">
- <refnamediv>
- <refname>ST_MemSize</refname>
-
- <refpurpose>Returns the amount of space (in bytes) the geometry takes.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>integer <function>ST_MemSize</function></funcdef>
- <paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns the amount of space (in bytes) the geometry takes. </para>
- <para>This is a nice compliment to PostgreSQL built in functions pg_column_size, pg_size_pretty, pg_relation_size, pg_total_relation_size.</para>
- <note><para>pg_relation_size which gives the byte size of a table may return byte size lower than ST_MemSize. This is because
- pg_relation_size does not add toasted table contribution and large geometries are stored in TOAST tables.</para>
- <para>pg_total_relation_size - includes, the table, the toasted tables, and the indexes.</para>
- <para>pg_column_size returns how much space a geometry would take in a column considering compression, so may be lower than ST_MemSize</para>
- </note>
-
- <para>&Z_support;</para>
- <para>&curve_support;</para>
- <para>&P_support;</para>
- <para>&T_support;</para>
- <para>Changed: 2.2.0 name changed to ST_MemSize to follow naming convention. In prior versions this function was called ST_Mem_Size, old name deprecated though still available.</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>
---Return how much byte space Boston takes up in our Mass data set
-SELECT pg_size_pretty(SUM(ST_MemSize(the_geom))) as totgeomsum,
-pg_size_pretty(SUM(CASE WHEN town = 'BOSTON' THEN ST_MemSize(the_geom) ELSE 0 END)) As bossum,
-CAST(SUM(CASE WHEN town = 'BOSTON' THEN ST_MemSize(the_geom) ELSE 0 END)*1.00 /
- SUM(ST_MemSize(the_geom))*100 As numeric(10,2)) As perbos
-FROM towns;
-
-totgeomsum bossum perbos
----------- ------ ------
-1522 kB 30 kB 1.99
-
-
-SELECT ST_MemSize(ST_GeomFromText('CIRCULARSTRING(220268 150415,220227 150505,220227 150406)'));
-
----
-73
-
---What percentage of our table is taken up by just the geometry
-SELECT pg_total_relation_size('public.neighborhoods') As fulltable_size, sum(ST_MemSize(the_geom)) As geomsize,
-sum(ST_MemSize(the_geom))*1.00/pg_total_relation_size('public.neighborhoods')*100 As pergeom
-FROM neighborhoods;
-fulltable_size geomsize pergeom
-------------------------------------------------
-262144 96238 36.71188354492187500000
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para></para>
- </refsection>
- </refentry>
-
- <refentry id="ST_Point_Inside_Circle">
- <refnamediv>
- <refname>ST_PointInsideCircle</refname>
-
- <refpurpose>Is the point geometry inside the circle defined by center_x, center_y, radius</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>boolean <function>ST_PointInsideCircle</function></funcdef>
- <paramdef><type>geometry </type> <parameter>a_point</parameter></paramdef>
- <paramdef><type>float </type> <parameter>center_x</parameter></paramdef>
- <paramdef><type>float </type> <parameter>center_y</parameter></paramdef>
- <paramdef><type>float </type> <parameter>radius</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>The syntax for this functions is
- ST_PointInsideCircle(<geometry>,<circle_center_x>,<circle_center_y>,<radius>).
- Returns the true if the geometry is a point and is inside the
- circle. Returns false otherwise.</para>
- <note><para>This only works for points as the name suggests</para></note>
-
- <para>Availability: 1.2</para>
- <para>Changed: 2.2.0 In prior versions this used to be called ST_Point_Inside_Circle</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT ST_PointInsideCircle(ST_Point(1,2), 0.5, 2, 3);
- st_pointinsidecircle
-------------------------
- t
-</programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_DWithin" /></para>
- </refsection>
- </refentry>
-
-
</sect1>
<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="Geometry_Processing">
<title>Geometry Processing</title>
+
+ <refentry id="ST_Accum">
+ <refnamediv>
+ <refname>ST_Accum</refname>
+
+ <refpurpose>An aggregate function to construct an array of geometries.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry[] <function>ST_Accum</function></funcdef>
+ <paramdef><type>geometry set</type> <parameter>geomfield</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>An aggregate function to construct an array of geometries.</para>
+ <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
+ <para>&Z_support;</para>
+ <para>&curve_support;</para>
+ <para>&P_support;</para>
+ <para>&T_support;</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT (ST_Accum(the_geom)) As all_em, ST_AsText((ST_Accum(the_geom))[1]) As grabone,
+(ST_Accum(the_geom))[2:4] as grab_rest
+ FROM (SELECT ST_MakePoint(a*CAST(random()*10 As integer), a*CAST(random()*10 As integer), a*CAST(random()*10 As integer)) As the_geom
+ FROM generate_series(1,4) a) As foo;
+
+all_em|grabone | grab_rest
+
+-------------------------------------------------------------------------------+
+
+ {0101000080000000000000144000000000000024400000000000001040:
+ 0101000080000000000
+00018400000000000002C400000000000003040:
+0101000080000000000000354000000000000038400000000000001840:
+010100008000000000000040400000000000003C400000000000003040} |
+ POINT(5 10) | {010100008000000000000018400000000000002C400000000000003040:
+ 0101000080000000000000354000000000000038400000000000001840:
+ 010100008000000000000040400000000000003C400000000000003040}
+(1 row)
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_Collect" /></para>
+ </refsection>
+ </refentry>
+
<refentry id="ST_Buffer">
<refnamediv>
<refname>ST_Buffer</refname>
<sect1info>
<abstract>
<para>
- SFCGAL is a C++ wrapper library around CGAL that provides advanced 2D and 3D functions.
- For robustness, geometry coordinates have an exact rational number representation.
+ SFCGAL is a C++ wrapper library around CGAL that provides advanced 2D and 3D spatial functions.
+ For robustness, geometry coordinates have an exact rational number representation.
</para>
<para>
- Installation instructions of the library can be found on SFCGAL home page <ulink url="http://www.sfcgal.org">http://www.sfcgal.org</ulink>.
- To load the functions create extension postgis_sfcgal.
+ Installation instructions for the library can be found on the SFCGAL home page (<ulink url="http://www.sfcgal.org">http://www.sfcgal.org</ulink>).
+ To enable the functions use <code>create extension postgis_sfcgal</code>.
</para>
</abstract>
<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="Temporal">
- <title>Temporal Support</title>
+ <sect1info>
+ <abstract>
+ <para>These functions support working with trajectories.
+ A trajectory is a linear geometry with a measure (M value) on each coordinate.
+ The measure values must increase along the line.
+ Spatio-temporal data can be modelled by using relative times (such as the epoch)
+ as the measure values.
+ </para>
+ </abstract>
+ </sect1info>
+ <title>Trajectory Functions</title>
<refentry id="ST_IsValidTrajectory">
<refsection>
<title>Description</title>
-
<para>
-Tell if a geometry encodes a valid trajectory.
-Valid trajectories are encoded as LINESTRING with M value growing
-from each vertex to the next.
+Tests if a geometry encodes a valid trajectory.
+A valid trajectory is represented as a <varname>LINESTRING</varname>
+with measures (M values).
+The measure values must increase from each vertex to the next.
</para>
-
<para>
-Valid trajectories are expected as input to some spatio-temporal queries
+Valid trajectories are expected as input to spatio-temporal functions
like <xref linkend="ST_ClosestPointOfApproach" />
</para>
-
<para>Availability: 2.2.0</para>
<para>&Z_support;</para>
</refsection>
</programlisting>
</refsection>
- <!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para>
<refnamediv>
<refname>ST_ClosestPointOfApproach</refname>
<refpurpose>
-Returns the measure at which points interpolated along two lines are closest.
+Returns the measure at which points interpolated along two trajectories are closest.
</refpurpose>
</refnamediv>
<title>Description</title>
<para>
-Returns the smallest measure at which point interpolated along the given
-lines are at the smallest distance. Inputs must be valid trajectories as
+Returns the smallest measure at which points interpolated along the given
+trajectories are at the smallest distance.
+ </para>
+ <para>
+Inputs must be valid trajectories as
checked by <xref linkend="ST_IsValidTrajectory" />. Null is returned if
-the trajectories do not overlap on the M range.
+the trajectories do not overlap in their M ranges.
</para>
<para>
<para>&Z_support;</para>
</refsection>
-
<refsection>
<title>Examples</title>
<programlisting>
</programlisting>
</refsection>
- <!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para>
<refnamediv>
<refname>ST_DistanceCPA</refname>
<refpurpose>
-Returns the distance between closest points of approach in two trajectories.
+Returns the distance between the closest point of approach of two trajectories.
</refpurpose>
</refnamediv>
<title>Description</title>
<para>
-Returns the minimum distance two moving objects have ever been each-other.
+Returns the minimum distance two moving objects have ever been each other.
+ </para>
+ <para>
Inputs must be valid trajectories as checked by
<xref linkend="ST_IsValidTrajectory" />.
-Null is returned if the trajectories do not overlap on the M range.
+Null is returned if the trajectories do not overlap in their M ranges.
</para>
<para>Availability: 2.2.0</para>
</programlisting>
</refsection>
- <!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para>
<refnamediv>
<refname>ST_CPAWithin</refname>
<refpurpose>
-Returns true if the trajectories' closest points of approach
-are within the specified distance.
+Returns <varname>true</varname> if the closest point of approach of two trajectories
+is within the specified distance.
</refpurpose>
</refnamediv>
<para>
Checks whether two moving objects have ever been within the
-specified max distance.
+specified maximum distance.
</para>
<para>
Inputs must be valid trajectories as checked by
<xref linkend="ST_IsValidTrajectory" />.
-False is returned if the trajectories do not overlap on the M range.
+False is returned if the trajectories do not overlap in their M ranges.
</para>
<para>Availability: 2.2.0</para>
<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="Long_Transactions_Support">
- <title>Long Transactions Support</title>
+ <sect1info>
+ <abstract>
- <para>This module and associated pl/pgsql functions have been
- implemented to provide long locking support required by <ulink
- url="http://www.opengeospatial.org/standards/wfs">Web Feature Service</ulink> specification.</para>
+ <para>These functions implement locking to support long transactions. This mechanism is required by the
+ <ulink url="http://www.opengeospatial.org/standards/wfs">Web Feature Service</ulink> specification.</para>
+
+ </abstract>
+ </sect1info>
+
+ <title>Long Transaction Support</title>
<note>
- <para>Users must use <ulink
- url="http://www.postgresql.org/docs/current/static/transaction-iso.html">serializable
- transaction level</ulink> otherwise locking mechanism would
- break.</para>
+ <para>For the locking mechanism to operate correctly the <emphasis role="bold">serializable</emphasis>
+ <ulink url="http://www.postgresql.org/docs/current/static/transaction-iso.html">
+ transaction isolation level</ulink> must be used.</para>
</note>
+
<refentry id="AddAuth">
<refnamediv>
<refname>AddAuth</refname>
- <refpurpose>Add an authorization token to be used in current transaction.</refpurpose>
+ <refpurpose>Adds an authorization token to be used in the current transaction.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsection>
<title>Description</title>
- <para>Add an authorization token to be used in current transaction.</para>
+ <para>Adds an authorization token to be used in the current transaction.</para>
- <para>Creates/adds to a temp table called temp_lock_have_table the current transaction identifier
- and authorization token key.</para>
+ <para>Adds the current transaction identifier
+ and authorization token to a temporary table called <varname>temp_lock_have_table</varname>.</para>
<para>Availability: 1.1.3</para>
</refsection>
-
<refsection>
<title>Examples</title>
<refnamediv>
<refname>CheckAuth</refname>
- <refpurpose>Creates trigger on a table to prevent/allow updates and deletes of rows based on authorization token.</refpurpose>
+ <refpurpose>Creates a trigger on a table to prevent/allow updates and deletes of rows based on authorization token.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsection>
<title>Description</title>
- <para>Creates trigger on a table to prevent/allow updates and deletes of rows based on authorization token. Identify rows using <rowid_col> column.</para>
+ <para>Creates trigger on a table to prevent/allow updates and deletes of rows based on an authorization token.
+ Identify rows using <rowid_col> column.</para>
<para>If a_schema_name is not passed in, then searches for table in current schema.</para>
<note><para>If an authorization trigger already exists on this table function errors.</para>
<refnamediv>
<refname>DisableLongTransactions</refname>
- <refpurpose>Disable long transaction support. This function removes the
- long transaction support metadata tables, and drops all triggers
- attached to lock-checked tables.</refpurpose>
+ <refpurpose>Disables long transaction support.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsection>
<title>Description</title>
- <para>Disable long transaction support. This function removes the
+ <para>Disables long transaction support. This function removes the
long transaction support metadata tables, and drops all triggers
attached to lock-checked tables.</para>
<para>Drops meta table called <varname>authorization_table</varname> and a view called <varname>authorized_tables</varname>
<refnamediv>
<refname>EnableLongTransactions</refname>
- <refpurpose>Enable long transaction support. This function creates the
- required metadata tables, needs to be called once before using the
- other functions in this section. Calling it twice is
- harmless.</refpurpose>
+ <refpurpose>Enables long transaction support.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsection>
<title>Description</title>
- <para>Enable long transaction support. This function creates the
- required metadata tables, needs to be called once before using the
+ <para>Enables long transaction support.
+ This function creates the
+ required metadata tables. It must be called once before using the
other functions in this section. Calling it twice is
harmless.</para>
<para>Creates a meta table called <varname>authorization_table</varname> and a view called <varname>authorized_tables</varname></para>
<refnamediv>
<refname>LockRow</refname>
- <refpurpose>Set lock/authorization for specific row in table</refpurpose>
+ <refpurpose>Sets lock/authorization for a row in a table.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsection>
<title>Description</title>
- <para>Set lock/authorization for specific row in table
- <authid> is a text value, <expires> is a timestamp
- defaulting to now()+1hour. Returns 1 if lock has been assigned, 0
- otherwise (already locked by other auth)</para>
+ <para>Sets lock/authorization for a specific row in a table.
+ <varname>an_auth_token</varname> is a text value.
+ <varname>expire_dt</varname> is a timestamp
+ which defaults to <emphasis>now() + 1 hour</emphasis>.
+ Returns 1 if lock has been assigned, 0
+ otherwise (i.e. row is already locked by another auth.)</para>
<para>Availability: 1.1.3</para>
</refsection>
<refnamediv>
<refname>UnlockRows</refname>
- <refpurpose>Remove all locks held by specified authorization id. Returns
- the number of locks released.</refpurpose>
+ <refpurpose>Removes all locks held by an authorization token.
+ </refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsection>
<title>Description</title>
- <para>Remove all locks held by specified authorization id. Returns
- the number of locks released.</para>
+ <para>Removes all locks held by specified authorization token.
+ Returns the number of locks released.</para>
<para>Availability: 1.1.3</para>
</refsection>
projects / postgis / commitdiff