1v.out.postgis(1)            GRASS GIS User's Manual           v.out.postgis(1)
2
3
4

NAME

6       v.out.postgis  - Exports a vector map layer to PostGIS feature table.
7

KEYWORDS

9       vector, export, output, PostGIS, simple features, topology, 3D
10

SYNOPSIS

12       v.out.postgis
13       v.out.postgis --help
14       v.out.postgis     [-tl2]     input=name      [type=string[,string,...]]
15       [layer=string]  output=string  [output_layer=name]   [output_link=name]
16       [options=key=value[,key=value,...]]    [--overwrite]  [--help]  [--ver‐
17       bose]  [--quiet]  [--ui]
18
19   Flags:
20       -t
21           Do not export attribute table
22
23       -l
24           Export PostGIS topology instead of simple features
25
26       -2
27           Force 2D output even if input is 3D
28           Useful if input is 3D but all z coordinates are identical
29
30       --overwrite
31           Allow output files to overwrite existing files
32
33       --help
34           Print usage summary
35
36       --verbose
37           Verbose module output
38
39       --quiet
40           Quiet module output
41
42       --ui
43           Force launching GUI dialog
44
45   Parameters:
46       input=name [required]
47           Name of input vector map
48
49       type=string[,string,...]
50           Input feature type
51           Options: point, line, boundary, centroid, area, face, kernel, auto
52           Default: auto
53
54       layer=string
55           Layer number or name
56           Default: 1
57
58       output=string [required]
59           Name for output PostGIS datasource
60           Starts with ’PG’ prefix, eg. ’PG:dbname=grass’
61
62       output_layer=name
63           Name for output PostGIS layer
64           If not specified, input name is used
65
66       output_link=name
67           Name for output vector map defined as a link to the PostGIS feature
68           table
69           If  not  specified, the vector link is not created. The link can be
70           also manually created by ’v.external’ module.
71
72       options=key=value[,key=value,...]
73           Creation options
74           Examples:
75                   ’FID=cat’: define feature id column ’cat’
76                   ’GEOMETRY_NAME=wkb_geometry’: define geometry  col‐
77           umn ’wkb_geometry’
78                   ’SPATIAL_INDEX=NO’:  do not create spatial index on
79           geometry column
80

DESCRIPTION

82       v.out.postgis exports an existing GRASS vector  map  layer  to  PostGIS
83       feature table. Features without category are skipped.
84
85       By  default  GRASS  GIS  topological features are converted into simple
86       features (see OGC Simple Feature  Access  specification  for  details).
87       Flag -l allows to export vector features as topological elements stored
88       in PostGIS Topology schema. Note that topological export requires Post‐
89       GIS version 2 or later.
90
91       Additional creation options can be defined by options parameter:
92
93           •   FID=<column> - name of column which will be used as primary key
94               (feature id), default: fid
95
96           •   GEOMETRY_NAME=<column> name of column which will  be  used  for
97               storing geometry data in feature table, default: geom
98
99           •   SPATIAL_INDEX=YES|NO - enable/disable creating spatial index on
100               geometry column, default: YES
101
102           •   PRIMARY_KEY=YES|NO - enable/disable adding primary key  on  FID
103               column, default: YES
104
105           •   SRID=<value>  -  spatial reference identifier, default: not de‐
106               fined
107       PostGIS Topology related options (relevant only for -l flag):
108
109           •   TOPOSCHEMA_NAME=<schema  name>  -  name  of  PostGIS   Topology
110               schema, default: topo_<input>
111
112           •   TOPOGEOM_NAME=<column>  - name of column which will be used for
113               storing topogeometry data in feature table, default: topo
114
115           •   TOPO_TOLERANCE=<value> - tolerance for PostGIS Topology schema,
116               see CreateTopology function for defails, default: 0
117
118           •   TOPO_GEO_ONLY=YES|NO  -  store  in PostGIS Topology schema only
119               data relevant to Topo-Geo data model, default: NO
120
121       Creation options are comma-separated pairs (key=value), the options are
122       case-insensitive.  Note  that options defined by v.external.out are ig‐
123       nored by v.out.postgis.
124
125       v.out.postgis optionally also creates a new vector map in  the  current
126       mapset if output_link is defined.
127

NOTES

129       By  default  v.out.postgis  exports vector data as simple features, ie.
130       boundaries and centroids (forming topological areas)  become  polygons,
131       isles  become  holes.  Geometry of simple feature elements is stored in
132       PostGIS feature table in the column named "geom". Name of the  geometry
133       column  can be changed by options=GEOMETRY_NAME=<column>. Note that for
134       exporting vector features as simple features can be alternatively  used
135       PostgreSQL driver from OGR library through v.out.ogr module.
136
137       Also note that it’s allowed to store in the feature table only features
138       of the same type, ie. mixing of points and lines is not currently  pos‐
139       sible. The feature type is determined for output feature table from the
140       first vector feature accessing data  sequentially  (type=auto).  Vector
141       features  of  other  types  are  during export skipped. User can choose
142       preferable feature type by type parameter. Only  single  type  is  cur‐
143       rently allowed (see TODO section for details).
144
145       v.out.postgis currently supports only three basic output simple feature
146       types: Points, Linestrings and Polygons. Also 3D features of  the  same
147       type  are  supported,  eg. 3D points are exported as PointZ simple fea‐
148       ture. Faces are exported as 3D polygons. 3D features are written to the
149       output  automatically  if  input  vector map is 3D. If -2 flag is given
150       then the output is always 2D (z-coordinate is silently ignored  for  3D
151       input vector maps).
152
153       Multigeometries  are  not  currently  supported. Features with the same
154       category are exported as multiple singe features.
155
156       v.out.postgis also allows exporting vector features as topological ele‐
157       ments in PostGIS Topology schema. PostGIS Topology extension uses three
158       tables to store basic topological elements which forms topological  ob‐
159       jects  like  areas  or isles in GRASS terminology. Nodes (0-dimensional
160       topological elements) are stored in "node" table, edges  (1-dimensional
161       elements)  in "edge" table and faces (2-dimensional elements) in "face"
162       table.
163
164           •   GRASS nodes are stored in node table
165
166           •   GRASS points are stored in node table as regular nodes
167
168           •   GRASS centroids are stored  in  node  table  as  regular  nodes
169               ("containing_face" refers to related area)
170
171           •   GRASS lines are stored in edge table
172
173           •   GRASS boundaries are stored in edge table
174
175           •   GRASS areas are stored in face table
176       Tables  node,  edge and face are stored in given topological schema. By
177       default v.out.postgis defines its name as topo_<input>.  Alternatively,
178       the    name    for    topology   schema   can   be   defined   by   op‐
179       tions=TOPOSCHEMA_NAME=<name>.
180

EXAMPLES

182   Export Simple Features
183       Export vector map "urbanarea" as feature table "urbanarea"  located  in
184       database  "grass",  schema  "public". Note that this database schema is
185       automatically used when not defined by the user.
186       v.out.postgis input=urbanarea output="PG:dbname=grass"
187       GRASS areas are converted into polygons, isles into holes. We can check
188       the number or created polygons by simple SQL query below.
189       db.select driver=pg database=grass \
190        sql="SELECT ST_GeometryType(geom) as geom_type, count(*) from urbanarea group by geom_type"
191       geom_type|count
192       ST_Polygon|657
193       Note: same procedure can be done by v.out.ogr module, eg.
194       v.out.ogr input=urbanarea output="PG:dbname=grass" format=PostgreSQL
195       In  this  case GRASS vector data are exported to PostGIS database using
196       OGR library, namely using PostgreSQL driver. Contrary to the  v.out.ogr
197       module,  v.out.postgis is using directly PostGIS data provider which is
198       part of GRASS vector engine. Beside that,  v.out.postgis  is  optimized
199       for PostGIS export including topological access to the data.
200
201   Export data into specific database schema
202       Database  schema  for  storing  exported  data  can  be defined by out‐
203       put_layer  as  <schema_name>.<table_name>.  If  the  specified   schema
204       doesn’t exist in the database, then it’s automatically created.
205
206       Export  vector map "bridges" as feature table in database schema "gras‐
207       sout".
208       v.out.postgis input=bridges output="PG:dbname=grass" output_layer=grassout.bridges
209
210   Export data with creation options
211       Example below demonstrates how to define name for geometry  column  and
212       disable  building spatial index. Spatial reference system is defined by
213       srid identifier which corresponds in this case with  EPSG  3358  (North
214       Carolina dataset).
215       v.out.postgis input=roadsmajor output="PG:dbname=grass" options="GEOMETRY_NAME=wkb_geometry,SPATIAL_INDEX=NO,SRID=3358"
216
217   Link exported data
218       Exported data can be linked as vector map created in the current mapset
219       by specifying output_link parameter. In the example  below  vector  map
220       "busstopsall"  from  PERMANENT  mapset is exported into "grass" PostGIS
221       database. v.out.postgis after successful export  also  creates  in  the
222       current mapset GRASS vector map as a link to the PostGIS feature table.
223       v.out.postgis input=busstopsall@PERMANENT output="PG:dbname=grass" output_link=busstopsall_pg
224       Created link can be checked by v.info:
225        v.info busstopsall_pg
226       ...
227        |----------------------------------------------------------------------------|
228        | Map format:      PostGIS (PostgreSQL)                                      |
229        | DB table:        public.busstopsall                                        |
230        | DB name:         grass                                                     |
231        | Geometry column: geom                                                      |
232        | Feature type:    point                                                     |
233        | Topology:        pseudo (simple features)                                  |
234        |----------------------------------------------------------------------------|
235       ...
236
237   Export data without attributes
238       v.out.postgis allows ignoring attributes when exporting vector features
239       by specifying -t flag.  Command below exports vector  features  without
240       attributes.  The feature will contain only two columns, the fid and ge‐
241       ometry column.
242       v.out.postgis -t input=railroads output="PG:dbname=grass"
243
244   Export topological data
245       By default v.out.postgis exports data as simple features. Flag  -l  al‐
246       lows exporting data as topological elements instead of simple features.
247       Export topological elements is stored in PostGIS Topology schema.
248       v.out.postgis -l input=busroutesall output="PG:dbname=grass"
249       For more info about PostGIS Topology implementation in  GRASS  see  the
250       wiki page.
251

TODO

253           •   Multi-feature export
254
255           •   Allow mixed features (points, lines)
256
257           •   Support  other simple feature types like GeometryCollection and
258               others
259
260           •   Implement missing options from v.out.ogr: -a, -s, -c, -p, -n
261
262           •   Add options: cats, where
263

REQUIREMENTS

265           •   PostGIS 2.x or later for topological export (flag -l)
266

REFERENCES

268           •   OGC Simple Feature Access specification
269
270           •   PostGIS Topology documentation
271
272           •   GRASS-PostGIS data provider
273

SEE ALSO

275        v.out.ogr, v.external, v.external.out, v.in.ogr
276
277       See also PostGIS and PostGIS Topology wiki page from GRASS User Wiki.
278

AUTHOR

280       Martin Landa, Czech Technical University in Prague, Czech Republic (de‐
281       velopment  supported  by  Fondazione  Edmund Mach and Comune di Trento,
282       Italy)
283

SOURCE CODE

285       Available at: v.out.postgis source code (history)
286
287       Accessed: Saturday Oct 28 18:18:43 2023
288
289       Main index | Vector index | Topics index | Keywords index  |  Graphical
290       index | Full index
291
292       © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
293
294
295
296GRASS 8.3.1                                                   v.out.postgis(1)
Impressum