Delayed Read for 'GDAL' Vector Data Sources
Overview
Lazy read for drawings. A 'dplyr' back end for data sources supported by 'GDAL' vector drivers, that allows working with local or remote sources as if they are in-memory data frames. Basic features work with any drawing format ('GDAL vector data source') supported by the 'gdalraster' package.
Breaking changes
- The backend now uses gdalraster for all GDAL access. Geometry columns in collected results are wk-typed (
wk::wkb,wk::wkt,wk::rct). st_as_sf()is no longer registered fortbl_GDALVectorConnection. Usecollect()first, thensf::st_as_sf()on the resulting tibble.- DBI class names renamed:
SFSQLConnection→GDALVectorConnection,SFSQLDriver→GDALVectorDriver,SFSQLResult→GDALVectorResult. The driver constructor is nowGDALSQL()(wasSFSQL()). - The magrittr pipe (
%>%) is no longer re-exported. Use R's native pipe (|>).
Compatibility
- Full compatibility with dbplyr >= 2.6.0. The new dbplyr dialect system (
sql_dialect()) caused several silent regressions with the previous development code:
Show all changes in 0.4.0Hide the rest of the changes in 0.4.0
sql_translation(),sql_escape_logical(), andsql_query_fields()now dispatch on a custom dialect class (sql_dialect_gdal_vector/sql_dialect_gdal_sqlite) rather than the connection class, matching how dbplyr 2.6.0 dispatches these generics.- Identifier quoting now uses double quotes (ANSI SQL) rather than backticks. GDAL's embedded SQLite engine rejects backtick-quoted identifiers generated by dbplyr 2.6.0's default SQLite dialect.
supports_window_clause()was removed from dbplyr 2.6.0; it is now conditionally registered only when the generic exists.- Spatial SQL translations (SpatiaLite functions) are gated on dialect: SQLITE connections get full spatial translations, OGRSQL connections get base translations only.
New features
- New
geom_formatargument todbConnect()controls geometry output:"WKB"(default),"WKT","NONE", or"BBOX". Configurable globally viaoptions(lazysf.geom_format = ...). - New
dialectargument todbConnect()controls SQL dialect:"SQLITE"(the default),"OGRSQL","INDIRECT_SQLITE", or""(let GDAL choose). SQLITE is the default because it supports subqueries (required for dbplyr verb chaining) and spatial SQL functions likeST_Area(). Configurable globally viaoptions(lazysf.dialect = ...). lazysf()now passes...through todbConnect(), sogeom_formatanddialectcan be set directly:lazysf(dsn, geom_format = "WKT").- Added
db_connection_describe()method for informative printing:GDAL <SQLITE> WKB [/path/to/file.gpkg]. - New
sql_query_fields()method generatesLIMIT 0SQL for field discovery (replacing dbplyr's defaultWHERE (0 = 1)which OGRSQL can't handle). For named tables,dbSendQuery()intercepts this and uses$getLayerDefn()for pure OGR metadata access — no SQL execution at all. Subqueries are correctly wrapped in parentheses with an alias. - New
.schema_from_defn()builds typed empty data frames from OGR layer definitions, mapping OGR field types to R types (OFTInteger→integer,OFTReal→double,OFTDateTime→POSIXct,OFSTBoolean→logical, etc.). Schema column names and types match whatfetch()returns. - New
dbListFields()method uses$getLayerDefn()for schema introspection without executing SQL. - Geometry columns are now automatically marked with wk types on materialization:
wk::wkb()for WKB,wk::wkt()for WKT, andwk::rct()for BBOX. CRS from the layer's spatial reference is attached to all geometry vectors. - New
sql_translation()method provides SpatiaLite function translations for the SQLITE dialect. R functions likest_area(),st_intersects(),st_buffer(),st_transform()etc. translate to their SpatiaLite SQL equivalents, enabling idiomatic dplyr pipelines with spatial operations:lazysf("countries.gpkg") |> filter(st_area(geom) > 1e6). OGRSQL dialect falls back to base SQLite translations only. - Added
sql_escape_logical()method: TRUE/FALSE map to 1/0 for SQLite, NA maps to NULL. - Added
supports_window_clause()method (returns TRUE for SQLITE dialect). - Future-proofed for upcoming dbplyr
sql_dialect()generic. When the next version of dbplyr ships with the new dialect system, lazysf will automatically provide SQLite translation without any code changes. - New
use_arrowargument todbConnect()andlazysf()enables GDAL's Arrow C stream interface for reading features. Columnar transfer viaGDALVector$getArrowStream()and nanoarrow, typically much faster for larger datasets. Requires GDAL >= 3.6. Configurable globally viaoptions(lazysf.use_arrow = ...). - Geometry columns are automatically marked with wk types on materialization. CRS is attached. This enables
sf::st_as_sf()on the collected tibble via sf's wk support without any lazysf-specific method.
Bug fixes
- Multiline SQL from dbplyr is now collapsed to a single line before passing to
GDALVector. GDAL's constructor rejects SQL with newline characters, which dbplyr generates forrename(),transmute(), and any verb that enumerates columns explicitly. - Table-qualified column prefixes from GDAL (e.g.
nc.AREAfromSELECT "nc".*) are now stripped automatically so column names match what dbplyr expects. OGRFeatureSetclass is stripped from fetch results. The gdalraster print method for this class conflicts with wk-typed geometry columns.- FID column name is normalized to uppercase
"FID"in both thefetch()and Arrow paths, matching GDAL's behavior (GeoPackage stores"fid"butfetch()returns"FID"). - Geometry column from
getLayerDefn()is excluded from the attribute field loop in.schema_from_defn()—getLayerDefn()includes geometry as a field butfetch()handles it separately viareturnGeomAs.
Known issues
- GDAL's GDALVector initialization emits "SpatiaLite is not available" warnings on systems without SpatiaLite linked. These are harmless C++ diagnostics that can't be suppressed from R. Tracked upstream in gdalraster.
- No window functions:
slice_min(),slice_max(),row_number()etc. are not supported by GDAL's SQLite engine. Usearrange() |> head()instead. - Spatial SQL function availability depends on GDAL build configuration.
ST_Area()andST_SRID()work without SpatiaLite (GDAL-native).ST_AsText(),ST_Intersects(), and most geometry operations require SpatiaLite.
Dependencies
- gdalraster (>= 2.0.0) replaces sf in Imports.
- wk added to Imports for geometry type marking.
- sf removed from dependencies (was previously in Imports, then Suggests).
- nanoarrow added to Suggests (for Arrow stream interface).
- dbplyr (>= 2.0.0) now required (2nd edition backend API).
- magrittr removed from dependencies.
From NEWS.md in the release
Install
Health
- OK13 OK2026-08-05
- NOTE12 OK, 1 NOTE2026-08-01
- OK13 OK2026-06-09
- ERROR12 OK, 1 ERROR2026-06-08
- OK14 OK2026-03-10
Documentation
- Help pages
- 9 (5 internal)includes a package overview page
- Examples that run
- 100%4 run in a plain check
- Exported functions with examples
- 67%
- Documented parameters
- 67%
- Return-value docs
- 33%
- Help pages citing references
- 0%
- GDAL SQL with lazysf HTML
Downloads
Repository
- PRs merged (all time)
- 100%
- Median days to close, 50 most recently updated closed issues
- 47
- Median days to close, 50 most recently updated closed PRs
- 0
Stars over time
Forks over time
Issues over time
Commits over time
10 development-tooling and community-health practices detected across 6 families in the upstream repository
Checks run against github.com/hypertidy/lazysf on 2026-10-22.
The R CMD check workflow runs on Linux, macOS and Windows, and on R-devel
GitHub Pages site last deployed 2026-07-12 · The repository has a site deploy workflow
pkgdown site last built 2026-07-12, before release 0.4.0 (2026-07-13)
Show all practicesHide 2 practices
This repository shows signs of AI coding tools.
- GitHub Copilotfirst seen 2026-02-18Pull request: opened by its own accountCommits: 5 by its own account
- Claude Codefirst seen 2026-07-12Named in .Rbuildignore: .claude
Dependencies
Installing lazysf adds 32 packages (21 with compiled code, 28 MB of source tarballs). Heaviest: stringi 11 MB, gdalraster 3.2 MB, Rcpp 1.8 MB.
Code & Tests
People & History
Package metadata
- First published
- 2020-11-14
- Total releases
- 4 / 6 yrs
- License
- GPL-3 OSI
- Minimum R
- ≥ 4.1.0
- Download size
- 249 KB
Cite
Cite this package
Run in R for the authors' preferred citation:
citation("lazysf")This package has no citation file, so citation() returns this entry built from DESCRIPTION.
Cite the R Observatory
For a number measured here: a download total, a coverage figure, an archival date.
From data release v2026-10-24, which the citation names so these numbers can be found later. More on citing and the projects behind them.