Utility functions for managing vector data sources

This set of functions can be used to create new vector datasets, test existence of dataset/layer/field, test dataset and layer capabilities, create new layers in an existing dataset, delete layers, create new attribute and geometry fields on an existing layer, rename and delete fields, and edit data with SQL statements.

Usage

ogr_ds_exists(dsn, with_update = FALSE)

ogr_ds_format(dsn)

ogr_ds_test_cap(dsn, with_update = TRUE)

ogr_ds_create(
  format,
  dsn,
  layer = NULL,
  layer_defn = NULL,
  geom_type = NULL,
  srs = NULL,
  fld_name = NULL,
  fld_type = NULL,
  dsco = NULL,
  lco = NULL,
  overwrite = FALSE
)

ogr_ds_layer_count(dsn)

ogr_ds_layer_names(dsn)

ogr_layer_exists(dsn, layer)

ogr_layer_test_cap(dsn, layer, with_update = TRUE)

ogr_layer_create(
  dsn,
  layer,
  layer_defn = NULL,
  geom_type = NULL,
  srs = NULL,
  lco = NULL
)

ogr_layer_field_names(dsn, layer)

ogr_layer_delete(dsn, layer)

ogr_field_index(dsn, layer, fld_name)

ogr_field_create(
  dsn,
  layer,
  fld_name,
  fld_defn = NULL,
  fld_type = "OFTInteger",
  fld_subtype = "OFSTNone",
  fld_width = 0L,
  fld_precision = 0L,
  is_nullable = TRUE,
  is_ignored = FALSE,
  is_unique = FALSE,
  default_value = ""
)

ogr_geom_field_create(
  dsn,
  layer,
  fld_name,
  geom_fld_defn = NULL,
  geom_type = NULL,
  srs = NULL,
  is_nullable = TRUE,
  is_ignored = FALSE
)

ogr_field_rename(dsn, layer, fld_name, new_name)

ogr_field_delete(dsn, layer, fld_name)

ogr_execute_sql(dsn, sql, spatial_filter = NULL, dialect = NULL)

Arguments

dsn: Character string. The vector data source name, e.g., a filename or database connection string.
with_update: Logical scalar. TRUE to request update access when opening the dataset, or FALSE to open read-only.
format: GDAL short name of the vector format as character string. Examples of some common output formats include: "GPKG", "FlatGeobuf", "ESRI Shapefile", "SQLite".
layer: Character string for a layer name in a vector dataset.
layer_defn: A feature class definition for layer as a list of zero or more attribute field definitions, and at least one geometry field definition (see ogr_define). Each field definition is a list with named elements containing values for the field $type and other properties. If layer_defn is given, it will be used and any additional parameters passed that relate to the feature class definition will be ignored (i.e., geom_type and srs, as well as fld_name and fld_type in ogr_ds_create()). The first geometry field definition in layer_defn defines the geometry type and spatial reference system for the layer (the geom field definition must contain $type, and should also contain $srs when creating a layer from a feature class definition).
geom_type: Character string specifying a geometry type (see Details).
srs: Character string containing a spatial reference system definition as OGC WKT or other well-known format (e.g., the input formats usable with srs_to_wkt()).
fld_name: Character string containing the name of an attribute field in layer.
fld_type: Character string containing the name of a field data type (e.g., OFTInteger, OFTReal, OFTString).
dsco: Optional character vector of format-specific creation options for dsn ("NAME=VALUE" pairs).
lco: Optional character vector of format-specific creation options for layer ("NAME=VALUE" pairs).
overwrite: Logical scalar. TRUE to overwrite dsn if it already exists when calling ogr_ds_create(). Default is FALSE.
fld_defn: A field definition as list (see ogr_def_field()). Additional arguments in ogr_field_create() will be ignored if a fld_defn is given.
fld_subtype: Character string containing the name of a field subtype. One of OFSTNone (the default), OFSTBoolean, OFSTInt16, OFSTFloat32, OFSTJSON, OFSTUUID.
fld_width: Optional integer scalar specifying max number of characters.
fld_precision: Optional integer scalar specifying number of digits after the decimal point.
is_nullable: Optional NOT NULL field constraint (logical scalar). Defaults to TRUE.
is_ignored: Whether field is ignored when retrieving features (logical scalar). Defaults to FALSE.
is_unique: Optional UNIQUE constraint on the field (logical scalar). Defaults to FALSE.
default_value: Optional default value for the field as a character string.
geom_fld_defn: A geometry field definition as list (see ogr_def_geom_field()). Additional arguments in ogr_geom_field_create() will be ignored if a geom_fld_defn is given.
new_name: Character string containing a new name to assign.
sql: Character string containing an SQL statement (see Note).
spatial_filter: Either a numeric vector of length four containing a bounding box (xmin, ymin, xmax, ymax), or a character string containing a geometry as OGC WKT, representing a spatial filter.
dialect: Character string specifying the SQL dialect to use. The OGR SQL engine ("OGRSQL") will be used by default if a value is not given. The "SQLite" dialect can also be used (see Note).

Details

These functions are complementary to ogrinfo() and ogr2ogr() for vector data management. They are also intended to support vector I/O in a future release of gdalraster. Bindings to OGR wrap portions of the GDAL Vector API (ogr_core.h and ogr_api.h, https://gdal.org/api/vector_c_api.html).

ogr_ds_exists() tests whether a vector dataset can be opened from the given data source name (DSN), potentially testing for update access. Returns a logical scalar.

ogr_ds_format() returns a character string containing the short name of the format driver for a given DSN, or NULL if the dataset cannot be opened as a vector source.

ogr_ds_test_cap() tests the capabilities of a vector data source, attempting to open it with update access by default. Returns a list of capabilities with values TRUE or FALSE, or NULL is returned if dsn cannot be opened with the requested access. Wrapper of GDALDatasetTestCapability() in the GDAL API. The returned list contains the following named elements:

CreateLayer: TRUE if this datasource can create new layers
DeleteLayer: TRUE if this datasource can delete existing layers
CreateGeomFieldAfterCreateLayer: TRUE if the layers of this datasource support geometry field creation just after layer creation
CurveGeometries: TRUE if this datasource supports curve geometries
Transactions: TRUE if this datasource supports (efficient) transactions
EmulatedTransactions: TRUE if this datasource supports transactions through emulation
RandomLayerRead: TRUE if this datasource has a dedicated GetNextFeature() implementation, potentially returning features from layers in a non-sequential way
RandomLayerWrite: TRUE if this datasource supports calling CreateFeature() on layers in a non-sequential way

ogr_ds_create() creates a new vector datasource, optionally also creating a layer, and optionally creating one or more fields on the layer. The attribute fields and geometry field(s) to create can be specified as a feature class definition (layer_defn as list, see ogr_define), or alternatively, by giving the geom_type and srs, optionally along with one fld_name and fld_type to be created in the layer. Returns a logical scalar, TRUE indicating success.

ogr_ds_layer_count() returns the number of layers in a vector dataset.

ogr_ds_layer_names() returns a character vector of layer names in a vector dataset, or NULL if no layers are found.

ogr_layer_exists() tests whether a layer can be accessed by name in a given vector dataset. Returns a logical scalar.

ogr_layer_test_cap() tests whether a layer supports named capabilities, attempting to open the dataset with update access by default. Returns a list of capabilities with values TRUE or FALSE. NULL is returned if dsn cannot be opened with the requested access, or layer cannot be found. The returned list contains the following named elements: RandomRead, SequentialWrite, RandomWrite, UpsertFeature, FastSpatialFilter, FastFeatureCount, FastGetExtent, FastSetNextByIndex, CreateField, CreateGeomField, DeleteField, ReorderFields, AlterFieldDefn, AlterGeomFieldDefn, DeleteFeature, StringsAsUTF8, Transactions, CurveGeometries. See the GDAL documentation for OGR_L_TestCapability().

ogr_layer_create() creates a new layer in an existing vector data source, with a specified geometry type and spatial reference definition. This function also accepts a feature class definition given as a list of field names and their definitions (see ogr_define). (Note: use ogr_ds_create() to create single-layer formats such as "ESRI Shapefile", "FlatGeobuf", "GeoJSON", etc.) Returns a logical scalar, TRUE indicating success.

ogr_layer_field_names() returns a character vector of field names on a layer, or NULL if no fields are found.

ogr_layer_delete() deletes an existing layer in a vector dataset. Returns a logical scalar, TRUE indicating success.

ogr_field_index() tests for existence of an attribute field by name. Returns the field index on the layer (0-based), or -1 if the field does not exist.

ogr_field_create() creates a new attribute field of specified data type in a given DSN/layer. Several optional field properties can be specified in addition to the type. Returns a logical scalar, TRUE indicating success.

ogr_geom_field_create() creates a new geometry field of specified type in a given DSN/layer. Returns a logical scalar, TRUE indicating success.

ogr_field_rename() renames an existing field on a vector layer. Not all format drivers support this function. Some drivers may only support renaming a field while there are still no features in the layer. AlterFieldDefn is the relevant layer capability to check. Returns a logical scalar, TRUE indicating success.

ogr_field_delete() deletes an existing field on a vector layer. Not all format drivers support this function. Some drivers may only support deleting a field while there are still no features in the layer. Returns a logical scalar, TRUE indicating success.

ogr_execute_sql() executes an SQL statement against the data store. This function can be used to modify the schema or edit data using SQL (e.g., ALTER TABLE, DROP TABLE, CREATE INDEX, DROP INDEX, INSERT, UPDATE, DELETE), or to execute a query (i.e., SELECT). Returns NULL (invisibly) for statements that are in error, or that have no results set, or an object of class GDALVector representing a results set from the query. Wrapper of GDALDatasetExecuteSQL() in the GDAL API.

Note

The OGR SQL document linked under See Also contains information on the SQL dialect supported internally by GDAL/OGR. Some format drivers (e.g., PostGIS) pass the SQL directly through to the underlying RDBMS (unless OGRSQL is explicitly passed as the dialect). The SQLite dialect can also be requested with the SQLite string passed as the dialect argument of ogr_execute_sql(). This assumes that GDAL/OGR is built with support for SQLite, and preferably also with Spatialite support to benefit from spatial functions. The GDAL document for SQLite dialect has detailed information.

Other SQL dialects may also be present for some vector formats. For example, the "INDIRECT_SQLITE" dialect might potentially be used with GeoPackage format (https://gdal.org/drivers/vector/gpkg.html#sql).

The function ogrinfo() can also be used to edit data with SQL statements (GDAL >= 3.7).

The name of the geometry column of a layer is empty ("") with some formats such as ESRI Shapefile and FlatGeobuf. Implications for SQL may depend on the dialect used. See the GDAL documentation for the "OGR SQL" and "SQLite" dialects for details.

Examples

dsn <- file.path(tempdir(), "test1.gpkg")
ogr_ds_create("GPKG", dsn)
#> [1] TRUE
ogr_ds_exists(dsn, with_update = TRUE)
#> [1] TRUE
ogr_ds_layer_count(dsn)
#> [1] 0
ogr_ds_test_cap(dsn)
#> $CreateLayer
#> [1] TRUE
#> 
#> $DeleteLayer
#> [1] TRUE
#> 
#> $CreateGeomFieldAfterCreateLayer
#> [1] FALSE
#> 
#> $CurveGeometries
#> [1] TRUE
#> 
#> $Transactions
#> [1] TRUE
#> 
#> $EmulatedTransactions
#> [1] FALSE
#> 
#> $RandomLayerRead
#> [1] FALSE
#> 
#> $RandomLayerWrite
#> [1] TRUE
#> 
ogr_layer_exists(dsn, "layer1")
#> [1] FALSE
if (ogr_ds_test_cap(dsn)$CreateLayer) {
  opt <- c("GEOMETRY_NULLABLE=NO", "DESCRIPTION=test layer")
  ogr_layer_create(dsn, "layer1", geom_type = "Polygon", srs = "EPSG:5070",
                   lco = opt)
}
#> [1] TRUE
ogr_ds_layer_count(dsn)
#> [1] 1
ogr_layer_exists(dsn, "layer1")
#> [1] TRUE
ogr_ds_layer_names(dsn)
#> [1] "layer1"

ogr_layer_field_names(dsn, "layer1")
#> [1] "geom"
ogr_field_index(dsn, "layer1", "field1")
#> [1] -1
if (ogr_layer_test_cap(dsn, "layer1")$CreateField) {
  ogr_field_create(dsn, "layer1", "field1",
                   fld_type = "OFTInteger64",
                   is_nullable = FALSE)
  ogr_field_create(dsn, "layer1", "field2",
                   fld_type = "OFTString")
}
#> [1] TRUE
ogr_field_index(dsn, "layer1", "field1")
#> [1] 0
ogr_layer_field_names(dsn, "layer1")
#> [1] "field1" "field2" "geom"  

# delete a field
if (ogr_layer_test_cap(dsn, "layer1")$DeleteField) {
  ogr_field_delete(dsn, "layer1", "field2")
}
#> [1] TRUE
ogr_layer_field_names(dsn, "layer1")
#> [1] "field1" "geom"  

# define a feature class (layer definition)
defn <- ogr_def_layer("Point", srs = epsg_to_wkt(4326))
# add the attribute fields
defn$fld1_name <- ogr_def_field("OFTInteger64",
                                is_nullable = FALSE,
                                is_unique = TRUE)
defn$fld2_name <- ogr_def_field("OFTString",
                                fld_width = 25,
                                is_nullable = FALSE,
                                default_value = "'a default string'")
defn$third_field <- ogr_def_field("OFTReal",
                                  default_value = "0.0")

ogr_layer_create(dsn, "layer2", layer_defn = defn)
#> [1] TRUE
ogr_ds_layer_names(dsn)
#> [1] "layer1" "layer2"
ogr_layer_field_names(dsn, "layer2")
#> [1] "fld1_name"   "fld2_name"   "third_field" "geom"       

# add a field using SQL instead
sql <- "ALTER TABLE layer2 ADD field4 float"
ogr_execute_sql(dsn, sql)
#> info: open dataset successful on DSN:
#>   '/tmp/Rtmp25ItvQ/test1.gpkg'
ogr_layer_field_names(dsn, "layer2")
#> [1] "fld1_name"   "fld2_name"   "third_field" "field4"      "geom"       

# rename a field
if (ogr_layer_test_cap(dsn, "layer1")$AlterFieldDefn) {
  ogr_field_rename(dsn, "layer2", "field4", "renamed_field")
}
#> [1] TRUE
ogr_layer_field_names(dsn, "layer2")
#> [1] "fld1_name"     "fld2_name"     "third_field"   "renamed_field"
#> [5] "geom"         

# GDAL >= 3.7
if (as.integer(gdal_version()[2]) >= 3070000)
  ogrinfo(dsn, "layer2")

deleteDataset(dsn)
#> [1] TRUE

# edit data using SQL
src <- system.file("extdata/ynp_fires_1984_2022.gpkg", package="gdalraster")
perims_shp <- file.path(tempdir(), "mtbs_perims.shp")
ogr2ogr(src, perims_shp, src_layers = "mtbs_perims")
ogr_ds_format(perims_shp)
#> [1] "ESRI Shapefile"
ogr_ds_layer_names(perims_shp)
#> [1] "mtbs_perims"
ogr_layer_field_names(perims_shp, "mtbs_perims")
#>  [1] "event_id"   "incid_name" "incid_type" "map_id"     "burn_bnd_a"
#>  [6] "burn_bnd_l" "burn_bnd_1" "ig_date"    "ig_year"    ""          

if (ogr_layer_test_cap(perims_shp, "mtbs_perims")$CreateField) {
  sql <- "ALTER TABLE mtbs_perims ADD burn_bnd_ha float"
  ogr_execute_sql(perims_shp, sql)
  # with GDAL >= 3.7, equivalent to:
  # ogrinfo(perims_shp, cl_arg = c("-sql", sql), read_only = FALSE)
}
#> info: open dataset successful on DSN:
#>   '/tmp/Rtmp25ItvQ/mtbs_perims.shp'

sql <- "UPDATE mtbs_perims SET burn_bnd_ha = (burn_bnd_ac / 2.471)"
ogr_execute_sql(perims_shp, sql, dialect = "SQLite")
#> info: open dataset successful on DSN:
#>   '/tmp/Rtmp25ItvQ/mtbs_perims.shp'
ogr_layer_field_names(perims_shp, "mtbs_perims")
#>  [1] "event_id"   "incid_name" "incid_type" "map_id"     "burn_bnd_a"
#>  [6] "burn_bnd_l" "burn_bnd_1" "ig_date"    "ig_year"    "burn_bnd_h"
#> [11] ""          

# if GDAL >= 3.7:
#   ogrinfo(perims_shp, "mtbs_perims")
# or, for output incl. the feature data (omit the default "-so" arg):
#   ogrinfo(perims_shp, "mtbs_perims", cl_arg = "-nomd")

deleteDataset(perims_shp)
#> [1] TRUE