Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
v.out.postgis(1)	    GRASS GIS User's Manual	      v.out.postgis(1)

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=nameA [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=stringA [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:
	   A A A A A A A A 'FID=cat': define feature id	column 'cat'
	   A A A A A A A A 'GEOMETRY_NAME=wkb_geometry': define	geometry  col-
	   umn 'wkb_geometry'
	   A A A A A A A A '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:

	   o   FID=<column> - name of column which will	be used	as primary key
	       (feature	id), default: fid

	   o   GEOMETRY_NAME=<column> name of column which will	 be  used  for
	       storing geometry	data in	feature	table, default:	geom

	   o   SPATIAL_INDEX=YES|NO - enable/disable creating spatial index on
	       geometry	column,	default: YES

	   o   PRIMARY_KEY=YES|NO - enable/disable adding primary key  on  FID
	       column, default:	YES

	   o   SRID=<value>  -	spatial	reference identifier, default: not de-
	       fined
       PostGIS Topology	related	options	(relevant only for -l flag):

	   o   TOPOSCHEMA_NAME=<schema	name>  -  name	of  PostGIS   Topology
	       schema, default:	topo_<input>

	   o   TOPOGEOM_NAME=<column>  - name of column	which will be used for
	       storing topogeometry data in feature table, default: topo

	   o   TOPO_TOLERANCE=<value> -	tolerance for PostGIS Topology schema,
	       see CreateTopology function for defails,	default: 0

	   o   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.

	   o   GRASS nodes are stored in node table

	   o   GRASS points are	stored in node table as	regular	nodes

	   o   GRASS centroids are stored  in  node  table  as	regular	 nodes
	       ("containing_face" refers to related area)

	   o   GRASS lines are stored in edge table

	   o   GRASS boundaries	are stored in edge table

	   o   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
	   o   Multi-feature export

	   o   Allow mixed features (points, lines)

	   o   Support	other simple feature types like	GeometryCollection and
	       others

	   o   Implement missing options from v.out.ogr: -a, -s, -c, -p, -n

	   o   Add options: cats, where

REQUIREMENTS
	   o   PostGIS 2.x or later for	topological export (flag -l)

REFERENCES
	   o   OGC Simple Feature Access specification

	   o   PostGIS Topology	documentation

	   o   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)

       Main index | Vector index | Topics index	| Keywords index  |  Graphical
       index | Full index

       A(C) 2003-2020 GRASS Development	Team, GRASS GIS	7.8.4 Reference	Manual

GRASS 7.8.4						      v.out.postgis(1)

NAME | KEYWORDS | SYNOPSIS | DESCRIPTION | NOTES | EXAMPLES | TODO | REQUIREMENTS | REFERENCES | SEE ALSO | AUTHOR | SOURCE CODE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=v.out.postgis&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help