Provided by: grass-doc_7.0.3-1build1_all bug

NAME

       v.out.postgis  - Exports a vector map layer to PostGIS feature table.

KEYWORDS

       vector, export, 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]   [--verbose]   [--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 PostGIS 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 defined
       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 ignored 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 possible. 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 currently 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 feature. 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 elements in PostGIS
       Topology schema. PostGIS Topology extension uses three tables to store  basic  topological
       elements  which  forms topological objects 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 options=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   output_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 "grassout".
       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 geometry 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 allows 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 (development supported
       by Fondazione Edmund Mach and Comune di Trento, Italy)

       Last changed: $Date: 2015-11-24 09:08:30 +0100 (Tue, 24 Nov 2015) $

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

       © 2003-2016 GRASS Development Team, GRASS GIS 7.0.3 Reference Manual