1v.external(1)               GRASS GIS User's Manual              v.external(1)
2
3
4

NAME

6       v.external   - Creates a new pseudo-vector map as a link to an OGR-sup‐
7       ported layer or a PostGIS feature table.
8

KEYWORDS

10       vector, import, external, OGR, PostGIS, level1
11

SYNOPSIS

13       v.external
14       v.external --help
15       v.external  [-ojfltb]  input=string   [layer=name]    [where=sql_query]
16       [output=name]   [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]
17
18   Flags:
19       -o
20           Override projection check (use current location’s projection)
21           Assume  that the dataset has the same projection as the current lo‐
22           cation
23
24       -j
25           Perform projection check only and exit
26
27       -f
28           List supported formats and exit
29
30       -l
31           List available layers in data source and exit
32
33       -t
34           List available layers including feature type  in  data  source  and
35           exit
36           Format: layer name,type,projection check,geometry
37
38       -b
39           Do not build topology
40           Advantageous when handling a large number of points
41
42       --overwrite
43           Allow output files to overwrite existing files
44
45       --help
46           Print usage summary
47
48       --verbose
49           Verbose module output
50
51       --quiet
52           Quiet module output
53
54       --ui
55           Force launching GUI dialog
56
57   Parameters:
58       input=string [required]
59           Name of input OGR or PostGIS data source
60           Examples:
61                   ESRI Shapefile: directory containing a shapefile
62                   MapInfo File: directory containing a mapinfo file
63                   PostGIS  database:  connection  string, eg. ’PG:db‐
64           name=db user=grass’
65
66       layer=name
67           Name of OGR layer or PostGIS feature table to be linked
68           Examples:
69                   ESRI Shapefile: shapefile name
70                   MapInfo File: mapinfo file name
71                   PostGIS database: table name
72
73       where=sql_query
74           WHERE conditions of SQL statement without ’where’ keyword
75           Example: income < 1000 and population >= 10000
76
77       output=name
78           Name for output GRASS vector map (default: input layer)
79

DESCRIPTION

81       v.external creates new vector map as a link to external  OGR  layer  or
82       PostGIS  feature  table.  OGR  (Simple Features Library) is part of the
83       GDAL library, so you need to install GDAL to use v.external for  exter‐
84       nal  OGR  layers.  Note that a PostGIS feature table can be linked also
85       using built-in GRASS-PostGIS data driver (requires GRASS  to  be  built
86       with PostgreSQL support).
87

NOTES

89       The  simple feature data model used by OGR (or PostGIS) is very differ‐
90       ent from the topological format used by GRASS. Instead of  true  topol‐
91       ogy, so called ’pseudo topology’ is created for data linked by v.exter‐
92       nal. User should learn the difference between those  two  formats,  be‐
93       cause  some  modules working correctly with GRASS native data, can pro‐
94       duce wrong results with input vector maps created by v.external.
95
96       Limitations:
97
98       Due to these data model differences v.external does not work  with  all
99       data formats. In general, for all formats that do not have a key column
100       (e.g. SHAPE file), attributes are not accessible, and attributes  would
101       get  lost  when modifying the geometries. Therefore it is generally not
102       safe to link vector data with v.external. In many  cases  it  does  not
103       make  sense to use v.external linked data with simple features, instead
104       vector data should be imported with v.import or v.in.ogr  to  get  true
105       topology  support.  Importantly,  point  cloud  data  which do not have
106       topology, can be linked with v.external as long as  there  are  no  at‐
107       tributes  attached  to  these point cloud data, or if the format of the
108       point cloud data has a key column that allows linking vector geometries
109       to attributes.
110
111       See  v.db.connect  for an example of maintaining attributes in external
112       DBMS in also writable mode.
113
114   Supported OGR vector formats
115       To list supported OGR formats, type
116       v.external -f
117       For details see GDAL web site.
118

EXAMPLES

120   ESRI Shapefile
121       Assuming   that    ’test_shape.shp’    is    located    in    directory
122       ’/home/user/shape_data’.
123       v.external input=/home/user/shape_data layer=test_shape output=grass_map
124
125   PostGIS layers
126       By  default, PostGIS links are created by built-in PostGIS support, ie.
127       using GRASS-PostGIS data driver. If the environment variable GRASS_VEC‐
128       TOR_OGR  exists,  or  GRASS is compiled without PostgreSQL support then
129       GRASS will use OGR-PostgreSQL driver for creating a link.
130
131       List of layers for given data source can be printed by -l flag.
132       v.external input="PG:host=localhost user=postgres dbname=postgis" -l
133       ...
134       polymap
135       ...
136       v.external input="PG:host=localhost user=postgres dbname=postgis" layer=polymap
137       Note: Authentication details (user password) can be preferably  defined
138       by db.login.
139
140   MapInfo files
141       Assuming that ’mapinfo_test’ MapInfo file is located in the current di‐
142       rectory (".").
143       v.external input=./ layer=mapinfo_test output=grass_map
144
145   SDTS files
146       Note: you have to select the CATD file
147       v.external input=CITXCATD.DDF output=cities
148
149   TIGER files
150       v.external input=input/2000/56015/ layer=CompleteChain,PIP output=t56015_all
151
152   Linking subset of features
153       By where option only subset of features can be linked. In  the  example
154       below only one feature (in this case a vector tile) will be linked as a
155       new GRASS vector map.
156       v.external in="PG:dbname=tiles" layer=wrs2_descending where="pr=191026"
157       ...
158       Number of areas: 1
159       ...
160

REFERENCES

162       OGR vector library C API documentation
163

SEE ALSO

165        v.external.out, v.clean, v.db.connect,  v.import,  v.in.db,  v.in.ogr,
166       v.out.ogr
167
168       GDAL Library
169       PostGIS
170
171       See also GRASS user wiki page for more examples.
172

AUTHORS

174       Radim Blazek, ITC-Irst, Trento, Italy
175       PostGIS  support by Martin Landa, GeoForAll (OSGeoREL) Lab, Czech Tech‐
176       nical University in Prague, Czech Republic
177

SOURCE CODE

179       Available at: v.external source code (history)
180
181       Accessed: Saturday Jan 21 21:16:27 2023
182
183       Main index | Vector index | Topics index | Keywords index  |  Graphical
184       index | Full index
185
186       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
187
188
189
190GRASS 8.2.1                                                      v.external(1)