GDAL-VECTOR-LAYER-ALGEBRA(1)

📦
version 3.13.3 · 4 versions
, in alpine 3.24, arch rolling, ubuntu stonking

💅 gdal-vector-layer-algebra 💅

okay bestie, welcome to the gdal-vector-layer-algebra page from the GDAL manual (section 1) 🎀 yes she's long, yes she's worth it, and no we are not skipping a single flag. buckle up. ✨

🌸 NAME 🌸

gdal-vector-layer-algebra — perform algebraic operation between 2 layers 💞

Added in version 3.12. so she's fresh out the box, periodt. 👑

🦋 SYNOPSIS 🦋

Usage: gdal vector layer-algebra [OPTIONS] <OPERATION> <INPUT> <METHOD> <OUTPUT>

Perform algebraic operation between 2 layers.

🎀 Positional arguments

  • --operation <OPERATION> — Operation to perform. OPERATION=union|intersection|sym-difference|identity|update|clip|erase [required] — like, you have to pick one, she's not optional girl. 🔥
  • -i, --input <INPUT> — Input vector dataset [required]
  • --method <METHOD> — Method vector dataset [required]
  • -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] — so like, she goes silent but only when she's not in a pipeline, iykyk. 🤫

⭐ Options

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — Output format
  • --co, --creation-option <KEY>=<VALUE> — Creation option [may be repeated] 🔁
  • --lco, --layer-creation-option <KEY>=<VALUE> — Layer creation option [may be repeated] 🔁
  • --overwrite — Whether overwriting existing output dataset is allowed
  • --update — Whether to open existing dataset in update mode
  • --overwrite-layer — Whether overwriting existing output layer is allowed
  • --append — Whether appending to existing layer is allowed
  • --input-layer <INPUT-LAYER> — Input layer name
  • --method-layer <METHOD-LAYER> — Method layer name
  • --output-layer <OUTPUT-LAYER> — Output layer name
  • --geometry-type <GEOMETRY-TYPE> — Geometry type

💜 Advanced Options

  • --oo, --open-option <KEY>=<VALUE> — Open options [may be repeated] 🔁
  • --if, --input-format <INPUT-FORMAT> — Input formats [may be repeated] 🔁
  • --input-prefix <INPUT-PREFIX> — Prefix for fields corresponding to input layer
  • --input-field <INPUT-FIELD> — Input field(s) to add to output layer [may be repeated] — Mutually exclusive with --no-input-field, --all-input-field 🚫
  • --no-input-field — Do not add any input field to output layer — Mutually exclusive with --input-field, --all-input-field 🚫
  • --all-input-field — Add all input fields to output layer — Mutually exclusive with --input-field, --no-input-field 🚫
  • --method-prefix <METHOD-PREFIX> — Prefix for fields corresponding to method layer
  • --method-field <METHOD-FIELD> — Method field(s) to add to output layer [may be repeated] — Mutually exclusive with --no-method-field, --all-method-field 🚫
  • --no-method-field — Do not add any method field to output layer — Mutually exclusive with --method-field, --all-method-field 🚫
  • --all-method-field — Add all method fields to output layer — Mutually exclusive with --method-field, --no-method-field 🚫

✨ DESCRIPTION ✨

so gdal vector layer-algebra performs various vector layer algebraic operations 💫 the command takes a vector input source and a method source and generates the output of the operation in the specified output file. that's the whole vibe: two layers walk in, one algebraic result walks out. 🫶

👑 PROGRAM-SPECIFIC OPTIONS 👑

  • --geometry-type <GEOMETRY-TYPE> — Change the geometry type to be one of GEOMETRY, POINT, LINESTRING, POLYGON, MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRYCOLLECTION, CURVE, CIRCULARSTRING, COMPOUNDCURVE, SURFACE, CURVEPOLYGON, MULTICURVE, MULTISURFACE, POLYHEDRALSURFACE or TIN. and listen, you can slap a Z, M or ZM suffix onto any of those values to indicate the dimensionality. adding letters like accessories, iconic. 💅
  • --input-layer <INPUT-LAYER> — Name of the input vector layer. 📛
  • --operation union|intersection|sym-difference|identity|update|clip|erase — Select the operation to perform among:
    • union — A union is a set of features, which represent areas that are in either of the operand layers. The operation is symmetric, and input and method layers can be interchanged. [image] 🔄
    • intersection — An intersection is a set of features, which represent the common areas of two layers. The operation is symmetric, and input and method layers can be interchanged. [image] 🤝
    • sym-difference — A symmetric difference is a set of features, which represent areas that are in operand layers but which do not intersect. The operation is symmetric, and input and method layers can be interchanged. [image] 🔀
    • identity — The identity method identifies features in the input layer with features in the method layer possibly splitting features into several features. By default the result layer has attributes from both operand layers. [image] 🪪
    • update — The update method creates a layer, which add features into the input layer from the method layer possibly cutting features in the input layer. By default the result layer has attributes only from the input layer. [image] 🆙
    • clip — The clip method creates a layer, which has features from the input layer clipped to the areas of the features in the method layer. By default the result layer has attributes of the input layer. [image] ✂️
    • erase — The erase method creates a layer, which has features from the input layer whose areas are erased by the features in the method layer. By default the result layer has attributes of the input layer. [image] 🧽
  • --method-layer <METHOD-LAYER> — Name of the method vector layer. 📛

🧚 Advanced options

  • --all-input-field — Add all input fields to output layer. Mutually exclusive with --input-field, --no-input-field. 🚫
  • --all-method-field — Add all method fields to output layer. Mutually exclusive with --method-field, --no-method-field. 🚫
  • --input-field <INPUT-FIELD> — Input field(s) to add to output layer [may be repeated] Mutually exclusive with --no-input-field, --all-input-field. 🔁🚫
  • --input-prefix <INPUT-PREFIX> — Prefix for fields corresponding to input layer. Defaults to input_ if there are both input and method fields, otherwise empty string. 🌸
  • --method-field <METHOD-FIELD> — Input field(s) to add to output layer [may be repeated] Mutually exclusive with --no-method-field, --all-method-field. 🔁🚫
  • --method-prefix <METHOD-PREFIX> — Prefix for fields corresponding to method layer. Defaults to method_ if there are both input and method fields, otherwise empty string. 🌸
  • --no-input-field — Do not add any input field to output layer. Mutually exclusive with --input-field, --all-input-field. 🚫
  • --no-method-field — Do not add any method field to output layer. Mutually exclusive with --method-field, --all-method-field. 🚫

bestie we are not done yet, there's a part 2 coming and she has more to say. don't go anywhere 💖🦋

✨ STANDARD OPTIONS ✨

okay bestie, these are the options that basically every gdal vector subcommand shares, so once you learn them here you're set for life 💅

  • --append — whether we're allowed to append features onto layer(s) that already exist. also, lowkey iconic: this creates the output dataset if it isn't there yet. ✨
  • --co, --creation-option <NAME>=<VALUE> — tons of formats have one or more optional dataset creation options, and these let you control little particulars about the file being created. like, for example, the GeoPackage driver supports creation options that control the version. 🎀

May be repeated.

The dataset creation options you get vary by format driver, and some of the simple formats have literally no creation options at all (rip 🫶). you can list the options a format supports with the --formats command line option, but the documentation for the format is the definitive source of info on driver creation options. check the Vector drivers format specific documentation for the legal creation options of each format.

heads up bestie: dataset creation options are different from layer creation options. don't get it twisted 💀
  • --if, --input-format <format> — the format/driver name we should try to open the input file(s) with. generally you don't need to specify this, but it's there to skip automatic driver detection when the autodetect fails to pick the right driver. can be repeated several times to give several candidate drivers. note that it does not force those drivers to open the dataset — and in particular, some drivers have requirements on file extensions. 🙈

May be repeated.

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

May be repeated.

Which layer creation options exist varies by format driver, and some simple formats have none at all. you can list the options a format supports with the --formats command line option, but again, the documentation for the format is the definitive source of info on driver creation options. See Vector drivers format specific documentation for legal creation options for each format.

and yes, layer creation options are different from dataset creation options. two separate girlies, two separate jobs 😭
  • --oo, --open-option <NAME>=<VALUE> — dataset open option (format specific). that's it, that's the whole thing 💜

May be repeated.

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output vector format we're using. the allowed values can be given by:
gdal --formats | grep vector | grep rw | sort

run that and let it tell you the tea ☕

  • --output-layer <NAME> — specifies the name of the layer the features get written to. if you don't specify it, output layer names will just be the same as the input layer names. main character names carrying over, love that for us 👑
  • --overwrite — lets the program overwrite an existing target file or dataset. otherwise, by default, gdal errors out if the target file or dataset already exists. so if you want it gone, say so fr fr 🌸
  • --overwrite-layer — whether overwriting the existing output vector layer is allowed. ✨
  • --update — whether to open an existing output dataset in update mode. 🦋

💫 RETURN STATUS CODE 💫

the program returns status code 0 when it slays (success), and non-zero when it doesn't (error). and no cap: non-blocking errors that get emitted as warnings are still counted as a successful execution, so don't panic 💅

🎀 EXAMPLES 🎀

Example 1: Performs a union between both input and method layers.

$ gdal vector layer-algebra union input.shp method.shp output.shp

literally copy, paste, watch it cook 🔥

🌈 AUTHOR 🌈

Even Rouault <even.rouault@spatialys.com>

(a legend, honestly 👑)

1998-2026

okay bestie, that's the whole page!! this was GDAL-VECTOR-LAYER-ALGEBRA(1), dated Aug 18, 2026 — screenshot it, bookmark it, tattoo it, whatever, just go do your layer algebra and slay 🫶✨💅

📦 where this page comes from