v.out.postgis(1grass)

1v.out.postgis(1)              Grass 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, 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 column ’wkb_geometry’
77           ’SPATIAL_INDEX=NO’: do not create spatial index on geometry column
78

DESCRIPTION

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

NOTES

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

EXAMPLES

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

TODO

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

REQUIREMENTS

264           ·   PostGIS 2.x or later for topological export (flag -l)
265

REFERENCES

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

AUTHOR

279       Martin  Landa,  Czech  Technical  University  in Prague, Czech Republic
280       (development supported by Fondazione Edmund Mach and Comune di  Trento,
281       Italy)
282
283       Last changed: $Date: 2015-11-24 09:07:58 +0100 (Tue, 24 Nov 2015) $
284

SOURCE CODE

286       Available at: v.out.postgis source code (history)
287
288       Main  index  | Vector index | Topics index | Keywords index | Graphical
289       index | Full index
290
291       © 2003-2019 GRASS Development Team, GRASS GIS 7.4.4 Reference Manual
292
293
294
295GRASS 7.4.4                                                   v.out.postgis(1)