[postgis-tickets] [SCM] PostGIS branch master updated. 3.1.0alpha1-121-g130fdf6

[git at osgeo.org]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "PostGIS".

The branch, master has been updated
       via  130fdf694621d0406f09f880ec85715f1aa1571f (commit)
      from  4c185f8617824a21f46569170dd16c3427e1b197 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 130fdf694621d0406f09f880ec85715f1aa1571f
Author: Sandro Santilli <strk at kbt.io>
Date:   Fri May 15 16:16:12 2020 +0200

    Add section about managing stats during topology building/editing
    
    And refs to it from TopoGeo_addLineString and TopoGeo_addPolygon

diff --git a/doc/extras_topology.xml b/doc/extras_topology.xml
index 8a3fe0a..8867b04 100644
--- a/doc/extras_topology.xml
+++ b/doc/extras_topology.xml
@@ -643,6 +643,44 @@ face without edges |   0 |
 		</refentry>
 	</sect2>
 
+	<sect2 id="Topology_StatsManagement"
+           xreflabel="maintaining statistics during topology editing and population" >
+	     <sect2info>
+            <abstract>
+                <para>
+This section discusses management of database statistics during
+topology building.
+                </para>
+            </abstract>
+        </sect2info>
+	    <title>Topology Statistics Management</title>
+
+<para>
+Adding elements to a topology triggers many database queries for
+finding existing edges that will be split, adding nodes and and
+updating edges that will node with the new linework. For this reason
+it is useful that statistics about the data in the topology tables
+are up-to-date.
+</para>
+
+<para>
+PostGIS Topology population and editing functions do not automatically
+update the statistics because a updating stats after each and every
+change in a topology would be overkill, so it is the caller's duty
+to take care of that.
+</para>
+
+<note>
+<para>
+That the statistics updated by autovacuum
+will NOT be visible to transactions which started before autovacuum
+process completed, so long-running transactions will need to run
+ANALYZE themeselves, to use updated statistics.
+</para>
+</note>
+
+	</sect2>
+
 	<sect2 id="Topology_Constructors">
     <sect2info>
         <abstract>
@@ -959,6 +997,11 @@ The given line will snap to existing nodes or edges within given tolerance.
 Existing edges and faces may be split by the line.
                 </para>
 
+                <note><para>
+Updating statistics about topologies being loaded via this function is
+up to caller, see <xref linkend="Topology_StatsManagement"/>.
+                </para></note>
+
                 <!-- use this format if new function -->
                 <para>Availability: 2.0.0</para>
 			</refsection>
@@ -1003,6 +1046,11 @@ The boundary of the given polygon will snap to existing nodes or edges within gi
 Existing edges and faces may be split by the boundary of the new polygon.
                 </para>
 
+                <note><para>
+Updating statistics about topologies being loaded via this function is
+up to caller, see <xref linkend="Topology_StatsManagement"/>.
+                </para></note>
+
                 <!-- use this format if new function -->
                 <para>Availability: 2.0.0</para>
 			</refsection>

-----------------------------------------------------------------------

Summary of changes:
 doc/extras_topology.xml | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)


hooks/post-receive
-- 
PostGIS