<!-- Converted by db4-upgrade version 1.1 -->
<section xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Overlay_Functions">
    <title>Overlay Functions</title><info>
    <abstract>
    <para>These functions compute results arising from the overlay of two geometries.
    These are also known as point-set theoretic boolean operations.
    Some related functions are also provided.
    </para>
    </abstract>
    </info>



    <refentry xml:id="ST_ClipByBox2D">
      <refnamediv>
        <refname>ST_ClipByBox2D</refname>
        <refpurpose>Computes the portion of a geometry falling within a rectangle.</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <funcsynopsis>
            <funcprototype>
                <funcdef>geometry <function>ST_ClipByBox2D</function></funcdef>
                <paramdef><type>geometry</type> <parameter>geom</parameter></paramdef>
                <paramdef><type>box2d</type> <parameter>box</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
      </refsynopsisdiv>

      <refsection>
        <title>Description</title>

        <para>
        Clips a geometry by a 2D box in a fast and tolerant but possibly invalid way.
        Topologically invalid input geometries do not result in exceptions being thrown.
        The output geometry is not guaranteed to be valid
        (in particular, self-intersections for a polygon may be introduced).
        </para>

        <para>Performed by the GEOS module.</para>

        <para role="availability" conformance="2.2.0">Availability: 2.2.0</para>

      </refsection>

      <refsection>
        <title>Examples</title>
            <programlisting>
-- Rely on implicit cast from geometry to box2d for the second parameter
SELECT ST_ClipByBox2D(geom, ST_MakeEnvelope(0,0,10,10)) FROM mytab;
      </programlisting>
      </refsection>
      <refsection>
        <title>See Also</title>
        <para>
<xref linkend="ST_Intersection"/>,
<xref linkend="ST_MakeBox2D"/>,
<xref linkend="ST_MakeEnvelope"/>
    </para>
      </refsection>
    </refentry>

    <refentry xml:id="ST_Difference">
      <refnamediv>
        <refname>ST_Difference</refname>

        <refpurpose>Computes a geometry representing the part of geometry A
            that does not intersect geometry B.</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <funcsynopsis>
          <funcprototype>
            <funcdef>geometry <function>ST_Difference</function></funcdef>
            <paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
            <paramdef><type>geometry </type> <parameter>geomB</parameter></paramdef>
            <paramdef choice="opt"><type>float8 </type> <parameter>gridSize = -1</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
      </refsynopsisdiv>

      <refsection>
        <title>Description</title>

        <para>Returns a geometry representing the part of geometry A
            that does not intersect geometry B.
            This is equivalent to <code>A - ST_Intersection(A,B)</code>.
            If A is completely contained in B
            then an empty atomic geometry of appropriate type is returned.</para>
        <note><para>This is the only overlay function where input order matters.
            ST_Difference(A, B) always returns a portion of A.</para></note>

            <para>
If the optional <code>gridSize</code> argument is provided, the inputs are
snapped to a grid of the given size, and the result vertices are computed
on that same grid. (Requires GEOS-3.9.0 or higher)
            </para>

        <para>Performed by the GEOS module</para>
        <para role="enhanced" conformance="3.1.0">Enhanced: 3.1.0 accept a gridSize parameter.</para>
        <para role="geos_requirement" conformance="3.9.0">Requires GEOS &gt;= 3.9.0 to use the gridSize parameter.</para>

        <para>&sfs_compliant; s2.1.1.3</para>
        <para>&sqlmm_compliant; SQL-MM 3: 5.1.20</para>
        <para>&Z_support; However, the result is computed using XY only.
            The result Z values are copied, averaged or interpolated.</para>
      </refsection>

      <refsection>
        <title>Examples</title>
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry>
                        <para>
                            <informalfigure>
                                <mediaobject>
                                  <imageobject>
                                    <imagedata fileref="images/st_symdifference01.png"/>
                                  </imageobject>
                                  <caption><para>The input linestrings </para></caption>
                                </mediaobject>
                            </informalfigure>
                        </para>
                    </entry>

                    <entry>
                        <para><informalfigure>
                            <mediaobject>
                              <imageobject>
                                <imagedata fileref="images/st_difference01.png"/>
                              </imageobject>
                              <caption><para>The difference of the two linestrings</para></caption>
                            </mediaobject>
                          </informalfigure>
                    </para>
                </entry>
                  </row>
        </tbody>
    </tgroup>
</informaltable>
<para>The difference of 2D linestrings.</para>
<programlisting>SELECT ST_AsText(
    ST_Difference(
            'LINESTRING(50 100, 50 200)'::geometry,
            'LINESTRING(50 50, 50 150)'::geometry
        )
    );

st_astext
---------
LINESTRING(50 150,50 200)
</programlisting>

<para>The difference of 3D points.</para>
<programlisting>SELECT ST_AsEWKT( ST_Difference(
                   'MULTIPOINT(-118.58 38.38 5,-118.60 38.329 6,-118.614 38.281 7)' :: geometry,
                   'POINT(-118.614 38.281 5)' :: geometry
                  ) );

st_asewkt
---------
MULTIPOINT(-118.6 38.329 6,-118.58 38.38 5)
</programlisting>
      </refsection>

      <refsection>
        <title>See Also</title>

        <para><xref linkend="ST_SymDifference"/>, <xref linkend="ST_Intersection"/>, <xref linkend="ST_Union"/></para>
      </refsection>
    </refentry>

    <refentry xml:id="ST_Intersection">
        <refnamediv>
            <refname>ST_Intersection</refname>

            <refpurpose>
Computes a geometry representing the shared portion of geometries A and B.
            </refpurpose>
        </refnamediv>
        <refsynopsisdiv>
            <funcsynopsis>
                <funcprototype>
                    <funcdef>geometry <function>ST_Intersection</function></funcdef>
                    <paramdef>
                        <type>geometry</type>
                        <parameter>geomA</parameter>
                    </paramdef>
                    <paramdef>
                        <type>geometry</type>
                        <parameter>geomB</parameter>
                    </paramdef>
                    <paramdef choice="opt">
                        <type>float8</type>
                        <parameter>gridSize = -1</parameter>
                    </paramdef>
                </funcprototype>
                <funcprototype>
                    <funcdef>geography <function>ST_Intersection</function></funcdef>
                    <paramdef>
                        <type>geography</type>
                        <parameter>geogA</parameter>
                    </paramdef>
                    <paramdef>
                        <type>geography</type>
                        <parameter>geogB</parameter>
                    </paramdef>
                </funcprototype>
            </funcsynopsis>
        </refsynopsisdiv>
        <refsection>
            <title>Description</title>
            <para>Returns a geometry representing the point-set
                intersection of two geometries.
                In other words, that portion of geometry A and geometry B
                that is shared between the two geometries.</para>

            <para>If the geometries have no points in common (i.e. are disjoint)
            then an empty atomic geometry of appropriate type is returned.</para>

            <para>
If the optional <code>gridSize</code> argument is provided, the inputs are
snapped to a grid of the given size, and the result vertices are computed
on that same grid.  (Requires GEOS-3.9.0 or higher)
            </para>

            <para>ST_Intersection in conjunction with <xref linkend="ST_Intersects"/> is useful for clipping geometries such as in bounding box, buffer, or region
                queries where you only require the portion of a geometry that is inside a country or region of interest.</para>

            <note><para>&geography_transform; It first determines the best SRID that
                    fits the bounding box of the 2 geography objects (if geography objects are within one half zone UTM but not same UTM will pick one of those) (favoring UTM or Lambert Azimuthal Equal Area (LAEA) north/south pole, and falling back on mercator in worst case scenario)  and then intersection in that best fit planar spatial ref and retransforms back to WGS84 geography.</para></note>

        <warning><para>This function will drop the M coordinate values if present.</para></warning>

          <warning><para>If working with 3D geometries, you may want to use SFGCAL based <xref linkend="ST_3DIntersection"/> which does a proper 3D intersection for 3D geometries.  Although this function works with Z-coordinate, it does an averaging of Z-Coordinate.</para></warning>

        <para>Performed by the GEOS module</para>

        <para role="enhanced" conformance="3.1.0">Enhanced: 3.1.0 accept a gridSize parameter</para>
        <para role="geos_requirement" conformance="3.9.0">Requires GEOS &gt;= 3.9.0 to use the gridSize parameter</para>
        <para role="changed" conformance="3.0.0">Changed: 3.0.0 does not depend on SFCGAL.</para>
        <para role="availability" conformance="1.5">Availability: 1.5 support for geography data type was introduced.</para>

        <para>&sfs_compliant; s2.1.1.3</para>
        <para>&sqlmm_compliant; SQL-MM 3: 5.1.18</para>
        <para>&Z_support; However, the result is computed using XY only.
            The result Z values are copied, averaged or interpolated.</para>
        </refsection>
        <refsection>
        <title>Examples</title>
<programlisting>SELECT ST_AsText(ST_Intersection('POINT(0 0)'::geometry, 'LINESTRING ( 2 0, 0 2 )'::geometry));
 st_astext
---------------
GEOMETRYCOLLECTION EMPTY

SELECT ST_AsText(ST_Intersection('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry));
 st_astext
---------------
POINT(0 0)</programlisting>
<para>
Clip all lines (trails) by country. Here we assume country geom are POLYGON or MULTIPOLYGONS.
NOTE: we are only keeping intersections that result in a LINESTRING or MULTILINESTRING because we don't
care about trails that just share a point. The dump is needed to expand a geometry collection into individual single MULT* parts.
The below is fairly generic and will work for polys, etc. by just changing the where clause.</para>
<programlisting>select clipped.gid, clipped.f_name, clipped_geom
from (
         select trails.gid, trails.f_name,
             (ST_Dump(ST_Intersection(country.geom, trails.geom))).geom clipped_geom
         from country
              inner join trails on ST_Intersects(country.geom, trails.geom)
     ) as clipped
where ST_Dimension(clipped.clipped_geom) = 1;</programlisting>
<para>For polys e.g. polygon landmarks, you can also use the sometimes faster hack that buffering anything by 0.0 except a polygon results in an empty geometry collection.
(So a geometry collection containing polys, lines and points buffered by 0.0 would only leave the polygons and dissolve the collection shell.)</para>
<programlisting>select poly.gid,
    ST_Multi(
        ST_Buffer(
            ST_Intersection(country.geom, poly.geom),
            0.0
        )
    ) clipped_geom
from country
     inner join poly on ST_Intersects(country.geom, poly.geom)
where not ST_IsEmpty(ST_Buffer(ST_Intersection(country.geom, poly.geom), 0.0));</programlisting>
        </refsection>

        <refsection>
        <title>Examples: 2.5Dish</title>
        <para>Note this is not a true intersection, compare to the same example using <xref linkend="ST_3DIntersection"/>.</para>
        <programlisting>
select ST_AsText(ST_Intersection(linestring, polygon)) As wkt
from  ST_GeomFromText('LINESTRING Z (2 2 6,1.5 1.5 7,1 1 8,0.5 0.5 8,0 0 10)') AS linestring
 CROSS JOIN ST_GeomFromText('POLYGON((0 0 8, 0 1 8, 1 1 8, 1 0 8, 0 0 8))') AS polygon;

               st_astext
---------------------------------------
 LINESTRING Z (1 1 8,0.5 0.5 8,0 0 10)
        </programlisting>
      </refsection>
        <refsection>
            <title>See Also</title>
            <para><xref linkend="ST_3DIntersection"/>, <xref linkend="ST_Difference"/>, <xref linkend="ST_Union"/>, <xref linkend="ST_Dimension"/>, <xref linkend="ST_Dump"/>, <xref linkend="ST_Force2D"/>, <xref linkend="ST_SymDifference"/>, <xref linkend="ST_Intersects"/>, <xref linkend="ST_Multi"/></para>
        </refsection>
    </refentry>


    <refentry xml:id="ST_MemUnion">
      <refnamediv>
        <refname>ST_MemUnion</refname>

        <refpurpose>Aggregate function which unions geometries in a memory-efficent but slower way</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <funcsynopsis>
          <funcprototype>
            <funcdef>geometry <function>ST_MemUnion</function></funcdef>
            <paramdef><type>geometry set</type> <parameter>geomfield</parameter></paramdef>
          </funcprototype>

        </funcsynopsis>
      </refsynopsisdiv>

      <refsection>
        <title>Description</title>

    <para>An aggregate function that unions the input geometries, merging them to produce a result geometry
        with no overlaps.
        The output may be a single geometry, a MultiGeometry, or a Geometry Collection.
        </para>

        <note>
          <para>Produces the same result as <xref linkend="ST_Union"/>, but uses less memory
            and more processor time.
            This aggregate function works by unioning the geometries incrementally, as opposed to
            the ST_Union aggregate which first accumulates an array and then unions the contents
            using a fast algorithm.</para>
        </note>

        <para>&Z_support; However, the result is computed using XY only.
            The result Z values are copied, averaged or interpolated.</para>
      </refsection>


      <refsection>
        <title>Examples</title>

            <programlisting>
SELECT id,
       ST_MemUnion(geom) as singlegeom
FROM sometable f
GROUP BY id;
</programlisting>
      </refsection>

      <!-- Optionally add a "See Also" section -->
      <refsection>
        <title>See Also</title>

        <para><xref linkend="ST_Union"/></para>
      </refsection>
    </refentry>

    <refentry xml:id="ST_Node">
      <refnamediv>
        <refname>ST_Node</refname>

        <refpurpose>
Nodes a collection of lines.
        </refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <funcsynopsis>
          <funcprototype>
            <funcdef>geometry <function>ST_Node</function></funcdef>
            <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
          </funcprototype>

        </funcsynopsis>
      </refsynopsisdiv>

      <refsection>
        <title>Description</title>

        <para>
Returns a (Multi)LineString representing the fully noded version of a collection of linestrings.
The noding preserves all of the input nodes,
and introduces the least possible number of new nodes.
The resulting linework is dissolved (duplicate lines are removed).
        </para>

        <para>This is a good way to create fully-noded linework suitable for use as input to <xref linkend="ST_Polygonize"/>.</para>

        <para><xref linkend="ST_UnaryUnion"/> can also be used to node and dissolve linework.
        It provides an option to specify a gridSize, which can provide simpler and more robust output.
        See also <xref linkend="ST_Union"/> for an aggregate variant.
        </para>

        <para>&Z_support;</para>
        <para>Performed by the GEOS module.</para>
        <para role="availability" conformance="2.0.0">Availability: 2.0.0</para>

        <para role="changed" conformance="2.4.0">
Changed: 2.4.0 this function uses GEOSNode internally instead of GEOSUnaryUnion.
This may cause the resulting linestrings to have a different order and direction compared to PostGIS &lt; 2.4.
        </para>
      </refsection>
      <refsection>
        <title>Examples</title>
        <para>Noding a 3D LineString which self-intersects</para>
        <programlisting>
SELECT ST_AsText(
        ST_Node('LINESTRINGZ(0 0 0, 10 10 10, 0 10 5, 10 0 3)'::geometry)
    ) As  output;
output
-----------
MULTILINESTRING Z ((0 0 0,5 5 4.5),(5 5 4.5,10 10 10,0 10 5,5 5 4.5),(5 5 4.5,10 0 3))
        </programlisting>

        <para>Noding two LineStrings which share common linework.
        Note that the result linework is dissolved.</para>
        <programlisting>
SELECT ST_AsText(
        ST_Node('MULTILINESTRING ((2 5, 2 1, 7 1), (6 1, 4 1, 2 3, 2 5))'::geometry)
    ) As  output;
output
-----------
MULTILINESTRING((2 5,2 3),(2 3,2 1,4 1),(4 1,2 3),(4 1,6 1),(6 1,7 1))
        </programlisting>

      </refsection>

      <!-- Optionally add a "See Also" section -->
      <refsection>
        <title>See Also</title>

        <para>
            <xref linkend="ST_UnaryUnion"/>, <xref linkend="ST_Union"/>
        </para>
      </refsection>
    </refentry>

    <refentry xml:id="ST_Split">
        <refnamediv>
            <refname>ST_Split</refname>
            <refpurpose>Returns a collection of geometries created by splitting a geometry by another geometry.</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
            <funcsynopsis>
              <funcprototype>
                <funcdef>geometry <function>ST_Split</function></funcdef>
                <paramdef><type>geometry</type> <parameter>input</parameter></paramdef>
                <paramdef><type>geometry</type> <parameter>blade</parameter></paramdef>
              </funcprototype>
            </funcsynopsis>
        </refsynopsisdiv>

        <refsection>
            <title>Description</title>
            <para>
            The function supports splitting a LineString by a (Multi)Point, (Multi)LineString or (Multi)Polygon boundary,
            or a (Multi)Polygon by a LineString.
            When a (Multi)Polygon is used as as the blade, its linear components
            (the boundary) are used for splitting the input.
            The result geometry is always a collection.
            </para>

            <para>
            This function is in a sense the opposite of <xref linkend="ST_Union"/>.
            Applying ST_Union to the returned collection should theoretically yield the original geometry
            (although due to numerical rounding this may not be exactly the case).
            </para>

            <note><para>
            If the the input and blade do not intersect due to numerical precision issues,
            the input may not be split as expected.
            To avoid this situation it may be necessary
            to snap the input to the blade first, using <xref linkend="ST_Snap"/> with a small tolerance.
            </para></note>

            <para role="availability" conformance="2.0.0">Availability: 2.0.0 requires GEOS</para>
            <para role="enhanced" conformance="2.2.0">Enhanced: 2.2.0 support for splitting a line by a multiline, a multipoint or (multi)polygon boundary was introduced.</para>
            <para role="enhanced" conformance="2.5.0">Enhanced: 2.5.0 support for splitting a polygon by a multiline was introduced.</para>

        </refsection>
        <refsection>
            <title>Examples</title>
            <para>Split a Polygon by a Line.</para>
            <informaltable>
                <tgroup cols="2">
                    <tbody>
                      <row>
                        <entry>
                                               <para>
                            <informalfigure>
                            <mediaobject>
                              <imageobject>
                                <imagedata fileref="images/st_split01.png"/>
                              </imageobject>
                              <caption><para>Before Split</para></caption>
                            </mediaobject>
                            </informalfigure>
                                               </para>
                        </entry>
                        <entry>
                                               <para>
                            <informalfigure>
                            <mediaobject>
                              <imageobject>
                                <imagedata fileref="images/st_split02.png"/>
                              </imageobject>
                              <caption><para>After split</para></caption>
                            </mediaobject>
                            </informalfigure>
                                              </para>
                        </entry>
                    </row>
                    </tbody>
                </tgroup>
            </informaltable>
            <programlisting>
SELECT ST_AsText( ST_Split(
                ST_Buffer(ST_GeomFromText('POINT(100 90)'), 50), -- circle
                ST_MakeLine(ST_Point(10, 10),ST_Point(190, 190)) -- line
    ));

-- result --
 GEOMETRYCOLLECTION(
            POLYGON((150 90,149.039264020162 80.2454838991936,146.193976625564 70.8658283817455,..),
            POLYGON(..))
)
            </programlisting>
            <para>Split a MultiLineString by a Point, where the point lies exactly on both LineStrings elements.</para>
            <informaltable>
                <tgroup cols="2">
                    <tbody>
                      <row>
                        <entry>
                                               <para>
                            <informalfigure>
                            <mediaobject>
                              <imageobject>
                                <imagedata fileref="images/st_split03.png"/>
                              </imageobject>
                              <caption><para>Before Split</para></caption>
                            </mediaobject>
                            </informalfigure>
                                               </para>
                        </entry>
                        <entry>
                                               <para>
                            <informalfigure>
                            <mediaobject>
                              <imageobject>
                                <imagedata fileref="images/st_split04.png"/>
                              </imageobject>
                              <caption><para>After split</para></caption>
                            </mediaobject>
                            </informalfigure>
                                               </para>
                        </entry>
                    </row>
                    </tbody>
                </tgroup>
            </informaltable>
            <programlisting>
SELECT ST_AsText(ST_Split(
    'MULTILINESTRING((10 10, 190 190), (15 15, 30 30, 100 90))',
    ST_Point(30,30))) As split;

split
------
GEOMETRYCOLLECTION(
    LINESTRING(10 10,30 30),
    LINESTRING(30 30,190 190),
    LINESTRING(15 15,30 30),
    LINESTRING(30 30,100 90)
)
            </programlisting>

        <para>Split a LineString by a Point, where the point does not lie exactly on the line.
        Shows using <xref linkend="ST_Snap"/> to snap the line to the point to allow it to be split.
        </para>
        <programlisting>
WITH data AS (SELECT
  'LINESTRING(0 0, 100 100)'::geometry AS line,
  'POINT(51 50)':: geometry AS point
)
SELECT ST_AsText( ST_Split( ST_Snap(line, point, 1), point)) AS snapped_split,
       ST_AsText( ST_Split(line, point)) AS not_snapped_not_split
       FROM data;

                            snapped_split                            |            not_snapped_not_split
---------------------------------------------------------------------+---------------------------------------------
 GEOMETRYCOLLECTION(LINESTRING(0 0,51 50),LINESTRING(51 50,100 100)) | GEOMETRYCOLLECTION(LINESTRING(0 0,100 100))
</programlisting>
        </refsection>
        <refsection>
        <title>See Also</title>
        <para>
            <xref linkend="ST_Snap"/>, <xref linkend="ST_Union"/>
        </para>
        </refsection>
    </refentry>

   <refentry xml:id="ST_Subdivide">
      <refnamediv>
        <refname>ST_Subdivide</refname>
        <refpurpose>Computes a rectilinear subdivision of a geometry.</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <funcsynopsis>
            <funcprototype>
                <funcdef>setof geometry <function>ST_Subdivide</function></funcdef>
                <paramdef><type>geometry</type> <parameter>geom</parameter></paramdef>
                <paramdef><type>integer</type> <parameter>max_vertices=256</parameter></paramdef>
                <paramdef choice="opt"><type>float8</type> <parameter>gridSize = -1</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>

      <refsection>
        <title>Description</title>

        <para>
            Returns a set of geometries that are the result of dividing <varname>geom</varname>
            into parts using rectilinear lines,
            with each part containing no more than <code>max_vertices</code>.
        </para>
        <para>
            <code>max_vertices</code> must be 5 or more, as 5 points are needed to represent a closed box.
            <code>gridSize</code> can be specified to have clipping work in fixed-precision space (requires GEOS-3.9.0+).
        </para>
        <para>
            Point-in-polygon and other spatial operations are normally faster for indexed subdivided datasets.
            Since the bounding boxes for the parts usually cover a smaller area than the original geometry bbox,
            index queries produce fewer "hit" cases.
            The "hit" cases are faster because the spatial operations
            executed by the index recheck process fewer points.
        </para>
        <note><para>
            This is a <link xlink:href="https://www.postgresql.org/docs/current/queries-table-expressions.html#QUERIES-TABLEFUNCTIONS">set-returning function</link>
            (SRF) that return a set of rows containing single geometry values.
            It can be used in a SELECT list or a FROM clause
            to produce a result set with one record for each result geometry.
        </para></note>

        <para>Performed by the GEOS module.</para>
        <para role="availability" conformance="2.2.0">Availability: 2.2.0</para>
        <para role="enhanced" conformance="2.5.0">Enhanced: 2.5.0 reuses existing points on polygon split, vertex count is lowered from 8 to 5.</para>
        <para role="enhanced" conformance="3.1.0">Enhanced: 3.1.0 accept a gridSize parameter.</para>
        <para role="geos_requirement" conformance="3.9.0">Requires GEOS &gt;= 3.9.0 to use the gridSize parameter</para>
      </refsection>

      <refsection>
        <title>Examples</title>

        <para><emphasis role="bold">Example:</emphasis>
        Subdivide a polygon into parts with no more than 10 vertices,
        and assign each part a unique id.
        </para>

        <informalfigure>
            <mediaobject>
                <imageobject>
                <imagedata fileref="images/st_subdivide01.png"/>
                </imageobject>
                <caption><para>Subdivided to maximum 10 vertices</para></caption>
            </mediaobject>
            </informalfigure>
<programlisting>
SELECT row_number() OVER() As rn, ST_AsText(geom) As wkt
    FROM (SELECT ST_SubDivide(
        'POLYGON((132 10,119 23,85 35,68 29,66 28,49 42,32 56,22 64,32 110,40 119,36 150,
        57 158,75 171,92 182,114 184,132 186,146 178,176 184,179 162,184 141,190 122,
        190 100,185 79,186 56,186 52,178 34,168 18,147 13,132 10))'::geometry,10))  AS f(geom);
</programlisting>
<screen> rn │                                                      wkt
────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  1 │ POLYGON((119 23,85 35,68 29,66 28,32 56,22 64,29.8260869565217 100,119 100,119 23))
  2 │ POLYGON((132 10,119 23,119 56,186 56,186 52,178 34,168 18,147 13,132 10))
  3 │ POLYGON((119 56,119 100,190 100,185 79,186 56,119 56))
  4 │ POLYGON((29.8260869565217 100,32 110,40 119,36 150,57 158,75 171,92 182,114 184,114 100,29.8260869565217 100))
  5 │ POLYGON((114 184,132 186,146 178,176 184,179 162,184 141,190 122,190 100,114 100,114 184))
  </screen>

        <para><emphasis role="bold">Example:</emphasis>
        Densify a long geography line using ST_Segmentize(geography, distance),
        and use ST_Subdivide to split the resulting line into sublines of 8 vertices.
        </para>
        <informalfigure>
            <mediaobject>
                <imageobject>
                <imagedata fileref="images/st_subdivide02.png"/>
                </imageobject>
                <caption><para>The densified and split lines.</para></caption>
            </mediaobject>
            </informalfigure>
<programlisting>
SELECT ST_AsText( ST_Subdivide(
            ST_Segmentize('LINESTRING(0 0, 85 85)'::geography,
                          1200000)::geometry,    8));
</programlisting>
<screen>
LINESTRING(0 0,0.487578359029357 5.57659056746196,0.984542144675897 11.1527721155093,1.50101059639722 16.7281035483571,1.94532113630331 21.25)
LINESTRING(1.94532113630331 21.25,2.04869538062779 22.3020741387339,2.64204641967673 27.8740533545155,3.29994062412787 33.443216802941,4.04836719489742 39.0084282520239,4.59890468420694 42.5)
LINESTRING(4.59890468420694 42.5,4.92498503922732 44.5680389206321,5.98737409390639 50.1195229244701,7.3290919767674 55.6587646879025,8.79638749938413 60.1969505994924)
LINESTRING(8.79638749938413 60.1969505994924,9.11375579533779 61.1785363177625,11.6558166691368 66.6648504160202,15.642041247655 72.0867690601745,22.8716627200212 77.3609628116894,24.6991785131552 77.8939011989848)
LINESTRING(24.6991785131552 77.8939011989848,39.4046096622744 82.1822848017636,44.7994523421035 82.5156766227011)
LINESTRING(44.7994523421035 82.5156766227011,85 85)
</screen>

        <para><emphasis role="bold">Example:</emphasis>
        Subdivide the complex geometries of a table in-place.
        The original geometry records are deleted from the source table,
        and new records for each subdivided result geometry are inserted.
        </para>

<programlisting><![CDATA[

WITH complex_areas_to_subdivide AS (
    DELETE from polygons_table
    WHERE ST_NPoints(geom) > 255
    RETURNING id, column1, column2, column3, geom
)
INSERT INTO polygons_table (fid, column1, column2, column3, geom)
    SELECT fid, column1, column2, column3,
           ST_Subdivide(geom, 255) as geom
    FROM complex_areas_to_subdivide;

]]></programlisting>

        <para><emphasis role="bold">Example:</emphasis>
        Create a new table containing subdivided geometries,
        retaining the key of the original geometry so that the new table
        can be joined to the source table.
        Since ST_Subdivide is a set-returning (table) function
        that returns a set of single-value rows,
        this syntax automatically produces a table with one row for each result part.
        </para>

<programlisting>
CREATE TABLE subdivided_geoms AS
    SELECT pkey, ST_Subdivide(geom) AS geom
    FROM original_geoms;
</programlisting>

      </refsection>
      <refsection>
        <title>See Also</title>
        <para>
<xref linkend="ST_ClipByBox2D"/>,
<xref linkend="ST_Segmentize"/>,
<xref linkend="ST_Split"/>,
<xref linkend="ST_NPoints"/>
    </para>
      </refsection>
    </refentry>

    <refentry xml:id="ST_SymDifference">
      <refnamediv>
        <refname>ST_SymDifference</refname>

        <refpurpose>Computes a geometry representing the portions of geometries A and B
            that do not intersect.</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <funcsynopsis>
          <funcprototype>
            <funcdef>geometry <function>ST_SymDifference</function></funcdef>
            <paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
            <paramdef><type>geometry </type> <parameter>geomB</parameter></paramdef>
            <paramdef choice="opt"><type>float8 </type> <parameter>gridSize = -1</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
      </refsynopsisdiv>

      <refsection>
        <title>Description</title>

        <para>Returns a geometry representing the portions of geonetries A and B
            that do not intersect.
            This is equivalent to <code>ST_Union(A,B) - ST_Intersection(A,B)</code>.
            It is called a symmetric difference because <code>ST_SymDifference(A,B) = ST_SymDifference(B,A)</code>.
            </para>

            <para>
If the optional <code>gridSize</code> argument is provided, the inputs are
snapped to a grid of the given size, and the result vertices are computed
on that same grid. (Requires GEOS-3.9.0 or higher)
            </para>

        <para>Performed by the GEOS module</para>

        <para role="enhanced" conformance="3.1.0">Enhanced: 3.1.0 accept a gridSize parameter.</para>
        <para role="geos_requirement" conformance="3.9.0">Requires GEOS &gt;= 3.9.0 to use the gridSize parameter</para>

        <para>&sfs_compliant; s2.1.1.3</para>
        <para>&sqlmm_compliant; SQL-MM 3: 5.1.21</para>
        <para>&Z_support; However, the result is computed using XY only.
            The result Z values are copied, averaged or interpolated.</para>
      </refsection>


      <refsection>
        <title>Examples</title>

        <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry>
                        <para>
                            <informalfigure>
                                <mediaobject>
                                  <imageobject>
                                    <imagedata fileref="images/st_symdifference01.png"/>
                                  </imageobject>
                                  <caption><para>The original linestrings shown together</para></caption>
                                </mediaobject>
                            </informalfigure>
                        </para>
                    </entry>

                    <entry>
                        <para><informalfigure>
                            <mediaobject>
                              <imageobject>
                                <imagedata fileref="images/st_symdifference02.png"/>
                              </imageobject>
                              <caption><para>The symmetric difference of the two linestrings</para></caption>
                            </mediaobject>
                          </informalfigure>
                    </para>
                </entry>
                  </row>
        </tbody>
    </tgroup>
</informaltable>
<programlisting>
--Safe for 2d - symmetric difference of 2 linestrings
SELECT ST_AsText(
    ST_SymDifference(
        ST_GeomFromText('LINESTRING(50 100, 50 200)'),
        ST_GeomFromText('LINESTRING(50 50, 50 150)')
    )
);

st_astext
---------
MULTILINESTRING((50 150,50 200),(50 50,50 100))
</programlisting>

<programlisting>

--When used in 3d doesn't quite do the right thing
SELECT ST_AsEWKT(ST_SymDifference(ST_GeomFromEWKT('LINESTRING(1 2 1, 1 4 2)'),
    ST_GeomFromEWKT('LINESTRING(1 1 3, 1 3 4)')))

st_astext
------------
MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
        </programlisting>
      </refsection>

      <!-- Optionally add a "See Also" section -->
      <refsection>
        <title>See Also</title>

        <para><xref linkend="ST_Difference"/>, <xref linkend="ST_Intersection"/>, <xref linkend="ST_Union"/></para>
      </refsection>
</refentry>

    <refentry xml:id="ST_UnaryUnion">
      <refnamediv>
        <refname>ST_UnaryUnion</refname>

        <refpurpose>Computes the union of the components of a single geometry.</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <funcsynopsis>
          <funcprototype>
            <funcdef>geometry <function>ST_UnaryUnion</function></funcdef>
            <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
            <paramdef choice="opt"><type>float8 </type> <parameter>gridSize = -1</parameter></paramdef>
          </funcprototype>

        </funcsynopsis>
      </refsynopsisdiv>

      <refsection>
        <title>Description</title>

        <para>
        A single-input variant of <xref linkend="ST_Union"/>.
        The input may be a single geometry, a MultiGeometry, or a GeometryCollection.
        The union is applied to the individual elements of the input.
        </para>
        <para>
        This function can be used to fix MultiPolygons which  are
        invalid due to overlapping components.
        However, the input components must each be valid.
        An invalid input component such as a bow-tie polygon may cause an error.
        For this reason it may be better to use <xref linkend="ST_MakeValid"/>.
        </para>

        <para>
        Another use of this function is to node and dissolve a collection of
        linestrings which cross or overlap
        to make them <link linkend="Simple_Geometry">simple</link>.
        (<xref linkend="ST_Node"/> also does this,
        but it does not provide the <code>gridSize</code> option.)
        </para>

        <para>
        It is possible to combine ST_UnaryUnion with <xref linkend="ST_Collect"/> to fine-tune
        how many geometries are be unioned at once.
        This allows trading off between memory usage and compute time,
        striking a balance between ST_Union and <xref linkend="ST_MemUnion"/>.
        </para>

        <para>
        If the optional <code>gridSize</code> argument is provided, the inputs are
        snapped to a grid of the given size, and the result vertices are computed
        on that same grid. (Requires GEOS-3.9.0 or higher)
        </para>

        <para>&Z_support; However, the result is computed using XY only.
            The result Z values are copied, averaged or interpolated.</para>
        <para role="enhanced" conformance="3.1.0">Enhanced: 3.1.0 accept a gridSize parameter.</para>
        <para role="geos_requirement" conformance="3.9.0">Requires GEOS &gt;= 3.9.0 to use the gridSize parameter</para>
        <para role="availability" conformance="2.0.0">Availability: 2.0.0</para>

      </refsection>


      <!-- Optionally add a "See Also" section -->
      <refsection>
        <title>See Also</title>

        <para>
            <xref linkend="ST_Union"/>,
            <xref linkend="ST_MemUnion"/>,
            <xref linkend="ST_MakeValid"/>,
            <xref linkend="ST_Collect"/>,
            <xref linkend="ST_Node"/>
        </para>
      </refsection>
    </refentry>

<refentry xml:id="ST_Union">
  <refnamediv>
    <refname>ST_Union</refname>
    <refpurpose>Computes a geometry representing the point-set union of
        the input geometries.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcprototype>
        <funcdef>geometry <function>ST_Union</function></funcdef>
        <paramdef><type>geometry</type> <parameter>g1</parameter></paramdef>
        <paramdef><type>geometry</type> <parameter>g2</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>geometry <function>ST_Union</function></funcdef>
        <paramdef><type>geometry</type> <parameter>g1</parameter></paramdef>
        <paramdef><type>geometry</type> <parameter>g2</parameter></paramdef>
        <paramdef><type>float8</type> <parameter>gridSize</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>geometry <function>ST_Union</function></funcdef>
        <paramdef><type>geometry[]</type> <parameter>g1_array</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>geometry <function>ST_Union</function></funcdef>
        <paramdef><type>geometry set</type> <parameter>g1field</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>geometry <function>ST_Union</function></funcdef>
        <paramdef><type>geometry set</type> <parameter>g1field</parameter></paramdef>
        <paramdef><type>float8</type> <parameter>gridSize</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>
    <para>Unions the input geometries, merging geometry to produce a result geometry
        with no overlaps.
        The output may be an atomic geometry, a MultiGeometry, or a Geometry Collection.
        Comes in several variants:</para>

    <para><emphasis role="bold">Two-input variant:</emphasis>
        returns a geometry that is the union of two input geometries.
        If either input is NULL, then NULL is returned.
        </para>

    <para><emphasis role="bold">Array variant:</emphasis>
        returns a geometry that is the union of an array of geometries.
    </para>

    <para><emphasis role="bold">Aggregate variant:</emphasis>
        returns a geometry that is the union of a rowset of geometries.
        The ST_Union() function is an "aggregate"
        function in the terminology of PostgreSQL. That means that it
        operates on rows of data, in the same way the SUM() and AVG()
        functions do and like most aggregates, it also ignores NULL geometries.</para>

    <para>See <xref linkend="ST_UnaryUnion"/> for a non-aggregate, single-input variant.</para>

    <para>The ST_Union array and set variants use the fast Cascaded Union algorithm described in <link xlink:href="http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html">http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html</link>
    </para>

    <para>A <code>gridSize</code> can be specified to work in fixed-precision space.
        The inputs are snapped to a grid of the given size, and the result vertices are computed
        on that same grid.
        (Requires GEOS-3.9.0 or higher)
    </para>

    <note><para><xref linkend="ST_Collect"/> may sometimes be used in place of ST_Union,
        if the result is not required to be non-overlapping.
        ST_Collect is usually faster than ST_Union because it performs no processing
        on the collected geometries.
        </para></note>

    <para>Performed by the GEOS module.</para>
    <para>ST_Union creates MultiLineString and does not sew LineStrings into a single LineString.
        Use <xref linkend="ST_LineMerge"/> to sew LineStrings.</para>

    <para>NOTE: this function was formerly called GeomUnion(), which
        was renamed from "Union" because UNION is an SQL reserved
        word.</para>

    <para role="enhanced" conformance="3.1.0">Enhanced: 3.1.0 accept a gridSize parameter.</para>
    <para role="geos_requirement" conformance="3.9.0">Requires GEOS &gt;= 3.9.0 to use the gridSize parameter</para>
    <para role="changed" conformance="3.0.0">Changed: 3.0.0 does not depend on SFCGAL.</para>
    <para role="availability" conformance="1.4.0">Availability: 1.4.0 - ST_Union was enhanced. ST_Union(geomarray) was introduced and also faster aggregate collection in PostgreSQL.</para>

    <para>&sfs_compliant; s2.1.1.3</para>
    <note><para>Aggregate version is not explicitly defined in OGC SPEC.</para></note>
    <para>&sqlmm_compliant; SQL-MM 3: 5.1.19
        the z-index (elevation) when polygons are involved.</para>
    <para>&Z_support; However, the result is computed using XY only.
        The result Z values are copied, averaged or interpolated.</para>
      </refsection>

      <refsection>
        <title>Examples</title>
        <para>Aggregate example</para>
            <programlisting>
SELECT id,
       ST_Union(geom) as singlegeom
FROM sometable f
GROUP BY id;
              </programlisting>
        <para>Non-Aggregate example</para>
            <programlisting>
select ST_AsText(ST_Union('POINT(1 2)' :: geometry, 'POINT(-2 3)' :: geometry))

st_astext
----------
MULTIPOINT(-2 3,1 2)

select ST_AsText(ST_Union('POINT(1 2)' :: geometry, 'POINT(1 2)' :: geometry))

st_astext
----------
POINT(1 2)</programlisting>
<para>3D example - sort of supports 3D (and with mixed dimensions!)</para>
<programlisting>select ST_AsEWKT(ST_Union(geom))
from (
         select 'POLYGON((-7 4.2,-7.1 4.2,-7.1 4.3, -7 4.2))'::geometry geom
         union all
         select 'POINT(5 5 5)'::geometry geom
         union all
         select 'POINT(-2 3 1)'::geometry geom
         union all
         select 'LINESTRING(5 5 5, 10 10 10)'::geometry geom
     ) as foo;

st_asewkt
---------
GEOMETRYCOLLECTION(POINT(-2 3 1),LINESTRING(5 5 5,10 10 10),POLYGON((-7 4.2 5,-7.1 4.2 5,-7.1 4.3 5,-7 4.2 5)));
</programlisting>
<para>3d example not mixing dimensions</para>
<programlisting>select ST_AsEWKT(ST_Union(geom))
from (
         select 'POLYGON((-7 4.2 2,-7.1 4.2 3,-7.1 4.3 2, -7 4.2 2))'::geometry geom
         union all
         select 'POINT(5 5 5)'::geometry geom
         union all
         select 'POINT(-2 3 1)'::geometry geom
         union all
         select 'LINESTRING(5 5 5, 10 10 10)'::geometry geom
     ) as foo;

st_asewkt
---------
GEOMETRYCOLLECTION(POINT(-2 3 1),LINESTRING(5 5 5,10 10 10),POLYGON((-7 4.2 2,-7.1 4.2 3,-7.1 4.3 2,-7 4.2 2)))

--Examples using new Array construct
SELECT ST_Union(ARRAY(SELECT geom FROM sometable));

SELECT ST_AsText(ST_Union(ARRAY[ST_GeomFromText('LINESTRING(1 2, 3 4)'),
            ST_GeomFromText('LINESTRING(3 4, 4 5)')])) As wktunion;

--wktunion---
MULTILINESTRING((3 4,4 5),(1 2,3 4))

              </programlisting>
      </refsection>
      <refsection>
        <title>See Also</title>
        <para>
            <xref linkend="ST_Collect"/>,
            <xref linkend="ST_UnaryUnion"/>,
            <xref linkend="ST_MemUnion"/>,
            <xref linkend="ST_Intersection"/>,
            <xref linkend="ST_Difference"/>,
            <xref linkend="ST_SymDifference"/>
        </para>
      </refsection>
    </refentry>

</section>