GDAL `--append` 矢量图层追加详解：从命令行到源码实现

• GIS
• 遥感
• 数据工程

导读

本文聚焦 GDAL 新版命令行体系（3.11 起引入的gdal vector系列子命令）中与“向已有矢量图层追加要素”相关的--append选项，以 doc/source/programs/gdal_options/append_vector.rst 为核心，结合其实际生效的源码实现，说明该选项的行为语义、与--overwrite/--overwrite-layer/--update的配合关系，并通过gdal vector convert、gdal vector pipeline write等真实命令示例演示其用法。读完本文，你将掌握在 GDAL 新命令体系中安全地向既有矢量数据集追加要素、并在输出数据集不存在时自动创建数据集的完整方案。

选项定位：一个被多个命令共享的公共选项

原文档append_vector.rst是一个典型的 RSToption定义片段，全文内容如下：

.. option:: --append Whether appending features to existing layer(s) is allowed. This also creates the output dataset if it does not exist yet.

该片段通过.. include::机制被大量gdal vector *命令文档复用。在当前仓库中，以下文档均引用了它（搜索证据）：

• 转换类：gdal_vector_convert.rst
• 管道输出类：gdal_vector_write.rst
• 图层代数类：gdal_vector_layer_algebra.rst
• 空间处理类：gdal_vector_buffer.rst、gdal_vector_clip.rst、gdal_vector_concave_hull.rst、gdal_vector_convex_hull.rst
• 编辑/校正类：gdal_vector_edit.rst、gdal_vector_make_valid.rst、gdal_vector_clean_coverage.rst
• 统计/索引类：gdal_raster_zonal_stats.rst、gdal_raster_index.rst、gdal_raster_polygonize.rst、gdal_raster_as_features.rst
• 其他：gdal_vector_sql.rst、gdal_vector_select.rst、gdal_vector_reproject.rst、gdal_vector_index.rst 等

可见，--append是“输出到矢量数据集”的通用写侧参数，属于写参数前缀省略集合中的一员（见 gdalalg_abstract_pipeline.cpp 中的apszWriteParametersPrefixOmitted列表），在管道语法中允许省略前缀。

行为语义：两个关键承诺

结合原文档与源码，--append提供两个明确的行为承诺：

1. 允许向已存在的图层追加要素：当目标图层（--output-layer指定的图层）已经存在于输出数据集中时，指定--append后，新要素将被追加写入该图层，而不是报错退出。
2. 输出数据集不存在时自动创建：如果输出数据集文件尚不存在，即使指定了--append，也会自动创建该数据集及目标图层，追加模式因此不会因目标缺失而失败。

第二个行为在 gdalalg_vector_output_abstract.cpp 的SetupOutputDataset()中体现：当输出数据集指针为空时，会根据输出格式驱动创建数据集（poDriver->Create(...)），随后再按--output-layer查找目标图层。

参数定义与底层实现

--append的实际注册位于矢量输出抽象算法中（gdalalg_vector_output_abstract.cpp）：

AddArg("append", 0, _("Whether appending to existing layer is allowed"), &m_appendLayer) .SetDefault(false) .AddAction([&updateArg] { updateArg.Set(true); });

三个值得注意的实现细节：

• 默认关闭：SetDefault(false)表明未指定--append时，追加行为不被允许；
• 隐含启用 update：AddAction([&updateArg] { updateArg.Set(true); })说明一旦指定--append，--update会被自动置为 true。这与原文档“允许追加”的语义以及 ogr2ogr 的-append行为（ogr2ogr.rst：Append to existing layer instead of creating new. This option also enables -update.）保持一致——追加本质上是一种更新式写入；
• 与--overwrite/--overwrite-layer互斥：--overwrite与--overwrite-layer属于overwrite-update互斥组（gdalalg_vector_output_abstract.cpp），--update与其互斥，而--append又强制--update，因此不能与覆盖类参数同时使用。

与 overwrite / update 系列选项的关系

在SetupOutputDataset()中，追加模式存在以下判定逻辑（gdalalg_vector_output_abstract.cpp）：

• 若目标图层已存在且指定了--overwrite-layer：删除该图层后重建；
• 若目标图层已存在、未指定--append：直接报错，提示“Layer 'X' already exists. Specify the--overwrite-layeroption to overwrite it, or--appendto append to it.”；
• 若目标图层不存在，但指定了--append或--overwrite-layer：报错 “Cannot find layer 'X'”，因为追加与覆盖都需要一个既有图层作为操作对象。

因此四类写模式可归纳为：

实战：在gdal vector convert中使用--append

gdal vector convert是独立可运行的转换命令，其RunStep()本身只负责把输入数据集转发给输出（gdalalg_vector_convert.cpp），真正的写入与追加逻辑由输出抽象算法完成。官方文档提供了三个示例（gdal_vector_convert.rst）：

# 1. 基础转换：poly.shp → output.gpkg $ gdal vector convert poly.shp output.gpkg # 2. 向既有 GeoPackage 新增图层（--update 模式），并重命名为 "lines" $ gdal vector convert --update --output-layer=lines line.shp output.gpkg # 3. 将 poly2.shp 的要素追加到既有 GeoPackage 的 poly 图层，且不显示进度条 $ gdal vector convert --quiet --append --output-layer=poly poly2.shp output.gpkg

示例 3 正是--append的典型用法：--output-layer=poly指定目标图层，--append允许追加。注意由于--append会自动开启--update，这里无需再显式写--update。若省略--append，当poly图层已存在时会直接报错。

在gdal vector pipeline write中追加

gdal vector pipeline write是gdal vector pipeline管道的最后一步，专门负责写出矢量数据集（gdal_vector_write.rst）。它的文档同样引用了append_vector.rst（gdal_vector_write.rst），因此--append在管道写出步骤中同样可用。官方示例：

$ gdal vector pipeline ... [other commands here] ... ! write out.gpkg --overwrite

若希望把管道结果追加到既有out.gpkg的指定图层，可改为：

$ gdal vector pipeline ... [other commands here] ... ! write out.gpkg --append --output-layer=target_layer

该命令的底层是 gdalalg_vector_write.cpp 中注册的GDALVectorWriteAlgorithm，它同样调用AddVectorOutputArgs()注册输出参数，从而与gdal vector convert共享同一套追加逻辑。

边界与注意事项

• 目标图层必须已存在：--append允许向已有图层追加，但不会自动创建目标图层；若指定了--output-layer而图层不存在，将报错Cannot find layer。若输出数据集不存在，则会自动创建数据集与默认图层，此时不应指定不存在的--output-layer。
• 不能与覆盖参数同用：--append（经由--update）与--overwrite/--overwrite-layer属于互斥参数组，同时指定会被拒绝。
• 与 upsert 的区别：gdal vector convert、gdal vector pipeline write还提供--upsert选项（upsert.rst、gdal_vector_convert.rst）。--upsert是--append的变体，使用OGRLayer::UpsertFeature实现插入或更新，目前仅 GeoPackage、Elasticsearch、MongoDBv3 等实现 upsert 的驱动支持；它以输入要素的 FID 为键更新既有要素，因此要求源与目标图层的 FID 语义一致。
• Shapefile 特殊处理：当输出为 ESRI Shapefile 且图层数不超过 1 时，输出图层名会被自动设为文件名主名（gdalalg_vector_output_abstract.cpp），追加场景下的图层命名会自动对齐。

小结

--append是 GDAL 新版gdal vector命令体系中统一追加要素的入口：它允许向既有图层追加要素、在输出数据集缺失时自动创建，并自动启用--update，同时与覆盖类参数互斥。无论是gdal vector convert的简单追加，还是gdal vector pipeline管道末尾的write步骤，均可复用同一套语义。相关文档与实现可继续参阅 append_vector.rst、gdal_vector_convert.rst、gdal_vector_write.rst 以及 gdalalg_vector_output_abstract.cpp。

• GIS
• 遥感
• 数据工程