1OGR2OGR(1)                           GDAL                           OGR2OGR(1)
2
3
4

NAME

6       ogr2ogr - Converts simple features data between file formats.
7

SYNOPSIS

9          ogr2ogr [--help-general] [-skipfailures] [-append] [-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
21                  # 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]
34                  [-relaxedFieldNameMatch] [-forceNullable] [-unsetDefault]
35                  [-fieldTypeToString All|(type1[,type2]*)] [-unsetFieldWidth]
36                  [-mapFieldType type1|All=type2[,type3=type4]*]
37                  [-fieldmap identity | index1[,index2]*]
38                  [-splitlistfields] [-maxsubfields val]
39                  [-explodecollections] [-zfield field_name]
40                  [-gcp ungeoref_x ungeoref_y georef_x georef_y [elevation]]* [-order n | -tps]
41                  [-nomd] [-mo "META-TAG=VALUE"]* [-noNativeData]
42

DESCRIPTION

44       ogr2ogr  can  be used to convert simple features data between file for‐
45       mats. It can also perform various operations during the  process,  such
46       as spatial or attribute selection, reducing the set of attributes, set‐
47       ting the output coordinate system or  even  reprojecting  the  features
48       during translation.
49
50       -f <format_name>
51              Output  file  format  name,  e.g.  ESRI Shapefile, MapInfo File,
52              PostgreSQL.  Starting with GDAL 2.3, if not specified, the  for‐
53              mat  is  guessed  from the extension (previously was ESRI Shape‐
54              file).
55
56       -append
57              Append to existing layer instead of creating new
58
59       -overwrite
60              Delete the output layer and recreate it empty
61
62       -update
63              Open existing output datasource in update mode rather than  try‐
64              ing to create a new one
65
66       -select <field_list>
67              Comma-delimited  list  of fields from input layer to copy to the
68              new layer. A field is skipped if  mentioned  previously  in  the
69              list  even  if  the  input  layer  has  duplicate  field  names.
70              (Defaults to all; any field is skipped  if  a  subsequent  field
71              with  same name is found.) Geometry fields can also be specified
72              in the list.
73
74              Note this setting cannot be used together with -append. To  con‐
75              trol  the  selection  of  fields  when appending to a layer, use
76              -fieldmap or -sql.
77
78       -progress
79              Display progress on terminal. Only works if  input  layers  have
80              the "fast feature count" capability.
81
82       -sql <sql_statement>
83              SQL  statement  to  execute.  The  resulting table/layer will be
84              saved to the output. Starting with GDAL 2.1, the @filename  syn‐
85              tax  can  be used to indicate that the content is in the pointed
86              filename.
87
88       -dialect <dialect>
89              SQL dialect. In some cases can be used to use (unoptimized)  OGR
90              SQL instead of the native SQL of an RDBMS by passing OGRSQL. The
91              "SQLITE" dialect can also be used with any datasource.
92
93       -where restricted_where
94              Attribute query (like SQL WHERE). Starting with  GDAL  2.1,  the
95              @filename  syntax can be used to indicate that the content is in
96              the pointed filename.
97
98       -skipfailures
99              Continue after a failure, skipping the failed feature.
100
101       -spat <xmin> <ymin> <xmax> <ymax>
102              spatial query extents, in the SRS of the source layer(s) (or the
103              one  specified  with  -spat_srs).  Only  features whose geometry
104              intersects the extents will be selected. The geometries will not
105              be clipped unless -clipsrc is specified.
106
107       -spat_srs <srs_def>
108              Override spatial filter SRS.
109
110       -geomfield <field>
111              Name  of the geometry field on which the spatial filter operates
112              on.
113
114       -dsco NAME=VALUE
115              Dataset creation option (format specific)
116
117       -lco NAME=VALUE
118              Layer creation option (format specific)
119
120       -nln <name>
121              Assign an alternate name to the new layer
122
123       -nlt <type>
124              Define the geometry type for the created  layer.  One  of  NONE,
125              GEOMETRY, POINT, LINESTRING, POLYGON, GEOMETRYCOLLECTION, MULTI‐
126              POINT, MULTIPOLYGON, MULTILINESTRING, CIRCULARSTRING,  COMPOUND‐
127              CURVE,  CURVEPOLYGON,  MULTICURVE,  and  MULTISURFACE non-linear
128              geometry types. Add Z, M, or ZM to  the  type  name  to  specify
129              coordinates  with  elevation, measure, or elevation and measure.
130              PROMOTE_TO_MULTI can be used  to  automatically  promote  layers
131              that  mix  polygon or multipolygons to multipolygons, and layers
132              that mix linestrings or  multilinestrings  to  multilinestrings.
133              Can  be  useful  when converting shapefiles to PostGIS and other
134              target drivers that implement strict checks for geometry  types.
135              CONVERT_TO_LINEAR  can be used to to convert non-linear geometry
136              types into linear geometry types by approximating them, and CON‐
137              VERT_TO_CURVE  to  promote  a non-linear type to its generalized
138              curve type (POLYGON to CURVEPOLYGON, MULTIPOLYGON  to  MULTISUR‐
139              FACE,  LINESTRING  to  COMPOUNDCURVE, MULTILINESTRING to MULTIC‐
140              URVE). Starting with version 2.1 the type can be defined as mea‐
141              sured  ("25D"  remains  as an alias for single "Z"). Some forced
142              geometry conversions may result in invalid geometries, for exam‐
143              ple  when  forcing  conversion  of multi-part multipolygons with
144              -nlt POLYGON, the resulting polygon will break the  Simple  Fea‐
145              tures rules.
146
147              Starting  with  GDAL 3.0.5, -nlt CONVERT_TO_LINEAR and -nlt PRO‐
148              MOTE_TO_MULTI can be used simultaneously.
149
150       -dim <val>
151              Force the coordinate dimension to val (valid values are XY, XYZ,
152              XYM, and XYZM - for backwards compatibility 2 is an alias for XY
153              and 3 is an alias for XYZ). This affects both the layer geometry
154              type,  and feature geometries. The value can be set to layer_dim
155              to instruct feature geometries to be promoted to the  coordinate
156              dimension declared by the layer. Support for M was added in GDAL
157              2.1.
158
159       -a_srs <srs_def>
160              Assign an output SRS. Srs_def can be a full WKT definition (hard
161              to escape properly), or a well known definition (i.e. EPSG:4326)
162              or a file with a WKT definition.
163
164       -t_srs <srs_def>
165              Reproject/transform to this SRS on output.
166
167       -s_srs <srs_def>
168              Override source SRS.
169
170       -ct <string>
171              A PROJ string (single step operation  or  multiple  step  string
172              starting  with +proj=pipeline), a WKT2 string describing a Coor‐
173              dinateOperation, or a urn:ogc:def:coordinateOperation:EPSG::XXXX
174              URN overriding the default transformation from the source to the
175              target CRS. It must take into account  the  axis  order  of  the
176              source and target CRS.
177
178              New in version 3.0.
179
180
181       -preserve_fid
182              Use the FID of the source features instead of letting the output
183              driver automatically assign a new one (for formats that  require
184              an  FID).   If not in append mode, this behaviour is the default
185              if the output driver has a FID layer creation option,  un  which
186              case  the  name of the source FID column will be used and source
187              feature IDs will be attempted to be  preserved.  This  behaviour
188              can be disabled by setting -unsetFid.
189
190       -fid fid
191              If provided, only the feature with the specified feature id will
192              be processed.  Operates exclusive of the  spatial  or  attribute
193              queries.  Note:  if you want to select several features based on
194              their feature id, you can also use the fact the 'fid' is a  spe‐
195              cial  field  recognized  by OGR SQL. So, -where "fid in (1,3,5)"
196              would select features 1, 3 and 5.
197
198       -limit nb_features
199              Limit the number of features per layer.
200
201       -oo NAME=VALUE
202              Input dataset open option (format specific).
203
204       -doo NAME=VALUE
205              Destination dataset open option (format specific), only valid in
206              -update mode.
207
208       -gt n  Group  n  features per transaction (default 20000). Increase the
209              value for better performance when writing into DBMS drivers that
210              have  transaction support. n can be set to unlimited to load the
211              data into a single transaction.
212
213       -ds_transaction
214              Force the use of a dataset level transaction (for  drivers  that
215              support  such mechanism), especially for drivers such as FileGDB
216              that only support dataset level transaction in emulation mode.
217
218       -clipsrc [xmin ymin xmax ymax]|WKT|datasource|spat_extent
219              Clip geometries to the  specified  bounding  box  (expressed  in
220              source  SRS),  WKT  geometry  (POLYGON  or MULTIPOLYGON), from a
221              datasource or to the spatial extent of the -spa.. option if  you
222              use  the  spat_extent keyword. When specifying a datasource, you
223              will generally want to use it in  combination  of  the  -clipsr‐
224              clayer, -clipsrcwhere or -clipsrcsql options
225
226       -clipsrcsql <sql_statement>
227              Select desired geometries using an SQL query instead.
228
229       -clipsrclayer <layername>
230              Select the named layer from the source clip datasource.
231
232       -clipsrcwhere <expression>
233              Restrict desired geometries based on attribute query.
234
235       -clipdst <xmin> <ymin> <xmax> <ymax>
236              Clip geometries after reprojection to the specified bounding box
237              (expressed in dest SRS), WKT geometry (POLYGON or  MULTIPOLYGON)
238              or  from  a  datasource.  When specifying a datasource, you will
239              generally want to use it in combination  of  the  -clipdstlayer,
240              -clipdstwhere or -clipdstsq.. options
241
242       -clipdstsql <sql_statement>
243              Select desired geometries using an SQL query instead.
244
245       -clipdstlayer <layername>
246              Select the named layer from the destination clip datasource.
247
248       -clipdstwhere <expression>
249              Restrict desired geometries based on attribute query.
250
251       -wrapdateline
252              Split  geometries  crossing  the  dateline meridian (long. = +/-
253              180deg)
254
255       -datelineoffset
256              Offset from dateline in degrees  (default  long.  =  +/-  10deg,
257              geometries within 170deg to -170deg will be split)
258
259       -simplify <tolerance>
260              Distance  tolerance for simplification. Note: the algorithm used
261              preserves topology per feature, in particular for polygon geome‐
262              tries, but not for a whole layer.
263
264       -segmentize <max_dist>
265              Maximum  distance  between  2 nodes. Used to create intermediate
266              points.
267
268       -makevalid
269              Run the OGRGeometry::MakeValid() operation, followed by OGRGeom‐
270              etryFactory::removeLowerDimensionSubGeoms(),  on  geometries  to
271              ensure they are valid regarding the rules of the Simple Features
272              specification.
273
274       -fieldTypeToString type1,...
275              Converts  any  field  of  the  specified type to a field of type
276              string in the destination layer.  Valid  types  are  :  Integer,
277              Integer64,  Real,  String,  Date,  Time, DateTime, Binary, Inte‐
278              gerList, Integer64List, RealList, StringList. Special value  All
279              can be used to convert all fields to strings.  This is an alter‐
280              nate way to using the CAST operator of OGR SQL, that  may  avoid
281              typing  a  long SQL query. Note that this does not influence the
282              field types used by the source driver, and is only an afterwards
283              conversion.
284
285       -mapFieldType srctype|All=dsttype,...
286              Converts  any field of the specified type to another type. Valid
287              types are : Integer, Integer64, Real, String, Date, Time,  Date‐
288              Time,  Binary, IntegerList, Integer64List, RealList, StringList.
289              Types can also include  subtype  between  parenthesis,  such  as
290              Integer(Boolean),  Real(Float32),  ...  Special value All can be
291              used to convert all fields to another type. This is an alternate
292              way to using the CAST operator of OGR SQL, that may avoid typing
293              a long SQL  query.  This  is  a  generalization  of  -fieldType‐
294              ToString.   Note  that  this  does not influence the field types
295              used by the source driver, and is only an afterwards conversion.
296
297       -unsetFieldWidth
298              Set field width and precision to 0.
299
300       -splitlistfields
301              Split fields of type StringList, RealList or IntegerList into as
302              many fields of type String, Real or Integer as necessary.
303
304       -maxsubfields <val>
305              To be combined with -splitlistfields to limit the number of sub‐
306              fields created for each split field.
307
308       -explodecollections
309              Produce one feature for each geometry in any  kind  of  geometry
310              collection in the source file, applied after any -sql option.
311
312       -zfield <field_name>
313              Uses the specified field to fill the Z coordinate of geometries.
314
315       -gcp <ungeoref_x> <ungeoref_y> <georef_x> <georef_y> <elevation>
316              Add  the indicated ground control point. This option may be pro‐
317              vided multiple times to provide a set of GCPs.
318
319       -order <n>
320              Order of polynomial used for warping (1 to 3). The default is to
321              select a polynomial order based on the number of GCPs.
322
323       -tps   Force  use  of  thin plate spline transformer based on available
324              GCPs.
325
326       -fieldmap
327              Specifies the list of field indexes to be copied from the source
328              to the destination. The (n)th value specified in the list is the
329              index of the field in the target layer definition in  which  the
330              n(th)  field  of  the  source  layer must be copied. Index count
331              starts at zero. To omit a field, specify a value  of  -1.  There
332              must  be  exactly as many values in the list as the count of the
333              fields in the source layer. We can use the 'identity' setting to
334              specify  that the fields should be transferred by using the same
335              order.  This setting should be used along with the -append  set‐
336              ting.
337
338       -addfields
339              This  is  a specialized version of -append. Contrary to -append,
340              -addfields has the effect of adding, to existing target  layers,
341              the  new  fields  found  in source layers. This option is useful
342              when merging files that have non-strictly identical  structures.
343              This might not work for output formats that don't support adding
344              fields to existing non-empty layers. Note that if  you  plan  to
345              use  -addfields, you may need to combine it with -forceNullable,
346              including for the initial import.
347
348       -relaxedFieldNameMatch
349              Do field name matching between source and existing target  layer
350              in a more relaxed way if the target driver has an implementation
351              for it.
352
353       -forceNullable
354              Do not propagate not-nullable constraints  to  target  layer  if
355              they exist in source layer.
356
357       -unsetDefault
358              Do  not  propagate  default field values to target layer if they
359              exist in source layer.
360
361       -unsetFid
362              Can be specify to prevent the name of the source FID column  and
363              source feature IDs from being re-used for the target layer. This
364              option can for example be useful if  selecting  source  features
365              with a ORDER BY clause.
366
367       -nomd  To  disable  copying  of metadata from source dataset and layers
368              into target dataset and layers, when supported by output driver.
369
370       -mo META-TAG=VALUE
371              Passes a metadata key and value to set on  the  output  dataset,
372              when supported by output driver.
373
374       -noNativeData
375              To disable copying of native data, i.e. details of source format
376              not captured by OGR abstraction, that are otherwise preserved by
377              some drivers (like GeoJSON) when converting to same format.
378
379              New in version 2.1.
380
381

PERFORMANCE HINTS

383       When writing into transactional DBMS (SQLite/PostgreSQL,MySQL, etc...),
384       it might be beneficial to increase the number of INSERT statements exe‐
385       cuted between BEGIN TRANSACTION and COMMIT TRANSACTION statements. This
386       number is specified with the  -gt  option.  For  example,  for  SQLite,
387       explicitly  defining  -gt 65536 ensures optimal performance while popu‐
388       lating some table containing many hundreds of thousands or millions  of
389       rows.  However, note that -skipfailures overrides -gt and sets the size
390       of transactions to 1.
391
392       For PostgreSQL, the PG_USE_COPY config option can be set to YES  for  a
393       significant  insertion  performance boost. See the PG driver documenta‐
394       tion page.
395
396       More generally, consult the documentation page of the input and  output
397       drivers for performance hints.
398

C API

400       This utility is also callable from C with GDALVectorTranslate().
401

EXAMPLES

403       Basic conversion from Shapefile to GeoPackage:
404
405          ogr2ogr \
406            -f GPKG output.gpkg \
407            input.shp
408
409       Change the coordinate reference system from EPSG:4326 to EPSG:3857:
410
411          ogr2ogr \
412            -s_srs EPSG:4326 \
413            -t_srs EPSG:3857 \
414            -f GPKG output.gpkg \
415            input.gpkg
416
417       Example  appending to an existing layer (both -update and -append flags
418       need to be used):
419
420          ogr2ogr -update -append -f PostgreSQL PG:dbname=warmerda abc.tab
421
422       Clip input layer with a bounding box (<xmin> <ymin> <xmax> <ymax>):
423
424          ogr2ogr \
425            -spat -13.931 34.886 46.23 74.12 \
426            -f GPKG output.gpkg \
427            natural_earth_vector.gpkg
428
429       Filter Features by a -where clause:
430
431          ogr2ogr \
432            -where "\"POP_EST\" < 1000000" \
433            -f GPKG output.gpkg \
434            natural_earth_vector.gpkg \
435            ne_10m_admin_0_countries
436
437       Example reprojecting from ETRS_1989_LAEA_52N_10E to EPSG:4326 and clip‐
438       ping to a bounding box:
439
440          ogr2ogr -wrapdateline -t_srs EPSG:4326 -clipdst -5 40 15 55 france_4326.shp europe_laea.shp
441
442       Example  for using the -fieldmap setting. The first field of the source
443       layer is used to fill the third field (index 2 = third  field)  of  the
444       target  layer,  the  second  field  of the source layer is ignored, the
445       third field of the source layer used to fill the  fifth  field  of  the
446       target layer.
447
448          ogr2ogr -append -fieldmap 2,-1,4 dst.shp src.shp
449
450       More examples are given in the individual format pages.
451

AUTHOR

453       Frank  Warmerdam  <warmerdam@pobox.com>,  Silke  Reimer  <silke@inteva‐
454       tion.de>
455
457       1998-2021
458
459
460
461
462                                 Jan 05, 2021                       OGR2OGR(1)
Impressum