1v.out.postgis(1) GRASS GIS 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 de‐
106 fined
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 ig‐
123 nored 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 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 • 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 op‐
179 tions=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 ge‐
241 ometry 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 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
253 • Multi-feature export
254 • Allow mixed features (points, lines)
256 • Support other simple feature types like GeometryCollection and
258 others
259 • Implement missing options from v.out.ogr: -a, -s, -c, -p, -n
261 • Add options: cats, where
263
265 • PostGIS 2.x or later for topological export (flag -l)
266
268 • OGC Simple Feature Access specification
269 • PostGIS Topology documentation
271 • GRASS-PostGIS data provider
273
275 v.out.ogr, v.external, v.external.out, v.in.ogr
276 See also PostGIS and PostGIS Topology wiki page from GRASS User Wiki.
278
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
285 Available at: v.out.postgis source code (history)
286 Accessed: Saturday Oct 28 18:18:43 2023
288 Main index | Vector index | Topics index | Keywords index | Graphical
290 index | Full index
291 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
293GRASS 8.3.1 v.out.postgis(1)