v.out.postgis(1grass) GRASS GIS User's Manual v.out.postgis(1grass)
NAME
v.out.postgis - Exports a vector map layer to PostGIS feature table.
KEYWORDS
vector, export, output, PostGIS, simple features, topology, 3D
SYNOPSIS
v.out.postgis
v.out.postgis --help
v.out.postgis [-tl2] input=name [type=string[,string,...]]
[layer=string] output=string [output_layer=name] [output_link=name]
[options=key=value[,key=value,...]] [--overwrite] [--help] [--ver-
bose] [--quiet] [--ui]
Flags:
-t
Do not export attribute table
-l
Export PostGIS topology instead of simple features
-2
Force 2D output even if input is 3D
Useful if input is 3D but all z coordinates are identical
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog
Parameters:
input=name [required]
Name of input vector map
type=string[,string,...]
Input feature type
Options: point, line, boundary, centroid, area, face, kernel, auto
Default: auto
layer=string
Layer number or name
Default: 1
output=string [required]
Name for output PostGIS datasource
Starts with ’PG’ prefix, eg. ’PG:dbname=grass’
output_layer=name
Name for output PostGIS layer
If not specified, input name is used
output_link=name
Name for output vector map defined as a link to the PostGIS feature
table
If not specified, the vector link is not created. The link can be
also manually created by ’v.external’ module.
options=key=value[,key=value,...]
Creation options
Examples:
’FID=cat’: define feature id column ’cat’
’GEOMETRY_NAME=wkb_geometry’: define geometry column
’wkb_geometry’
’SPATIAL_INDEX=NO’: do not create spatial index on geometry
column
DESCRIPTION
v.out.postgis exports an existing GRASS vector map layer to PostGIS
feature table. Features without category are skipped.
By default GRASS GIS topological features are converted into simple
features (see OGC Simple Feature Access specification for details).
Flag -l allows to export vector features as topological elements stored
in PostGIS Topology schema. Note that topological export requires Post-
GIS version 2 or later.
Additional creation options can be defined by options parameter:
• FID=<column> - name of column which will be used as primary key
(feature id), default: fid
• GEOMETRY_NAME=<column> name of column which will be used for
storing geometry data in feature table, default: geom
• SPATIAL_INDEX=YES|NO - enable/disable creating spatial index on
geometry column, default: YES
• PRIMARY_KEY=YES|NO - enable/disable adding primary key on FID
column, default: YES
• SRID=<value> - spatial reference identifier, default: not de-
fined
PostGIS Topology related options (relevant only for -l flag):
• TOPOSCHEMA_NAME=<schema name> - name of PostGIS Topology
schema, default: topo_<input>
• TOPOGEOM_NAME=<column> - name of column which will be used for
storing topogeometry data in feature table, default: topo
• TOPO_TOLERANCE=<value> - tolerance for PostGIS Topology schema,
see CreateTopology function for defails, default: 0
• TOPO_GEO_ONLY=YES|NO - store in PostGIS Topology schema only
data relevant to Topo-Geo data model, default: NO
Creation options are comma-separated pairs (key=value), the options are
case-insensitive. Note that options defined by v.external.out are ig-
nored by v.out.postgis.
v.out.postgis optionally also creates a new vector map in the current
mapset if output_link is defined.
NOTES
By default v.out.postgis exports vector data as simple features, ie.
boundaries and centroids (forming topological areas) become polygons,
isles become holes. Geometry of simple feature elements is stored in
PostGIS feature table in the column named "geom". Name of the geometry
column can be changed by options=GEOMETRY_NAME=<column>. Note that for
exporting vector features as simple features can be alternatively used
PostgreSQL driver from OGR library through v.out.ogr module.
Also note that it’s allowed to store in the feature table only features
of the same type, ie. mixing of points and lines is not currently pos-
sible. The feature type is determined for output feature table from the
first vector feature accessing data sequentially (type=auto). Vector
features of other types are during export skipped. User can choose
preferable feature type by type parameter. Only single type is cur-
rently allowed (see TODO section for details).
v.out.postgis currently supports only three basic output simple feature
types: Points, Linestrings and Polygons. Also 3D features of the same
type are supported, eg. 3D points are exported as PointZ simple fea-
ture. Faces are exported as 3D polygons. 3D features are written to the
output automatically if input vector map is 3D. If -2 flag is given
then the output is always 2D (z-coordinate is silently ignored for 3D
input vector maps).
Multigeometries are not currently supported. Features with the same
category are exported as multiple singe features.
v.out.postgis also allows exporting vector features as topological ele-
ments in PostGIS Topology schema. PostGIS Topology extension uses three
tables to store basic topological elements which forms topological ob-
jects like areas or isles in GRASS terminology. Nodes (0-dimensional
topological elements) are stored in "node" table, edges (1-dimensional
elements) in "edge" table and faces (2-dimensional elements) in "face"
table.
• GRASS nodes are stored in node table
• GRASS points are stored in node table as regular nodes
• GRASS centroids are stored in node table as regular nodes
("containing_face" refers to related area)
• GRASS lines are stored in edge table
• GRASS boundaries are stored in edge table
• GRASS areas are stored in face table
Tables node, edge and face are stored in given topological schema. By
default v.out.postgis defines its name as topo_<input>. Alternatively,
the name for topology schema can be defined by op-
tions=TOPOSCHEMA_NAME=<name>.
EXAMPLES
Export Simple Features
Export vector map "urbanarea" as feature table "urbanarea" located in
database "grass", schema "public". Note that this database schema is
automatically used when not defined by the user.
v.out.postgis input=urbanarea output="PG:dbname=grass"
GRASS areas are converted into polygons, isles into holes. We can check
the number or created polygons by simple SQL query below.
db.select driver=pg database=grass \
sql="SELECT ST_GeometryType(geom) as geom_type, count(*) from urbanarea group by geom_type"
geom_type|count
ST_Polygon|657
Note: same procedure can be done by v.out.ogr module, eg.
v.out.ogr input=urbanarea output="PG:dbname=grass" format=PostgreSQL
In this case GRASS vector data are exported to PostGIS database using
OGR library, namely using PostgreSQL driver. Contrary to the v.out.ogr
module, v.out.postgis is using directly PostGIS data provider which is
part of GRASS vector engine. Beside that, v.out.postgis is optimized
for PostGIS export including topological access to the data.
Export data into specific database schema
Database schema for storing exported data can be defined by out-
put_layer as <schema_name>.<table_name>. If the specified schema
doesn’t exist in the database, then it’s automatically created.
Export vector map "bridges" as feature table in database schema "gras-
sout".
v.out.postgis input=bridges output="PG:dbname=grass" output_layer=grassout.bridges
Export data with creation options
Example below demonstrates how to define name for geometry column and
disable building spatial index. Spatial reference system is defined by
srid identifier which corresponds in this case with EPSG 3358 (North
Carolina dataset).
v.out.postgis input=roadsmajor output="PG:dbname=grass" options="GEOMETRY_NAME=wkb_geometry,SPATIAL_INDEX=NO,SRID=3358"
Link exported data
Exported data can be linked as vector map created in the current mapset
by specifying output_link parameter. In the example below vector map
"busstopsall" from PERMANENT mapset is exported into "grass" PostGIS
database. v.out.postgis after successful export also creates in the
current mapset GRASS vector map as a link to the PostGIS feature table.
v.out.postgis input=busstopsall@PERMANENT output="PG:dbname=grass" output_link=busstopsall_pg
Created link can be checked by v.info:
v.info busstopsall_pg
...
|----------------------------------------------------------------------------|
| Map format: PostGIS (PostgreSQL) |
| DB table: public.busstopsall |
| DB name: grass |
| Geometry column: geom |
| Feature type: point |
| Topology: pseudo (simple features) |
|----------------------------------------------------------------------------|
...
Export data without attributes
v.out.postgis allows ignoring attributes when exporting vector features
by specifying -t flag. Command below exports vector features without
attributes. The feature will contain only two columns, the fid and ge-
ometry column.
v.out.postgis -t input=railroads output="PG:dbname=grass"
Export topological data
By default v.out.postgis exports data as simple features. Flag -l al-
lows exporting data as topological elements instead of simple features.
Export topological elements is stored in PostGIS Topology schema.
v.out.postgis -l input=busroutesall output="PG:dbname=grass"
For more info about PostGIS Topology implementation in GRASS see the
wiki page.
TODO
• Multi-feature export
• Allow mixed features (points, lines)
• Support other simple feature types like GeometryCollection and
others
• Implement missing options from v.out.ogr: -a, -s, -c, -p, -n
• Add options: cats, where
REQUIREMENTS
• PostGIS 2.x or later for topological export (flag -l)
REFERENCES
• OGC Simple Feature Access specification
• PostGIS Topology documentation
• GRASS-PostGIS data provider
SEE ALSO
v.out.ogr, v.external, v.external.out, v.in.ogr
See also PostGIS and PostGIS Topology wiki page from GRASS User Wiki.
AUTHOR
Martin Landa, Czech Technical University in Prague, Czech Republic (de-
velopment supported by Fondazione Edmund Mach and Comune di Trento,
Italy)
SOURCE CODE
Available at: v.out.postgis source code (history)
Accessed: unknown
Main index | Vector index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 v.out.postgis(1grass)
Generated by dwww version 1.14 on Fri Jan 24 09:28:20 CET 2025.