GDAL-VECTOR-UPDATE(1)

NAME
gdal-vector-update - Update an existing vector dataset with an input vector dataset

Added in version 3.13.

SYNOPSIS

            Usage: gdal vector update [OPTIONS] <INPUT> <OUTPUT>

            Update an existing vector dataset with an input vector dataset.

            Positional arguments:
              -i, --input <INPUT>                              Input vector datasets [required] [not available in pipelines]
              -o, --output <OUTPUT>                            Output vector dataset [required]

            Common Options:
              -h, --help                                       Display help message and exit
              --json-usage                                     Display usage as JSON document and exit
              --config <KEY>=<VALUE>                           Configuration option [may be repeated]
              -q, --quiet                                      Quiet mode (no progress bar or warning message) [not available in pipelines]

            Options:
              --input-layer <INPUT-LAYER>                      Input layer name
              --output-layer <OUTPUT-LAYER>                    Output layer name
              --mode <MODE>                                    Set update mode. MODE=merge|update-only|append-only (default: merge)
              --key <KEY>                                      Field(s) used as a key to identify features [may be repeated]

            Advanced Options:
              --if, --input-format <INPUT-FORMAT>              Input formats [may be repeated] [not available in pipelines]
              --oo, --open-option <KEY>=<VALUE>                Open options [may be repeated] [not available in pipelines]
              --output-oo, --output-open-option <KEY>=<VALUE>  Output open options [may be repeated]

DESCRIPTION

gdal vector update can be used to update the features of an existing output vector dataset with the features of the input vector. It identifies matching features between input and output based on their feature ID by default, or based on the value of one or several columns forming a key, when using --key.

With the default merge mode, features found in both layers will be updated, and features only existing in the input layer will be created in the output layer.

The schemas of the input and output layers do not need to be identical (except on columns specified by --key), but they should use the same CRS for geometry columns, as no on-the-fly reprojection is done. If a column exists in the input layer but not in the output layer, it will not be created. And if a column exists in the output layer and not in the input layer, its content will not be updated.

gdal vector update can be used as a step of a pipeline, with the input dataset being the output of the previous step.

PROGRAM-SPECIFIC OPTIONS

    --input-layer <INPUT-LAYER>
        Input layer name. Must be specified if the input dataset has several layers.

    --key <KEY>
        Field(s) used as a key to identify features. For multiple fields, specify --key multiple times.

    --mode merge|update-only|append-only
        Defines how updates are done. Default is merge.

        When using the default merge mode, features found in both layers will be updated, and features only existing in the input layer will be created in the output layer.

        When using the update-only mode, features found in both layers will be updated, and features only found in the input layer will be ignored.

        When using the append-only mode, features found in both layers will not be updated, and features only found in the input layer will be created in the output layer.

    --output-layer <OUTPUT-LAYER>
        Output layer name. Must be specified if the output dataset has several layers.

STANDARD OPTIONS

    --if, --input-format <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 appropriate 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.

        May be repeated.

    --oo, --open-option <NAME>=<VALUE>
        Dataset open option (format specific).

        May be repeated.

    --output-open-option, --output-oo <NAME>=<VALUE>
        Added in version 3.12.

        Dataset open option for output dataset (format specific).

        May be repeated.

RETURN STATUS CODE

The program returns status code 0 in case of success, and non-zero in case of error (non-blocking errors emitted as warnings are considered as a successful execution).

EXAMPLES

  Example 1: Update existing out.gpkg with content of in.gpkg, using identifier as the key.

            $ gdal vector update --key identifier in.gpkg out.gpkg

AUTHOR
Even Rouault <even.rouault@spatialys.com>

COPYRIGHT
1998-2026