165
160
converts simple features data between file formats
168
\section synopsis SYNOPSIS
162
\section ogr2ogr_synopsis SYNOPSIS
176
Usage: ogr2ogr [--help-general] [-skipfailures] [-append] [-update] [-gt n]
169
Usage: ogr2ogr [--help-general] [-skipfailures] [-append] [-update]
177
170
[-select field_list] [-where restricted_where]
178
171
[-progress] [-sql <sql statement>] [-dialect dialect]
179
172
[-preserve_fid] [-fid FID]
180
[-spat xmin ymin xmax ymax] [-wrapdateline]
181
[-clipsrc [xmin ymin xmax ymax]|WKT|datasource|spat_extent]
182
[-clipsrcsql sql_statement] [-clipsrclayer layer]
183
[-clipsrcwhere expression]
184
[-clipdst [xmin ymin xmax ymax]|WKT|datasource]
185
[-clipdstsql sql_statement] [-clipdstlayer layer]
186
[-clipdstwhere expression]
173
[-spat xmin ymin xmax ymax]
187
174
[-a_srs srs_def] [-t_srs srs_def] [-s_srs srs_def]
188
175
[-f format_name] [-overwrite] [[-dsco NAME=VALUE] ...]
189
[-segmentize max_dist] [-fieldTypeToString All|(type1[,type2]*)]
190
176
dst_datasource_name src_datasource_name
191
177
[-lco NAME=VALUE] [-nln name] [-nlt type] [layer [layer ...]]
181
[-clipsrc [xmin ymin xmax ymax]|WKT|datasource|spat_extent]
182
[-clipsrcsql sql_statement] [-clipsrclayer layer]
183
[-clipsrcwhere expression]
184
[-clipdst [xmin ymin xmax ymax]|WKT|datasource]
185
[-clipdstsql sql_statement] [-clipdstlayer layer]
186
[-clipdstwhere expression]
188
[[-simplify tolerance] | [-segmentize max_dist]]
189
[-fieldTypeToString All|(type1[,type2]*)]
190
[-splitlistfields] [-maxsubfields val]
191
[-explodecollections] [-zfield field_name]
195
\section description DESCRIPTION
195
\section ogr2ogr_description DESCRIPTION
198
197
This program can be used to convert simple features data between file formats
199
198
performing various operations during the process such as spatial or attribute
223
222
<dt> <b>-sql</b> <em>sql_statement</em>:</dt><dd> SQL statement to execute.
224
223
The resulting table/layer will be saved to the output.</dd>
225
224
<dt> <b>-dialect</b> <em>dialect</em>:</dt><dd> SQL dialect. In some cases can be used to use (unoptimized) OGR SQL instead of the native SQL of an RDBMS by passing OGRSQL. </dd>
226
<dt> <b>-wrapdateline</b>:</dt><dd> (starting with GDAL 1.7.0) split geometries crossing the dateline meridian (long. = +/- 180deg)</dd>
227
225
<dt> <b>-where</b><em> restricted_where</em>:</dt><dd> Attribute query (like SQL WHERE)</dd>
228
226
<dt> <b>-skipfailures</b>:</dt><dd>Continue after a failure, skipping the failed feature.</dd>
229
<dt> <b>-gt</b> <em>n</em>:</dt><dd> group <em>n</em> features per transaction (default 200)</dd>
230
227
<dt> <b>-spat</b><em> xmin ymin xmax ymax</em>:</dt><dd> spatial query extents. Only features
231
228
whose geometry intersects the extents will be selected. The geometries will not be clipped unless -clipsrc is specified</dd>
229
<dt> <b>-dsco</b> <em>NAME=VALUE</em>:</dt><dd> Dataset creation option (format specific)</dd>
230
<dt> <b>-lco</b><em> NAME=VALUE</em>:</dt><dd> Layer creation option (format specific)</dd>
231
<dt> <b>-nln</b><em> name</em>:</dt><dd> Assign an alternate name to the new layer</dd>
232
<dt> <b>-nlt</b><em> type</em>:</dt><dd> Define the geometry type for the
233
created layer. One of NONE, GEOMETRY, POINT, LINESTRING, POLYGON,
234
GEOMETRYCOLLECTION, MULTIPOINT, MULTIPOLYGON or MULTILINESTRING.
235
Add "25D" to the name to get 2.5D versions.</dd>
236
<dt> <b>-a_srs</b><em> srs_def</em>:</dt><dd> Assign an output SRS</dd>
237
<dt> <b>-t_srs</b><em> srs_def</em>:</dt><dd> Reproject/transform to this SRS on output</dd>
238
<dt> <b>-s_srs</b><em> srs_def</em>:</dt><dd> Override source SRS</dd>
239
<dt> <b>-preserve_fid</b>:</dt><dd>Use the FID of the source features instead of letting the output driver to automatically assign a new one.</dd>
240
<dt> <b>-fid</b> <i>fid</i>:</dt><dd> If provided, only the feature with this feature
241
id will be reported. Operates exclusive of the spatial or attribute
242
queries. Note: if you want to select several features based on their feature id, you can
243
also use the fact the 'fid' is a special field recognized by OGR SQL. So, '-where "fid in (1,3,5)"'
244
would select features 1, 3 and 5.</dd>
247
Srs_def can be a full WKT definition (hard to escape properly), or a well
248
known definition (ie. EPSG:4326) or a file with a WKT definition.
253
<dt> <b>-gt</b> <em>n</em>:</dt><dd> group <em>n</em> features per transaction (default 200). Increase the value
254
for better performance when writing into DBMS drivers that have transaction support.</dd>
232
255
<dt> <b>-clipsrc</b><em> [xmin ymin xmax ymax]|WKT|datasource|spat_extent</em>:
233
256
</dt><dd> (starting with GDAL 1.7.0) clip geometries to the specified bounding
234
257
box (expressed in source SRS), WKT geometry (POLYGON or MULTIPOLYGON), from a
245
268
<dt> <b>-clipdstsql</b> <em>sql_statement</em>:</dt><dd>Select desired geometries using an SQL query instead.</dd>
246
269
<dt> <b>-clipdstlayer</b> <em>layername</em>:</dt><dd>Select the named layer from the destination clip datasource.</dd>
247
270
<dt> <b>-clipdstwhere</b> <em>expression</em>:</dt><dd>Restrict desired geometries based on attribute query.</dd>
248
<dt> <b>-dsco</b> <em>NAME=VALUE</em>:</dt><dd> Dataset creation option (format specific)</dd>
249
<dt> <b>-lco</b><em> NAME=VALUE</em>:</dt><dd> Layer creation option (format specific)</dd>
250
<dt> <b>-nln</b><em> name</em>:</dt><dd> Assign an alternate name to the new layer</dd>
251
<dt> <b>-nlt</b><em> type</em>:</dt><dd> Define the geometry type for the
252
created layer. One of NONE, GEOMETRY, POINT, LINESTRING, POLYGON,
253
GEOMETRYCOLLECTION, MULTIPOINT, MULTIPOLYGON or MULTILINESTRING.
254
Add "25D" to the name to get 2.5D versions.</dd>
255
<dt> <b>-a_srs</b><em> srs_def</em>:</dt><dd> Assign an output SRS</dd>
256
<dt> <b>-t_srs</b><em> srs_def</em>:</dt><dd> Reproject/transform to this SRS on output</dd>
257
<dt> <b>-s_srs</b><em> srs_def</em>:</dt><dd> Override source SRS</dd>
258
<dt> <b>-fid</b> <i>fid</i>:</dt><dd> If provided, only the feature with this feature
259
id will be reported. Operates exclusive of the spatial or attribute
260
queries. Note: if you want to select several features based on their feature id, you can
261
also use the fact the 'fid' is a special field recognized by OGR SQL. So, '-where "fid in (1,3,5)"'
262
would select features 1, 3 and 5.</dd>
271
<dt> <b>-wrapdateline</b>:</dt><dd> (starting with GDAL 1.7.0) split geometries crossing the dateline meridian (long. = +/- 180deg)</dd>
272
<dt> <b>-simplify</b><em> tolerance</em>:</dt><dd> (starting with GDAL 1.9.0) distance tolerance for simplification.
273
This method will preserve topology, in particular for polygon geometries.</dd>
263
274
<dt> <b>-segmentize</b><em> max_dist</em>:</dt><dd> (starting with GDAL 1.6.0) maximum distance between 2 nodes.
264
Used to create intermediate pointsspatial query extents</dd>
275
Used to create intermediate points</dd>
265
276
<dt> <b>-fieldTypeToString</b><em> type1, ...</em>:</dt><dd> (starting with GDAL 1.7.0) converts any field of the
266
277
specified type to a field of type string in the destination layer. Valid types are : Integer, Real, String, Date, Time,
267
278
DateTime, Binary, IntegerList, RealList, StringList. Special value <b>All</b> can be used to convert all fields to strings.
268
279
This is an alternate way to using the CAST operator of OGR SQL, that may avoid typing a long SQL query.</dd>
280
<dt> <b>-splitlistfields</b>:</dt><dd>(starting with GDAL 1.8.0) split fields of type StringList, RealList or IntegerList into as many fields of type String, Real or Integer as necessary.</dd>
281
<dt> <b>-maxsubfields</b> <em>val</em>:</dt><dd>To be combined with -splitlistfields to limit the number of subfields created for each split field.</dd>
282
<dt> <b>-explodecollections</b>:</dt><dd>(starting with GDAL 1.8.0) produce one feature for each geometry in any kind of geometry collection in the source file</dd>
283
<dt> <b>-zfield</b> <em>field_name</em>:</dt><dd>(starting with GDAL 1.8.0) Uses the specified field to fill the Z coordinate of geometries</dd>
271
Srs_def can be a full WKT definition (hard to escape properly), or a well
272
known definition (ie. EPSG:4326) or a file with a WKT definition.
286
\section ogr2ogr_performance PERFORMANCE HINTS
288
When writing into transactional DBMS (SQLite/PostgreSQL,MySQL, etc...),
289
it might be beneficial to increase the number
290
of INSERT statements executed between BEGIN TRANSACTION and COMMIT TRANSACTION statements.
291
This number is specified with the -gt option. For example, for SQLite, explicitly defining
292
<b>-gt 1024</b> usually ensures a noticeable performance boost;
293
defining an even bigger <b>-gt 65536</b> ensures optimal performance while
294
populating some table containing many hundredth thousand or million rows. However, note that
295
if there are failed insertions, the scope of -skipfailures is a whole transaction.
297
For PostgreSQL, the PG_USE_COPY config option can be set to YES for significantly insertion
298
performance boot. See the PG driver documentation page.
300
More generally, consult the documentation page of the input and output drivers for performance hints.
302
\section ogr2ogr_example EXAMPLE
274
304
Example appending to an existing layer (both flags need to be used):