.. _gdal_vector_concat:

================================================================================
``gdal vector concat``
================================================================================

.. versionadded:: 3.11

.. only:: html

    Concatenate vector datasets

.. Index:: gdal vector concat

Synopsis
--------

.. program-output:: gdal vector concat --help-doc

Description
-----------

:program:`gdal vector concat` concatenates several source datasets.

It has 3 main modes:

- :option:`--mode` = ``merge-per-layer-name`` (the default). The output
  dataset generated by the command will contain as many layers as there are
  different layer names in the source datasets.
  For example if there are 2 datasets, one with layers `a` and `b`, and the
  other one with layers `b` and `c`, 3 output layers will be created: `a`,
  `b` (merging the 2 source layers) and `c`.

- :option:`--mode` = ``stack``. The output dataset generated by the command will
  contain as many layers as there are layers in the source datasets.
  For example if there are 2 datasets ``ds1`` (with layers `a` and `b`) and
  ``ds2`` (with layers `b` and `c`), 4 output layers will be created: ``ds1_a``,
  ``ds1_b``, ``ds2_b`` and ``ds2_c``.

- :option:`--mode` = ``single``. The output dataset generated by the command will
  contain one single layer, merging all layers in the source datasets.

When an output layer merges several source layer, by default the resulting
schema will contain the union of all source fields. It is possible to select
only the intersection with the :option:`--field-strategy` set to ``intersection``.
Regarding the resulting CRS, by default the CRS of the source layer will be
used as the target CRS, and features of other source layers that do no match
this CRS will be reprojected to it. :option:`--dst-crs` can be used to select
a given destination CRS.

This command can also be used as the first step of :ref:`gdal_vector_pipeline`.

Standard options
++++++++++++++++

.. include:: gdal_options/of_vector.rst

.. include:: gdal_options/co_vector.rst

.. include:: gdal_options/overwrite.rst

.. option:: --update

    Whether the output dataset must be opened in update mode. Implies that
    it already exists. This mode is useful when adding new layer(s) to an
    already existing dataset.

.. option:: --overwrite-layer

    Whether overwriting existing layer(s) is allowed.

.. option:: --append

    Whether appending features to existing layer(s) is allowed

.. option:: -l, --layer, --input-layer <LAYER>

    Name of one or more layers to inspect.  If no layer names are passed, then
    all layers will be selected.

.. option:: --output-layer <OUTPUT-LAYER>

    Name of the output vector layer (in ``single`` mode, and the default is
    "merged"), or template to name the output vector layers in ``stack``
    mode (the default value is ``{AUTO_NAME}``).
    Not allowed in ``merge-per-layer-name`` mode.

    The template in ``stack`` mode can be a string with the following variables
    that will be substituted with a value computed from the input layer being processed:

    -  ``{AUTO_NAME}``: equivalent to ``{DS_BASENAME}_{LAYER_NAME}`` if both
       values are different, or ``{LAYER_NAME}`` when they are identical
       (case of shapefile).
    -  ``{DS_NAME}``: name of the source dataset
    -  ``{DS_BASENAME}``: base name of the source dataset
    -  ``{DS_INDEX}``: index of the source dataset
    -  ``{LAYER_NAME}``: name of the source layer
    -  ``{LAYER_INDEX}``: index of the source layer

.. option:: --mode merge-per-layer-name|stack|single

    Determine the strategy to create output layers from source layers. See
    introductory paragraph for more details.

.. option:: --source-layer-field-name <SOURCE-LAYER-FIELD-NAME>

    If specified, the schema of the target layer will be extended with a field
    whose name is the value of this option and whose content is
    determined :option:`--source-layer-field-content`.

.. option:: --source-layer-field-content <SOURCE-LAYER-FIELD-CONTENT>

    If specified, the schema of the target layer will be extended with a new field
    (whose name is given by :option:`--source-layer-field-name`,
    or ``source_ds_lyr`` otherwise), whose content is determined by the specified
    template (see :option:`--output-layer` for variables that can be used).

.. option:: --field-strategy union|intersection

    Determines how the schema of the target layer is built from the schemas of
    the input layers:

    - ``union`` (default) to use a super-set of all the fields from all source layers.

    - ``intersection`` to use a sub-set of all the common fields from all
      source layers.

.. option:: -s, --src-crs <SRC-CRS>

    Set source spatial reference. If not specified the SRS found in the input
    dataset will be used.

    .. include:: options/srs_def_gdalwarp.rst

.. option:: -d, --dst-crs <SRC-CRS>

    Set destination spatial reference.

    .. include:: options/srs_def_gdalwarp.rst


.. GDALG output (on-the-fly / streamed dataset)
.. --------------------------------------------

.. include:: gdal_cli_include/gdalg_vector_compatible.rst

Examples
--------

.. example::
   :title: Creating a GeoPackage stacking all input shapefiles in separate layers.

   .. code-block:: bash

       gdal vector concat --stack *.shp out.gpkg

.. example::
   :title: Adding a field to indicate the source layer, and reprojecting to a single CRS

   Concatenate the content of :file:`france.shp` and :file:`germany.shp` in :file:`merged.shp`,
   reprojecting them to ETRS89, and add a 'country' field to each feature whose value is 'france' or
   'germany' depending where it comes from:

   .. code-block:: bash

       gdal vector concat --single --source-layer-field-name=country --dst-crs=EPSG:4258 france.shp germany.shp merged.shp
