## NAME

v.to.pg - Export areas and lines from an existing vector map to Postgres/PostGIS table. (GRASS-RDBMS Interface Display Program)

## SYNOPSIS

v.to.pg
v.to.pg help
v.to.pg [-fvtp] key=name tab=name type=name [where=name] map=name [color=name]

## ALTERNATE

v.to.pg -s help
v.to.pg ]-sfvp] sql=filename map=name type=name [color=name]

## DESCRIPTION

v.to.pg exports vectors from an existing vector map based on the unique values in a database column (or optionally all vectors without referencing to any existing table, see -t option). Each row returned by a user constructed database query will be associated with a vector feature which may be drawn on the graphics display if X-windows are there. The user can control the color of the vector draw by specifying a color on the command line.

As result, a new Postgres table table_bnd or table_arc (or table_mpoly and table_mstring for PostGIS) is created to hold areas as internal type "polygon" and lines as "open path", where table is the tab parameter. Besides these elements in fields called boundary or segment, the table would also have the category field (named after key parameter), case number this category occurred in map (as field called 'num'), and an extra boolean field 'ex' for 'true' if the polygon is external and 'f' if it is a hole for table_bnd only.

For PostGIS, the difference is that types of the imported entities are POLYGON (i.e., with "holes" all in one POLYGON) and LINESTRING, respectively. The fields are called grass_poly and grass_line. There is no need to define whether a polygon is internal ("hole") or external, in this case, therefore there is no field 'ex'.

## COMMAND LINE OPTIONS

### Flag:

-f
  Fill polygons selected on the query criteria.
-t
  Export all map vectors without reference to existing table ('where' clause ignored).
-v
  Verbose mode with statistics on the completion of the insertions.
-p
  Create and populate PostGIS GEOMETRY format table instead of normal Postgres geometry types.

### Parameters:

key=databasecolumnname
  Column in table "tab" of the currently selected database containing values corresponding to the vector maps category values. Table is designated on the command line by tab=tablename and vector is given on the command line by map=mapname.
tab=databasetablename
  Table in the currently selected database containing a column which has values corresponding to vector category values in the map designated by map=map.
where=SQLwhereclause
  SQL "where" clause which specifies the query criteria to be used in subsetting the database. The field names specified in the where option must indicate the column(s) to be used, the operators to be used in the evaluation and the values which the data in the column will be evaluated against.

If the database column used as the selection criteria is a character field then the associated value must be placed in quotes. To determine the data types associated with columns in the currently selected database use the g.column.pg command with the -v flag.

Queries which are more complex are best implemented using the -s flag and a prepared SQL file.

map=map
  Name of an existing vector map with category values which correspond to values in a specified column in the currently selected database.
color=name
  Color to draw vectors in
  Colors: red, orange, yellow, green, blue, indigo, violet, magenta, brown, gray, white, black
type=area,line
  Type of the coverage to export.

## ALTERNATE COMMAND LINE USAGE

The alternate command line usage is provided to simplify the process of retrieving information from more than one table in the query criteria. The alternate command line structure is selected using the the [-s] flag on the command line. When using this flag the user must include the name of a text file on the command line as well. This file must include a complete, well formed SQL SELECT statement specifying the query criteria to retrieve values which correspond to category values in a GRASS data layer.

### Flag:

-s
  SQL select statements are input from a prepared file
-f
  Fill polygons selected on the query criteria
-v
  Verbose mode with statistics on the completion of the insertions.
-p
  Create and populate PostGIS GEOMETRY format table instead of normal Postgres geometry types.

### Parameters:

sql=filename
  SQL statements specifying well formed selection criteria.
map=name
  Name of an existing vector map
color=name
  Color to draw vectors in
  Colors: red, orange, yellow, green, blue, indigo, violet, magenta, brown, gray, white, black
type=area,line
  Type of the coverage to export.

EXAMPLE:

1. v.to.pg -f key=rec_id map=kuruma_id tab=info_kuruma type=area where='type_id >32 and type_id < 38' color=red

Result: only polygons with type in 33-37 range would be inserted in table info_kuruma_bnd and displayed in red color.

2. v.to.pg -v -s -f -p sql=oak.sql map=kuruma_id type=area

oak.sql is:

select rec_id from info_kuruma where type_id > 32 and type_id <38;

Result: this command would do the same as in the first example, some information printed on screen. However, the result table would be in PostGIS format.

## BUGS

none

## NOTE

This program requires the Postgres database software.

The 'total' mode of import (i.e., without referencing to existing table and to categories count in map) leads to that field 'num' in result tables would be incoherent (simply counts vectors from beginning to end).

## SEE ALSO

g.column.pg, g.select.pg, g.stats.pg, g.table.pg, d.rast.pg, d.site.pg, d.what.r.pg, d.what.s.pg, d.what.v.pg, v.reclass.pg

## AUTHOR

Alex Shevlakov (sixote@yahoo.com)