GDAL-VECTOR-PIPELINE(1)

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

💖 GDAL-VECTOR-PIPELINE 💖

okay so hi bestie 🫶 this is <pink>GDAL-VECTOR-PIPELINE(1)</pink>, straight out of the GDAL corner of your manual. it's giving pipeline couture, and ngl it's a long one, so buckle up. ✨

🌸 NAME 🌸

gdal-vector-pipeline — Process a vector dataset applying several steps

Added in version 3.11. 🎀 (yes queen, it's new new)

🦋 DESCRIPTION 🦋

okay so gdal vector pipeline is THE step for processing a vector dataset — it runs a whole lil' assembly line of processing steps, and every step takes vector in and gives vector back out. 💅

if you're doing that mixie thing where raster and vector are hanging out together in one pipeline, no worries — go consult gdal pipeline instead, that's its whole job. 🌈

here's the iconic part: most steps run on-demand feature evaluation — unless their own docs say otherwise — and they do NOT "materialize" the resulting dataset that each step's operation produces. so it's like, chill, nothing gets written down unless someone says so. ✨

but sometimes, for performance reasons, you do want to actually bake an intermediate dataset out to disk. in that case, bestie, go use gdal vector materialize. 🧚

⭐ SYNOPSIS ⭐

Usage: gdal vector pipeline [OPTIONS] <PIPELINE>

and <PIPELINE> is literally of this form, no cap:

<PIPELINE> is of the form: read|concat [READ-OPTIONS] ( ! <STEP-NAME> [STEP-OPTIONS] )* ! write|info [WRITE-OPTIONS]

👑 Common Options

  • -h, --help — show the help message and dip. 🫶
  • --json-usage — print the usage as a JSON document and bounce.
  • --config <KEY>=<VALUE> — set a configuration option. [may be repeated] 💜
  • -q, --quiet — quiet mode, so no progress bar and no warning messages. [not available in pipelines] 🙈

💅 Options

  • --skip-errors — skip errors when writing features. [not available in pipelines] 💀

🎀 How a pipeline is shaped

a pipeline chains several steps together, and they're separated with the ! (exclamation mark) character. like, the punctuation IS the plumbing. 😭

the first step has to be read or concat. the last one has to be info, partition or write. (yes, those are the only legal ways to start and end, periodt.)

each step comes with its own positional or non-positional arguments, whatever it needs. and apart from read, concat, info, partition and write — which are the special ones — all the other steps can potentially show up several times in a single pipeline. slay. 🔥

🌈 STEPS 🌈

here's the whole guest list, alphabetized and everything:

  • buffer
  • check-coverage
  • check-geometry
  • clean-coverage
  • clip
  • combine
  • concave-hull
  • concat
  • convex-hull
  • create
  • dissolve
  • edit
  • explode-collections
  • export-schema
  • external
  • filter
  • info
  • limit
  • make-point
  • make-valid
  • materialize
  • partition
  • read
  • rename-layer
  • reproject
  • segmentize
  • select
  • set-field-type
  • set-geom-type
  • simplify
  • simplify-coverage
  • sort
  • sql
  • swap-xy
  • tee
  • update
  • write

🫧 buffer

buffer [OPTIONS] <DISTANCE>

computes a buffer around the geometries of a vector dataset. it's giving personal space, but make it geometry. 💖

Positional arguments

  • --distance <DISTANCE> — how far out to extend the geometry. [required] 👑

Options

  • --active-layer <ACTIVE-LAYER> — set the active layer. (if you don't specify, it's all of them) 🎀
  • --active-geometry <ACTIVE-GEOMETRY> — the geometry field name to restrict the processing to. (if you don't specify, it's all of them)
  • --endcap-style <ENDCAP-STYLE> — the endcap style. ENDCAP-STYLE=round|flat|square (default: round) 🌸
  • --join-style <JOIN-STYLE> — the join style. JOIN-STYLE=round|mitre|bevel (default: round)
  • --mitre-limit <MITRE-LIMIT> — mitre ratio limit (only affects mitered join style). (default: 5)
  • --quadrant-segments <QUADRANT-SEGMENTS> — number of line segments used to approximate a quarter circle. (default: 8)
  • --side <SIDE> — sets whether the computed buffer should be single-sided or not. SIDE=both|left|right (default: both)
details for options can be found in gdal vector buffer. 🦋

🫧 check-coverage

check-coverage [OPTIONS]

checks a polygon coverage for validity. like a vibe check but for polygons. ✨

Options

  • --include-valid — include valid inputs in the output, but with an empty geometry.
  • --geometry-field <GEOMETRY-FIELD> — name of the geometry field to check.
  • --maximum-gap-width <MAXIMUM-GAP-WIDTH> — maximum width of a gap to be flagged. 🚩
details for options can be found in gdal vector check-coverage. 💜

🫧 check-geometry

check-geometry [OPTIONS]

checks a dataset for invalid geometries. somebody has to do it. 🙈

Options

  • --include-field <INCLUDE-FIELD> — fields from the input layer to include in the output (special values: ALL and NONE) (default: NONE) [may be repeated] 💅
  • --include-valid — include valid inputs in the output, but with an empty geometry.
  • --geometry-field <GEOMETRY-FIELD> — name of the geometry field to check.
details for options can be found in gdal vector check-geometry. 🎀

🫧 clean-coverage

clean-coverage [OPTIONS]

alters polygon boundaries so shared edges become identical — gap removal AND overlap removal, a genuine glow-up for your topology. 👑

Options

  • --active-layer <ACTIVE-LAYER> — set the active layer. (if you don't specify, it's all of them)
  • --snapping-distance <SNAPPING-DISTANCE> — distance tolerance for snapping nodes. 📌
  • --merge-strategy <MERGE-STRATEGY> — the algorithm to assign overlaps to neighboring polygons. MERGE-STRATEGY=longest-border|max-area|min-area|min-index
  • --maximum-gap-width <MAXIMUM-GAP-WIDTH> — maximum width of a gap to be closed.
details for options can be found in gdal vector clean-coverage. 🌸

🫧 clip

clip [OPTIONS]

clips a vector dataset. ✂️ iconic behavior.

Options

  • --active-layer <ACTIVE-LAYER> — set the active layer. (if you don't specify, it's all of them)
  • --bbox <BBOX> — clipping bounding box as xmin,ymin,xmax,ymax. Mutually exclusive with --geometry, --like ⚠️
  • --bbox-crs <BBOX-CRS> — CRS of the clipping bounding box.
  • --geometry <GEOMETRY> — clipping geometry (WKT or GeoJSON). Mutually exclusive with --bbox, --like ⚠️
  • --geometry-crs <GEOMETRY-CRS> — CRS of the clipping geometry.
  • --like <DATASET> — dataset to use as a template for bounds. Mutually exclusive with --bbox, --geometry ⚠️
  • --like-sql <SELECT-STATEMENT> — SELECT statement to run on the 'like' dataset. Mutually exclusive with --like-where ⚠️
  • --like-layer <LAYER-NAME> — name of the layer of the 'like' dataset.
  • --like-where <WHERE-EXPRESSION> — WHERE SQL clause to run on the 'like' dataset. Mutually exclusive with --like-sql ⚠️
details for options can be found in gdal vector clip. 🦋

🫧 combine

combine [OPTIONS]

combines features into collections. friendship bracelet energy, but geometrically. 💖

Options

  • --group-by <GROUP-BY> — names of field(s) by which inputs should be grouped. [may be repeated]
  • --keep-nested — avoid combining the components of multipart geometries. 🪆
  • --add-extra-fields <ADD-EXTRA-FIELDS> — whether to add extra fields, depending on if they have identical values within each group. ADD-EXTRA-FIELDS=no|sometimes-identical|always-identical (default: no)
details for options can be found in gdal vector combine. ✨

🫧 concave-hull

concave-hull [OPTIONS]

computes the concave hull of the geometries of a vector dataset. the ✨*curvy*✨ edition.

Options

  • --active-layer <ACTIVE-LAYER> — set the active layer. (if you don't specify, it's all of them)
  • --active-geometry <ACTIVE-GEOMETRY> — the geometry field name to restrict the processing to. (if you don't specify, it's all of them)
  • --ratio <RATIO> — ratio controlling the concavity. [required] 👑
  • --allow-holes — allow holes in the output polygon. 🕳️
  • --tight — whether the hull must follow the outer boundaries of the input polygons.
details for options can be found in gdal vector concave-hull. 🌸

🫧 concat

concat [OPTIONS] <INPUTS>...

concatenates vector datasets. yes, all the datasets. bring them together, bestie. 🫶

Positional arguments

  • -i, --input <INPUTS> — input vector datasets [1.. values] [required] 🔥

Options

  • -l, --layer, --input-layer <INPUT-LAYER> — input layer name(s). [may be repeated]
  • --mode <MODE> — determines the strategy to create output layers from source layers. MODE=merge-per-layer-name|stack|single (default: merge-per-layer-name)
  • --output-layer <OUTPUT-LAYER> — name of the output vector layer (single mode), or a template to name the output vector layers (stack mode).
  • --source-layer-field-name <SOURCE-LAYER-FIELD-NAME> — name of the new field to add, which contains the identification of the source layer, with the value determined from 'source-layer-field-content'.
  • --source-layer-field-content <SOURCE-LAYER-FIELD-CONTENT> — a string, possibly using {AUTO_NAME}, {DS_NAME}, {DS_BASENAME}, {DS_INDEX}, {LAYER_NAME}, {LAYER_INDEX} 🎀
  • --field-strategy <FIELD-STRATEGY> — how to determine target fields from source fields. FIELD-STRATEGY=union|intersection (default: union)
  • -s, --input-crs <INPUT-CRS> — input CRS.
  • -d, --output-crs <OUTPUT-CRS> — output CRS.

Advanced Options

  • --if, --input-format <INPUT-FORMAT> — input formats. [may be repeated]
  • --oo, --open-option <KEY>=<VALUE> — open options. [may be repeated] 💜
details for options can be found in gdal vector concat. 🌈

🫧 convex-hull

convex-hull [OPTIONS]

computes the convex hull of the geometries of a vector dataset. taut, snatched, zero concavity. 💅

Options

  • --active-layer <ACTIVE-LAYER> — set the active layer. (if you don't specify, it's all of them)
  • --active-geometry <ACTIVE-GEOMETRY> — the geometry field name to restrict the processing to. (if you don't specify, it's all of them)
details for options can be found in gdal vector convex-hull. ⭐

🫧 create

create [OPTIONS] <OUTPUT>

creates a vector dataset. from nothing. main character energy fr fr. 👑

Positional arguments

  • -o, --output <OUTPUT> — output vector dataset [required] ✨

✨ Options ✨

bestie this step comes loaded, so let's get into it 🎀

  • -i, --like, --input <TEMPLATE-DATASET> — the input vector dataset(s). Mutually exclusive with --schema and --field, so no trying to do all three at once 💅
  • -l, --layer, --input-layer <INPUT-LAYER> — input layer name(s), and yeah you can repeat this one as many times as you need 🫶
  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — the output format ("GDALG" is allowed, iconic)
  • --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 an existing output dataset is allowed
  • --update — whether to open the existing dataset in update mode
  • --overwrite-layer — whether overwriting an existing output layer is allowed
  • --output-layer <OUTPUT-LAYER> — the output layer name ✨
  • --geometry-type <GEOMETRY-TYPE> — layer geometry type
  • --geometry-field <GEOMETRY-FIELD> — name of the geometry field to create (if the output format supports it). Default: geom
  • --crs <CRS> — set the CRS
  • --fid <FID> — FID column name
  • --schema <SCHEMA_JSON> — read OGR_SCHEMA and populate field definitions from it. Mutually exclusive with --input and --field
  • --field <NAME>:<TYPE>[(,<WIDTH>[,<PRECISION>])]> — add a field definition to the output layer [may be repeated]. Mutually exclusive with --input and --schema

🚀 Advanced Options 🚀

  • --if, --input-format <INPUT-FORMAT> — input formats [may be repeated]
  • --oo, --open-option <KEY>=<VALUE> — open options [may be repeated]
  • --output-oo, --output-open-option <KEY>=<VALUE> — output open options [may be repeated]

Details for options can be found in gdal vector create.

💧 dissolve 💧

* dissolve [OPTIONS]

Dissolves multipart features — merging all that multi-part energy into one cohesive vibe 🔥

Options

  • --active-layer <ACTIVE-LAYER> — set the active layer (if you don't say which one, it's all of them)
  • --active-geometry <ACTIVE-GEOMETRY> — geometry field name to restrict the processing to (if not specified, all)

Details for options can be found in gdal vector dissolve.

✏️ edit ✏️

* edit [OPTIONS]

Edit the metadata of a vector dataset. Glow-up for your dataset's little info card 💖

Options

  • --active-layer <ACTIVE-LAYER> — set the active layer (if not specified, all)
  • --output-layer <OUTPUT-LAYER> — output layer name
  • --geometry-type <GEOMETRY-TYPE> — layer geometry type
  • --crs <CRS> — override CRS (no reprojection, bestie, it's just a relabel)
  • --metadata <KEY>=<VALUE> — add/update a dataset metadata item [may be repeated]
  • --unset-metadata <KEY> — remove a dataset metadata item [may be repeated]
  • --layer-metadata <KEY>=<VALUE> — add/update a layer metadata item [may be repeated]
  • --unset-layer-metadata <KEY> — remove a layer metadata item [may be repeated]
  • --unset-fid — unset the identifier of each feature and the FID column name

Details for options can be found in gdal vector edit.

🎆 explode-collections 🎆

* explode-collections [OPTIONS]

Explode geometries of type collection of a vector dataset — like popping a confetti cannon of little geometries 🎉

Options

  • --active-layer <ACTIVE-LAYER> — set the active layer (if not specified, all)
  • --active-geometry <ACTIVE-GEOMETRY> — geometry field name to restrict the processing to (if not specified, all)
  • --geometry-type <GEOMETRY-TYPE> — geometry type
  • --skip-on-type-mismatch — skip the feature when the change of feature geometry type failed

Details for options can be found in gdal vector explode-collections.

📤 export-schema 📤

Added in version 3.12. ✨

* export-schema [OPTIONS]

Export the OGR_SCHEMA from a vector dataset.

Positional arguments:

(none bestie, it's a pure options situation)

Options

  • -l, --layer, --input-layer <INPUT-LAYER> — input layer name [may be repeated]

Details for options can be found in gdal vector export-schema.

🌐 external 🌐

* external [OPTIONS] <COMMAND>

Execute an external program as a step of a pipeline 🚀

Positional arguments:

  • --command <COMMAND> — external command, optionally with <INPUT> and/or <OUTPUT> or <INPUT-OUTPUT> placeholders [required]

Options

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — output format

🚀 Advanced Options 🚀

  • --if, --input-format <INPUT-FORMAT> — input formats

Details for options can be found in gdal external.

🧚 filter 🧚

* filter [OPTIONS]

Filter a vector dataset — we're being selective, and honestly, same.

Options

  • --active-layer <ACTIVE-LAYER> — set the active layer (if not specified, all)
  • --bbox <BBOX> — bounding box as xmin,ymin,xmax,ymax
  • --where <WHERE>|@<filename> — attribute query in a restricted form of the queries used in the SQL WHERE statement
  • --update-extent — update layer extent to take into account the filter

Details for options can be found in gdal vector filter.

🔍 info 🔍

Added in version 3.12. ✨

* info [OPTIONS]

Return information on a vector dataset — the dataset spills the tea about itself ☕

Positional arguments:

(none, bestie — all options all day)

Options

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — output format. OUTPUT-FORMAT=json|text
  • -l, --layer, --input-layer <INPUT-LAYER> — input layer name [may be repeated]. Mutually exclusive with --sql and --fid
  • --features — list all features (beware of RAM consumption on large layers — this one can get heavy, bestie). Mutually exclusive with --summary
  • --summary — list the layer names and the geometry type. Mutually exclusive with --features
  • --limit <FEATURE-COUNT> — limit the number of features per layer (implies --features)
  • --sql <statement>|@<filename> — execute the indicated SQL statement and return the result. Mutually exclusive with --input-layer and --fid
  • --where <WHERE>|@<filename> — attribute query in a restricted form of the queries used in the SQL WHERE statement
  • --fid <FID> — feature identifier. Mutually exclusive with --input-layer and --sql
  • --dialect <DIALECT> — SQL dialect

🔮 Esoteric Options 🔮

  • --crs-format <CRS-FORMAT> — which format to use to report the CRS. CRS-FORMAT=AUTO|WKT2|PROJJSON (default: AUTO)

Details for options can be found in gdal vector info.

🚧 limit 🚧

* limit [OPTIONS] <LIMIT>

Truncate a vector dataset to no more than a specified number of features. Setting boundaries, we love to see it 💅

Positional arguments:

  • --limit <LIMIT> — limit the number of features to read per layer [required]

Options

  • --active-layer <ACTIVE-LAYER> — set the active layer (if not specified, all)

📍 make-point 📍

* make-point [OPTIONS]

Create point geometries from attribute fields — your data becomes dots, slay 🌸

Options

  • --x <X> — field from which the X coordinate should be read [required]
  • --y <Y> — field from which the Y coordinate should be read [required]
  • --z <Z> — optional field from which the Z coordinate should be read
  • --m <M> — optional field from which the M coordinate should be read
  • --output-crs <OUTPUT-CRS> — output CRS

Details for options can be found in gdal vector make-point.

🩹 make-valid 🩹

* make-valid [OPTIONS]

Fix the validity of geometries of a vector dataset — healing your wonky shapes, no cap 🫶

Options

  • --active-layer <ACTIVE-LAYER> — set the active layer (if not specified, all)
  • --active-geometry <ACTIVE-GEOMETRY> — geometry field name to restrict the processing to (if not specified, all)
  • --method <METHOD> — algorithm to use when repairing invalid geometries.. METHOD=linework|structure (default: linework)
  • --keep-lower-dim — keep components of lower dimension after MakeValid()

Details for options can be found in gdal vector make-valid.

💾 materialize 💾

* materialize [OPTIONS]

Materialize a piped dataset on disk to increase the efficiency of the following steps — a lil glow-up pit stop so everything downstream runs smoother 🔥

Options

  • -o, --output <OUTPUT> — materialized dataset name (created by the algorithm)
  • -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 an existing output dataset is allowed

Details for options can be found in gdal vector materialize.

🍰 partition 🍰

Added in version 3.12. ✨

* partition [OPTIONS] <OUTPUT>

Partition a vector dataset into multiple files — slicing the whole cake into lil pieces 🍓

Positional arguments:

  • -o, --output <OUTPUT> — output directory [required]

✨ Options

okay bestie, picking right back up in partition land — here's every knob it's got: 👇

  • --overwrite — whether we're allowed to just overwrite an existing output dataset. Mutually exclusive with --append, so pick a lane. 💅
  • --append — whether appending to an existing layer is allowed. Mutually exclusive with --overwrite.
  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — the output format.
  • --co, --creation-option <KEY>=<VALUE> — creation option. Can be repeated, and you should absolutely repeat it.
  • --lco, --layer-creation-option <KEY>=<VALUE> — layer creation option. Also repeatable.
  • --field <FIELD> — the attribute or geometry field(s) you're partitioning on. Repeatable.
  • --scheme <SCHEME> — the partitioning scheme. SCHEME=hive|flat, default is hive.
  • --pattern <PATTERN> — the filename pattern. It's 'part_%010d' when scheme=hive, and '{LAYER_NAME}_{FIELD_VALUE}_%010d' when scheme=flat.
  • --feature-limit <FEATURE-LIMIT> — maximum number of features per file.
  • --max-file-size <MAX-FILE-SIZE> — maximum file size, and yes you can tack an MB or GB suffix on it.
  • --omit-partitioned-field — whether to leave the partitioned fields out of the target layer definition.
  • --skip-errors — skip errors when writing features.

Details for options can be found in gdal vector partition.

🌸 read 🌸

* read [OPTIONS] <INPUT>
------------------------

Read a vector dataset. Iconic, simple, does exactly what it says.

💜 Positional arguments

  • -i, --input <INPUT> — the input vector datasets. Required, no skipping this one.

💜 Options

  • -l, --layer, --input-layer <INPUT-LAYER> — input layer name(s). Repeat it as many times as you need.

💜 Advanced Options

  • --if, --input-format <INPUT-FORMAT> — input formats. Repeatable.
  • --oo, --open-option <KEY>=<VALUE> — open options. Repeatable.

Details for options can be found in gdal vector pipeline read.

🎀 rename-layer 🎀

* rename-layer [OPTIONS]
------------------------

Rename layer(s) of a vector dataset. Glow-up for your layer names, basically.

✨ Options

  • -l, --input-layer <INPUT-LAYER> — input layer name.
  • --output-layer <OUTPUT-LAYER> — output layer name.
  • --ascii — force names to ASCII characters.
  • --lower-case — force names to lower case. Heads up: only on ASCII characters.
  • --filename-compatible — force names to be usable as filenames.
  • --reserved-characters <RESERVED-CHARACTERS> — the reserved character(s) to be removed.
  • --replacement-character <REPLACEMENT-CHARACTER> — the replacement character used when ASCII conversion isn't possible.
  • --max-length <MAX-LENGTH> — maximum length of layer names.

Details for options can be found in gdal vector rename-layer.

🦋 reproject 🦋

* reproject [OPTIONS]
---------------------

Reproject a vector dataset. Sending your geometry to a whole new CRS. ✈️

✨ Options

  • --active-layer <ACTIVE-LAYER> — set active layer. If you don't specify one, it's all of them.
  • -s, --input-crs <INPUT-CRS> — input CRS.
  • -d, --output-crs <OUTPUT-CRS> — output CRS. Required, fr fr.

Details for options can be found in gdal vector reproject.

⭐ segmentize ⭐

* segmentize [OPTIONS] <MAX-LENGTH>
-----------------------------------

Segmentize geometries of a vector dataset. Chopping those long straight bits into lil segments.

💜 Positional arguments

  • --max-length <MAX-LENGTH> — maximum length of a segment. Required.

✨ Options

  • --active-layer <ACTIVE-LAYER> — set active layer. Not specified means all of them.
  • --active-geometry <ACTIVE-GEOMETRY> — the geometry field name to restrict the processing to. Not specified means all of them.

Details for options can be found in gdal vector segmentize.

🌈 select 🌈

* select [OPTIONS] <FIELDS>
---------------------------

Select a subset of fields from a vector dataset. Curating your field lineup, basically.

💜 Positional arguments

  • --fields <FIELDS> — the fields to select (or to exclude, if you passed --exclude). Repeatable, and required.

✨ Options

  • --active-layer <ACTIVE-LAYER> — set active layer. Not specified means all of them.
  • --output-layer <OUTPUT-LAYER> — output layer name.
  • --exclude — exclude the specified fields. Mutually exclusive with --ignore-missing-fields.
  • --ignore-missing-fields — ignore missing fields. Mutually exclusive with --exclude.

Details for options can be found in gdal vector select.

🍓 set-field-type 🍓

* set-field-type [OPTIONS]
--------------------------

Modify the type of a field of a vector dataset. Field type makeover time. 💅

✨ Options

  • --active-layer <ACTIVE-LAYER> — set active layer. Not specified means all of them.
  • --field-name <FIELD-NAME> — field name. Required. Mutually exclusive with --input-field-type.
  • --input-field-type <INPUT-FIELD-TYPE> — source field type or subtype. Required. Mutually exclusive with --field-name.
  • --output-field-type, --field-type <FIELD-TYPE> — target field type or subtype. Required.

Details for options can be found in gdal vector set-field-type.

🧚 set-geom-type 🧚

* set-geom-type [OPTIONS]
-------------------------

Modify the geometry type of a vector dataset. Giving your geoms the type they deserve.

✨ Options

  • --active-layer <ACTIVE-LAYER> — set active layer. Not specified means all of them.
  • --active-geometry <ACTIVE-GEOMETRY> — the geometry field name to restrict the processing to. Not specified means all of them.
  • --layer-only — only modify the layer geometry type. Mutually exclusive with --feature-only.
  • --feature-only — only modify the geometry type of features. Mutually exclusive with --layer-only.
  • --geometry-type <GEOMETRY-TYPE> — geometry type.
  • --multi — force geometries to MULTI geometry types. Mutually exclusive with --single.
  • --single — force geometries to non-MULTI geometry types. Mutually exclusive with --multi.
  • --linear — convert curve geometries to linear types. Mutually exclusive with --curve.
  • --curve — convert linear geometries to curve types. Mutually exclusive with --linear.
  • --dim <DIM> — force geometries to the specified dimension. DIM=XY|XYZ|XYM|XYZM.
  • --skip — skip the feature when the change of feature geometry type failed.

Details for options can be found in gdal vector set-geom-type.

🫶 simplify 🫶

* simplify [OPTIONS] <TOLERANCE>
--------------------------------

Simplify geometries of a vector dataset. Fewer points, same energy.

💜 Positional arguments

  • --tolerance <TOLERANCE> — distance tolerance for simplification. Required.

✨ Options

  • --active-layer <ACTIVE-LAYER> — set active layer. Not specified means all of them.
  • --active-geometry <ACTIVE-GEOMETRY> — the geometry field name to restrict the processing to. Not specified means all of them.

Details for options can be found in gdal vector simplify.

👑 simplify-coverage 👑

* simplify-coverage [OPTIONS] <TOLERANCE>
-----------------------------------------

Simplify shared boundaries of a polygonal vector dataset. This one's the careful version — it keeps shared edges shared, no gaps opening up between neighbours.

💜 Positional arguments

  • --tolerance <TOLERANCE> — distance tolerance for simplification. Required.

✨ Options

  • --active-layer <ACTIVE-LAYER> — set active layer. Not specified means all of them.
  • --preserve-boundary — whether the exterior boundary should be preserved.

Details for options can be found in gdal vector simplify-coverage.

🔥 sort 🔥

* sort [OPTIONS]
----------------

Spatially order the features in a layer — getting everything laid out nicely instead of vibing at random.

✨ Options

  • --geometry-field <GEOMETRY-FIELD> — name of the geometry field to use in the sort.
  • --method <METHOD> — geometry sorting algorithm. METHOD=hilbert|strtree, default is hilbert.
  • --use-tempfile — write features to a temporary file so you don't have to hold the entire input dataset in memory.

Details for options can be found in gdal vector sort.

💀 sql 💀

* sql [OPTIONS] <statement>|@<filename>
---------------------------------------

Apply SQL statement(s) to a dataset.

💜 Positional arguments

  • --sql <statement>|@<filename> — SQL statement(s). Repeatable, and required.

✨ Options

  • -l, --output-layer <OUTPUT-LAYER> — output layer name(s). Repeatable.
  • --dialect <DIALECT> — SQL dialect, e.g. OGRSQL, SQLITE.

Details for options can be found in gdal vector sql.

🎀 swap-xy 🎀

* swap-xy [OPTIONS]
-------------------

Swap X and Y coordinates of geometries of a vector dataset. Yes bestie, sometimes they really are just backwards.

✨ Options

  • --active-layer <ACTIVE-LAYER> — set active layer. Not specified means all of them.
  • --active-geometry <ACTIVE-GEOMETRY> — the geometry field name to restrict the processing to. Not specified means all of them.

Details for options can be found in gdal vector swap-xy.

🌸 tee 🌸

* tee [OPTIONS] [<PIPELINE>...]
-------------------------------

Pipes the input into the output stream and side nested pipelines. One input, multiple destinies. Main character behaviour. ✨

💜 Positional arguments

  • --tee-pipeline <PIPELINE> — nested pipeline. Takes [1.. values].

Details for options can be found in Output nested pipeline.

💜 update 💜

* update [OPTIONS] <OUTPUT>
---------------------------

Update an existing vector dataset with an input vector dataset.

💜 Positional arguments

  • -o, --output <OUTPUT> — output vector dataset. Required.

✨ 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 is merge.
  • --key <KEY> — field(s) used as a key to identify features. Repeatable.

💜 Advanced Options

  • --output-oo, --output-open-option <KEY>=<VALUE> — output open options. Repeatable.

Details for options can be found in gdal vector update.

🌈 write 🌈

* write [OPTIONS] <OUTPUT>
--------------------------

Write a vector dataset.

💜 Positional arguments

  • -o, --output <OUTPUT> — output vector dataset. Required.
  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — the output format, bestie 💅 and yes, GDALG is allowed here 👀
  • --co, --creation-option <KEY>=<VALUE> — a creation option. [may be repeated] so go off, stack 'em ✨
  • --lco, --layer-creation-option <KEY>=<VALUE> — a layer creation option. [may be repeated] too 🎀
  • --overwrite — tells you whether overwriting an existing output dataset is allowed
  • --update — tells you whether to open the existing dataset in update mode
  • --overwrite-layer — whether overwriting an existing output layer is allowed
  • --append — whether appending to an existing layer is allowed. mutually exclusive with --upsert, so pick a lane, bestie 🙈
  • -l, --output-layer <OUTPUT-LAYER> — the name of the output layer
  • --skip-errors — skip errors when writing features (like, just don't look at them 💀)
  • --no-create-empty-layers — don't create layers that no features are ever gonna be written to

🧚 Advanced Options

  • --output-oo, --output-open-option <KEY>=<VALUE> — output open options. [may be repeated] 🌸
  • --upsert — upsert features (which, heads up, implies append). mutually exclusive with --append 🔥
Details for options can be found in gdal vector pipeline write.

🦋 GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET) 🦋

okay this part is genuinely iconic. you can serialize a whole pipeline as a JSON file using the GDALG output format 💖 and then that resulting file can be opened as a vector dataset using the GDALG: GDAL Streamed Algorithm driver — which applies the specified pipeline in an on-the-fly / streamed way. it's giving magic, no cap ✨

the command_line member of that JSON file should nominally be the whole command line without the final write step — and that's exactly what gets generated by gdal vector pipeline ! .... ! write out.gdalg.json:

{
    "type": "gdal_streamed_alg",
    "command_line": "gdal vector pipeline ! read in.gpkg ! reproject --output-crs=EPSG:32632"
}

the final write step can be added, but if you do, it has to explicitly specify the stream output format and a non-significant output dataset name. non-negotiable bestie 😌

{
    "type": "gdal_streamed_alg",
    "command_line": "gdal vector pipeline ! read in.gpkg ! reproject --output-crs=EPSG:32632 ! write --output-format=streamed streamed_dataset"
}

🌈 SUBSTITUTIONS 🌈

Added in version 3.12.

so it's possible to use gdal pipeline to use a pipeline that's already serialized in a .gdal.json file, and then customize its existing steps — typically changing an input filename, specifying an output filename, or adding/modifying arguments of steps 🫶

See Substitutions.

🧚 NESTED PIPELINE 🧚

Added in version 3.12.

yes bestie, you can create "nested pipelines", i.e. pipelines inside pipelines. recursion said main character energy 💅

a nested pipeline is delimited by square brackets ([ and ]) surrounded by a space character. 🎀

there are 2 kinds of nested pipelines:

  • input nested pipelines: where the result dataset of the nested pipeline is used as the input dataset for an argument of the main pipeline.
  • output nested pipelines: where the output of a step of the main pipeline is used as the input of the nested pipeline in a following step. output nested pipelines can only be used with the tee step. 😤
See Nested pipeline.

⭐ RETURN STATUS CODE ⭐

the program returns status code 0 in case of success, and non-zero in case of error. but lowkey important: non-blocking errors emitted as warnings are considered a successful execution ✨

💖 EXAMPLES 💖

Example 1: Reproject a GeoPackage file to CRS EPSG:32632 ("WGS 84 / UTM zone 32N")

$ gdal vector pipeline ! read in.gpkg ! reproject --output-crs=EPSG:32632 ! write out.gpkg --overwrite

Example 2: Serialize the command of a reprojection of a GeoPackage file in a GDALG file, and later read it

$ gdal vector pipeline ! read in.gpkg ! reproject --output-crs=EPSG:32632 ! write in_epsg_32632.gdalg.json --overwrite
$ gdal vector info in_epsg_32632.gdalg.json

Example 3: Union 2 source shapefiles (with similar structure), reproject them to EPSG:32632, keep only cities larger than 1 million inhabitants and write to a GeoPackage

$ gdal vector pipeline ! concat --single --output-crs=EPSG:32632 france.shp belgium.shp ! filter --where "pop > 1e6" ! write out.gpkg --overwrite

Example 4: Filter and reproject a GeoPackage layer to a GeoJSON file

⚠️ when using select to restrict the output fields, ensure that it appears after the filter step in the pipeline when the filter expression references fields. if a field required by the filter gets removed by select, it will not be available and the command will fail with: ERROR 1: "worldcity" not recognised as an available field. 😭

if you want the output to contain spatial data, you must also include the geometry field in the selected fields. in this example the source dataset has no named geometry column. in such cases the special field _ogr_geometry_ can be used to reference the geometry. if no geometry field is included, reprojection will fail with: ERROR 1: reproject: Layer 'ne_110m_populated_places_simple' has no spatial reference system. 💀

and finally — ensure that there are no spaces between the field names in the list. for example: "_ogr_geometry_, name" will produce the error: ERROR 1: Field ' name' does not exist in layer 'ne_110m_populated_places_simple'. 🙈

Bash

gdal vector pipeline \
    ! read natural_earth_vector.gpkg --layer ne_110m_populated_places_simple \
    ! filter --where "worldcity = 1" \
    ! select --fields "_ogr_geometry_,name" \
    ! reproject --output-crs=ESRI:53009 \
    ! write worldcity_53009.geojson --overwrite

PowerShell

gdal vector pipeline `
    ! read natural_earth_vector.gpkg --layer ne_110m_populated_places_simple `
    ! filter --where "worldcity = 1" `
    ! select --fields "_ogr_geometry_,name" `
    ! reproject --output-crs=ESRI:53009 `
    ! write worldcity_53009.geojson --overwrite
📸 [image] — yeah there's a lil picture sitting right here in the original page, bestie. not me being a man page with visuals 🔥

👑 AUTHOR 👑

Even Rouault <even.rouault@spatialys.com>

1998-2026

okay that's the whole thing, we did it 🥳 and for the record, this lil masterpiece comes from the GDAL-VECTOR-PIPELINE(1) man page, dated Aug 18, 2026. slay, go run some pipelines bestie 💅✨🫶

📦 where this page comes from