GDAL-VECTOR-PIPELINE(1)

GDAL

GDAL-VECTOR-PIPELINE(1)

NAME¶

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

Added in version 3.11.

DESCRIPTION¶

gdal vector pipeline can be used to process a vector dataset and perform various processing steps that accept vector and generate vector.

For pipelines mixing raster and vector, consult gdal pipeline.

Most steps proceed in on-demand evaluation of features, unless otherwise stated in their documentation, without "materializing" the resulting dataset of the operation of each step. It may be desirable sometimes for performance purposes to proceed to materializing an intermediate dataset to disk using gdal vector materialize.

SYNOPSIS¶

Usage: gdal vector pipeline [OPTIONS] <PIPELINE>
Process a vector dataset applying several steps.
Positional arguments:
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:


  --skip-errors           Skip errors when writing features [not available in pipelines]
<PIPELINE> is of the form: read|concat [READ-OPTIONS] ( ! <STEP-NAME> [STEP-OPTIONS] )* ! write|info [WRITE-OPTIONS]

A pipeline chains several steps, separated with the ! (exclamation mark) character. The first step must be read or concat, and the last one info, partition or write. Each step has its own positional or non-positional arguments. Apart from read, concat, info, partition and write, all other steps can potentially be used several times in a pipeline.

STEPS¶

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>
-----------------------------
Compute a buffer around geometries of a vector dataset.
Positional arguments:


  --distance <DISTANCE>                    Distance to which to extend the geometry. [required]
Options:


  --active-layer <ACTIVE-LAYER>            Set active layer (if not specified, all)


  --active-geometry <ACTIVE-GEOMETRY>      Geometry field name to which to restrict the processing (if not specified, all)


  --endcap-style <ENDCAP-STYLE>            Endcap style.. ENDCAP-STYLE=round|flat|square (default: round)


  --join-style <JOIN-STYLE>                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]
--------------------------
Check a polygon coverage for validity
Options:


  --include-valid                          Include valid inputs in output, with empty geometry


  --geometry-field <GEOMETRY-FIELD>        Name of 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]
--------------------------
Check a dataset for invalid geometries
Options:


  --include-field <INCLUDE-FIELD>    Fields from input layer to include in output (special values: ALL and NONE) (default: NONE) [may be repeated]


  --include-valid                    Include valid inputs in output, with empty geometry


  --geometry-field <GEOMETRY-FIELD>  Name of geometry field to check

Details for options can be found in gdal vector check-geometry.

clean-coverage¶

* clean-coverage [OPTIONS]
--------------------------
Alter polygon boundaries to make shared edges identical, removing gaps and overlaps
Options:


  --active-layer <ACTIVE-LAYER>            Set active layer (if not specified, all)


  --snapping-distance <SNAPPING-DISTANCE>  Distance tolerance for snapping nodes


  --merge-strategy <MERGE-STRATEGY>        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]
----------------
Clip a vector dataset.
Options:


  --active-layer <ACTIVE-LAYER>    Set active layer (if not specified, all)


  --bbox <BBOX>                    Clipping bounding box as xmin,ymin,xmax,ymax


                                   Mutually exclusive with --geometry, --like


  --bbox-crs <BBOX-CRS>            CRS of clipping bounding box


  --geometry <GEOMETRY>            Clipping geometry (WKT or GeoJSON)


                                   Mutually exclusive with --bbox, --like


  --geometry-crs <GEOMETRY-CRS>    CRS of 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]
-------------------
Combine features into collections
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]
------------------------
Compute the concave hull of geometries of a vector dataset.
Options:


  --active-layer <ACTIVE-LAYER>        Set active layer (if not specified, all)


  --active-geometry <ACTIVE-GEOMETRY>  Geometry field name to which to restrict the processing (if not specified, all)


  --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>...
------------------------------
Concatenate vector datasets.
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>                                              Determine 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 template to name the output vector layers (stack mode)


  --source-layer-field-name <SOURCE-LAYER-FIELD-NAME>        Name of the new field to add to contain identification of the source layer, with 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]
-----------------------
Compute the convex hull of geometries of a vector dataset.
Options:


  --active-layer <ACTIVE-LAYER>        Set active layer (if not specified, all)


  --active-geometry <ACTIVE-GEOMETRY>  Geometry field name to which to restrict the processing (if not specified, all)

Details for options can be found in gdal vector convex-hull.

create¶

* create [OPTIONS] <OUTPUT>
---------------------------
Create a vector dataset.
Positional arguments:


  -o, --output <OUTPUT>                                Output vector dataset [required]
Options:


  -i, --like, --input <TEMPLATE-DATASET>               Input vector datasets


                                                       Mutually exclusive with --schema, --field


  -l, --layer, --input-layer <INPUT-LAYER>             Input layer name(s) [may be repeated]


  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format ("GDALG" allowed)


  --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


  --output-layer <OUTPUT-LAYER>                        Output layer name


  --geometry-type <GEOMETRY-TYPE>                      Layer geometry type


  --geometry-field <GEOMETRY-FIELD>                    Name of the geometry field to create (if supported by the output format) (default: geom)


  --crs <CRS>                                          Set CRS


  --fid <FID>                                          FID column name


  --schema <SCHEMA_JSON>                               Read OGR_SCHEMA and populate field definitions from it


                                                       Mutually exclusive with --input, --field


  --field <NAME>:<TYPE>[(,<WIDTH>[,<PRECISION>])]>     Add a field definition to the output layer [may be repeated]


                                                       Mutually exclusive with --input, --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
Options:


  --active-layer <ACTIVE-LAYER>        Set active layer (if not specified, all)


  --active-geometry <ACTIVE-GEOMETRY>  Geometry field name to which to restrict the processing (if not specified, all)

Details for options can be found in gdal vector dissolve.

edit¶

* edit [OPTIONS]
----------------
Edit metadata of a vector dataset.
Options:


  --active-layer <ACTIVE-LAYER>    Set active layer (if not specified, all)


  --output-layer <OUTPUT-LAYER>    Output layer name


  --geometry-type <GEOMETRY-TYPE>  Layer geometry type


  --crs <CRS>                      Override CRS (without reprojection)


  --metadata <KEY>=<VALUE>         Add/update dataset metadata item [may be repeated]


  --unset-metadata <KEY>           Remove dataset metadata item [may be repeated]


  --layer-metadata <KEY>=<VALUE>   Add/update layer metadata item [may be repeated]


  --unset-layer-metadata <KEY>     Remove 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.
Options:


  --active-layer <ACTIVE-LAYER>        Set active layer (if not specified, all)


  --active-geometry <ACTIVE-GEOMETRY>  Geometry field name to which to restrict the processing (if not specified, all)


  --geometry-type <GEOMETRY-TYPE>      Geometry type


  --skip-on-type-mismatch              Skip feature when 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:
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.
Options:


  --active-layer <ACTIVE-LAYER>  Set 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.
Positional arguments:
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, --fid


  --features                                           List all features (beware of RAM consumption on large layers)


                                                       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, --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, --sql


  --dialect <DIALECT>                                  SQL dialect
Esoteric Options:


  --crs-format <CRS-FORMAT>                            Which format to use to report 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.
Positional arguments:


  --limit <LIMIT>                Limit the number of features to read per layer [required]
Options:


  --active-layer <ACTIVE-LAYER>  Set active layer (if not specified, all)

make-point¶

* make-point [OPTIONS]
----------------------
Create point geometries from attribute fields
Options:


  --x <X>                    Field from which X coordinate should be read [required]


  --y <Y>                    Field from which Y coordinate should be read [required]


  --z <Z>                    Optional field from which Z coordinate should be read


  --m <M>                    Optional field from which 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 validity of geometries of a vector dataset.
Options:


  --active-layer <ACTIVE-LAYER>        Set active layer (if not specified, all)


  --active-geometry <ACTIVE-GEOMETRY>  Geometry field name to which to restrict the processing (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.
Options:


  -o, --output <OUTPUT>                                Materialized dataset name (created by 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 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.
Positional arguments:


  -o, --output <OUTPUT>                                Output directory [required]
Options:


  --overwrite                                          Whether overwriting existing output dataset is allowed


                                                       Mutually exclusive with --append


  --append                                             Whether appending to existing layer is allowed


                                                       Mutually exclusive with --overwrite


  -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]


  --field <FIELD>                                      Attribute or geometry field(s) on which to partition [may be repeated]


  --scheme <SCHEME>                                    Partitioning scheme. SCHEME=hive|flat (default: hive)


  --pattern <PATTERN>                                  Filename pattern ('part_%010d' for scheme=hive, '{LAYER_NAME}_{FIELD_VALUE}_%010d' for scheme=flat)


  --feature-limit <FEATURE-LIMIT>                      Maximum number of features per file


  --max-file-size <MAX-FILE-SIZE>                      Maximum file size (MB or GB suffix can be used)


  --omit-partitioned-field                             Whether to omit partitioned fields from 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.
Positional arguments:


  -i, --input <INPUT>                       Input vector datasets [required]
Options:


  -l, --layer, --input-layer <INPUT-LAYER>  Input layer name(s) [may be repeated]
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 pipeline read.

rename-layer¶

* rename-layer [OPTIONS]
------------------------
Rename layer(s) of a vector dataset.
Options:


  -l, --input-layer <INPUT-LAYER>                  Input layer name


  --output-layer <OUTPUT-LAYER>                    Output layer name


  --ascii                                          Force names to ASCII character


  --lower-case                                     Force names to lower case (only on ASCII characters)


  --filename-compatible                            Force names to be usable as filenames


  --reserved-characters <RESERVED-CHARACTERS>      Reserved character(s) to be removed


  --replacement-character <REPLACEMENT-CHARACTER>  Replacement character when ASCII conversion not 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.
Options:


  --active-layer <ACTIVE-LAYER>  Set active layer (if not specified, all)


  -s, --input-crs <INPUT-CRS>    Input CRS


  -d, --output-crs <OUTPUT-CRS>  Output CRS [required]

Details for options can be found in gdal vector reproject.

segmentize¶

* segmentize [OPTIONS] <MAX-LENGTH>
-----------------------------------
Segmentize geometries of a vector dataset.
Positional arguments:


  --max-length <MAX-LENGTH>            Maximum length of a segment [required]
Options:


  --active-layer <ACTIVE-LAYER>        Set active layer (if not specified, all)


  --active-geometry <ACTIVE-GEOMETRY>  Geometry field name to which to restrict the processing (if not specified, all)

Details for options can be found in gdal vector segmentize.

select¶

* select [OPTIONS] <FIELDS>
---------------------------
Select a subset of fields from a vector dataset.
Positional arguments:


  --fields <FIELDS>              Fields to select (or exclude if --exclude) [may be repeated] [required]
Options:


  --active-layer <ACTIVE-LAYER>  Set active layer (if not specified, all)


  --output-layer <OUTPUT-LAYER>  Output layer name


  --exclude                      Exclude 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.
Options:


  --active-layer <ACTIVE-LAYER>                   Set active layer (if not specified, all)


  --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.
Options:


  --active-layer <ACTIVE-LAYER>        Set active layer (if not specified, all)


  --active-geometry <ACTIVE-GEOMETRY>  Geometry field name to which to restrict the processing (if not specified, all)


  --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 feature when 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.
Positional arguments:


  --tolerance <TOLERANCE>              Distance tolerance for simplification. [required]
Options:


  --active-layer <ACTIVE-LAYER>        Set active layer (if not specified, all)


  --active-geometry <ACTIVE-GEOMETRY>  Geometry field name to which to restrict the processing (if not specified, all)

Details for options can be found in gdal vector simplify.

simplify-coverage¶

* simplify-coverage [OPTIONS] <TOLERANCE>
-----------------------------------------
Simplify shared boundaries of a polygonal vector dataset.
Positional arguments:


  --tolerance <TOLERANCE>        Distance tolerance for simplification. [required]
Options:


  --active-layer <ACTIVE-LAYER>  Set active layer (if not specified, all)


  --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
Options:


  --geometry-field <GEOMETRY-FIELD>  Name of geometry field to use in sort


  --method <METHOD>                  Geometry sorting algorithm. METHOD=hilbert|strtree (default: hilbert)


  --use-tempfile                     Write features to a temporary file to avoid reading the entire input dataset into 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) [may be repeated] [required]
Options:


  -l, --output-layer <OUTPUT-LAYER>  Output layer name(s) [may be repeated]


  --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.
Options:


  --active-layer <ACTIVE-LAYER>        Set active layer (if not specified, all)


  --active-geometry <ACTIVE-GEOMETRY>  Geometry field name to which to restrict the processing (if not specified, all)

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.
Positional arguments:


  --tee-pipeline <PIPELINE>  Nested pipeline [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: merge)


  --key <KEY>                                      Field(s) used as a key to identify features [may be repeated]
Advanced Options:


  --output-oo, --output-open-option <KEY>=<VALUE>  Output open options [may be repeated]

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]
Options:


  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format ("GDALG" allowed)


  --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


                                                       Mutually exclusive with --upsert


  -l, --output-layer <OUTPUT-LAYER>                    Output layer name


  --skip-errors                                        Skip errors when writing features


  --no-create-empty-layers                             Avoid creating layers to which no features will be written
Advanced Options:


  --output-oo, --output-open-option <KEY>=<VALUE>      Output open options [may be repeated]


  --upsert                                             Upsert features (implies 'append')


                                                       Mutually exclusive with --append

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

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

A pipeline can be serialized as a JSON file using the GDALG output format. The resulting file can then be opened as a vector dataset using the GDALG: GDAL Streamed Algorithm driver, and apply the specified pipeline in a on-the-fly / streamed way.

The command_line member of the JSON file should nominally be the whole command line without the final write step, and is what is 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 so it must explicitly specify the stream output format and a non-significant output dataset name.

{


    "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.

It is possible to use gdal pipeline to use a pipeline already serialized in a .gdal.json file, and 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.

It is possible to create "nested pipelines", i.e. pipelines inside pipelines.

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 (non-blocking errors emitted as warnings are considered as 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 is 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.

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]

AUTHOR¶

Even Rouault <even.rouault@spatialys.com>

COPYRIGHT¶

1998-2026

June 5, 2026

Source file:	gdal-vector-pipeline.1.en.gz (from gdal-bin 3.13.1+dfsg-1)
Source last updated:	2026-06-05T11:10:29Z
Converted to HTML:	2026-06-05T14:39:22Z