Skip to content

v.in.db

Creates new vector (points) map from database table containing coordinates.

v.in.db [-t] table=name [driver=name] [database=name] x=name y=name [z=name] [key=name] [where=sql_query] output=name [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

v.in.db table=name x=name y=name output=name

grass.script.run_command("v.in.db", table, driver="sqlite", database="$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db", x, y, z=None, key=None, where=None, output, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("v.in.db", table="name", x="name", y="name", output="name")

Parameters

table=name [required]
    Input table name
driver=name
    Name of database driver
    Allowed values: dbf, ogr, sqlite
    Default: sqlite
database=name
    Name of database
    Default: $GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db
x=name [required]
    Name of column containing x coordinate
y=name [required]
    Name of column containing y coordinate
z=name
    Name of column containing z coordinate
key=name
    Name of column containing category number
    Must refer to an integer column
where=sql_query
    WHERE conditions of SQL statement without 'where' keyword
    Example: income < 1000 and population >= 10000
output=name [required]
    Name for output vector map
-t
    Use imported table as attribute table for new map
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

table : str, required
    Input table name
    Used as: input, dbtable, name
driver : str, optional
    Name of database driver
    Used as: input, dbdriver, name
    Allowed values: dbf, ogr, sqlite
    Default: sqlite
database : str, optional
    Name of database
    Used as: input, dbname, name
    Default: $GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db
x : str, required
    Name of column containing x coordinate
    Used as: input, dbcolumn, name
y : str, required
    Name of column containing y coordinate
    Used as: input, dbcolumn, name
z : str, optional
    Name of column containing z coordinate
    Used as: input, dbcolumn, name
key : str, optional
    Name of column containing category number
    Must refer to an integer column
    Used as: input, dbcolumn, name
where : str, optional
    WHERE conditions of SQL statement without 'where' keyword
    Example: income < 1000 and population >= 10000
    Used as: input, sql_query, sql_query
output : str, required
    Name for output vector map
    Used as: output, vector, name
flags : str, optional
    Allowed values: t
    t
        Use imported table as attribute table for new map
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

v.in.db creates a new vector point map from database table or file containing coordinates.

NOTES

If GRASS comes with OGR support than v.in.db allows importing data from different input files, eg. CSV or MS Excel (assuming that GDAL/OGR library is compiled with this support).

v.in.db creates key column "cat" automatically when key option is not given. Note that this operation is possible to perform only when -t flag is not given. Currently, automated creation of key column is supported only when default DB driver for output vector map is SQLite driver otherwise key option must be specified by the user. Default DB driver is defined by db.connect.

EXAMPLES

Creating a map from PostgreSQL table

v.in.db driver=pg database="host=myserver.itc.it,dbname=mydb" \
        table=pat_stazioni x=east y=north z=quota key=id output=pat_stazioni

If an ID column is not present in the PostgreSQL table, a new column should be added. See PostgreSQL DB driver page for details.

Creating a map from PostGIS

To extract coordinate values from PostGIS, functions have to be used:

v.in.db driver=pg database="host=myserver.itc.it,dbname=mydb" \
        table=station x="x(geom)" y="y(geom)" z="z(geom)" key=id out=meteostations

If an ID column is not present in the PostgreSQL table, a new column should be added. See PostgreSQL DB driver page for details.

Alternatively a vector point map can be imported from PostGIS database using v.in.ogr.

Creating a map from Open Document spreadsheet (ODS) file

A new vector point map is created from given sheet in ODS file. The database option points to the ODS file. Option table is the name of selected spreadsheet list, the key option is the identifier column:

# preview table structure with OGR tool (table name is "Layer name" here):
ogrinfo -al -so meteodata.ods

# import sheet from ODS into map
v.in.db key=ID table=mysheet x=long y=lat z=height output=meteodata \
         driver=ogr database=meteodata.ods

Creating a map from MS Excel file

A new vector point map is created from given sheet in MS Excel file. The database option points to the file in MS Excel format. Option table is name of the selected spreadsheet "List1":

v.in.db table=List1 x=long y=lat z=height output=meteodata \
         driver=ogr database=meteodata.xls

Note that in this example the key option is omitted. In this case v.in.db tries to add key column automatically. This requires SQLite to be a default DB driver.

Creating a map from DBF table

A new 3D point vector map is created from DBF table. Column 'idcol' contains unique row IDs. The database option is the directory where the DBF file is stored.

v.in.db driver=dbf database=/home/user/tables/ table=pointsfile x=x y=y z=z \
        key=idcol out=dtmpoints

To check result:

v.info dtmpoints
v.info -c dtmpoints

If DB driver for output vector map is different from SQLite driver and an ID column is missing in the DBF file, it has to be added beforehand, e.g. with OpenOffice. Alternatively, import the table with db.in.ogr into GRASS and then with v.in.db from the imported table (db.in.ogr optionally adds an unique ID column).

Creating a point map from DBF table for selected records only

The user can import only selected vector points from a table using the where parameter (see above for general DBF handling):

v.in.db driver=dbf  database=/home/user/tables/ table=pointsfile x=x y=y z=z \
        key=idcol out=dtmpoints where="x NOT NULL and z > 100"

Creating a map from SQLite table

A new vector point map is created from table in SQLite database file. Column 'idcol' contains unique row IDs. The database option is the the SQLite database file.

v.in.db driver=sqlite database=/home/user/tables/mysqlite.db table=pointsfile x=x y=y z=z \
        key=idcol out=dtmpoints

SEE ALSO

db.execute, db.in.ogr, v.info, v.in.geonames, v.in.ogr, v.to.db

SQL support in GRASS GIS

AUTHORS

Radim Blazek
Various updates for GRASS 7 by Martin Landa, Czech Technical University in Prague, Czech Republic

SOURCE CODE

Available at: v.in.db source code (history)
Latest change: Saturday Mar 29 14:59:39 2025 in commit 0bfa813