new(GDALVector, dsn)
The first layer by index is assumed if the layer argument is omitted, so this form of the constructor might be used for single-layer formats like shapefile.
new(GDALVector, dsn, layer)
Constructor specifying the name of a layer to open. The layer argument may also be given as an SQL SELECT statement to define a layer as the result set.
new(GDALVector, dsn, layer, read_only)
Constructor specifying read/write access (read_only = {TRUE|FALSE}). The layer argument is required in this form of the constructor, but may be given as empty string (""), in which case the first layer by index will be assumed.
new(GDALVector, dsn, layer, read_only, open_options)
Constructor specifying dataset open options as a character vector of NAME=VALUE pairs.
new(GDALVector, dsn, layer, read_only, open_options, spatial_filter, dialect))
Constructor to specify a spatial filter and/or SQL dialect. All arguments are required in this form of the constructor, but open_options may be NULL, and spatial_filter or dialect may be an empty string ("").
$defaultGeomColName
Character string specifying a name to use for returned columns when the geometry column name in the source layer is empty, like with shapefiles etc. Defaults to "geom".
$returnGeomAs
Character string specifying the return format of feature geometries. Must be one of WKB (the default), WKB_ISO, WKT, WKT_ISO, BBOX, or NONE. Using WKB/WKT exports as 99-402 extended dimension (Z) types for Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon and GeometryCollection. For other geometry types, it is equivalent to using WKB_ISO/WKT_ISO (see https://libgeos.org/specifications/wkb/). Using BBOX exports as a list of numeric vectors, each of length 4 with values xmin, ymin, xmax, ymax. If an empty geometry is encountered these values will be NA_real_ in the corresponding location. Using NONE will result in no geometry value being present in the feature returned.
$promoteToMulti
A logical value specifying whether to automatically promote geometries from Polygon to MultiPolygon, Point to MultiPoint, or LineString to MultiLineString during read operations (i.e., with methods $getFeature(), $getNextFeature(), $fetch()). Defaults to FALSE. Setting to TRUE may be useful when reading from layers such as shapefiles that mix, e.g., Polygons and MultiPolygons.
$convertToLinear
A logical value specifying whether to convert non-linear geometry types into linear geometry types by approximating them (i.e., during read operations with methods $getFeature(), $getNextFeature(), $fetch()). Defaults to FALSE. If set to TRUE, handled conversions are:
wkbCurvePolygon -> wkbPolygon
wkbCircularString -> wkbLineString
wkbCompoundCurve -> wkbLineString
wkbMultiSurface -> wkbMultiPolygon
wkbMultiCurve -> wkbMultiLineString
$wkbByteOrder
Character string specifying the byte order for WKB geometries. Must be either LSB (Least Significant Byte first, the default) or MSB (Most Significant Byte first).
$arrowStreamOptions
Character vector of "NAME=VALUE" pairs giving options used by the $getArrowStream() method (see below). The available options may be driver and GDAL version specific. Options available as of GDAL 3.8 are listed below. For more information about options for Arrow stream, see the GDAL API documentation for OGR_L_GetArrowStream().
INCLUDE_FID=YES/NO. Defaults to YES.
MAX_FEATURES_IN_BATCH=integer. Maximum number of features to retrieve in an ArrowArray batch. Defaults to 65536.
TIMEZONE=unknown/UTC/(+|:)HH:MM or any other value supported by Arrow (GDAL >= 3.8).
GEOMETRY_METADATA_ENCODING=OGC/GEOARROW (GDAL >= 3.8). The GDAL default is OGC if not specified.
GEOMETRY_ENCODING=WKB (Arrow/Parquet drivers). To force a fallback to the generic implementation when the native geometry encoding is not WKB. Otherwise the geometry will be returned with its native Arrow encoding (possibly using GeoArrow encoding).
$quiet
A logical value, FALSE by default. Set to TRUE to suppress various messages and warnings.
$transactionsForce
A logical value, FALSE by default. Affects the behavior of attempted transactions on the layer (see the $startTransaction() method below). By default, only "efficient" transactions will be attempted. Some drivers may offer an emulation of transactions, but sometimes with significant overhead, in which case the user must explicitly allow for such an emulation by first setting $transactionsForce <- TRUE.
$open(read_only)
(Re-)opens the vector layer on the existing DSN. Use this method to open a layer that has been closed using $close(). May be used to re-open a layer with a different read/write access (read_only set to TRUE or FALSE). The method will first close an open dataset, so it is not required to call $close() explicitly in this case. No return value, called for side effects.
$isOpen()
Returns a logical value indicating whether the vector dataset is open.
$getDsn()
Returns a character string containing the dsn associated with this GDALVector object (dsn originally used to open the layer).
$getFileList()
Returns a character vector of files believed to be part of the data source. If it returns an empty string ("") it means there is believed to be no local file system files associated with the dataset (e.g., a virtual file system). The returned filenames will normally be relative or absolute paths depending on the path used to originally open the dataset.
$info()
Prints information about the vector layer to the console (no return value, called for that side effect only). For non-SQL DSN/layer, calls ogrinfo() passing the command options cl_arg = c("-so", "-nomd"), and for layers open with a SQL statement, calls ogrinfo() passing the command options cl_arg = c("-so", "-nomd", "-sql", <statement>).
$getDriverShortName()
Returns the short name of the vector format driver.
$getDriverLongName()
Returns the long name of the vector format driver.
$getName()
Returns the layer name.
$getFieldNames()
Returns a character vector of the layer's field names.
$testCapability()
Tests whether the layer supports named capabilities based on the current read/write access. Returns a list of capabilities with values TRUE or FALSE. The returned list contains the following named elements: RandomRead, SequentialWrite, RandomWrite, UpsertFeature, FastSpatialFilter, FastFeatureCount, FastGetExtent, FastSetNextByIndex, FastGetArrowStream, FastWriteArrowBatch, CreateField, CreateGeomField, DeleteField, ReorderFields, AlterFieldDefn, AlterGeomFieldDefn, DeleteFeature, StringsAsUTF8, Transactions, CurveGeometries. Note that some layer capabilities are GDAL version dependent and may not be listed if not supported by the GDAL version currently in use. (See the GDAL documentation for OGR_L_TestCapability().)
$getFIDColumn()
Returns the name of the underlying database column being used as the FID column, or empty string ("") if not supported.
$getGeomType()
Returns the well known name of the layer geometry type as character string. For layers with multiple geometry fields, this method only returns the geometry type of the first geometry column. For other columns, use $getLayerDefn(). For layers without any geometry field, this method returns "NONE".
$getGeometryColumn()
Returns he name of the underlying database column being used as the geometry column, or an empty string ("") if not supported. For layers with multiple geometry fields, this method only returns the name of the first geometry column. For other columns, use $getLayerDefn().
$getSpatialRef()
Returns a WKT string containing the spatial reference system for this layer, or empty string ("") if no spatial reference exists.
$bbox()
Returns a numeric vector of length four containing the bounding box for this layer (xmin, ymin, xmax, ymax). Note that bForce = true is set in the underlying API call to OGR_L_GetExtent(), so the entire layer may be scanned to compute a minimum bounding rectangle (see FastGetExtent in the list returned by $testCapability()). Depending on the format driver, a spatial filter may or may not be taken into account, so it is safer to call $bbox() without setting a spatial filter.
$getLayerDefn()
Returns a list containing the OGR feature class definition for this layer (a.k.a. layer definition). The list contains zero or more attribute field definitions, along with one or more geometry field definitions. See ogr_define for details of the field and feature class definitions.
$getFieldDomain(domain_name)
Returns a list containing the definition of the OGR field domain with the passed domain_name, or NULL if domain_name is not found. See ogr_define for specification of the list containing a field domain definition. Some formats support the use of field domains which describe the valid values that can be stored in a given attribute field, e.g., coded values that are present in a specified enumeration, values constrained to a specified range, or values that must match a specified pattern. See https://gdal.org/en/stable/user/vector_data_model.html#field-domains. Requires GDAL >= 3.3.
$setAttributeFilter(query)
Sets an attribute query string to be used when fetching features via the $getNextFeature() or $fetch() methods. Only features for which query evaluates as true will be returned. The query string should be in the format of an SQL WHERE clause, described in the "WHERE" section of the OGR SQL dialect documentation (e.g., "population > 1000000 and population < 5000000", where population is an attribute in the layer). In some cases (RDBMS backed drivers, SQLite, GeoPackage) the native capabilities of the database may be used to to interpret the WHERE clause, in which case the capabilities will be broader than those of OGR SQL. Note that installing a query string will generally result in resetting the current reading position (as with $resetReading() described below). The query parameter may be set to empty string ("") to clear the current attribute filter.
$getAttributeFilter()
Returns the attribute query string currently in use, or empty string ("") if an attribute filter is not set.
$setIgnoredFields(fields)
Set which fields can be omitted when retrieving features from the layer. The fields argument is a character vector of field names. Passing an empty string ("") for fields will reset to no ignored fields. If the format driver supports this functionality (testable using $testCapability()$IgnoreFields), it will not fetch the specified fields in subsequent calls to $getFeature() / $getNextFeature() / $fetch(), and thus save some processing time and/or bandwidth. Besides field names of the layer, the following special fields can be passed: "OGR_GEOMETRY" to ignore geometry and "OGR_STYLE" to ignore layer style. By default, no fields are ignored. Note that fields that are used in an attribute filter should generally not be set as ignored fields, as most drivers (such as those relying on the OGR SQL engine) will be unable to correctly evaluate the attribute filter. No return value, called for side effects.
$setSelectedFields(fields)
Set which fields will be included when retrieving features from the layer. The fields argument is a character vector of field names. Passing an empty string ("") for fields will reset to no ignored fields. See the $setIgnoredFields() method above for more information. The data source must provide IgnoreFields capability in order to set selected fields. Note that geometry fields, if desired, must be specified when setting selected fields, either by including named geometry field(s) or the special field "OGR_GEOMETRY" in the fields argument. No return value, called for side effects.
$getIgnoredFields()
Returns a character vector containing the list of currently ignored fields, or an empty vector (character(0)) if no fields are currently set to ignored (or if the format driver does not support ignored fields).
$setSpatialFilter(wkt)
Sets a new spatial filter from a geometry in WKT format. This method sets the geometry to be used as a spatial filter when fetching features via the $getNextFeature() or $fetch() methods. Only features that geometrically intersect the filter geometry will be returned. Currently this test may be inaccurately implemented (depending on the vector format driver), but it is guaranteed that all features whose envelope overlaps the envelope of the spatial filter will be returned. This can result in more shapes being returned that should strictly be the case. wkt is a character string containing a WKT geometry in the same coordinate system as the layer. An empty string ("") may be passed indicating that the current spatial filter should be cleared, but no new one instituted.
$setSpatialFilterRect(bbox)
Sets a new rectangular spatial filter. This method sets a rectangle to be used as a spatial filter when fetching features via the $getNextFeature() or $fetch() methods. Only features that geometrically intersect the given rectangle will be returned. bbox is a numeric vector of length four containing xmin, ymin, xmax, ymax in the same coordinate system as the layer as a whole (as returned by $getSpatialRef()).
$getSpatialFilter()
Returns the current spatial filter geometry as a WKT string, or empty string ("") if a spatial filter is not set.
$clearSpatialFilter()
Clears a spatial filter that was set with $setSpatialFilterRect(). No return value, called for that side effect.
$getFeatureCount()
Returns the number of features in the layer. For dynamic databases the count may not be exact. This method forces a count in the underlying API call (i.e., bForce = TRUE in the call to OGR_L_GetFeatureCount()). Note that some vector drivers will actually scan the entire layer once to count features. The FastFeatureCount element in the list returned by the $testCapability() method can be checked if this might be a concern. The number of features returned takes into account the spatial and/or attribute filters. Some driver implementations of this method may alter the read cursor of the layer.
$getNextFeature()
Fetch the next available feature from this layer. Only features matching the current spatial and/or attribute filter (if defined) will be returned. This method implements sequential access to the features of a layer. The $resetReading() method can be used to start at the beginning again. Returns a list with the unique feature identifier (FID), the attribute and geometry field names, and their values. The returned list carries the OGRFeature class attribute with S3 methods for for print() and plot(). NULL is returned if no more features are available.
$setNextByIndex(i)
Moves the read cursor to feature i in the current result set (with 0-based indexing). This method allows positioning of a layer such that a call to $getNextFeature() or $fetch() will read the requested feature(s), where i is an absolute index into the current result set. So, setting i = 3 would mean the next feature read with $getNextFeature() would have been the fourth feature read if sequential reading took place from the beginning of the layer, including accounting for spatial and attribute filters. This method is not implemented efficiently by all vector format drivers. The default implementation simply resets reading to the beginning and then calls GetNextFeature() i times. To determine if fast seeking is available on the current layer, check the FastSetNextByIndex element in the list returned by the $testCapability() method. No return value, called for side effect.
$getFeature(fid)
Returns a feature by its identifier. The value of fid must be a numeric value, optionally carrying the bit64::integer64 class attribute. Success or failure of this operation is unaffected by any spatial or attribute filters that may be in effect. The RandomRead element in the list returned by $testCapability() can be checked to establish if this layer supports efficient random access reading; however, the call should always work if the feature exists since a fallback implementation just scans all the features in the layer looking for the desired feature. Returns a list with the unique feature identifier (FID), the attribute and geometry field names, and their values, or NULL on failure. Note that sequential reads (with $getNextFeature()) are generally considered interrupted by a call to $getFeature().
$resetReading()
Reset feature reading to start on the first feature. No return value, called for that side effect.
$fetch(n)
Fetches the next n features from the layer and returns them as a data frame. This allows retrieving the entire set of features, one page of features at a time, or the remaining features (from the current cursor position). Returns a data frame with as many rows as features were fetched, and as many columns as attribute plus geometry fields in the result set, even if the result is a single value or has one or zero rows. The returned data frame carries the OGRFeatureSet class attribute with S3 methods for for print() and plot().
This method is an analog of DBI::dbFetch().
The n argument is the maximum number of features to retrieve per fetch given as integer or numeric but assumed to be a whole number (will be truncated). Use n = -1 or n = Inf to retrieve all pending features (resets reading to the first feature). Otherwise, $fetch() can be called multiple times to perform forward paging from the current cursor position. Passing n = NA is also supported and returns the remaining features. Fetching zero features is possible to retrieve the structure of the feature set as a data frame (columns fully typed).
OGR field types are returned as the following R types (type-specific NA for OGR NULL values):
OFTInteger: integer value
OFTInteger subtype OFSTBoolean: logical value
OFTIntegerList: vector of integer (list column)
OFTInteger64: numeric value carrying the "integer64" class attribute
OFTInteger64 subtype OFSTBoolean: logical value
OFTInteger64List: vector of bit64::integer64 (list column)
OFTReal: numeric value
OFTRealList: vector of numeric (list column)
OFTString: character string
OFTStringList: vector of character strings (list column)
OFTDate: numeric value of class "Date"
OFTDateTime: numeric value of class "POSIXct" (millisecond accuracy)
OFTTime: character string ("HH:MM:SS")
OFTBinary: raw vector (list column, NULL entries for OGR NULL values)
Geometries are not returned if the field returnGeomAs is set to NONE. Omitting the geometries may be beneficial for performance and memory usage when access only to feature attributes is needed. Geometries are returned as raw vectors in a data frame list column when returnGeomAs is set to WKB (the default) or WKB_ISO, or as character strings when returnGeomAs is set to one of WKT or WKT_ISO.
Note that $getFeatureCount() is called internally when fetching the full feature set or all remaining features (but not for a page of features).
$getArrowStream()
Returns a nanoarrow_array_stream object exposing an Arrow C stream on the layer (requires GDAL >= 3.6). The writable field $arrowStreamOptions can be used to set options before calling this method (see above). An error is raised if an array stream on the layer cannot be obtained. Generally, only one ArrowArrayStream can be active at a time on a given layer (i.e., the last active one must be explicitly released before a next one is asked). Changing attribute or spatial filters, ignored columns, modifying the schema or using $resetReading()/$getNextFeature() while using an ArrowArrayStream is strongly discouraged and may lead to unexpected results. As a rule of thumb, no OGRLayer methods that affect the state of a layer should be called on the layer while an ArrowArrayStream on it is active. Methods available on the stream object are: $get_schema(), $get_next() and $release() (see Examples).
The stream should be released once reading is complete. Calling the release method as soon as you can after consuming a stream is recommended by the nanoarrow documentation.
See also the $testCapability() method above to check whether the format driver provides a specialized implementation (FastGetArrowStream), as opposed to the (slower) default implementation. Note however that specialized implementations may fallback to the default when attribute or spatial filters are in use. (See the GDAL documentation for OGR_L_GetArrowStream().)
$releaseArrowStream()
Releases the Arrow C stream returned by $getArrowStream() and clears the nanoarrow_array_stream object (if GDAL >= 3.6, otherwise does nothing). This is equivalent to calling the $release() method on the nanoarrow_array_stream object. No return value, called for side effects.
$setFeature(feature)
Rewrites/replaces an existing feature. This method writes a feature based on the feature id within the input feature. The feature argument is a named list of fields and their values, and must include a $FID element referencing the existing feature to rewrite. The RandomWrite element in the list returned by $testCapability() can be checked to establish if this layer supports random access writing via $setFeature(). The way omitted fields in the passed feature are processed is driver dependent:
SQL-based drivers which implement set feature through SQL UPDATE will skip unset fields, and thus the content of the existing feature will be preserved.
The shapefile driver will write a NULL value in the DBF file.
The GeoJSON driver will take into account unset fields to remove the corresponding JSON member.
Returns logical TRUE upon successful completion, or FALSE if setting the feature did not succeed. The FID of the last feature written to the layer may be obtained with the method $getLastWriteFID() (see below). To set a feature, but create it if it doesn't exist see the $upsertFeature() method.
$createFeature(feature)
Creates and writes a new feature within the layer. The feature argument is a named list of fields and their values (might be one row of a data frame). The passed feature is written to the layer as a new feature, rather than overwriting an existing one. If the feature has a $FID element with other than NA (i.e., a numeric value, optionally carrying the bit64::integer64 class attribute and assumed to be a whole number), then the format driver may use that as the feature id of the new feature, but not necessarily. The FID of the last feature written to the layer may be obtained with the method $getLastWriteFID() (see below). Returns logical TRUE upon successful completion, or FALSE if creating the feature did not succeed. To create a feature, but set it if it already exists see the $upsertFeature() method.
$batchCreateFeature(feature_set)
Batch version of $createFeature(). Creates and writes a batch of new features within the layer from input passed as a data frame in the feature_set argument. Column names in the data frame must match field names of the layer and have compatible data types. The specifications listed above under the $fetch() method generally apply to input data types for writing, but integers may be passed as 'numeric', and the 'integer64' class attribute is not strictly required on 'numeric' input if it is not needed for the data being passed to an OFTInteger64 field. Returns a logical vector of length equal to the number of input features (rows of the data frame), with TRUE indicating success for the feature at that row index, or FALSE if writing the feature failed. It is recommended to use transactions when batch writing features to a layer (see $startTransaction() below). This will generally give large performance benefit with data sources that provide efficient transaction support (e.g., RDBMS-based sources such as GeoPackage and PostGIS). In addition, the return value of $batchCreateFeature() can be checked, and the transaction optionally committed or rolled back based on results of the operation across the full set of input features.
$upsertFeature(feature)
Rewrites/replaces an existing feature or creates a new feature within the layer. This method will write a feature to the layer, based on the feature id within the input feature. The feature argument is a named list of fields and their values (might be one row of a data frame), potentially including a $FID element referencing an existing feature to rewrite. If the feature id doesn't exist a new feature will be written. Otherwise, the existing feature will be rewritten. The UpsertFeature element in the list returned by $testCapability() can be checked to determine if this layer supports upsert writing. See $setFeature() above for a description of how omitted fields in the passed feature are processed. Returns logical TRUE upon successful completion, or FALSE if upsert did not succeed. Requires GDAL >= 3.6.
$getLastWriteFID()
Returns the FID of the last feature written (either newly created or updated existing). NULL is returned if no features have been written in the layer. Note that OGRNullFID (-1) may be returned after writing a feature in some formats. This is the case if a FID has not been assigned yet, and generally does not indicate an error (e.g., formats that do not store a persistent FID and assign FIDs upon a sequential read operation). The returned FID is a numeric value carrying the bit64::integer64 class attribute.
$deleteFeature(fid)
Deletes a feature from the layer. The feature with the indicated feature ID is deleted from the layer if supported by the format driver. The value of fid must be a numeric value, optionally carrying the bit64::integer64 class attribute (should be a whole number, will be truncated). The DeleteFeature element in the list returned by $testCapability() can be checked to establish if this layer has delete feature capability. Returns logical TRUE if the operation succeeds, or FALSE on failure.
$syncToDisk()
Flushes pending changes to disk. This call is intended to force the layer to flush any pending writes to disk, and leave the disk file in a consistent state. It would not normally have any effect on read-only datasources. Some formats do not implement this method, and will still return no error. An error is only returned if an error occurs while attempting to flush to disk. In any event, you should always close any opened datasource with $close() which will ensure all data is correctly flushed. Returns logical TRUE if no error occurs (even if nothing is done) or FALSE on error.
$startTransaction()
Creates a transaction if supported by the vector data source. By default, only "efficient" transactions will be attempted. See the writable field $transactionsForce above, which must be set to TRUE to allow for emulated transactions. These are supported by some drivers but with potentially significant overhead. The function ogr_ds_test_cap() can be used to determine whether a vector data source supports efficient or emulated transactions.
All changes done after the start of the transaction are definitely applied in the data source if $commitTransaction() is called. They can be canceled by calling rollbackTransaction() instead. Nested transactions are not supported. Transactions are implemented at the dataset level, so multiple GDALVector objects using the same data source should not have transactions active at the same time.
In case $startTransaction() fails, neither $commitTransaction() nor $rollbackTransaction() should be called. If an error occurs after a successful $startTransaction(), the whole transaction may or may not be implicitly canceled, depending on the format driver (e.g., the PostGIS driver will cancel it, SQLite/GPKG will not). In any case, in the event of an error, an explicit call to rollbackTransaction() should be done to keep things balanced.
Returns logical TRUE if the transaction is created, or FALSE on failure.
$commitTransaction()
Commits a transaction if supported by the vector data source. Returns a logical value, TRUE if the transaction is successfully committed. Returns FALSE if no transaction is active, or the rollback fails, or if the data source does not support transactions. Depending on the format driver, this may or may not abort layer sequential reading that may be active.
$rollbackTransaction()
Rolls back a data source to its state before the start of the current transaction, if transactions are supported by the data source. Returns a logical value, TRUE if the transaction is successfully rolled back. Returns FALSE if no transaction is active, or the rollback fails, or if the data source does not support transactions.
$getMetadata()
Returns a character vector of all metadata NAME=VALUE pairs for the layer or empty string ("") if there are no metadata items.
$setMetadata(metadata)
Sets metadata on the layer if the format supports it. The metadata argument is given as a character vector of NAME=VALUE pairs. Returns logical TRUE on success or FALSE if metadata could not be set.
$getMetadataItem(mdi_name)
Returns the value of a specific metadata item named mdi_name, or empty string ("") if no matching item is found.
$close()
Closes the vector dataset (no return value, called for side effects). Calling $close() results in proper cleanup, and flushing of any pending writes. The GDALVector object is still available after calling $close(). The layer can be re-opened on the existing dsn with $open(read_only = {TRUE|FALSE}).
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4