Columnar Query Engine for Larger-than-RAM Data
Overview
A minimal columnar query engine with lazy execution on datasets larger than RAM. Provides 'dplyr'-like verbs (filter(), select(), mutate(), group_by(), summarise(), joins, window functions) and common aggregations (n(), sum(), mean(), min(), max(), sd(), first(), last()) backed by a pure C11 pull-based execution engine and a custom on-disk format ('.vtr'). Reads and writes 'GeoTIFF' (including tiled and 'BigTIFF' layouts) and a tiled raster format ('.vec') with overview pyramids and time cubes for larger-than-RAM raster data. Streams vector operations (spatial transforms, point-in-polygon and nearest-feature joins including a two-sided grid-partitioned join, select-by-location, clip, erase, dissolve, 'rasterization', 'polygonization', and contouring) through 'sf', and runs raster operations (zonal statistics, focal windows, terrain derivatives, resample or 'reproject' warp, polygon masking, map algebra, and 'mosaicking') in native C or over the tiled '.vec' format, one batch or tile at a time for data larger than RAM.
New features
tbl_parquet()reads Parquet files natively, with no arrow dependency (#25): data page v1 and v2, the dictionary, RLE/bit-packed, delta and byte-stream-split encodings, and UNCOMPRESSED, SNAPPY, GZIP, ZSTD and LZ4 pages. Logical types map toDate,POSIXct, int64 and double; struct fields are flattened and one-level lists and maps are read as joined text (list_sep). Only the columns a query uses are read, row-group statistics skip groups a filter cannot match, and a vector of files or a directory reads as one table. BROTLI and LZO pages, and lists of lists, raise an error naming the column.tbl_tiff()reads LZW-compressed GeoTIFFs, including thosevec_to_tiff(compression = "lzw")writes, and undoes predictor 2 (horizontal differencing) and predictor 3 (floating point) for LZW and DEFLATE strips and tiles (#21).
Show all changes in 0.13.0Hide the rest of the changes in 0.13.0
- Expressions support
sin(),cos(),tan(),asin(),acos(),atan(),atan2(),sinh(),cosh(),tanh(),asinh(),acosh(),atanh(),expm1(),log1p()and^(#22). A math call with the wrong number of arguments is now an error instead of dropping the extra ones, andsign(),pmin()/pmax()follow base R onNaN. - Every verb that takes expressions captures them through rlang, so
!!,!!!,{{ }},:=,.dataand.envwork as in dplyr (#24).group_by()andcount()accept!!sym(k),.data[[k]],across(all_of(k)),pick()and computed groups (group_by(odd = x %% 2)), and gain.add. spatial_join()gainskeep_geom.keep_geom = FALSEdrops the left geometry, and withcoords =the points are never encoded (#23).
Performance and memory
vectra_mem()is now a bound on what a query allocates (#19, #28). All the buffering steps of a query (sorts, joins, grouped aggregates, fuzzy joins, k-mer counts) reserve the bytes they actually allocate from one shared pool ofvectra_mem()bytes, and spill when it is exhausted; each is guaranteed a quarter of an equal share. Previously each step received the whole budget and counted only part of what it allocated, so a join feeding a grouped aggregate could peak at several times the budget. Temporary spill files are written uncompressed, which is faster at the same peak memory. On 2e7 rows with a 256 MB budget, a join followed by a grouped summary went from 50.1 s and 427 MB above idle to 7.7 s and 168 MB.- Grouped
summarise()aggregates in hash tables instead of always sorting its input (#16). When the groups outgrow their share of the budget, the rest of the input is hash-partitioned to disk and each partition aggregated in turn; results stay sorted by key, andmedian()/n_distinct()keep their spilling path. On 2e7 rows and 1,000 groups this took 0.9 s instead of 1.9 s, with memory falling from 1.16 GB to under 100 MB. arrange()with enough memory emits its result in 131,072-row batches from one permutation instead of as a single batch holding a second copy of the data (#20).arrange()followed bywrite_vtr()on 2e7 rows went from 54.8 s to 3.5 s.- Column pruning passes through
mutate(),select()andrename(), so a scan reads only the columns a query uses (#17). Filters prune row groups by zone map, sorted-column search and index even when written after amutate(),select(),arrange()or another filter, and in every input ofbind_rows()(#18); the plan no longer depends on the order the verbs are written in. spatial_join()'s native path is a lazy streaming node: the result flows into the next verb without a spill and without buffering R data frames (#23). Tagging 1e7 points and counting went from 72.5 s to 6.9 s.compress = "fast", thewrite_vtr()default, runs its LZ stage at the fastest match-search level; streaming a filtered result to.vtris about 2.8x faster for files about 3.6% larger (#26).compress = "small"also tries that setting, so it is still never larger than"fast".
Bug fixes
bind_rows()of stores whose column types differ keeps the widened type after column pruning instead of narrowing a double to an integer.- Filter pushdown no longer stops after the 16th input of
bind_rows(). arrange()documentation now states thatNAsorts last in both directions, which is what it has always done.explain()no longer prints an offload grade of "streaming scan" for plans that contain a sort or a join; the grade is shown only for replay caches and partitions that carry one (#27).
Installation
configurenow tests the candidate OpenMP flags by building, loading and calling a small parallel routine, and keeps the first that works (#15). On macOS it tries-Xclang -fopenmp -lompfirst, so a binary that uses OpenMP records a real dependency on thelibomp.dylibthat CRAN's R ships instead of looking its symbols up at load time; if nothing works the package builds single-threaded and says so. The package now compiles without warnings when OpenMP is unavailable.
Documentation
- The engine, large-data, spatial, formats and indexing vignettes, and the README, describe the current engine: the tdc container format, hash-first aggregation, the shared memory pool, spilling joins, streaming windows and mapped hash indexes (#27).
From NEWS.md in the release
Install
Health
- OK13 OK2026-09-17
- ERROR12 OK, 1 ERROR2026-09-08
- OK13 OK2026-08-04
- NOTE12 OK, 1 NOTE2026-08-01
- OK13 OK2026-07-04
Show 7 earlier changesHide 7 earlier changes
- ERROR12 OK, 1 ERROR2026-07-01
- OK13 OK2026-06-30
- ERROR12 OK, 1 ERROR2026-06-29
- OK12 OK, 1 FAILURE2026-06-08
- ERROR12 OK, 1 ERROR2026-06-07
- OK12 OK2026-05-09
- ERROR5 OK, 2 NOTE, 1 ERROR2026-04-22
Documentation
- Help pages
- 121
- Examples that run
- 84%86 run in a plain check (28 of them under a condition) · 13 only when donttest examples are enabled (R CMD check --as-cran) · 3 never run
- Exported functions with examples
- 86%
- Documented parameters
- 97%
- Return-value docs
- 100%
- Help pages citing references
- 2%
- Coverage and topology HTML
- Format Backends HTML
- Geometry functions in expressions HTML
- Getting Started with vectra HTML
- Indexing and Query Optimization HTML
- Joins HTML
- Network analysis HTML
- Offloading: streaming, monoids, and out-of-core fits HTML
- Out-of-core GIS with vectra HTML
- Species Distribution Models HTML
Show 5 moreHide 5 vignettes
Downloads
Repository
- PRs merged (all time)
- not measured
- Median days to close, 50 most recently updated closed issues
- 0
- Median days to close, 50 most recently updated closed PRs
- not measured
Stars over time
Releases over time
Issues over time
Commits over time
9 development-tooling and community-health practices detected across 6 families in the upstream repository
Checks run against github.com/gcol33/vectra on 2026-10-21.
The R CMD check workflow runs on Linux, macOS and Windows, and on R-devel
GitHub Pages site last deployed 2026-10-19
pkgdown site last built 2026-10-19
Show all practicesHide 2 practices
This repository shows signs of AI coding tools.
- Claude Codefirst seen 2026-03-05Named in .Rbuildignore: .claude, CLAUDE.mdNamed in .gitignore: .claude, CLAUDE.mdCommits: at least 280 crediting it in the message
- Claude Opus 4.8115 commits · Jun to Jul 2026
- Claude Opus 4.642 commits · Mar to Apr 2026
- Claude Opus 4.723 commits · Apr to May 2026
- Claude Sonnet 4.618 commits · Apr to May 2026
- Claude Fable 52 commits · Jun 2026
Some of these counts are a minimum, because the search stopped before the oldest commits.
Dependencies
Installing vectra adds 8 packages (6 with compiled code, 3.8 MB of source tarballs). Heaviest: libgeos 1.0 MB, vctrs 1.0 MB, rlang 766 KB.
Code & Tests
People & History
Pick two releases to compare their code metrics.
- 0.13.0Latest
- 0.12.42026-09-16 · diff ↗
- 0.12.32026-09-14 · diff ↗
- 0.12.02026-09-09 · diff ↗
- 0.11.82026-07-31 · diff ↗
- 0.11.32026-07-17 · diff ↗
- 0.11.12026-07-10 · diff ↗ ·
added 7 exports
feature_knn, kmer, rast_feature_distance, tbl_bed, tbl_fasta, tbl_fastq, vectra_mem - 0.9.82026-06-29 · diff ↗ ·
added 12 exports
as_embedding, cosine, dot, floor_time, interval_join, l2, resample, roll_max, roll_mean, roll_min, roll_n, roll_sum - 0.9.72026-06-29 · diff ↗ ·
added 17 exports
spatial_centerline, spatial_construct, spatial_eliminate, spatial_explode, spatial_knn, spatial_line_merge, spatial_locate, spatial_network, spatial_polygonize, spatial_route, spatial_service_area, spatial_simplify, spatial_smooth, spatial_snap, spatial_snap_grid, spatial_split, spatial_topology - 0.9.12026-06-29 · diff ↗ ·
added 19 exports
collect_sf, contours, focal, grid, mask, mosaic, polygonize, proximity, rast_calc, rasterize, spatial_clip, spatial_dissolve, spatial_filter, spatial_join, spatial_map, spatial_overlay, terrain, warp, zonal - 0.7.12026-06-12 · diff ↗ ·
added 5 exports
chunk_feeder, collect_chunked, group_map, group_modify, offload - unarchivedReturned to CRAN2026-05-08
- 0.6.22026-05-08 · diff ↗ ·
added 14 exports
tiff_band_names, tiff_crs, vec_build_overviews, vec_close_raster, vec_extract_points, vec_open_raster, vec_raster_layout, vec_raster_times, vec_read_pixel_series, vec_read_time_slice, vec_read_window, vec_to_tiff, vec_write_raster, vec_write_time_cube - archivedRemoved from CRAN2026-05-06issues were not corrected in time
- RR 4.6.0 released · 2026-04-24
- 0.5.12026-04-21
Show 1 earlier eventHide 1 earlier event
- RR 4.5.0 released · 2025-04-11
Package metadata
- First published
- 2026-04-21
- Total releases
- 13 / 1 yrs
- License
- MIT + file LICENSE OSI
- Minimum R
- ≥ 4.1.0
- Download size
- 2.3 MB
Cite
Cite this package
Run in R for the authors' preferred citation:
citation("vectra")This package has no citation file, so citation() returns this entry built from DESCRIPTION.
The repository also keeps a CITATION.cff.
Cite the R Observatory
For a number measured here: a download total, a coverage figure, an archival date.
From data release v2026-10-25, which the citation names so these numbers can be found later. More on citing and the projects behind them.