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,
return_obj = FALSE
)
ogr_ds_layer_count(dsn)
ogr_ds_layer_names(dsn)
ogr_layer_exists(dsn, layer)
ogr_layer_test_cap(dsn, layer = NULL, with_update = TRUE)
ogr_layer_create(
dsn,
layer,
layer_defn = NULL,
geom_type = NULL,
srs = NULL,
lco = NULL,
return_obj = FALSE
)
ogr_layer_field_names(dsn, layer = NULL)
ogr_layer_rename(dsn, layer, new_name)
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_unique = FALSE,
default_value = ""
)
ogr_geom_field_create(
dsn,
layer,
fld_name,
geom_fld_defn = NULL,
geom_type = NULL,
srs = NULL,
is_nullable = TRUE
)
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, orFALSE
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. The
layer
argument may be given as empty string (""
) in which case the first layer by index will be opened (except withogr_layer_delete()
andogr_layer_rename()
for which a layer name nust be specified).- 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. Iflayer_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
andsrs
, as well asfld_name
andfld_type
inogr_ds_create()
). The first geometry field definition inlayer_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 overwritedsn
if it already exists when callingogr_ds_create()
. Default isFALSE
.- return_obj
Logical scalar. If
TRUE
, an object of classGDALVector
open on the newly created layer will be returned. Defaults toFALSE
. Must be used with either thelayer
orlayer_defn
arguments.- new_name
Character string containing a new name to assign.
- fld_defn
A field definition as list (see
ogr_def_field()
). Additional arguments inogr_field_create()
will be ignored if afld_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_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 inogr_geom_field_create()
will be ignored if ageom_fld_defn
is given.- 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 layersDeleteLayer
:TRUE
if this datasource can delete existing layersCreateGeomFieldAfterCreateLayer
:TRUE
if the layers of this datasource support geometry field creation just after layer creationCurveGeometries
:TRUE
if this datasource supports curve geometriesTransactions
:TRUE
if this datasource supports (efficient) transactionsEmulatedTransactions
:TRUE
if this datasource supports transactions through emulationRandomLayerRead
:TRUE
if this datasource has a dedicatedGetNextFeature()
implementation, potentially returning features from layers in a non-sequential wayRandomLayerWrite
:TRUE
if this datasource supports callingCreateFeature()
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.
By default, returns logical TRUE
indicating success (output written to
dst_filename
), or an object of class GDALVector
for the
output layer will be returned if return_obj = TRUE
. An error is raised if
the operation fails.
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
, IgnoreFields
,
DeleteFeature
, Rename
, StringsAsUTF8
, 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.)
By default, returns logical TRUE
indicating success, or an object of class
GDALVector
will be returned if return_obj = TRUE
.
An error is raised if the operation fails.
ogr_layer_field_names()
returns a character vector of field names on a
layer, or NULL
if no fields are found. The first layer by index is opened
if NULL
is given for the layer
argument.
ogr_layer_rename()
renames a layer in a vector dataset. This operation is
implemented only by layers that expose the Rename
capability (see
ogr_layer_test_cap()
above). This operation will fail if a layer with the
new name already exists. Returns a logical scalar, TRUE
indicating success.
Requires GDAL >= 3.5.
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.
See also
OGR SQL dialect and SQLite SQL dialect:
https://gdal.org/user/ogr_sql_sqlite_dialect.html
Examples
## Create GeoPackage and manage schema
dsn <- file.path(tempdir(), "test1.gpkg")
ogr_ds_create("GPKG", dsn)
#> [1] TRUE
ogr_ds_exists(dsn, with_update = TRUE)
#> [1] TRUE
# dataset capabilities
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_create(dsn, layer = "layer1", geom_type = "Polygon",
srs = "EPSG:5070")
#> [1] TRUE
ogr_field_create(dsn, layer = "layer1",
fld_name = "field1",
fld_type = "OFTInteger64",
is_nullable = FALSE)
#> [1] TRUE
ogr_field_create(dsn, layer = "layer1",
fld_name = "field2",
fld_type = "OFTString")
#> [1] TRUE
ogr_ds_layer_count(dsn)
#> [1] 1
ogr_ds_layer_names(dsn)
#> [1] "layer1"
ogr_layer_field_names(dsn, layer = "layer1")
#> [1] "field1" "field2" "geom"
# delete a field
if (ogr_layer_test_cap(dsn, "layer1")$DeleteField) {
ogr_field_delete(dsn, layer = "layer1", fld_name = "field2")
}
#> [1] TRUE
ogr_layer_field_names(dsn, "layer1")
#> [1] "field1" "geom"
# define a feature class and create layer
defn <- ogr_def_layer("Point", srs = epsg_to_wkt(4326))
# add the attribute fields
defn$id_field <- ogr_def_field(fld_type = "OFTInteger64",
is_nullable = FALSE,
is_unique = TRUE)
defn$str_field <- ogr_def_field(fld_type = "OFTString",
fld_width = 25,
is_nullable = FALSE,
default_value = "'a default string'")
defn$numeric_field <- ogr_def_field(fld_type = "OFTReal",
default_value = "0.0")
ogr_layer_create(dsn, layer = "layer2", layer_defn = defn)
#> [1] TRUE
ogr_ds_layer_names(dsn)
#> [1] "layer1" "layer2"
ogr_layer_field_names(dsn, layer = "layer2")
#> [1] "id_field" "str_field" "numeric_field" "geom"
# add a field using SQL instead
ogr_execute_sql(dsn, sql = "ALTER TABLE layer2 ADD field4 float")
#> info: open dataset successful on DSN:
#> '/tmp/RtmprHgVyM/test1.gpkg'
# rename a field
if (ogr_layer_test_cap(dsn, "layer1")$AlterFieldDefn) {
ogr_field_rename(dsn, layer = "layer2",
fld_name = "field4",
new_name = "renamed_field")
}
#> [1] TRUE
ogr_layer_field_names(dsn, layer = "layer2")
#> [1] "id_field" "str_field" "numeric_field" "renamed_field"
#> [5] "geom"
# GDAL >= 3.7
if (as.integer(gdal_version()[2]) >= 3070000)
ogrinfo(dsn, "layer2")
## 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_dsn = src, dst_dsn = perims_shp, src_layers = "mtbs_perims")
ogr_ds_format(dsn = perims_shp)
#> [1] "ESRI Shapefile"
ogr_ds_layer_names(dsn = perims_shp)
#> [1] "mtbs_perims"
ogr_layer_field_names(dsn = perims_shp, layer = "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" ""
alt_tbl <- "ALTER TABLE mtbs_perims ADD burn_bnd_ha float"
ogr_execute_sql(dsn = perims_shp, sql = alt_tbl)
#> info: open dataset successful on DSN:
#> '/tmp/RtmprHgVyM/mtbs_perims.shp'
upd <- "UPDATE mtbs_perims SET burn_bnd_ha = (burn_bnd_ac / 2.471)"
ogr_execute_sql(dsn = perims_shp, sql = upd, dialect = "SQLite")
#> info: open dataset successful on DSN:
#> '/tmp/RtmprHgVyM/mtbs_perims.shp'
ogr_layer_field_names(dsn = perims_shp, layer = "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(dsn = perims_shp, layer = "mtbs_perims")
# or, for output incl. the feature data (omit the default "-so" arg):
# ogrinfo(dsn = perims_shp, layer = "mtbs_perims", cl_arg = "-nomd")