1OGR2OGR(1) GDAL OGR2OGR(1)
2
6 ogr2ogr - Converts simple features data between file formats.
7
9 ogr2ogr [--help-general] [-skipfailures] [-append | -upsert] [-update]
10 [-select field_list] [-where restricted_where|@filename]
11 [-progress] [-sql <sql statement>|@filename] [-dialect dialect]
12 [-preserve_fid] [-fid FID] [-limit nb_features]
13 [-spat xmin ymin xmax ymax] [-spat_srs srs_def] [-geomfield field]
14 [-a_srs srs_def] [-t_srs srs_def] [-s_srs srs_def] [-ct string]
15 [-f format_name] [-overwrite] [[-dsco NAME=VALUE] ...]
16 dst_datasource_name src_datasource_name
17 [-lco NAME=VALUE] [-nln name]
18 [-nlt type|PROMOTE_TO_MULTI|CONVERT_TO_LINEAR|CONVERT_TO_CURVE]
19 [-dim XY|XYZ|XYM|XYZM|2|3|layer_dim] [layer [layer ...]]
20 # Advanced options
22 [-gt n]
23 [[-oo NAME=VALUE] ...] [[-doo NAME=VALUE] ...]
24 [-clipsrc [xmin ymin xmax ymax]|WKT|datasource|spat_extent]
25 [-clipsrcsql sql_statement] [-clipsrclayer layer]
26 [-clipsrcwhere expression]
27 [-clipdst [xmin ymin xmax ymax]|WKT|datasource]
28 [-clipdstsql sql_statement] [-clipdstlayer layer]
29 [-clipdstwhere expression]
30 [-wrapdateline] [-datelineoffset val]
31 [[-simplify tolerance] | [-segmentize max_dist]]
32 [-makevalid]
33 [-addfields] [-unsetFid] [-emptyStrAsNull]
34 [-relaxedFieldNameMatch] [-forceNullable] [-unsetDefault]
35 [-fieldTypeToString All|(type1[,type2]*)] [-unsetFieldWidth]
36 [-mapFieldType type1|All=type2[,type3=type4]*]
37 [-dateTimeTo UTC|UTC(+|-)HH|UTC(+|-)HH:MM]]
38 [-fieldmap identity | index1[,index2]*]
39 [-splitlistfields] [-maxsubfields val]
40 [-resolveDomains]
41 [-explodecollections] [-zfield field_name]
42 [-gcp ungeoref_x ungeoref_y georef_x georef_y [elevation]]* [-order n | -tps]
43 [[-s_coord_epoch epoch] | [-t_coord_epoch epoch] | [-a_coord_epoch epoch]]
44 [-nomd] [-mo "META-TAG=VALUE"]* [-noNativeData]
45
47 ogr2ogr can be used to convert simple features data between file for‐
48 mats. It can also perform various operations during the process, such
49 as spatial or attribute selection, reducing the set of attributes, set‐
50 ting the output coordinate system or even reprojecting the features
51 during translation.
52 -f <format_name>
54 Output file format name, e.g. ESRI Shapefile, MapInfo File,
55 PostgreSQL. Starting with GDAL 2.3, if not specified, the for‐
56 mat is guessed from the extension (previously was ESRI Shape‐
57 file).
58 -append
60 Append to existing layer instead of creating new. This option
61 also enables -update.
62 -upsert
64 New in version 3.6.
65 Variant of -append where the OGRLayer::UpsertFeature() operation
68 is used to insert or update features instead of appending with
69 OGRLayer::CreateFeature().
70 This is currently implemented only in a few drivers: GPKG --
72 GeoPackage vector and MongoDBv3.
73 The upsert operation uses the FID of the input feature, when it
75 is set and is a "significant" (that is the FID column name is
76 not the empty string), as the key to update existing features.
77 It is crucial to make sure that the FID in the source and target
78 layers are consistent.
79 For the GPKG driver, it is also possible to upsert features
81 whose FID is unset or non-significant (-unsetFid can be used to
82 ignore the FID from the source feature), when there is a UNIQUE
83 column that is not the integer primary key.
84 -overwrite
86 Delete the output layer and recreate it empty
87 -update
89 Open existing output datasource in update mode rather than try‐
90 ing to create a new one
91 -select <field_list>
93 Comma-delimited list of fields from input layer to copy to the
94 new layer. A field is skipped if mentioned previously in the
95 list even if the input layer has duplicate field names. (De‐
96 faults to all; any field is skipped if a subsequent field with
97 same name is found.) Geometry fields can also be specified in
98 the list.
99 Note this setting cannot be used together with -append. To con‐
101 trol the selection of fields when appending to a layer, use
102 -fieldmap or -sql.
103 -progress
105 Display progress on terminal. Only works if input layers have
106 the "fast feature count" capability.
107 -sql <sql_statement>
109 SQL statement to execute. The resulting table/layer will be
110 saved to the output. Starting with GDAL 2.1, the @filename syn‐
111 tax can be used to indicate that the content is in the pointed
112 filename.
113 -dialect <dialect>
115 SQL dialect. In some cases can be used to use (unoptimized) OGR
116 SQL dialect instead of the native SQL of an RDBMS by passing the
117 OGRSQL dialect value. The SQL SQLite dialect dialect can be se‐
118 lect with the SQLITE and INDIRECT_SQLITE dialect values, and
119 this can be used with any datasource.
120 -where restricted_where
122 Attribute query (like SQL WHERE). Starting with GDAL 2.1, the
123 @filename syntax can be used to indicate that the content is in
124 the pointed filename.
125 -skipfailures
127 Continue after a failure, skipping the failed feature.
128 -spat <xmin> <ymin> <xmax> <ymax>
130 spatial query extents, in the SRS of the source layer(s) (or the
131 one specified with -spat_srs). Only features whose geometry in‐
132 tersects the extents will be selected. The geometries will not
133 be clipped unless -clipsrc is specified.
134 -spat_srs <srs_def>
136 Override spatial filter SRS.
137 -geomfield <field>
139 Name of the geometry field on which the spatial filter operates
140 on.
141 -dsco NAME=VALUE
143 Dataset creation option (format specific)
144 -lco NAME=VALUE
146 Layer creation option (format specific)
147 -nln <name>
149 Assign an alternate name to the new layer
150 -nlt <type>
152 Define the geometry type for the created layer. One of NONE, GE‐
153 OMETRY, POINT, LINESTRING, POLYGON, GEOMETRYCOLLECTION, MULTI‐
154 POINT, MULTIPOLYGON, MULTILINESTRING, CIRCULARSTRING, COMPOUND‐
155 CURVE, CURVEPOLYGON, MULTICURVE, and MULTISURFACE non-linear ge‐
156 ometry types. Add Z, M, or ZM to the type name to specify coor‐
157 dinates with elevation, measure, or elevation and measure. PRO‐
158 MOTE_TO_MULTI can be used to automatically promote layers that
159 mix polygon or multipolygons to multipolygons, and layers that
160 mix linestrings or multilinestrings to multilinestrings. Can be
161 useful when converting shapefiles to PostGIS and other target
162 drivers that implement strict checks for geometry types. CON‐
163 VERT_TO_LINEAR can be used to to convert non-linear geometry
164 types into linear geometry types by approximating them, and CON‐
165 VERT_TO_CURVE to promote a non-linear type to its generalized
166 curve type (POLYGON to CURVEPOLYGON, MULTIPOLYGON to MULTISUR‐
167 FACE, LINESTRING to COMPOUNDCURVE, MULTILINESTRING to MULTIC‐
168 URVE). Starting with version 2.1 the type can be defined as mea‐
169 sured ("25D" remains as an alias for single "Z"). Some forced
170 geometry conversions may result in invalid geometries, for exam‐
171 ple when forcing conversion of multi-part multipolygons with
172 -nlt POLYGON, the resulting polygon will break the Simple Fea‐
173 tures rules.
174 Starting with GDAL 3.0.5, -nlt CONVERT_TO_LINEAR and -nlt PRO‐
176 MOTE_TO_MULTI can be used simultaneously.
177 -dim <val>
179 Force the coordinate dimension to val (valid values are XY, XYZ,
180 XYM, and XYZM - for backwards compatibility 2 is an alias for XY
181 and 3 is an alias for XYZ). This affects both the layer geometry
182 type, and feature geometries. The value can be set to layer_dim
183 to instruct feature geometries to be promoted to the coordinate
184 dimension declared by the layer. Support for M was added in GDAL
185 2.1.
186 -a_srs <srs_def>
188 Assign an output SRS, but without reprojecting (use -t_srs to
189 reproject)
190 The coordinate reference systems that can be passed are anything
192 supported by the OGRSpatialReference.SetFromUserInput() call,
193 which includes EPSG Projected, Geographic or Compound CRS (i.e.
194 EPSG:4296), a well known text (WKT) CRS definition, PROJ.4 dec‐
195 larations, or the name of a .prj file containing a WKT CRS defi‐
196 nition.
197 -a_coord_epoch <epoch>
199 New in version 3.4.
200 Assign a coordinate epoch, linked with the output SRS. Useful
203 when the output SRS is a dynamic CRS. Only taken into account if
204 -a_srs is used.
205 -t_srs <srs_def>
207 Reproject/transform to this SRS on output, and assign it as out‐
208 put SRS.
209 A source SRS must be available for reprojection to occur. The
211 source SRS will be by default the one found in the source layer
212 when it is available, or as overridden by the user with -s_srs
213 The coordinate reference systems that can be passed are anything
215 supported by the OGRSpatialReference.SetFromUserInput() call,
216 which includes EPSG Projected, Geographic or Compound CRS (i.e.
217 EPSG:4296), a well known text (WKT) CRS definition, PROJ.4 dec‐
218 larations, or the name of a .prj file containing a WKT CRS defi‐
219 nition.
220 -t_coord_epoch <epoch>
222 New in version 3.4.
223 Assign a coordinate epoch, linked with the output SRS. Useful
226 when the output SRS is a dynamic CRS. Only taken into account if
227 -t_srs is used. It is also mutually exclusive with
228 -a_coord_epoch.
229 Currently -s_coord_epoch and -t_coord_epoch are mutually exclu‐
231 sive, due to lack of support for transformations between two dy‐
232 namic CRS.
233 -s_srs <srs_def>
235 Override source SRS. If not specified the SRS found in the input
236 layer will be used. This option has only an effect if used to‐
237 gether with -t_srs to reproject.
238 The coordinate reference systems that can be passed are anything
240 supported by the OGRSpatialReference.SetFromUserInput() call,
241 which includes EPSG Projected, Geographic or Compound CRS (i.e.
242 EPSG:4296), a well known text (WKT) CRS definition, PROJ.4 dec‐
243 larations, or the name of a .prj file containing a WKT CRS defi‐
244 nition.
245 -s_coord_epoch <epoch>
247 New in version 3.4.
248 Assign a coordinate epoch, linked with the source SRS. Useful
251 when the source SRS is a dynamic CRS. Only taken into account if
252 -s_srs is used.
253 Currently -s_coord_epoch and -t_coord_epoch are mutually exclu‐
255 sive, due to lack of support for transformations between two dy‐
256 namic CRS.
257 -ct <string>
259 A PROJ string (single step operation or multiple step string
260 starting with +proj=pipeline), a WKT2 string describing a Coor‐
261 dinateOperation, or a urn:ogc:def:coordinateOperation:EPSG::XXXX
262 URN overriding the default transformation from the source to the
263 target CRS. It must take into account the axis order of the
264 source and target CRS.
265 New in version 3.0.
267 -preserve_fid
270 Use the FID of the source features instead of letting the output
271 driver automatically assign a new one (for formats that require
272 a FID). If not in append mode, this behavior is the default if
273 the output driver has a FID layer creation option, in which case
274 the name of the source FID column will be used and source fea‐
275 ture IDs will be attempted to be preserved. This behavior can be
276 disabled by setting -unsetFid. This option is not compatible
277 with -explodecollections.
278 -fid fid
280 If provided, only the feature with the specified feature id will
281 be processed. Operates exclusive of the spatial or attribute
282 queries. Note: if you want to select several features based on
283 their feature id, you can also use the fact the 'fid' is a spe‐
284 cial field recognized by OGR SQL. So, -where "fid in (1,3,5)"
285 would select features 1, 3 and 5.
286 -limit nb_features
288 Limit the number of features per layer.
289 -oo NAME=VALUE
291 Input dataset open option (format specific).
292 -doo NAME=VALUE
294 Destination dataset open option (format specific), only valid in
295 -update mode.
296 -gt n Group n features per transaction (default 100 000). Increase the
298 value for better performance when writing into DBMS drivers that
299 have transaction support. n can be set to unlimited to load the
300 data into a single transaction.
301 -ds_transaction
303 Force the use of a dataset level transaction (for drivers that
304 support such mechanism), especially for drivers such as FileGDB
305 that only support dataset level transaction in emulation mode.
306 -clipsrc [xmin ymin xmax ymax]|WKT|datasource|spat_extent
308 Clip geometries to one of the following:
309 • the specified bounding box (expressed in source SRS)
311 • a WKT geometry (POLYGON or MULTIPOLYGON expressed in source
313 SRS)
314 • one or more geometries selected from a datasource
316 • the spatial extent of the -spat option if you use the spat_ex‐
318 tent keyword.
319 When specifying a datasource, you will generally want to use
321 -clipsrc in combination of the -clipsrclayer, -clipsrcwhere or
322 -clipsrcsql options.
323 -clipsrcsql <sql_statement>
325 Select desired geometries from the source clip datasource using
326 an SQL query.
327 -clipsrclayer <layername>
329 Select the named layer from the source clip datasource.
330 -clipsrcwhere <expression>
332 Restrict desired geometries from the source clip layer based on
333 an attribute query.
334 -clipdst [<xmin> <ymin> <xmax> <ymax>]|WKT|datasource
336 Clip geometries to one of the following:
337 • the specified bounding box (expressed in destination SRS)
339 • a WKT geometry (POLYGON or MULTIPOLYGON expressed in destina‐
341 tion SRS)
342 • one or more geometries selected from a datasource
344 When specifying a datasource, you will generally want to use
346 -clipdst in combination with the -clipdstlayer, -clipdstwhere or
347 -clipdstsql options.
348 -clipdstsql <sql_statement>
350 Select desired geometries from the destination clip datasource
351 using an SQL query.
352 -clipdstlayer <layername>
354 Select the named layer from the destination clip datasource.
355 -clipdstwhere <expression>
357 Restrict desired geometries from the destination clip layer
358 based on an attribute query.
359 -wrapdateline
361 Split geometries crossing the dateline meridian (long. = +/-
362 180deg)
363 -datelineoffset
365 Offset from dateline in degrees (default long. = +/- 10deg, ge‐
366 ometries within 170deg to -170deg will be split)
367 -simplify <tolerance>
369 Distance tolerance for simplification. Note: the algorithm used
370 preserves topology per feature, in particular for polygon geome‐
371 tries, but not for a whole layer.
372 -segmentize <max_dist>
374 Maximum distance between 2 nodes. Used to create intermediate
375 points.
376 -makevalid
378 Run the OGRGeometry::MakeValid() operation, followed by
379 OGRGeometryFactory::removeLowerDimensionSubGeoms(), on geome‐
380 tries to ensure they are valid regarding the rules of the Simple
381 Features specification.
382 -fieldTypeToString type1,...
384 Converts any field of the specified type to a field of type
385 string in the destination layer. Valid types are : Integer, In‐
386 teger64, Real, String, Date, Time, DateTime, Binary, Inte‐
387 gerList, Integer64List, RealList, StringList. Special value All
388 can be used to convert all fields to strings. This is an alter‐
389 nate way to using the CAST operator of OGR SQL, that may avoid
390 typing a long SQL query. Note that this does not influence the
391 field types used by the source driver, and is only an afterwards
392 conversion.
393 -mapFieldType srctype|All=dsttype,...
395 Converts any field of the specified type to another type. Valid
396 types are : Integer, Integer64, Real, String, Date, Time, Date‐
397 Time, Binary, IntegerList, Integer64List, RealList, StringList.
398 Types can also include subtype between parenthesis, such as In‐
399 teger(Boolean), Real(Float32), ... Special value All can be
400 used to convert all fields to another type. This is an alternate
401 way to using the CAST operator of OGR SQL, that may avoid typing
402 a long SQL query. This is a generalization of -fieldType‐
403 ToString. Note that this does not influence the field types
404 used by the source driver, and is only an afterwards conversion.
405 -dateTimeTo UTC|UTC(+|-)HH|UTC(+|-)HH:MM]
407 Converts date time values from the timezone specified in the
408 source value to the target timezone expressed with -dateTimeTo.
409 Datetime whose timezone is unknown or localtime are not modi‐
410 fied.
411 HH must be in the [0,14] range and MM=00, 15, 30 or 45.
413 -unsetFieldWidth
415 Set field width and precision to 0.
416 -splitlistfields
418 Split fields of type StringList, RealList or IntegerList into as
419 many fields of type String, Real or Integer as necessary.
420 -maxsubfields <val>
422 To be combined with -splitlistfields to limit the number of sub‐
423 fields created for each split field.
424 -explodecollections
426 Produce one feature for each geometry in any kind of geometry
427 collection in the source file, applied after any -sql option.
428 This options is not compatible with -preserve_fid but -sql "SE‐
429 LECT fid AS original_fid, * FROM ..." can be used to store the
430 original FID if needed.
431 -zfield <field_name>
433 Uses the specified field to fill the Z coordinate of geometries.
434 -gcp <ungeoref_x> <ungeoref_y> <georef_x> <georef_y> <elevation>
436 Add the indicated ground control point. This option may be pro‐
437 vided multiple times to provide a set of GCPs.
438 -order <n>
440 Order of polynomial used for warping (1 to 3). The default is to
441 select a polynomial order based on the number of GCPs.
442 -tps Force use of thin plate spline transformer based on available
444 GCPs.
445 -fieldmap
447 Specifies the list of field indexes to be copied from the source
448 to the destination. The (n)th value specified in the list is the
449 index of the field in the target layer definition in which the
450 n(th) field of the source layer must be copied. Index count
451 starts at zero. To omit a field, specify a value of -1. There
452 must be exactly as many values in the list as the count of the
453 fields in the source layer. We can use the 'identity' setting to
454 specify that the fields should be transferred by using the same
455 order. This setting should be used along with the -append set‐
456 ting.
457 -addfields
459 This is a specialized version of -append. Contrary to -append,
460 -addfields has the effect of adding, to existing target layers,
461 the new fields found in source layers. This option is useful
462 when merging files that have non-strictly identical structures.
463 This might not work for output formats that don't support adding
464 fields to existing non-empty layers. Note that if you plan to
465 use -addfields, you may need to combine it with -forceNullable,
466 including for the initial import.
467 -relaxedFieldNameMatch
469 Do field name matching between source and existing target layer
470 in a more relaxed way if the target driver has an implementation
471 for it.
472 -forceNullable
474 Do not propagate not-nullable constraints to target layer if
475 they exist in source layer.
476 -unsetDefault
478 Do not propagate default field values to target layer if they
479 exist in source layer.
480 -unsetFid
482 Can be specified to prevent the name of the source FID column
483 and source feature IDs from being re-used for the target layer.
484 This option can for example be useful if selecting source fea‐
485 tures with a ORDER BY clause.
486 -emptyStrAsNull
488 New in version 3.3.
489 Treat empty string values as null.
492 -resolveDomains
494 New in version 3.3.
495 When this is specified, any selected field that is linked to a
498 coded field domain will be accompanied by an additional field
499 ({dstfield}_resolved), that will contain the description of the
500 coded value.
501 -nomd To disable copying of metadata from source dataset and layers
503 into target dataset and layers, when supported by output driver.
504 -mo META-TAG=VALUE
506 Passes a metadata key and value to set on the output dataset,
507 when supported by output driver.
508 -noNativeData
510 To disable copying of native data, i.e. details of source format
511 not captured by OGR abstraction, that are otherwise preserved by
512 some drivers (like GeoJSON) when converting to same format.
513 New in version 2.1.
515
518 When writing into transactional DBMS (SQLite/PostgreSQL,MySQL, etc...),
519 it might be beneficial to increase the number of INSERT statements exe‐
520 cuted between BEGIN TRANSACTION and COMMIT TRANSACTION statements. This
521 number is specified with the -gt option. For example, for SQLite, ex‐
522 plicitly defining -gt 65536 ensures optimal performance while populat‐
523 ing some table containing many hundreds of thousands or millions of
524 rows. However, note that -skipfailures overrides -gt and sets the size
525 of transactions to 1.
526 For PostgreSQL, the PG_USE_COPY config option can be set to YES for a
528 significant insertion performance boost. See the PG driver documenta‐
529 tion page.
530 More generally, consult the documentation page of the input and output
532 drivers for performance hints.
533
535 This utility is also callable from C with GDALVectorTranslate().
536
538 Basic conversion from Shapefile to GeoPackage:
539 ogr2ogr output.gpkg input.shp
541 Change the coordinate reference system from EPSG:4326 to EPSG:3857:
543 ogr2ogr -s_srs EPSG:4326 -t_srs EPSG:3857 output.gpkg input.gpkg
545 Example appending to an existing layer:
547 ogr2ogr -append -f PostgreSQL PG:dbname=warmerda abc.tab
549 Clip input layer with a bounding box (<xmin> <ymin> <xmax> <ymax>):
551 ogr2ogr -spat -13.931 34.886 46.23 74.12 output.gpkg natural_earth_vector.gpkg
553 Filter Features by a -where clause:
555 ogr2ogr -where "\"POP_EST\" < 1000000" \
557 output.gpkg natural_earth_vector.gpkg ne_10m_admin_0_countries
558 Example reprojecting from ETRS_1989_LAEA_52N_10E to EPSG:4326 and clip‐
560 ping to a bounding box:
561 ogr2ogr -wrapdateline -t_srs EPSG:4326 -clipdst -5 40 15 55 france_4326.shp europe_laea.shp
563 Example for using the -fieldmap setting. The first field of the source
565 layer is used to fill the third field (index 2 = third field) of the
566 target layer, the second field of the source layer is ignored, the
567 third field of the source layer used to fill the fifth field of the
568 target layer.
569 ogr2ogr -append -fieldmap 2,-1,4 dst.shp src.shp
571 More examples are given in the individual format pages.
573
575 Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@inteva‐
576 tion.de>
577
579 1998-2023
580 Oct 30, 2023 OGR2OGR(1)