1v.out.postgis(1) Grass User's Manual v.out.postgis(1)
2
6 v.out.postgis - Exports a vector map layer to PostGIS feature table.
7
9 vector, export, output, PostGIS, simple features, topology, 3D
10
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 Flags:
20 -t
21 Do not export attribute table
22 -l
24 Export PostGIS topology instead of simple features
25 -2
27 Force 2D output even if input is 3D
28 Useful if input is 3D but all z coordinates are identical
29 --overwrite
31 Allow output files to overwrite existing files
32 --help
34 Print usage summary
35 --verbose
37 Verbose module output
38 --quiet
40 Quiet module output
41 --ui
43 Force launching GUI dialog
44 Parameters:
46 input=name [required]
47 Name of input vector map
48 type=string[,string,...]
50 Input feature type
51 Options: point, line, boundary, centroid, area, face, kernel, auto
52 Default: auto
53 layer=string
55 Layer number or name
56 Default: 1
57 output=string [required]
59 Name for output PostGIS datasource
60 Starts with ’PG’ prefix, eg. ’PG:dbname=grass’
61 output_layer=name
63 Name for output PostGIS layer
64 If not specified, input name is used
65 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 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
82 v.out.postgis exports an existing GRASS vector map layer to PostGIS
83 feature table. Features without category are skipped.
84 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 Additional creation options can be defined by options parameter:
92 · FID=<column> - name of column which will be used as primary key
94 (feature id), default: fid
95 · GEOMETRY_NAME=<column> name of column which will be used for
97 storing geometry data in feature table, default: geom
98 · SPATIAL_INDEX=YES|NO - enable/disable creating spatial index on
100 geometry column, default: YES
101 · PRIMARY_KEY=YES|NO - enable/disable adding primary key on FID
103 column, default: YES
104 · SRID=<value> - spatial reference identifier, default: not
106 defined
107 PostGIS Topology related options (relevant only for -l flag):
108 · TOPOSCHEMA_NAME=<schema name> - name of PostGIS Topology
110 schema, default: topo_<input>
111 · TOPOGEOM_NAME=<column> - name of column which will be used for
113 storing topogeometry data in feature table, default: topo
114 · TOPO_TOLERANCE=<value> - tolerance for PostGIS Topology schema,
116 see CreateTopology function for defails, default: 0
117 · TOPO_GEO_ONLY=YES|NO - store in PostGIS Topology schema only
119 data relevant to Topo-Geo data model, default: NO
120 Creation options are comma-separated pairs (key=value), the options are
122 case-insensitive. Note that options defined by v.external.out are
123 ignored by v.out.postgis.
124 v.out.postgis optionally also creates a new vector map in the current
126 mapset if output_link is defined.
127
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 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 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 Multigeometries are not currently supported. Features with the same
154 category are exported as multiple singe features.
155 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
159 objects 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 · GRASS nodes are stored in node table
165 · GRASS points are stored in node table as regular nodes
167 · GRASS centroids are stored in node table as regular nodes
169 ("containing_face" refers to related area)
170 · GRASS lines are stored in edge table
172 · GRASS boundaries are stored in edge table
174 · 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
179 options=TOPOSCHEMA_NAME=<name>.
180
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 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 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 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 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 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
241 geometry column.
242 v.out.postgis -t input=railroads output="PG:dbname=grass"
243 Export topological data
245 By default v.out.postgis exports data as simple features. Flag -l
246 allows exporting data as topological elements instead of simple fea‐
247 tures. Export topological elements is stored in PostGIS Topology
248 schema.
249 v.out.postgis -l input=busroutesall output="PG:dbname=grass"
250 For more info about PostGIS Topology implementation in GRASS see the
251 wiki page.
252
254 · Multi-feature export
255 · Allow mixed features (points, lines)
257 · Support other simple feature types like GeometryCollection and
259 others
260 · Implement missing options from v.out.ogr: -a, -s, -c, -p, -n
262 · Add options: cats, where
264
266 · PostGIS 2.x or later for topological export (flag -l)
267
269 · OGC Simple Feature Access specification
270 · PostGIS Topology documentation
272 · GRASS-PostGIS data provider
274
276 v.out.ogr, v.external, v.external.out, v.in.ogr
277 See also PostGIS and PostGIS Topology wiki page from GRASS User Wiki.
279
281 Martin Landa, Czech Technical University in Prague, Czech Republic
282 (development supported by Fondazione Edmund Mach and Comune di Trento,
283 Italy)
284
286 Available at: v.out.postgis source code (history)
287 Main index | Vector index | Topics index | Keywords index | Graphical
289 index | Full index
290 © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
292GRASS 7.8.2 v.out.postgis(1)