R: Utility functions for managing vector data sources

ogr_manage {gdalraster}

R Documentation

Utility functions for managing vector data sources

Description

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). Currently, this function does not return a result set for a SELECT statement. Returns NULL invisibly. Wrapper of GDALDatasetExecuteSQL() in the GDAL C 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)
ogr_ds_exists(dsn, with_update = TRUE)
ogr_ds_layer_count(dsn)
ogr_ds_test_cap(dsn)
ogr_layer_exists(dsn, "layer1")
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)
}
ogr_ds_layer_count(dsn)
ogr_layer_exists(dsn, "layer1")
ogr_ds_layer_names(dsn)

ogr_layer_field_names(dsn, "layer1")
ogr_field_index(dsn, "layer1", "field1")
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")
}
ogr_field_index(dsn, "layer1", "field1")
ogr_layer_field_names(dsn, "layer1")

# delete a field
if (ogr_layer_test_cap(dsn, "layer1")$DeleteField) {
  ogr_field_delete(dsn, "layer1", "field2")
}
ogr_layer_field_names(dsn, "layer1")

# 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)
ogr_ds_layer_names(dsn)
ogr_layer_field_names(dsn, "layer2")

# add a field using SQL instead
sql <- "ALTER TABLE layer2 ADD field4 float"
ogr_execute_sql(dsn, sql)
ogr_layer_field_names(dsn, "layer2")

# rename a field
if (ogr_layer_test_cap(dsn, "layer1")$AlterFieldDefn) {
  ogr_field_rename(dsn, "layer2", "field4", "renamed_field")
}
ogr_layer_field_names(dsn, "layer2")

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

deleteDataset(dsn)

# 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)
ogr_ds_layer_names(perims_shp)
ogr_layer_field_names(perims_shp, "mtbs_perims")

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

sql <- "UPDATE mtbs_perims SET burn_bnd_ha = (burn_bnd_ac / 2.471)"
ogr_execute_sql(perims_shp, sql, dialect = "SQLite")
ogr_layer_field_names(perims_shp, "mtbs_perims")

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

[Package gdalraster version 1.11.1 Index]