Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OGR2OGR(1)			     GDAL			    OGR2OGR(1)

NAME
       ogr2ogr - Converts simple features data between file formats.

SYNOPSIS
	  ogr2ogr [--help] [--long-usage] [--help-general]
		  [-of <output_format>]
		  [-dsco <NAME>=<VALUE>]... [-lco <NAME>=<VALUE>]...
		  [[-append]|[-upsert]|[-overwrite]]
		  [-update] [-sql <statement>|@<filename>] [-dialect <dialect>]
		  [-spat <xmin>	<ymin> <xmax> <ymax>]
		  [-where <restricted_where>|@<filename>] [-select <field_list>]
		  [-nln	<name>]	[-nlt <type>]...
		  [-s_srs <srs_def>]
		  [[-a_srs <srs_def>]|[-t_srs <srs_def>]]
		  <dst_dataset_name> <src_dataset_name>	[<layer_name>]...

	  Field	related	options:
		 [-addfields] [-relaxedFieldNameMatch]
		 [-fieldTypeToString All|<type1>[,<type2>]...]
		 [-mapFieldType	<srctype>|All=<dsttype>[,<srctype2>=<dsttype2>]...]
		 [-fieldmap <field_1>[,<field_2>]...]
		 [-splitlistfields] [-maxsubfields <n>]	[-emptyStrAsNull]
		 [-forceNullable] [-unsetFieldWidth]
		 [-unsetDefault] [-resolveDomains]
		 [-dateTimeTo UTC|UTC(+|-)<HH>|UTC(+|-)<HH>:<MM>] [-noNativeData]

	  Advanced geometry and	SRS related options:
		 [-dim layer_dim|2|XY|3|XYZ|XYM|XYZM]
		 [-s_coord_epoch <epoch>] [-a_coord_epoch <epoch>]
		 [-t_coord_epoch <epoch>] [-ct <pipeline_def>]
		 [-spat_srs <srs_def>] [-geomfield <name>]
		 [-segmentize <max_dist>] [-simplify <tolerance>]
		 [-makevalid] [-skipinvalid]
		 [-wrapdateline] [-datelineoffset <val_in_degree>]
		 [-clipsrc [<xmin> <ymin> <xmax> <ymax>]|<WKT>|<datasource>|spat_extent]
		 [-clipsrcsql <sql_statement>] [-clipsrclayer <layername>]
		 [-clipsrcwhere	<expression>]
		 [-clipdst [<xmin> <ymin> <xmax> <ymax>]|<WKT>|<datasource>]
		 [-clipdstsql <sql_statement>] [-clipdstlayer <layername>]
		 [-clipdstwhere	<expression>]
		 [-explodecollections] [-zfield	<name>]
		 [-gcp <ungeoref_x> <ungeoref_y> <georef_x> <georef_y> [<elevation>]]...
		 [-tps]	[-order	1|2|3]
		 [-xyRes <val>[	m|mm|deg]] [-zRes <val>[ m|mm]]	[-mRes <val>]
		 [-unsetCoordPrecision]

	  Other	options:
		 [--quiet] [-progress] [-if <format>]...
		 [-oo <NAME>=<VALUE>]... [-doo <NAME>=<VALUE>]...
		 [-fid <FID>] [-preserve_fid] [-unsetFid]
		 [[-skipfailures]|[-gt <n>|unlimited]]
		 [-limit <nb_features>]	[-ds_transaction]
		 [-mo <NAME>=<VALUE>]... [-nomd]

DESCRIPTION
       ogr2ogr	can  be	used to	convert	simple features	data between file for-
       mats. It	can also perform various operations during the	process,  such
       as spatial or attribute selection, reducing the set of attributes, set-
       ting  the  output  coordinate  system or	even reprojecting the features
       during translation.

       --help Show this	help message and exit

       --help-general
	      Gives a brief usage message for the generic GDAL commandline op-
	      tions and	exit.

       -if <format>
	      Format/driver name to be attempted to open the input file(s). It
	      is generally not necessary to specify it,	but it can be used  to
	      skip automatic driver detection, when it fails to	select the ap-
	      propriate	 driver.  This option can be repeated several times to
	      specify several candidate	drivers.  Note that it does not	 force
	      those  drivers  to open the dataset. In particular, some drivers
	      have requirements	on file	extensions.

	      New in version 3.2.

       -of <format_name>, -f <format_name>
	      Output file format name,	e.g.  ESRI  Shapefile,	MapInfo	 File,
	      PostgreSQL.   Starting with GDAL 2.3, if not specified, the for-
	      mat is guessed from the extension	(previously  was  ESRI	Shape-
	      file).

       -append
	      Append  to  existing  layer instead of creating new. This	option
	      also enables -update.

       -upsert
	      New in version 3.6.

	      Variant of -append where the OGRLayer::UpsertFeature() operation
	      is used to insert	or update features instead of  appending  with
	      OGRLayer::CreateFeature().

	      This  is	currently  implemented	only in	a few drivers: GPKG --
	      GeoPackage vector	and MongoDBv3.

	      The upsert operation uses	the FID	of the input feature, when  it
	      is  set  and  is a "significant" (that is	the FID	column name is
	      not the empty string), as	the key	to update  existing  features.
	      It is crucial to make sure that the FID in the source and	target
	      layers are consistent.

	      For  the	GPKG  driver,  it  is also possible to upsert features
	      whose FID	is unset or non-significant (-unsetFid can be used  to
	      ignore  the FID from the source feature),	when there is a	UNIQUE
	      column that is not the integer primary key.

       -overwrite
	      Delete the output	layer and recreate it empty

       -update
	      Open existing output datasource in update	mode rather than  try-
	      ing to create a new one

       -select <field_list>
	      Comma-delimited  list  of	fields from input layer	to copy	to the
	      new layer.

	      Starting with GDAL 3.9, field names with spaces, commas or  dou-
	      ble-quote	 should	 be surrounded with a starting and ending dou-
	      ble-quote	character, and double-quote characters in a field name
	      should be	escaped	with backslash.

	      Depending	on the shell used, this	might require further quoting.
	      For example, to select regular_field,  a_field_with  space,  and
	      comma and	a field	with " double quote with a Unix	shell:

		 -select "regular_field,\"a_field_with space, and comma\",\"a field with \\\" double quote\""

	      A	 field	is only	selected once, even if mentioned several times
	      in the list and if the input layer has duplicate field names.

	      Geometry fields can also be specified in the list.

	      All fields are selected when -select is not specified.  Specify-
	      ing  the	empty  string can be used to disable selecting any at-
	      tribute field, and only keep geometries.

	      Note this	setting	cannot be used together	with -append. To  con-
	      trol  the	 selection  of	fields	when appending to a layer, use
	      -fieldmap	or -sql.

       -progress
	      Display progress on terminal. Only works if  input  layers  have
	      the "fast	feature	count" capability.

       -sql <sql_statement>|@<filename>
	      SQL  statement  to  execute.  The	 resulting table/layer will be
	      saved to the output. Starting with GDAL 2.1, the @filename  syn-
	      tax  can	be used	to indicate that the content is	in the pointed
	      filename.	(Cannot	be used	with -spat_srs.)

       -dialect	<dialect>
	      SQL dialect. In some cases can be	used to	use the	 (unoptimized)
	      OGR SQL dialect instead of the native SQL	of an RDBMS by passing
	      the OGRSQL dialect value.	 The SQL SQLite	dialect	dialect	can be
	      chosen  with  the	SQLITE and INDIRECT_SQLITE dialect values, and
	      this can be used with any	datasource.

       -where <restricted_where>
	      Attribute	query (like SQL	WHERE).	Starting with  GDAL  2.1,  the
	      @filename	 syntax	can be used to indicate	that the content is in
	      the pointed filename.

       -skipfailures
	      Continue after a failure,	skipping the failed feature.

       -spat <xmin> <ymin> <xmax> <ymax>
	      spatial query extents, in	the SRS	of the source layer(s) (or the
	      one specified with -spat_srs). Only features whose geometry  in-
	      tersects	the  extents will be selected. The geometries will not
	      be clipped unless	-clipsrc is specified.

       -spat_srs <srs_def>
	      Override spatial filter SRS. (Cannot be used with	-sql.)

       -geomfield <field>
	      Name of the geometry field on which the spatial filter  operates
	      on.

       -dsco <NAME>=<VALUE>
	      Dataset creation option (format specific)

       -lco <NAME>=<VALUE>
	      Layer creation option (format specific)

       -nln <name>
	      Assign an	alternate name to the new layer

       -nlt <type>
	      Define  the  geometry  type  for the created layer. One of NONE,
	      GEOMETRY,	POINT, LINESTRING, POLYGON, GEOMETRYCOLLECTION,	MULTI-
	      POINT, MULTIPOLYGON, MULTILINESTRING, CIRCULARSTRING,  COMPOUND-
	      CURVE,  CURVEPOLYGON,  MULTICURVE,  and  MULTISURFACE non-linear
	      geometry types. Add Z, M,	or ZM to the type name to specify  co-
	      ordinates	 with  elevation,  measure,  or	elevation and measure.
	      PROMOTE_TO_MULTI can be used  to	automatically  promote	layers
	      that  mix	 polygon or multipolygons to multipolygons, and	layers
	      that mix linestrings or  multilinestrings	 to  multilinestrings.
	      Can  be  useful  when converting shapefiles to PostGIS and other
	      target drivers that implement strict checks for geometry	types.
	      CONVERT_TO_LINEAR	 can be	used to	to convert non-linear geometry
	      types into linear	geometry types by approximating	them, and CON-
	      VERT_TO_CURVE to promote a non-linear type  to  its  generalized
	      curve  type  (POLYGON to CURVEPOLYGON, MULTIPOLYGON to MULTISUR-
	      FACE, LINESTRING to COMPOUNDCURVE,  MULTILINESTRING  to  MULTIC-
	      URVE). Starting with version 2.1 the type	can be defined as mea-
	      sured  ("25D"  remains  as an alias for single "Z"). Some	forced
	      geometry conversions may result in invalid geometries, for exam-
	      ple when forcing conversion  of  multi-part  multipolygons  with
	      -nlt  POLYGON,  the resulting polygon will break the Simple Fea-
	      tures rules.

	      Starting with GDAL 3.0.5,	-nlt CONVERT_TO_LINEAR and  -nlt  PRO-
	      MOTE_TO_MULTI can	be used	simultaneously.

       -dim <val>
	      Force the	coordinate dimension to	val (valid values are XY, XYZ,
	      XYM, and XYZM - for backwards compatibility 2 is an alias	for XY
	      and 3 is an alias	for XYZ). This affects both the	layer geometry
	      type,  and feature geometries. The value can be set to layer_dim
	      to instruct feature geometries to	be promoted to the  coordinate
	      dimension	declared by the	layer. Support for M was added in GDAL
	      2.1.

       -a_srs <srs_def>
	      Assign  an  output  SRS, but without reprojecting	(use -t_srs to
	      reproject)

	      The coordinate reference systems that can	be passed are anything
	      supported	by the	OGRSpatialReference::SetFromUserInput()	 call,
	      which  includes EPSG Projected, Geographic or Compound CRS (i.e.
	      EPSG:4296), a well known text (WKT) CRS definition, PROJ.4  dec-
	      larations, or the	name of	a .prj file containing a WKT CRS defi-
	      nition.

       -a_coord_epoch <epoch>
	      New in version 3.4.

	      Assign  a	 coordinate  epoch, linked with	the output SRS.	Useful
	      when the output SRS is a dynamic CRS. Only taken into account if
	      -a_srs is	used.

       -t_srs <srs_def>
	      Reproject/transform to this SRS on output, and assign it as out-
	      put SRS.

	      A	source SRS must	be available for reprojection  to  occur.  The
	      source  SRS will be by default the one found in the source layer
	      when it is available, or as overridden by	the user with -s_srs

	      The coordinate reference systems that can	be passed are anything
	      supported	by the	OGRSpatialReference::SetFromUserInput()	 call,
	      which  includes EPSG Projected, Geographic or Compound CRS (i.e.
	      EPSG:4296), a well known text (WKT) CRS definition, PROJ.4  dec-
	      larations, or the	name of	a .prj file containing a WKT CRS defi-
	      nition.

       -t_coord_epoch <epoch>
	      New in version 3.4.

	      Assign  a	 coordinate  epoch, linked with	the output SRS.	Useful
	      when the output SRS is a dynamic CRS. Only taken into account if
	      -t_srs  is  used.	  It   is   also   mutually   exclusive	  with
	      -a_coord_epoch.

	      Before PROJ 9.4, -s_coord_epoch and -t_coord_epoch were mutually
	      exclusive,  due  to  lack	of support for transformations between
	      two dynamic CRS.

       -s_srs <srs_def>
	      Override source SRS. If not specified the	SRS found in the input
	      layer will be used. This option has only an effect if  used  to-
	      gether with -t_srs to reproject.

	      The coordinate reference systems that can	be passed are anything
	      supported	 by  the OGRSpatialReference::SetFromUserInput() call,
	      which includes EPSG Projected, Geographic	or Compound CRS	 (i.e.
	      EPSG:4296),  a well known	text (WKT) CRS definition, PROJ.4 dec-
	      larations, or the	name of	a .prj file containing a WKT CRS defi-
	      nition.

       -xyRes "<val>[ m|mm|deg]"
	      New in version 3.9.

	      Set/override the geometry	X/Y coordinate resolution. If  only  a
	      numeric value is specified, it is	assumed	to be expressed	in the
	      units of the target SRS.	The m, mm or deg suffixes can be spec-
	      ified to indicate	that the value must be interpreted as being in
	      meter, millimeter	or degree.

	      When  specifying	this  option,  the OGRGeometry::SetPrecision()
	      method is	run on geometries (that	are not	curves)	before passing
	      them to the output driver, to avoid  generating  invalid	geome-
	      tries  due  to  the  potentially	reduced	 precision (unless the
	      OGR_APPLY_GEOM_SET_PRECISION configuration option	is set to NO)

	      If neither this option nor -unsetCoordPrecision  are  specified,
	      the  coordinate resolution of the	source layer, if available, is
	      used.

       -zRes "<val>[ m|mm]"
	      New in version 3.9.

	      Set/override the geometry	Z coordinate resolution. If only a nu-
	      meric value is specified,	it is assumed to be expressed  in  the
	      units  of	the target SRS.	 The m or mm suffixes can be specified
	      to indicate that the value must be interpreted as	being in meter
	      or millimeter.  If neither this option nor  -unsetCoordPrecision
	      are specified, the coordinate resolution of the source layer, if
	      available, is used.

       -mRes <val>
	      New in version 3.9.

	      Set/override  the	 geometry M coordinate resolution.  If neither
	      this option nor -unsetCoordPrecision are specified, the  coordi-
	      nate resolution of the source layer, if available, is used.

       -unsetCoordPrecision
	      New in version 3.9.

	      Prevent  the  geometry  coordinate  resolution from being	set on
	      target layer(s).

       -s_coord_epoch <epoch>
	      New in version 3.4.

	      Assign a coordinate epoch, linked	with the  source  SRS.	Useful
	      when the source SRS is a dynamic CRS. Only taken into account if
	      -s_srs is	used.

	      Before PROJ 9.4, -s_coord_epoch and -t_coord_epoch were mutually
	      exclusive,  due  to  lack	of support for transformations between
	      two dynamic CRS.

       -ct <string>
	      A	PROJ string (single step operation  or	multiple  step	string
	      starting	with +proj=pipeline), a	WKT2 string describing a Coor-
	      dinateOperation, or a urn:ogc:def:coordinateOperation:EPSG::XXXX
	      URN overriding the default transformation	from the source	to the
	      target CRS.

	      It must take into	account	the axis order of the source and  tar-
	      get  CRS,	 that  is  typically  include a	step proj=axisswap or-
	      der=2,1 at the beginning of the pipeline if the source  CRS  has
	      northing/easting	axis  order, and/or at the end of the pipeline
	      if the target CRS	has northing/easting axis order.

	      New in version 3.0.

       -preserve_fid
	      Use the FID of the source	features instead of letting the	output
	      driver automatically assign a new	one (for formats that  require
	      a	 FID).	If not in append mode, this behavior is	the default if
	      the output driver	has a FID layer	creation option, in which case
	      the name of the source FID column	will be	used and  source  fea-
	      ture IDs will be attempted to be preserved. This behavior	can be
	      disabled	by  setting  -unsetFid.	 This option is	not compatible
	      with -explodecollections.

       -fid <fid>
	      If provided, only	the feature with the specified feature id will
	      be processed.  Operates exclusive	of the	spatial	 or  attribute
	      queries.	Note:  if you want to select several features based on
	      their feature id,	you can	also use the fact the 'fid' is a  spe-
	      cial  field  recognized  by OGR SQL. So, -where "fid in (1,3,5)"
	      would select features 1, 3 and 5.

       -limit <nb_features>
	      Limit the	number of features per layer.

       -oo <NAME>=<VALUE>
	      Input dataset open option	(format	specific).

       -doo <NAME>=<VALUE>
	      Destination dataset open option (format specific), only valid in
	      -update mode.

       -gt <n>
	      Group n features per transaction (default	100 000). Increase the
	      value for	better performance when	writing	into DBMS drivers that
	      have transaction support.	n can be set to	unlimited to load  the
	      data into	a single transaction.

       -ds_transaction
	      Force  the  use of a dataset level transaction (for drivers that
	      support such mechanism), especially for drivers such as  FileGDB
	      that only	support	dataset	level transaction in emulation mode.

       -clipsrc	[<xmin>	<ymin> <xmax> <ymax>]|WKT|<datasource>|spat_extent
	      Clip  geometries	(before	 potential reprojection) to one	of the
	      following:

	      	the specified bounding box (expressed in source	SRS)

	      	a WKT geometry (POLYGON	or MULTIPOLYGON	 expressed  in	source
		SRS)

	      	one or more geometries selected	from a datasource

	      	the spatial extent of the -spat	option if you use the spat_ex-
		tent keyword.

	      When  specifying	a  datasource,	you will generally want	to use
	      -clipsrc in combination of the -clipsrclayer,  -clipsrcwhere  or
	      -clipsrcsql options.

       -clipsrcsql <sql_statement>
	      Select  desired geometries from the source clip datasource using
	      an SQL query.

       -clipsrclayer <layername>
	      Select the named layer from the source clip datasource.

       -clipsrcwhere <expression>
	      Restrict desired geometries from the source clip layer based  on
	      an attribute query.

       -clipdst	[<xmin>	<ymin> <xmax> <ymax>]|<WKT>|<datasource>
	      Clip  geometries	(after	potential  reprojection) to one	of the
	      following:

	      	the specified bounding box (expressed in destination SRS)

	      	a WKT geometry (POLYGON	or MULTIPOLYGON	expressed in  destina-
		tion SRS)

	      	one or more geometries selected	from a datasource

	      When  specifying	a  datasource,	you will generally want	to use
	      -clipdst in combination with the -clipdstlayer, -clipdstwhere or
	      -clipdstsql options.

       -clipdstsql <sql_statement>
	      Select desired geometries	from the destination  clip  datasource
	      using an SQL query.

       -clipdstlayer <layername>
	      Select the named layer from the destination clip datasource.

       -clipdstwhere <expression>
	      Restrict	desired	 geometries  from  the	destination clip layer
	      based on an attribute query.

       -wrapdateline
	      Split geometries crossing	the dateline  meridian	(long.	=  +/-
	      180deg)

       -datelineoffset
	      Offset  from  dateline  in  degrees  (default long. = +/-	10deg,
	      geometries within	170deg to -170deg will be split)

       -simplify <tolerance>
	      Distance tolerance for simplification. Note: the algorithm  used
	      preserves	topology per feature, in particular for	polygon	geome-
	      tries, but not for a whole layer.

	      The  specified  value  of	 this  option is the tolerance used to
	      merge consecutive	 points	 of  the  output  geometry  using  the
	      OGRGeometry::Simplify()  method  The  unit of the	distance is in
	      georeferenced units of the source	vector dataset.	  This	option
	      is applied before	the reprojection implied by -t_srs

       -segmentize <max_dist>
	      The  specified  value of this option is the maximum distance be-
	      tween two	consecutive points of the output geometry  before  in-
	      termediate  points  are added.  The unit of the distance is geo-
	      referenced units of the source raster.  This option  is  applied
	      before the reprojection implied by -t_srs

       -makevalid
	      Run   the	  OGRGeometry::MakeValid()   operation,	  followed  by
	      OGRGeometryFactory::removeLowerDimensionSubGeoms(),  on	geome-
	      tries to ensure they are valid regarding the rules of the	Simple
	      Features specification.

       -skipinvalid
	      Run  the OGRGeometry::IsValid() operation	on geometries to check
	      if they are valid	regarding the rules  of	 the  Simple  Features
	      specification.   If  they	 are not, the feature is skipped. This
	      check is done after all other geometry operations.

       -fieldTypeToString All|<type1>[,<type2>]...
	      Converts any field of the	specified type	to  a  field  of  type
	      string  in the destination layer.	Valid types are	: Integer, In-
	      teger64, Real,  String,  Date,  Time,  DateTime,	Binary,	 Inte-
	      gerList,	Integer64List, RealList, StringList. Special value All
	      can be used to convert all fields	to strings.  This is an	alter-
	      nate way to using	the CAST operator of OGR SQL, that  may	 avoid
	      typing  a	 long SQL query. Note that this	does not influence the
	      field types used by the source driver, and is only an afterwards
	      conversion.  Also	note that this option is  without  effects  on
	      fields  whose presence and type is hard-coded in the output dri-
	      ver (e.g KML, GPX)

       -mapFieldType {<srctype>|All=<dsttype>[,<srctype2>=<dsttype2>]...}
	      Converts any field of the	specified type to another type.	 Valid
	      types  are : Integer, Integer64, Real, String, Date, Time, Date-
	      Time, Binary, IntegerList, Integer64List,	RealList,  StringList.
	      Types  can also include subtype between parenthesis, such	as In-
	      teger(Boolean), Real(Float32), ...  Special  value  All  can  be
	      used to convert all fields to another type. This is an alternate
	      way to using the CAST operator of	OGR SQL, that may avoid	typing
	      a	 long  SQL  query.  This  is  a	 generalization	of -fieldType-
	      ToString.	 Note that this	does not  influence  the  field	 types
	      used by the source driver, and is	only an	afterwards conversion.
	      Also  note  that	this option is without effects on fields whose
	      presence and type	is hard-coded in the output driver  (e.g  KML,
	      GPX)

       -dateTimeTo {UTC|UTC(+|-)<HH>|UTC(+|-)<HH>:<MM>}
	      Converts	date  time  values  from the timezone specified	in the
	      source value to the target timezone expressed with  -dateTimeTo.
	      Datetime	whose  timezone	 is unknown or localtime are not modi-
	      fied.

	      HH must be in the	[0,14] range and MM=00,	15, 30 or 45.

       -unsetFieldWidth
	      Set field	width and precision to 0.

       -splitlistfields
	      Split fields of type StringList, RealList	or IntegerList into as
	      many fields of type String, Real or Integer as necessary.

       -maxsubfields <val>
	      To be combined with -splitlistfields to limit the	number of sub-
	      fields created for each split field.

       -explodecollections
	      Produce one feature for each geometry in any  kind  of  geometry
	      collection  in  the  source file,	applied	after any -sql option.
	      This options is not compatible with -preserve_fid	but -sql  "SE-
	      LECT  fid	 AS original_fid, * FROM ..." can be used to store the
	      original FID if needed.

       -zfield <field_name>
	      Uses the specified field to fill the Z coordinate	of geometries.

       -gcp <ungeoref_x> <ungeoref_y> <georef_x> <georef_y> [<elevation>]
	      Use the indicated	ground control point to	compute	 a  coordinate
	      transformation.	The  transformation  method can	be selected by
	      specifying the -order or -tps options.  Note that	unlike	raster
	      tools such as gdal_edit or gdal_translate, GCPs are not added to
	      the  output dataset.  This option	may be provided	multiple times
	      to provide a set of GCPs (at least 2 GCPs	are needed).

       -order <n>
	      Order of polynomial used for warping (1 to 3). The default is to
	      select a polynomial order	based on the number of GCPs.

       -tps   Force use	of thin	plate spline transformer  based	 on  available
	      GCPs.

       -fieldmap
	      Specifies	the list of field indexes to be	copied from the	source
	      to the destination. The (n)th value specified in the list	is the
	      index  of	 the field in the target layer definition in which the
	      n(th) field of the source	layer  must  be	 copied.  Index	 count
	      starts  at  zero.	 To omit a field, specify a value of -1. There
	      must be exactly as many values in	the list as the	count  of  the
	      fields in	the source layer. We can use the 'identity' setting to
	      specify  that the	fields should be transferred by	using the same
	      order.  This setting should be used along	with the -append  set-
	      ting.

       -addfields
	      This  is	a specialized version of -append. Contrary to -append,
	      -addfields has the effect	of adding, to existing target  layers,
	      the  new	fields	found  in source layers. This option is	useful
	      when merging files that have non-strictly	identical  structures.
	      This might not work for output formats that don't	support	adding
	      fields  to  existing  non-empty layers. Note that	if you plan to
	      use -addfields, you may need to combine it with  -forceNullable,
	      including	for the	initial	import.

       -relaxedFieldNameMatch
	      Do  field	name matching between source and existing target layer
	      in a more	relaxed	way if the target driver has an	implementation
	      for it.

       -forceNullable
	      Do not propagate not-nullable constraints	 to  target  layer  if
	      they exist in source layer.

       -unsetDefault
	      Do  not  propagate  default field	values to target layer if they
	      exist in source layer.

       -unsetFid
	      Can be specified to prevent the name of the  source  FID	column
	      and  source feature IDs from being re-used for the target	layer.
	      This option can for example be useful if selecting  source  fea-
	      tures with a ORDER BY clause.

       -emptyStrAsNull
	      New in version 3.3.

	      Treat empty string values	as null.

       -resolveDomains
	      New in version 3.3.

	      When  this  is specified,	any selected field that	is linked to a
	      coded field domain will be accompanied by	 an  additional	 field
	      ({dstfield}_resolved),  that will	contain	the description	of the
	      coded value.

       -nomd  To disable copying of metadata from source  dataset  and	layers
	      into target dataset and layers, when supported by	output driver.

       -mo <META-TAG>=<VALUE>
	      Passes  a	 metadata  key and value to set	on the output dataset,
	      when supported by	output driver.

       -noNativeData
	      To disable copying of native data, i.e. details of source	format
	      not captured by OGR abstraction, that are	otherwise preserved by
	      some drivers (like GeoJSON) when converting to same format.

	      New in version 2.1.

       <dst_dataset_name>
	      Output dataset name.

       <src_dataset_name>
	      Source dataset name.

       <layer_name>
	      One or more source layer names to	copy to	the output dataset. If
	      no layer names are passed, then all source layers	are copied.

PERFORMANCE HINTS
       When writing into transactional DBMS (SQLite/PostgreSQL,MySQL, etc...),
       it might	be beneficial to increase the number of	INSERT statements exe-
       cuted between BEGIN TRANSACTION and COMMIT TRANSACTION statements. This
       number is specified with	the -gt	option.	For example, for  SQLite,  ex-
       plicitly	 defining -gt 65536 ensures optimal performance	while populat-
       ing some	table containing many hundreds of  thousands  or  millions  of
       rows.  However, note that -skipfailures overrides -gt and sets the size
       of transactions to 1.

       For PostgreSQL, the PG_USE_COPY config option can be set	to YES	for  a
       significant  insertion  performance boost. See the PG driver documenta-
       tion page.

       More generally, consult the documentation page of the input and	output
       drivers for performance hints.

KNOWN ISSUES
       Starting	 with  GDAL  3.8, ogr2ogr uses internally an Arrow array based
       API (cf RFC 86: Column-oriented read API	for vector  layers)  for  some
       source  formats	(in  particular	GeoPackage or FlatGeoBuf), and for the
       most basic types	of operations, to improve performance.	This  substan-
       tial  change  in	 the  ogr2ogr  internal	logic has required a number of
       fixes throughout	the GDAL 3.8.x bugfix releases to fully	stabilize  it,
       and  we believe most issues are resolved	with GDAL 3.9.	If you hit er-
       rors not	met with earlier  GDAL	versions,  you	may  specify  --config
       OGR2OGR_USE_ARROW_API  NO  on  the  ogr2ogr command line	to opt for the
       classic algorithm using an iterative feature based  approach.  If  that
       flag is needed with GDAL	>= 3.9,	please file an issue on	the GDAL issue
       tracker.

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

EXAMPLES
        Basic conversion from Shapefile to GeoPackage:

		ogr2ogr	output.gpkg input.shp

        Change	the coordinate reference system	from EPSG:4326 to EPSG:3857:

		ogr2ogr	-s_srs EPSG:4326 -t_srs	EPSG:3857 output.gpkg input.gpkg

        Example appending to an existing layer:

		ogr2ogr	-append	-f PostgreSQL PG:dbname=warmerda abc.tab

        Clip input layer with a bounding box (<xmin> <ymin> <xmax> <ymax>):

		ogr2ogr	-spat -13.931 34.886 46.23 74.12 output.gpkg natural_earth_vector.gpkg

        Filter	Features by a -where clause:

		ogr2ogr	-where "\"POP_EST\" < 1000000" \
		  output.gpkg natural_earth_vector.gpkg	ne_10m_admin_0_countries

       More examples are given in the individual format	pages.

ADVANCED EXAMPLES
        Reprojecting from ETRS_1989_LAEA_52N_10E to EPSG:4326 and clipping to
	 a bounding box:

		ogr2ogr	-wrapdateline -t_srs EPSG:4326 -clipdst	-5 40 15 55 france_4326.shp europe_laea.shp

        Using	the  -fieldmap setting.	The first field	of the source layer is
	 used to fill the third	field (index 2 = third field)  of  the	target
	 layer,	 the  second  field  of	the source layer is ignored, the third
	 field of the source layer used	to fill	the fifth field	of the	target
	 layer.

		ogr2ogr	-append	-fieldmap 2,-1,4 dst.shp src.shp

        Outputting geometries with the	CSV driver.

	 By  default,  this  driver does not preserve geometries on layer cre-
	 ation by default. An explicit layer creation option is	needed:

		ogr2ogr	-lco GEOMETRY=AS_XYZ TrackWaypoint.csv TrackWaypoint.kml

        Extracting only geometries.

	 There are different situations, depending if the input	 layer	has  a
	 named	geometry column, or not. First check, with ogrinfo if there is
	 a reported geometry column.

		ogrinfo	-so CadNSDI.gdb.zip PLSSPoint |	grep 'Geometry Column'
		Geometry Column	= SHAPE

	 In that situation where the input format is a FileGeodatabase,	it  is
	 called	 SHAPE	and can	thus be	referenced directly in a SELECT	state-
	 ment.

		ogr2ogr	-sql "SELECT SHAPE FROM	PLSSPoint" \
		  -lco GEOMETRY=AS_XY -f CSV /vsistdout/ CadNSDI.gdb.zip

	 For a shapefile with a	unnamed	geometry column, _ogr_geometry_	can be
	 used as a special name	to designate  the  implicit  geometry  column,
	 when  using  the default OGR SQL dialect. The name begins with	an un-
	 derscore and SQL syntax requires that it must appear  between	double
	 quotes.   In  addition	 the command line interpreter may require that
	 double	quotes are escaped and the final SELECT	statement  could  look
	 like:

		ogr2ogr	-sql "SELECT \"_ogr_geometry_\"	FROM PLSSPoint"	\
		  -lco GEOMETRY=AS_XY -f CSV /vsistdout/ CadNSDI.shp

	 If  using the SQL SQLite dialect, the special geometry	name is	geome-
	 try when the source geometry column has no name.

		ogr2ogr	-sql "SELECT geometry FROM PLSSPoint" -dialect SQLite \
		  -lco GEOMETRY=AS_XY -f CSV /vsistdout/ CadNSDI.shp

AUTHOR
       Frank  Warmerdam	 <warmerdam@pobox.com>,	 Silke	Reimer	<silke@inteva-
       tion.de>

COPYRIGHT
       1998-2025

				 Feb 11, 2025			    OGR2OGR(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ogr2ogr&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help