GDAL-VECTOR-COMBINE(1)

📦 version 3.13.3, in alpine 3.24, arch rolling, ubuntu stonking

💖 gdal-vector-combine(1) 💖

okay so bestie, welcome to gdal-vector-combine(1) — a page out of the GDAL manual (section 1, she's iconic). This is the tool that takes all ur geometries and clumps them together into collections. Very "let's all hold hands" energy. 🫶

✨ NAME ✨

gdal-vector-combine — Combine geometries into geometry collections.

Added in version 3.13. (she's new here and already slaying 👑)

🌸 SYNOPSIS 🌸

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

Combine features into collections

📥 Positional arguments

  • -i, --input <INPUT> — the input vector datasets. Required, bestie, you can't skip it. 🚨 Also heads up: not available in pipelines.
  • -o, --output <OUTPUT> — where the output vector dataset goes. Required too! Also not available in pipelines.

🎀 Common Options

  • -h, --help — shows u the help message and dips out. 💅
  • --json-usage — prints the usage as a JSON document and exits. For the data girlies. ✨
  • --config <KEY>=<VALUE> — a configuration option. May be repeated if u got lots of them.
  • -q, --quiet — quiet mode, meaning no progress bar and no warning messages. Peace and quiet, we love her. 😌 Not available in pipelines.

🔥 Options

  • -l, --layer, --input-layer <INPUT-LAYER> — name(s) of the input layer. May be repeated. Not available in pipelines.
  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — the output format. Fun fact: "GDALG" is allowed here. 👀 Not available in pipelines.
  • --co, --creation-option <KEY>=<VALUE> — a creation option. May be repeated. Not available in pipelines.
  • --lco, --layer-creation-option <KEY>=<VALUE> — a layer creation option. May be repeated. Not available in pipelines.
  • --overwrite — whether overwriting an existing output dataset is allowed. Not available in pipelines.
  • --update — whether to open the existing dataset in update mode. Not available in pipelines.
  • --overwrite-layer — whether overwriting an existing output layer is allowed. Not available in pipelines.
  • --append — whether appending to an existing layer is allowed. Not available in pipelines. 🚫 Mutually exclusive with --upsert — pick a lane, babe.
  • --output-layer <OUTPUT-LAYER> — the output layer name. Not available in pipelines.
  • --skip-errors — skip errors when writing features. Not available in pipelines.
  • --group-by <GROUP-BY> — names of field(s) by which the inputs should be grouped. May be repeated.
  • --keep-nested — avoids combining the components of multipart geometries. (Yes this is the opposite of what u might expect — the DESCRIPTION explains it, keep reading 📖)
  • --add-extra-fields <ADD-EXTRA-FIELDS> — whether to add extra fields, depending on if they have identical values within each group. Value goes ADD-EXTRA-FIELDS=no|sometimes-identical|always-identical (default: no).

🧚 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. Not available in pipelines.
  • --upsert — upsert features, which implies 'append'. Not available in pipelines. 🚫 Mutually exclusive with --append.

💜 DESCRIPTION 💜

gdal vector combine combines geometries into geometry collections. That's the whole vibe. ✨

The --group-by argument is how u decide which features get combined together. No --group-by, no grouping decisions, everything's one big happy family.

By default, the parts of multipart geometries get combined into an un-nested collection of the most specific type possible — like MultiPolygon rather than GeometryCollection. Example time: a Polygon and a two-part MultiPolygon would be combined into a three-part MultiPolygon. 🎉

Why tho? Because many GIS file formats and software packages do not handle nested GeometryCollection types. It's giving "we can't sit with u if ur nested". 😭

But if u do want that nested representation, the ST_Collect-style PostGIS vibe — a two-component GeometryCollection containing the Polygon and the MultiPolygon — then hit --keep-nested and she'll do it ur way.

Also: combine can be used as a step of gdal vector pipeline. 🚰 So u can chain her up with her friends.

👑 PROGRAM-SPECIFIC OPTIONS 👑

--group-by <FIELD_NAMES>

The names of fields whose unique values will be used to collect the input geometries. Okay so listen: any fields not listed in --group-by will be removed from the source layer. Gone. Bye. 🫡

And if --group-by is omitted entirely, the entire layer will be combined into a single feature. One feature. Just the one. 💀

--keep-nested

If the input geometries have multiple parts, this combines them into a GeometryCollection of the input geometries. (Nested. U asked for it. 🪆)

--add-extra-fields no|sometimes-identical|always-identical

Whether fields from source features that have the same value among the features belonging to a same group get copied to the corresponding output feature.

By default — no — only the fields listed in --group-by are copied to the output layer.

When u specify sometimes-identical: fields for which all input features within at least one output group have the same value will be copied to the output layer schema. The value of the field is the value that's common for all input features of a group. And if the input features within some group are not identical, the field value in the output for that group gets set to null. 🙈

When u specify always-identical: fields for which all input features within a given output group have the same value are copied to the output layer, provided this condition holds for all output groups. All of them. Every single one. No exceptions. Periodt.

🍓 INPUT FEATURES

For example, let's suppose we have four input features with the following content, and we group them by country:

  • name: Mainland France · country: France · country_fr: France · type: continental
  • name: Corsica · country: France · country_fr: France · type: island
  • name: Mainland USA · country: USA · country_fr: Etats-Unis d'Amérique · type: continental
  • name: Alaska · country: USA · country_fr: Etats-Unis d'Amérique · type: continental

🌈 OUTPUT WITH SOMETIMES-IDENTICAL

With sometimes-identical, the output will be:

  • country: France · country_fr: France · type: (blank)
  • country: USA · country_fr: Etats-Unis d'Amérique · type: continental

The name field has been removed because it is distinct for each input feature (everyone's special, but that means nobody gets to stay 😭). The type field appears as an output field, because at least for the USA, the two grouped input features that make it have the same value. For France, its content is set to null, because its value is different in the two input features.

⭐ OUTPUT WITH ALWAYS-IDENTICAL

With always-identical, the output will be:

  • country: France · country_fr: France
  • country: USA · country_fr: Etats-Unis d'Amérique

The type field has been removed because its value is different in the two input features of France. Sorry type, u almost made it. 💅

🎯 RETURN STATUS CODE 🎯

The program returns status code 0 in case of success, and non-zero in case of error.

Tiny little plot twist: non-blocking errors that get emitted as warnings are considered a successful execution. So a lil warning here and there is not a fail, bestie. 😌

💖 STANDARD OPTIONS 💖

Okay bestie, this is the part where we go flag by flag. Buckle up, it's giving ✨ thorough ✨.

  • --append — is it allowed to append features onto layer(s) that already exist? This flag says yes. Bonus: it also creates the output dataset if it's not there yet. Two birds, one slay. 🦋
  • --co, --creation-option <NAME>=<VALUE> — for setting dataset creation options. So many formats have optional dataset creation options that let you control little particulars about the file being made — like, the GeoPackage driver supports creation options to control the version, periodt.

May be repeated. 🔁

Which dataset creation options exist totally depends on the format driver, and some simple formats have literally zero creation options. You can list what's supported for a format with the --formats command line option, but the docs for the format are the definitive source of truth on driver creation options. Go look at the Vector drivers format specific documentation for the legal creation options per format.

Heads up: dataset creation options are not the same thing as layer creation options. Do not confuse them, I'm begging. 🙈
  • --if, --input-format <format> — the format/driver name you want it to try when opening the input file(s). Usually you don't need this, but it's handy for skipping automatic driver detection when that detection fails to pick the right driver. You can repeat this option several times to list several candidate drivers. But ngl — it does not force those drivers to open the dataset. Some drivers are picky about file extensions, and that's that. 💅

May be repeated.

  • --lco, --layer-creation-option <NAME>=<VALUE> — for setting layer creation options. Lots of formats have optional layer creation options to control particulars about the layer being created. Like, the GeoPackage driver supports layer creation options to control the feature identifier or geometry column name, setting the identifier or description, etc.

May be repeated. 🔁

Which layer creation options exist varies by format driver, and some simple formats have no layer creation options at all. You can list a format's supported options with the --formats command line option, but the format's docs are the definitive source of information on driver creation options. See the Vector drivers format specific documentation for legal creation options for each format.

And again, because it matters: layer creation options are different from dataset creation options. 🫶
  • --oo, --open-option <NAME>=<VALUE> — a dataset open option (format specific).

May be repeated.

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output vector format are we using, bestie? Allowed values may be given by
gdal --formats | grep vector | grep rw | sort
  • --output-open-option, --output-oo <NAME>=<VALUE> — added in version 3.12. ✨

Dataset open option for the output dataset (format specific).

May be repeated.

  • --overwrite — lets the program overwrite an existing target file or dataset. Otherwise, by default, gdal just errors out if the target file or dataset already exists. No take-backs, no accidents. 💀
  • --overwrite-layer — whether overwriting the existing output vector layer is allowed.
  • --skip-errors — added in version 3.12. ✨

Should failures to write feature(s) just be ignored? Sure, if you say so. But ⚠️ this option sets the size of the transaction unit to one feature at a time, which may cause severe slowdown when inserting into databases. Lowkey a tradeoff, highkey worth knowing.

  • --update — whether to open an existing output dataset in update mode.
  • --upsert — added in version 3.12. ✨

A 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, Elasticsearch: Geographically Encoded Objects for Elasticsearch, and MongoDBv3. (Drivers that implement upsert expose the GDAL_DCAP_UPSERT capability. iykyk.)

The upsert operation uses the FID of the input feature — when it is set, and when the FID column name is not the empty string — as the key to update existing features. It is crucial to make sure the FID in the source and target layers are consistent. Like, actually crucial. 😭

For the GPKG driver, it's also possible to upsert features whose FID is unset or non-significant. The --unset-fid option of gdal vector edit can be used to ignore the FID from the source feature. That works when there's a UNIQUE column that is not the integer primary key. 🌸

👑 AUTHOR 👑

Dan Baston <dbaston@gmail.com>

1998-2026

And that's the whole page, bestie!! 🎀 This was GDAL-VECTOR-COMBINE(1) from GDAL, dated Aug 18, 2026 — go forth and combine those vectors, you absolute icon. 💅✨🌈

📦 where this page comes from