forked from postgis/postgis
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathextras_topology.xml
3674 lines (3073 loc) · 137 KB
/
extras_topology.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="Topology">
<title>Topology</title>
<para>The PostGIS Topology types and functions are used to manage topological objects such as faces, edges and nodes. </para>
<para>Sandro Santilli's presentation at PostGIS Day Paris 2011 conference gives a good synopsis of PostGIS Topology and where it is headed <ulink url="http://strk.kbt.io/projects/postgis/Paris2011_TopologyWithPostGIS_2_0.pdf">Topology with PostGIS 2.0 slide deck</ulink>.</para>
<para>Vincent Picavet provides a good synopsis and overview of what is Topology, how is it used, and various FOSS4G tools that support it in <ulink url="https://github.com/Oslandia/presentations/blob/master/pgconf_eu_2012/pgconfeu2012_vincent_picavet_postgis_topology.pdf?raw=true">PostGIS Topology PGConf EU 2012</ulink>.</para>
<para>An example of a topologically based GIS database is the <ulink url="https://www.census.gov/geo/maps-data/data/tiger.html">US Census Topologically Integrated Geographic Encoding and Referencing System (TIGER)</ulink> database. If you want to experiment with PostGIS topology and need some data, check out <xref linkend="Topology_Load_Tiger" />.</para>
<para>The PostGIS topology module has existed in prior versions of PostGIS but was never part of the Official PostGIS documentation.
In PostGIS 2.0.0 major cleanup is going on to remove use of all deprecated functions in it, fix known usability issues, better document the features and functions, add new functions, and enhance to closer conform to SQL-MM standards.</para>
<para>Details of this project can be found at <ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiPostgisTopology">PostGIS Topology Wiki</ulink></para>
<para>All functions and tables associated with this module are installed in a schema called <varname>topology</varname>.</para>
<para>Functions that are defined in SQL/MM standard are prefixed with ST_ and functions specific to PostGIS are not prefixed.</para>
<para>Topolgy support is build by default starting with PostGIS 2.0, and can be disabled specifying --without-topology configure option at build time as described in <xref linkend="postgis_installation"/></para>
<sect1 id="Topology_Types">
<sect1info>
<abstract>
<para>This section lists the PostgreSQL data types installed by PostGIS Topology. Note we describe the casting behavior of these which is very
important especially when designing your own functions.
</para>
</abstract>
</sect1info>
<title>Topology Types</title>
<refentry id="getfaceedges_returntype">
<refnamediv>
<refname>getfaceedges_returntype</refname>
<refpurpose>A composite type that consists of a sequence number and edge number. This is the return type for <varname>ST_GetFaceEdges</varname></refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para>A composite type that consists of a sequence number and edge number. This is the return type for <varname>ST_GetFaceEdges</varname> function.</para>
<orderedlist>
<listitem>
<para><varname>sequence</varname> is an integer: Refers to a topology defined in the topology.topology table which defines the topology schema and srid.</para>
</listitem>
<listitem>
<para><varname>edge</varname> is an integer: The identifier of an edge.</para>
</listitem>
</orderedlist>
</refsection>
</refentry>
<refentry id="topogeometry">
<refnamediv>
<refname>TopoGeometry</refname>
<refpurpose>A composite type representing a topologically defined geometry</refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para>A composite type that refers to a topology geometry in a specific topology layer, having a specific type and a specific id. The elements of a TopoGeometry are the properties: topology_id, layer_id, id integer, type integer.</para>
<orderedlist>
<listitem>
<para><varname>topology_id</varname> is an integer: Refers to a topology defined in the topology.topology table which defines the topology schema and srid.</para>
</listitem>
<listitem>
<para><varname>layer_id</varname> is an integer: The layer_id in the layers table that the TopoGeometry belongs to. The combination of topology_id, layer_id provides a unique reference in the topology.layers table.</para>
</listitem>
<listitem>
<para><varname>id</varname> is an integer: The id is the autogenerated sequence number that uniquely defines the topogeometry in the respective topology layer.</para>
</listitem>
<listitem>
<para><varname>type</varname> integer between 1 - 4 that defines the geometry type: 1:[multi]point, 2:[multi]line, 3:[multi]poly, 4:collection</para>
</listitem>
</orderedlist>
</refsection>
<refsection>
<title>Casting Behavior</title>
<para>This section lists the automatic as well as explicit casts allowed for this data type</para>
<informaltable rowsep="1" frame="all">
<tgroup cols="2">
<tbody>
<row>
<entry>Cast To</entry>
<entry>Behavior</entry>
</row>
<row>
<entry>geometry</entry>
<entry>automatic</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="CreateTopoGeom"/></para>
</refsection>
</refentry>
<refentry id="validatetopology_returntype">
<refnamediv>
<refname>validatetopology_returntype</refname>
<refpurpose>A composite type that consists of an error message and id1 and id2 to denote location of error. This is the return type for <varname>ValidateTopology</varname></refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para>A composite type that consists of an error message and two integers. The <xref linkend="ValidateTopology" /> function returns a set of these to denote validation errors and the id1 and id2 to denote the ids of the topology objects involved in the error.</para>
<orderedlist>
<listitem>
<para><varname>error</varname> is varchar: Denotes type of error. </para>
<para>Current error descriptors are: coincident nodes, edge crosses node, edge not simple, edge end node geometry mis-match, edge start node geometry mismatch, face overlaps face,face within face, </para>
</listitem>
<listitem>
<para><varname>id1</varname> is an integer: Denotes identifier of edge / face / nodes in error.</para>
</listitem>
<listitem>
<para><varname>id2</varname> is an integer: For errors that involve 2 objects denotes the secondary edge / or node</para>
</listitem>
</orderedlist>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="ValidateTopology"/></para>
</refsection>
</refentry>
</sect1>
<sect1 id="Topology_Domains">
<sect1info>
<abstract>
<para>This section lists the PostgreSQL domains installed by PostGIS Topology. Domains can be used like object types as return objects of functions or table columns. The distinction between
a domain and a type is that a domain is an existing type with a check constraint bound to it.
</para>
</abstract>
</sect1info>
<title>Topology Domains</title>
<refentry id="topoelement">
<refnamediv>
<refname>TopoElement</refname>
<refpurpose>An array of 2 integers generally used to identify a TopoGeometry component.</refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para>
An array of 2 integers used to represent one component of a simple or
hierarchical <xref linkend="topogeometry" />.
</para>
<para>
In the case of a simple TopoGeometry the first element of the array
represents the identifier of a topological primitive and the second
element represents its type (1:node, 2:edge, 3:face). In the case of a
hierarchical TopoGeometry the first element of the array represents the
identifier of a child TopoGeometry and the second element represents
its layer identifier.
</para>
<note><para>
For any given hierarchical TopoGeometry all child TopoGeometry
elements will come from the same child layer, as specified in
the topology.layer record for the layer of the TopoGeometry
being defined.
</para></note>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
SELECT te[1] AS id, te[2] AS type FROM
( SELECT ARRAY[1,2]::topology.topoelement AS te ) f;
id | type
----+------
1 | 2
</programlisting>
<programlisting>SELECT ARRAY[1,2]::topology.topoelement;
te
-------
{1,2}
</programlisting>
<programlisting>
--Example of what happens when you try to case a 3 element array to topoelement
-- NOTE: topoement has to be a 2 element array so fails dimension check
SELECT ARRAY[1,2,3]::topology.topoelement;
ERROR: value for domain topology.topoelement violates check constraint "dimensions"
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para>
<xref linkend="GetTopoGeomElements"/>,
<xref linkend="topoelementarray" />,
<xref linkend="topogeometry" />,
<xref linkend="TopoGeom_addElement" />,
<xref linkend="TopoGeom_remElement" />
</para>
</refsection>
</refentry>
<refentry id="topoelementarray">
<refnamediv>
<refname>TopoElementArray</refname>
<refpurpose>An array of TopoElement objects</refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para>An array of 1 or more TopoElement objects, generally used to pass around components of TopoGeometry objects.</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT '{{1,2},{4,3}}'::topology.topoelementarray As tea;
tea
-------
{{1,2},{4,3}}
-- more verbose equivalent --
SELECT ARRAY[ARRAY[1,2], ARRAY[4,3]]::topology.topoelementarray As tea;
tea
-------
{{1,2},{4,3}}
--using the array agg function packaged with topology --
SELECT topology.TopoElementArray_Agg(ARRAY[e,t]) As tea
FROM generate_series(1,4) As e CROSS JOIN generate_series(1,3) As t;
tea
--------------------------------------------------------------------------
{{1,1},{1,2},{1,3},{2,1},{2,2},{2,3},{3,1},{3,2},{3,3},{4,1},{4,2},{4,3}}
</programlisting>
<programlisting>SELECT '{{1,2,4},{3,4,5}}'::topology.topoelementarray As tea;
ERROR: value for domain topology.topoelementarray violates check constraint "dimensions"
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para>
<xref linkend="topoelement" />,
<xref linkend="GetTopoGeomElementArray"/>,
<xref linkend="TopoElementArray_Agg" />
</para>
</refsection>
</refentry>
</sect1>
<sect1 id="Topology_ManagementFunctions">
<sect1info>
<abstract>
<para>This section lists the Topology functions for building new Topology schemas, validating topologies, and managing TopoGeometry Columns</para>
</abstract>
</sect1info>
<title>Topology and TopoGeometry Management</title>
<refentry id="AddTopoGeometryColumn">
<refnamediv>
<refname>AddTopoGeometryColumn</refname>
<refpurpose>Adds a topogeometry column to an existing table, registers this new column as a layer in topology.layer and returns the new layer_id.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>AddTopoGeometryColumn</function></funcdef>
<paramdef><type>varchar </type>
<parameter>topology_name</parameter></paramdef>
<paramdef><type>varchar </type>
<parameter>schema_name</parameter></paramdef>
<paramdef><type>varchar </type>
<parameter>table_name</parameter></paramdef>
<paramdef><type>varchar </type>
<parameter>column_name</parameter></paramdef>
<paramdef><type>varchar </type>
<parameter>feature_type</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>integer <function>AddTopoGeometryColumn</function></funcdef>
<paramdef><type>varchar </type>
<parameter>topology_name</parameter></paramdef>
<paramdef><type>varchar </type>
<parameter>schema_name</parameter></paramdef>
<paramdef><type>varchar </type>
<parameter>table_name</parameter></paramdef>
<paramdef><type>varchar </type>
<parameter>column_name</parameter></paramdef>
<paramdef><type>varchar </type>
<parameter>feature_type</parameter></paramdef>
<paramdef><type>integer </type>
<parameter>child_layer</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Each TopoGeometry object belongs to a specific Layer of a specific Topology. Before creating a TopoGeometry object you need to create its TopologyLayer.
A Topology Layer is an association of a feature-table with the topology. It also contain type and hierarchy information. We create a layer using the AddTopoGeometryColumn() function: </para>
<para>This function will both add the requested column to the table and add a record to the topology.layer table with all the given info.</para>
<para>If you don't specify [child_layer] (or set it to NULL) this layer would contain Basic TopoGeometries (composed by primitive topology elements).
Otherwise this layer will contain hierarchical TopoGeometries (composed by TopoGeometries from the child_layer).</para>
<para>Once the layer is created (its id is returned by the AddTopoGeometryColumn function) you're ready to construct TopoGeometry objects in it</para>
<para>Valid <varname>feature_type</varname>s are: POINT, LINE, POLYGON, COLLECTION</para>
<!-- use this format if new function -->
<para>Availability: 1.?</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>-- Note for this example we created our new table in the ma_topo schema
-- though we could have created it in a different schema -- in which case topology_name and schema_name would be different
CREATE SCHEMA ma;
CREATE TABLE ma.parcels(gid serial, parcel_id varchar(20) PRIMARY KEY, address text);
SELECT topology.AddTopoGeometryColumn('ma_topo', 'ma', 'parcels', 'topo', 'POLYGON');</programlisting>
<programlisting>
CREATE SCHEMA ri;
CREATE TABLE ri.roads(gid serial PRIMARY KEY, road_name text);
SELECT topology.AddTopoGeometryColumn('ri_topo', 'ri', 'roads', 'topo', 'LINE');
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="CreateTopology"/>, <xref linkend="CreateTopoGeom"/></para>
</refsection>
</refentry>
<refentry id="DropTopology">
<refnamediv>
<refname>DropTopology</refname>
<refpurpose>Use with caution: Drops a topology schema and deletes its reference from topology.topology table and references to tables in that schema from the geometry_columns table.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>DropTopology</function></funcdef>
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Drops a topology schema and deletes its reference from topology.topology table and references to tables in that schema from the geometry_columns table.
This function should be USED WITH CAUTION, as it could destroy data you care about. If the schema does not exist, it just removes reference entries the named schema.</para>
<!-- use this format if new function -->
<para>Availability: 1.?</para>
</refsection>
<refsection>
<title>Examples</title>
<para>Cascade drops the ma_topo schema and removes all references to it in topology.topology and geometry_columns.</para>
<programlisting>SELECT topology.DropTopology('ma_topo');</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para></para>
</refsection>
</refentry>
<refentry id="DropTopoGeometryColumn">
<refnamediv>
<refname>DropTopoGeometryColumn</refname>
<refpurpose>Drops the topogeometry column from the table named <varname>table_name</varname> in schema <varname>schema_name</varname> and unregisters the columns from topology.layer table.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>text <function>DropTopoGeometryColumn</function></funcdef>
<paramdef><type>varchar </type> <parameter>schema_name</parameter></paramdef>
<paramdef><type>varchar </type> <parameter>table_name</parameter></paramdef>
<paramdef><type>varchar </type> <parameter>column_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Drops the topogeometry column from the table named <varname>table_name</varname> in schema <varname>schema_name</varname> and unregisters the columns from topology.layer table. Returns summary
of drop status. NOTE: it first sets all values to NULL before dropping to bypass referential integrity checks.</para>
<!-- use this format if new function -->
<para>Availability: 1.?</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT topology.DropTopoGeometryColumn('ma_topo', 'parcel_topo', 'topo');</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="AddTopoGeometryColumn"/></para>
</refsection>
</refentry>
<refentry id="Populate_Topology_Layer">
<refnamediv>
<refname>Populate_Topology_Layer</refname>
<refpurpose>Adds missing entries to topology.layer table by reading metadata from topo tables.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>setof record <function>Populate_Topology_Layer</function></funcdef>
<paramdef></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Adds missing entries to the <varname>topology.layer</varname> table by inspecting topology constraints on tables.
This function is useful for fixing up entries in topology catalog after restores of schemas with topo data.</para>
<para>It returns the list of entries created. Returned columns are <varname>schema_name</varname>, <varname>table_name</varname>, <varname>feature_column</varname>.</para>
<!-- use this format if new function -->
<para>Availability: 2.3.0</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT CreateTopology('strk_topo');
CREATE SCHEMA strk;
CREATE TABLE strk.parcels(gid serial, parcel_id varchar(20) PRIMARY KEY, address text);
SELECT topology.AddTopoGeometryColumn('strk_topo', 'strk', 'parcels', 'topo', 'POLYGON');
-- this will return no records because this feature is already registered
SELECT *
FROM topology.Populate_Topology_Layer();
-- let's rebuild
TRUNCATE TABLE topology.layer;
SELECT *
FROM topology.Populate_Topology_Layer();
SELECT topology_id,layer_id, schema_name As sn, table_name As tn, feature_column As fc
FROM topology.layer;
</programlisting>
<screen> schema_name | table_name | feature_column
-------------+------------+----------------
strk | parcels | topo
(1 row)
topology_id | layer_id | sn | tn | fc
-------------+----------+------+---------+------
2 | 2 | strk | parcels | topo
(1 row)</screen>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="AddTopoGeometryColumn"/></para>
</refsection>
</refentry>
<refentry id="TopologySummary">
<refnamediv>
<refname>TopologySummary</refname>
<refpurpose>Takes a topology name and provides summary totals of types of objects in topology</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>text <function>TopologySummary</function></funcdef>
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Takes a topology name and provides summary totals of types of objects in topology.</para>
<!-- use this format if new function -->
<para>Availability: 2.0.0</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT topology.topologysummary('city_data');
topologysummary
--------------------------------------------------------
Topology city_data (329), SRID 4326, precision: 0
22 nodes, 24 edges, 10 faces, 29 topogeoms in 5 layers
Layer 1, type Polygonal (3), 9 topogeoms
Deploy: features.land_parcels.feature
Layer 2, type Puntal (1), 8 topogeoms
Deploy: features.traffic_signs.feature
Layer 3, type Lineal (2), 8 topogeoms
Deploy: features.city_streets.feature
Layer 4, type Polygonal (3), 3 topogeoms
Hierarchy level 1, child layer 1
Deploy: features.big_parcels.feature
Layer 5, type Puntal (1), 1 topogeoms
Hierarchy level 1, child layer 2
Deploy: features.big_signs.feature</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="Topology_Load_Tiger" /></para>
</refsection>
</refentry>
<refentry id="ValidateTopology">
<refnamediv>
<refname>ValidateTopology</refname>
<refpurpose>Returns a set of validatetopology_returntype objects detailing issues with topology</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>setof validatetopology_returntype <function>ValidateTopology</function></funcdef>
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns a set of <xref linkend="validatetopology_returntype"/> objects detailing issues with topology. List of possible errors and what the returned ids represent are displayed below:</para>
<informaltable rowsep="1" frame="all">
<tgroup cols="3">
<thead><row><entry>Error</entry><entry>id1</entry><entry>id2</entry></row></thead>
<tbody>
<row>
<entry>edge crosses node</entry>
<entry>edge_id</entry>
<entry>node_id</entry>
</row>
<row>
<entry>invalid edge</entry>
<entry>edge_id</entry>
<entry>null</entry>
</row>
<row>
<entry>edge not simple</entry>
<entry>edge_id</entry>
<entry>null</entry>
</row>
<row>
<entry>edge crosses edge</entry>
<entry>edge_id</entry>
<entry>edge_id</entry>
</row>
<row>
<entry>edge start node geometry mis-match</entry>
<entry>edge_id</entry>
<entry>node_id</entry>
</row>
<row>
<entry>edge end node geometry mis-match</entry>
<entry>edge_id</entry>
<entry>node_id</entry>
</row>
<row>
<entry>face without edges</entry>
<entry>face_id</entry>
<entry>null</entry>
</row>
<row>
<entry>face has no rings</entry>
<entry>face_id</entry>
<entry>null</entry>
</row>
<row>
<entry>face overlaps face</entry>
<entry>face_id</entry>
<entry>face_id</entry>
</row>
<row>
<entry>face within face</entry>
<entry>inner face_id</entry>
<entry>outer face_id</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<!-- use this format if new function -->
<para>Availability: 1.0.0</para>
<!-- use this format if not a new function but functionality enhanced -->
<para>Enhanced: 2.0.0 more efficient edge crossing detection and fixes for false positives that were existent in prior versions.</para>
<para>Changed: 2.2.0 values for id1 and id2 were swapped for 'edge crosses node' to be consistent with error description.</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT * FROM topology.ValidateTopology('ma_topo');
error | id1 | id2
-------------------+-----+-----
face without edges | 0 |
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="validatetopology_returntype"/>, <xref linkend="Topology_Load_Tiger" /></para>
</refsection>
</refentry>
</sect1>
<sect1 id="Topology_Constructors">
<sect1info>
<abstract>
<para>This section covers the topology functions for creating new topologies.</para>
</abstract>
</sect1info>
<title>Topology Constructors</title>
<refentry id="CreateTopology">
<refnamediv>
<refname>CreateTopology</refname>
<refpurpose>Creates a new topology schema and registers this new schema in the topology.topology table.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>CreateTopology</function></funcdef>
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>integer <function>CreateTopology</function></funcdef>
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
<paramdef><type>integer </type> <parameter>srid</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>integer <function>CreateTopology</function></funcdef>
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
<paramdef><type>integer </type> <parameter>srid</parameter></paramdef>
<paramdef><type>double precision </type> <parameter>prec</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>integer <function>CreateTopology</function></funcdef>
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
<paramdef><type>integer </type> <parameter>srid</parameter></paramdef>
<paramdef><type>double precision </type> <parameter>prec</parameter></paramdef>
<paramdef><type>boolean </type> <parameter>hasz</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Creates a new schema with name <varname>topology_name</varname> consisting of tables (<varname>edge_data</varname>,<varname>face</varname>,<varname>node</varname>, <varname>relation</varname>
and registers this new topology in the topology.topology table. It returns the id of the topology in the topology table. The srid is the spatial reference identified as
defined in spatial_ref_sys table for that topology. Topologies must be uniquely named. The tolerance is measured in the units of the spatial reference system. If the tolerance (<varname>prec</varname>) is not specified defaults to 0.</para>
<para>This is similar to the SQL/MM <xref linkend="ST_InitTopoGeo" /> but a bit more functional. <varname>hasz</varname> defaults to false if not specified.</para>
<!-- use this format if new function -->
<para>Availability: 1.?</para>
</refsection>
<refsection>
<title>Examples</title>
<para>This example creates a new schema called ma_topo that will store edges, faces, and relations in Massachusetts State Plane meters.
The tolerance represents 1/2 meter since the spatial reference system is a meter based spatial reference system</para>
<programlisting>SELECT topology.CreateTopology('ma_topo',26986, 0.5);</programlisting>
<para>Create Rhode Island topology in State Plane ft</para>
<programlisting>SELECT topology.CreateTopology('ri_topo',3438) As topoid;
topoid
------
2</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="spatial_ref_sys"/>, <xref linkend="ST_InitTopoGeo" />, <xref linkend="Topology_Load_Tiger" /></para>
</refsection>
</refentry>
<refentry id="CopyTopology">
<refnamediv>
<refname>CopyTopology</refname>
<refpurpose>Makes a copy of a topology structure (nodes, edges, faces, layers and TopoGeometries).</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>CopyTopology</function></funcdef>
<paramdef><type>varchar </type> <parameter>existing_topology_name</parameter></paramdef>
<paramdef><type>varchar </type> <parameter>new_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
Creates a new topology with name <varname>new_topology_name</varname> and SRID and precision taken from <varname>existing_topology_name</varname>, copies all nodes, edges and faces in there, copies layers and their TopoGeometries too.
</para>
<note><para>
The new rows in topology.layer will contain synthesized values for schema_name, table_name and feature_column. This is because the TopoGeometry will only exist as a definition but won't be available in any user-level table yet.
</para></note>
<!-- use this format if new function -->
<para>Availability: 2.0.0</para>
</refsection>
<refsection>
<title>Examples</title>
<para>
This example makes a backup of a topology called ma_topo
</para>
<programlisting>SELECT topology.CopyTopology('ma_topo', 'ma_topo_bakup');</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="spatial_ref_sys"/>, <xref linkend="CreateTopology" /></para>
</refsection>
</refentry>
<refentry id="ST_InitTopoGeo">
<refnamediv>
<refname>ST_InitTopoGeo</refname>
<refpurpose>Creates a new topology schema and registers this new schema in the topology.topology table and details summary of process.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>text <function>ST_InitTopoGeo</function></funcdef>
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>This is an SQL-MM equivalent of CreateTopology but lacks the spatial reference and tolerance options of CreateTopology and outputs a text description of creation instead of topology id.</para>
<!-- use this format if new function -->
<para>Availability: 1.?</para>
<para>&sqlmm_compliant; SQL-MM 3 Topo-Geo and Topo-Net 3: Routine Details: X.3.17</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT topology.ST_InitTopoGeo('topo_schema_to_create') AS topocreation;
astopocreation
------------------------------------------------------------
Topology-Geometry 'topo_schema_to_create' (id:7) created.
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="CreateTopology"/></para>
</refsection>
</refentry>
<refentry id="ST_CreateTopoGeo">
<refnamediv>
<refname>ST_CreateTopoGeo</refname>
<refpurpose>
Adds a collection of geometries to a given empty topology and returns a message detailing success.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>text <function>ST_CreateTopoGeo</function></funcdef>
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
<paramdef><type>geometry </type> <parameter>acollection</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
Adds a collection of geometries to a given empty topology and returns a message detailing success.
</para>
<para>Useful for populating an empty topology.</para>
<!-- use this format if new function -->
<para>Availability: 2.0 </para>
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details -- X.3.18</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
-- Populate topology --
SELECT topology.ST_CreateTopoGeo('ri_topo',
ST_GeomFromText('MULTILINESTRING((384744 236928,384750 236923,384769 236911,384799 236895,384811 236890,384833 236884,
384844 236882,384866 236881,384879 236883,384954 236898,385087 236932,385117 236938,
385167 236938,385203 236941,385224 236946,385233 236950,385241 236956,385254 236971,
385260 236979,385268 236999,385273 237018,385273 237037,385271 237047,385267 237057,
385225 237125,385210 237144,385192 237161,385167 237192,385162 237202,385159 237214,
385159 237227,385162 237241,385166 237256,385196 237324,385209 237345,385234 237375,
385237 237383,385238 237399,385236 237407,385227 237419,385213 237430,385193 237439,
385174 237451,385170 237455,385169 237460,385171 237475,385181 237503,385190 237521,
385200 237533,385206 237538,385213 237541,385221 237542,385235 237540,385242 237541,
385249 237544,385260 237555,385270 237570,385289 237584,385292 237589,385291 237596,385284 237630))',3438)
);
st_createtopogeo
----------------------------
Topology ri_topo populated
-- create tables and topo geometries --
CREATE TABLE ri.roads(gid serial PRIMARY KEY, road_name text);
SELECT topology.AddTopoGeometryColumn('ri_topo', 'ri', 'roads', 'topo', 'LINE');
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="AddTopoGeometryColumn"/>, <xref linkend="CreateTopology"/>, <xref linkend="DropTopology"/></para>
</refsection>
</refentry>
<refentry id="TopoGeo_AddPoint">
<refnamediv>
<refname>TopoGeo_AddPoint</refname>
<refpurpose>
Adds a point to an existing topology using a tolerance and possibly splitting an existing edge.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>TopoGeo_AddPoint</function></funcdef>
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
<paramdef><type>geometry </type> <parameter>apoint</parameter></paramdef>
<paramdef choice="opt"><type>float8 </type> <parameter>tolerance</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
Adds a point to an existing topology and return its identifier.
The given point will snap to existing nodes or edges within given tolerance.
An existing edge may be split by the snapped point.
</para>
<!-- use this format if new function -->
<para>Availability: 2.0.0</para>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para>
<xref linkend="TopoGeo_AddLineString"/>,
<xref linkend="TopoGeo_AddPolygon"/>,
<xref linkend="AddNode"/>,
<xref linkend="CreateTopology"/>
</para>
</refsection>
</refentry>
<refentry id="TopoGeo_AddLineString">
<refnamediv>
<refname>TopoGeo_AddLineString</refname>
<refpurpose>
Adds a linestring to an existing topology using a tolerance and possibly splitting existing edges/faces. Returns edge identifiers
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>SETOF integer <function>TopoGeo_AddLineString</function></funcdef>
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
<paramdef><type>geometry </type> <parameter>aline</parameter></paramdef>
<paramdef choice="opt"><type>float8 </type> <parameter>tolerance</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
Adds a linestring to an existing topology and return a set of edge identifiers forming it up.
The given line will snap to existing nodes or edges within given tolerance.
Existing edges and faces may be split by the line.
</para>
<!-- use this format if new function -->
<para>Availability: 2.0.0</para>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para>
<xref linkend="TopoGeo_AddPoint"/>,
<xref linkend="TopoGeo_AddPolygon"/>,
<xref linkend="AddEdge"/>,
<xref linkend="CreateTopology"/>
</para>
</refsection>
</refentry>
<refentry id="TopoGeo_AddPolygon">
<refnamediv>
<refname>TopoGeo_AddPolygon</refname>
<refpurpose>
Adds a polygon to an existing topology using a tolerance and possibly splitting existing edges/faces.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>TopoGeo_AddPolygon</function></funcdef>
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
<paramdef><type>geometry </type> <parameter>apoly</parameter></paramdef>
<paramdef choice="opt"><type>float8 </type> <parameter>atolerance</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
Adds a polygon to an existing topology and return a set of face identifiers forming it up.
The boundary of the given polygon will snap to existing nodes or edges within given tolerance.