gpkg_write: Write data to a GeoPackage

In gpkg: Utilities for the Open Geospatial Consortium 'GeoPackage' Format

Write data to a GeoPackage

Description

Write data to a GeoPackage

Usage

gpkg_write(
  x,
  y = NULL,
  table_name = NULL,
  datatype = "FLT4S",
  append = FALSE,
  overwrite = FALSE,
  NoData = NULL,
  gdal_options = NULL,
  auto_nodata = TRUE,
  destfile = NULL,
  ...
)

Arguments

x	Vector of source file path(s), or a list containing one or more SpatRaster, SpatRasterCollection, SpatVectorProxy, or data.frame objects.
y	character, geopackage, or DBIConnection.
table_name	character. Default NULL name is derived from source file. Required if x is a data.frame.
datatype	character. Data type. Defaults to "FLT4S" for GeoTIFF files, "INT2U" otherwise. See documentation for terra::writeRaster().
append	logical. Append to existing data source? Default: FALSE. When TRUE, new data are added to the existing table(s) if they exist. For raster data, this adds a new subdataset (layer) to the GeoPackage (via APPEND_SUBDATASET=YES creation option). For attribute tables, this appends rows to the existing table. For vector data, this maps to the insert argument of terra::writeVector(). Setting append=TRUE overrides overwrite=TRUE.
overwrite	logical. Overwrite existing data source? Default FALSE. When TRUE, existing table(s) with the same name are dropped and recreated. Note that this only affects the specific tables being written; it does not delete other existing tables in the GeoPackage file. To completely overwrite an entire GeoPackage file, delete it first using unlink().
NoData	numeric. Value to use as GDAL NoData Value
gdal_options	character. Additional gdal_options, passed to terra::writeRaster()
auto_nodata	logical. If TRUE (default), automatically select a datatype-appropriate default NoData value when NoData = NULL, determined by gpkg_default_nodata(). Set to FALSE to use terra's default behavior (NaN for floats), which may trigger GDAL warnings. Ignored if NoData is explicitly specified.
destfile	character. Path to output GeoPackage
...	Additional arguments are passed as GeoPackage creation options. See Details.

Details

gpkg_write() can write multiple layers of different types (raster, vector, and attributes) in a single call when x is a list. If calling gpkg_write() multiple times to build a GeoPackage, use append=TRUE to add additional layers. To replace a specific table while preserving others, use overwrite=TRUE. Note that overwrite=TRUE only drops the specified table_name and does not affect other tables in the file.

Additional, non-default GeoPackage creation options can be specified as arguments to this function. The full list of creation options can be viewed here or in the gpkg_creation_options dataset. The name of the argument is creation_option and the value is selected from one of the elements of values for that option.

If x contains source file paths, any comma-separated value (CSV) files are treated as attribute data–even if they contain a geometry column. GeoPackage source file paths are always treated as vector data sources, and only one layer will be read from the source and written to the target. If you need to read raster data from a GeoPackage first create a SpatRaster from the layer of interest (see gpkg_rast()) before passing to gpkg_write(). If you need to read multiple layers from any multi-layer source read them individually into suitable objects. For a source GeoPackage containing multiple layers you can use gpkg_read() (returns a geopackage object) or gpkg_tables() (returns a list object).

Value

Logical. TRUE on successful write of at least one grid.

See Also

gpkg_creation_options gpkg_default_nodata()

gpkg documentation built on April 3, 2026, 9:08 a.m.