## DESCRIPTION

v.external.out instructs GRASS to write vector maps in external data format (e.g. ESRI Shapefile, Mapinfo, and others) using OGR library. PostGIS data can be also written by built-in GRASS-PostGIS data provider.

## NOTES

Number of available output formats (`v.external.out -f`) depends on OGR installation. 'PostgreSQL' format is presented also when GRASS comes with PostgreSQL support (check for '--with-postgres' in `g.version -b` output).

To store geometry and attribute data in PostGIS database ('PostgreSQL' format) GRASS uses built-in GRASS-PostGIS data provider. PostGIS data can be written also by OGR library when `GRASS_VECTOR_OGR` environmental variable is defined or GRASS is not compiled with PostgreSQL support.

Creation options refer to the given output format selected by format option. See the list of valid creation options at OGR formats specification page, example for ESRI Shapefile or PostgreSQL/PostGIS format (section "Layer Creation Options").

Note that built-in GRASS-PostGIS data provider supports a limited number of creation options compared to PostgreSQL/PostGIS driver from OGR library:

- `SCHEMA=<name>` - name of schema where to create feature tables. If schema doesn't exists, it's automatically created when writing PostGIS data.
- `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 spatial index on geometry column, default: YES
- `PRIMARY_KEY=YES|NO` - enable/disable primary key on FID column, default: YES
- `TOPOLOGY=YES|NO` - enable/disable native PostGIS topology, default: NO

Creation options are comma-separated pairs (`key=value`), the options are case-insensitive.

## EXAMPLES

### ESRI Shapefile

v.external.out can be used along with v.external to process external geodata in GRASS while writing out the results directly eg. in ESRI Shapefile format:

    # register Shapefile in GRASS mapset:
    v.external dsn=/path/to/shapefiles layer=cities

    # define output directory for GRASS calculation results:
    v.external.out dsn=$HOME/gisoutput

    # do something (here: spatial query), write output directly as Shapefile
    v.select ainput=cities atype=point binput=forests btype=area operator=within output=fcities

Current settings can be printed using -p or -g flag.

    v.external.out -p

    dsn: /path/to/home/gisoutput
    format: ESRI Shapefile

### PostGIS (simple features)

PostGIS data can be accessed directly using GRASS-PostGIS data provider (GRASS must be compiled with PostgreSQL support).

    # register PostGIS table in GRASS mapset:
    v.external dsn=PG:dbname=gisdb layer=cities

    # define output PostGIS database for GRASS calculation results stored as simple features:
    v.external.out dsn=PG:dbname=gisdb format=PostgreSQL

    # do some processing...

Note: If the environment variable `GRASS_VECTOR_OGR` is defined, or GRASS is compiled without PostgreSQL support then GRASS will use PostgreSQL driver from OGR library for reading and writing PostGIS data.

### PostGIS Topology

    # define output PostGIS database for GRASS calculation results stored as topological elements:
    v.external.out dsn=PG:dbname=gisdb format=PostgreSQL options=topology=YES

    # do some processing...

Note: PostGIS topological access is supported only in built-in GRASS-PostGIS data provider.

### GRASS native format

To restore original settings, ie. use GRASS native format, type:

    v.external.out -r

## REFERENCES

- GRASS-OGR data provider
- OGR vector library C API documentation
- GRASS-PostGIS data provider
- libpq - C Library

## SEE ALSO

v.external, v.in.ogr, v.out.ogr, v.out.postgis

See also GRASS user wiki page for more examples.

## AUTHOR

Martin Landa, Czech Technical University in Prague, Czech Republic (development supported by Fondazione Edmund Mach and Comune di Trento, Italy)

Last changed: $Date$