GDAL-VECTOR-FILTER(1)

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

✨ NAME ✨

okay so this is the GDAL-VECTOR-FILTER(1) page from the GDAL manual, and it's literally all about gdal-vector-filter — the tool that filters a vector dataset for you 💅

Added in version 3.11. bestie, it's giving new-but-iconic.

📜 SYNOPSIS 📜

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

Filter a vector dataset.

Positional arguments (yes both of these are required, no skipping 🙈)

  • -i, --input <INPUT> — the input vector dataset(s). [required] and [not available in pipelines]
  • -o, --output <OUTPUT> — the output vector dataset. Also [required], also [not available in pipelines]

Common Options 🎀

  • -h, --help — show the help message and dip, exit stage left.
  • --json-usage — print the usage as a JSON document and exit. nerdy but cute.
  • --config <KEY>=<VALUE> — a configuration option, and yes you can repeat it [may be repeated]
  • -q, --quiet — quiet mode, aka no progress bar and no warning messages [not available in pipelines]

Options 👑

  • -l, --layer, --input-layer <INPUT-LAYER> — input layer name(s) [may be repeated] [not available in pipelines]
  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — output format, and "GDALG" is allowed here btw [not available in pipelines]
  • --co, --creation-option <KEY>=<VALUE> — creation option [may be repeated] [not available in pipelines]
  • --lco, --layer-creation-option <KEY>=<VALUE> — 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 an 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 ⚠️
  • --output-layer <OUTPUT-LAYER> — output layer name [not available in pipelines]
  • --skip-errors — skip errors when writing features [not available in pipelines]
  • --active-layer <ACTIVE-LAYER> — set the active layer (if not specified, all of them get it)
  • --bbox <BBOX> — bounding box, written 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 the layer extent so it takes the filter into account

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 (implies 'append') [not available in pipelines] — mutually exclusive with --append ⚠️

💖 DESCRIPTION 💖

gdal vector filter filters a vector dataset based on its spatial extent or on a SQL WHERE clause. simple as that, no cap 🦋

And it can also be used as a step inside gdal vector pipeline, which is honestly so versatile of it. main character energy fr.

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

This program supports serializing the command line into a JSON file using the GDALG output format. obsessed

The resulting file can then be opened as a vector dataset using the GDALG: GDAL Streamed Algorithm driver, and it applies the specified pipeline in an on-the-fly / streamed way. streamed?? on-the-fly?? she said efficiency. ✨

🎀 PROGRAM-SPECIFIC OPTIONS 🎀

  • --bbox <xmin>,<ymin>,<xmax>,<ymax> — the bounds you want to filter the dataset down to. they're assumed to be in the CRS of the input dataset, ok? The X and Y axis are the "GIS friendly ones", meaning X is longitude or easting, and Y is latitude or northing. And heads up bestie: filtering does not clip geometries to the bounding box — it filters, it does not trim 💅
  • --update-extent — updates the layer extent so it accounts for the filter(s). If you don't do this, the layer extent will generally be the one of the source layer before applying the filter(s). Heads up though: using this option requires doing a full scan of the filtered layers, so it's not free ✨
  • --where <WHERE>|@<filename> — attribute query (like SQL WHERE).

🌸 STANDARD OPTIONS 🌸

  • --active-layer <ACTIVE-LAYER> — sets the active layer. When it's specified, only the layer named by it gets subject to the processing, and the other layers are not modified at all. If you don't specify it, then all layers get subject to the processing. all of them. periodt.
  • --append — whether appending features to existing layer(s) is allowed. This also creates the output dataset if it doesn't already exist yet. she's a builder 💅
  • --co, --creation-option <NAME>=<VALUE> — lots of formats have one or more optional dataset creation options you can use to control particulars about the file being created. for example, the GeoPackage driver supports creation options that control the version.

[may be repeated]

The dataset creation options available vary by format driver, and some simple formats have no creation options at all. You can list the options supported for a format with the --formats command line option, but 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.

⚠️ note that dataset creation options are different from layer creation options. do not mix them up, i'm begging 🙈
  • --if, --input-format <format> — format/driver name to be attempted when opening the input file(s). It's generally not necessary to specify it, but it can be used to skip automatic driver detection, which is handy when detection fails to select the appropriate driver. You can repeat this option 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. so, yk. iykyk.

[may be repeated]

  • --input-layer <INPUT-LAYER> — specifies the name of one or more layers to process. By default, all layers get processed. If you want to read and write all layers but only process a subset, use --active-layer instead 🦋
  • --lco, --layer-creation-option <NAME>=<VALUE> — lots of formats have one or more optional layer creation options you can use to control particulars about the layer being created. for instance, the GeoPackage driver supports layer creation options for controlling the feature identifier or the geometry column name, setting the identifier or description, etc.

[may be repeated]

The layer creation options available vary by format driver, and some simple formats have no layer creation options at all. A list of options supported for a format can be listed with the --formats command line option, but 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 note that layer creation options are different from dataset creation options. both of them matter, they are not the same thing!!
  • --oo, --open-option <NAME>=<VALUE> — dataset open option (format specific).

[may be repeated]

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output vector format to use. Allowed values can be given by:
gdal --formats | grep vector | grep rw | sort
  • --output-layer <NAME> — specifies the name of the layer to which features will be written. If you don't specify it, the output layer names will be the same as the input layer names. slay, consistent.
  • --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 — allow the program to overwrite an existing target file or dataset. Otherwise, by default, gdal errors out if the target file or dataset already exists. she said no take-backsies unless you ask 💀
  • --overwrite-layer — whether overwriting the existing output vector layer is allowed.
  • --skip-errors — Added in version 3.12.

Whether failures to write feature(s) should be ignored. Note that this option sets the size of the transaction unit to one feature at a time, which may cause severe slowdown when inserting into databases. so like, caution, bestie, it's giving slow 😭

  • --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).

The upsert operation uses the FID of the input feature, when it is set (and the FID column name is not the empty string), as the key to update existing features. It is crucial to make sure that the FID in the source and target layers are consistent. fr fr, do not skip that part.

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), when there is a UNIQUE column that is not the integer primary key. iykyk 💅

⭐ 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, so don't panic over those 🫶)

🍓 EXAMPLES 🍓

Example 1: Select features from a GeoPackage file that intersect the bounding box from longitude 2, latitude 49, to longitude 3, latitude 50 in WGS 84

$ gdal vector filter --bbox=2,49,3,50 in.gpkg out.gpkg --overwrite

ate that. no notes. 🔥

💜 AUTHOR 💜

Even Rouault <even.rouault@spatialys.com>

1998-2026

okay that's the whole page bestie 💖 this was GDAL-VECTOR-FILTER(1) from the GDAL manual, and the footer said source/version GDAL with the date Aug 18, 2026 — so there you go, go filter something cute. bye bestie, stay streamed ✨🌸💅

📦 where this page comes from