Introduction to Cache

Sharing a ledger of spatial results through Google Drive

Cache stores results by the call that made them. When the result belongs to a place, e.g. a model fitted for one polygon, a ledger is more useful: one .rds file of rows (a polygon plus any columns, including fitted models), from which CacheGeoRead() returns the rows that overlap an area, and CacheGeo() computes only for an area the ledger does not yet cover. See ?CacheGeoLedger.

To share a ledger, create a Google Drive folder, share it “Anyone with the link” as a viewer, and give everyone the folder’s URL as remote. Reading needs no Google login; the file is downloaded only when its md5 differs from the local copy’s. Only the people who write need a login (googledrive::drive_auth()). Two writers at the same time do not lose each other’s rows: CacheGeoWrite() reads the file on Drive again just before writing, and merges again if it changed.

led <- CacheGeoLedger("fitsByPolygon.rds",
                      remote = "https://drive.google.com/drive/folders/<folder id>",
                      destinationPath = "inputs", key = "polygonID")

# anyone: the rows that overlap the study area (an sf object; 0 rows if none)
rows <- CacheGeoRead(led, area = studyArea)

# a writer: replaces the row with the same polygonID, uploads only if the file changed
CacheGeoWrite(led, newRow)

# read, and fit only what is missing
rows <- CacheGeo(led, area = studyArea, compute = function(area) fitThisPolygon(area))

Reproducible workflow

As part of a reproducible workflow, caching of function calls, code chunks, and other elements of a project is a critical component. The objective of a reproducible workflow is is likely that an entire work flow from raw data to publication, decision support, report writing, presentation building etc., could be built and be reproducible anywhere, on any computer, operating system, with any starting conditions, on demand. The reproducible::Cache function is built to work with any R function.

Differences with other approaches

Cache users DBI as a backend, with key functions, dbReadTable, dbRemoveTable, dbSendQuery, dbSendStatement, dbCreateTable and dbAppendTable. These can all be accessed via Cache, showCache, clearCache, and keepCache. It is optimized for speed of transactions, using digest::digest on objects and files. The main function is superficially similar to archivist::cache, which uses digest::digest in all cases to determine whether the arguments are identical in subsequent iterations. It also but does many things that make standard caching with digest::digest don’t work reliably between systems. For these, the function .robustDigest is introduced to make caching transferable between systems. This is relevant for file paths, environments, parallel clusters, functions (which are contained within an environment), and many others (e.g., see ?.robustDigest for methods). Cache also adds important elements like automated tagging and the option to retrieve disk-cached values via stashed objects in memory using memoise::memoise. This means that running Cache 1, 2, and 3 times on the same function will get progressively faster. This can be extremely useful for web apps built with, say shiny.

Function-level caching

Any function can be cached by wrapping Cache around the function call, or by using base pipe |>:

This will be a slight change to a function call, such as: terra::project(raster, crs = terra::crs(newRaster)) to Cache(terra::project(raster, crs = terra::crs(newRaster))) or with the pipe, which may be more convenient as it is easy to add and remove caching in the code base: terra::project(raster, crs = terra::crs(newRaster)) |> Cache()

This is particularly useful for expensive operations.

library(reproducible)
library(data.table)
## 
## Attaching package: 'data.table'
## The following object is masked from 'package:terra':
## 
##     shift
## The following object is masked from 'package:base':
## 
##     %notin%
tmpDir <- file.path(tempfile(), "reproducible_examples", "Cache")
dir.create(tmpDir, recursive = TRUE)

# Source raster with a complete LCC definition
ras <- terra::rast(terra::ext(0, 300, 0, 300), vals = 1:9e4, res = 1)
terra::crs(ras) <- "+proj=lcc +lat_1=60 +lat_2=70 +lat_0=50 +lon_0=-100 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs"

# Target CRS in PROJ form (no EPSG lookup)
newCRS <- "+proj=longlat +datum=WGS84 +no_defs"

# Derive target extent from source extent (no registry lookup)
target_ext <- terra::project(terra::ext(ras), from = terra::crs(ras), to = newCRS)

# Build template with chosen resolution; assign CRS
tmplate <- terra::rast(target_ext, resolution = 0.00001)
terra::crs(tmplate) <- newCRS

# No Cache
system.time(map1 <- terra::project(ras, tmplate, method = "near"))
##    user  system elapsed 
##    0.02    0.00    0.02
# Try with memoise for this example -- for many simple cases, memoising will not be faster
opts <- options("reproducible.useMemoise" = TRUE)
# With Cache -- a little slower the first time because saving to disk
system.time({
  suppressWarnings({
    map1 <- terra::project(ras, tmplate, method = "near") |> 
      Cache(cachePath = tmpDir)
  })
})
##    user  system elapsed 
##   0.126   0.004   0.130
# faster the second time; improvement depends on size of object and time to run function
system.time({
  map2 <- terra::project(ras, tmplate, method = "near") |> 
    Cache(cachePath = tmpDir)
})
##    user  system elapsed 
##   0.037   0.001   0.039
options(opts)

all.equal(map1, map2, check.attributes = FALSE) # TRUE
## [1] "Attributes: < Component \".Cache\": Component \"newCache\": 1 element mismatch >"                
## [2] "Attributes: < Component \"pntr\": Component \"origin\": Mean relative difference: 0.0003503788 >"

Caching examples

Basic use

try(clearCache(tmpDir, ask = FALSE), silent = TRUE) # just to make sure it is clear

ranNumsA <- rnorm(10, 16) |> Cache(cachePath = tmpDir)

# All same
ranNumsB <- rnorm(10, 16) |> Cache(cachePath = tmpDir) # recovers cached copy
ranNumsD1 <- Cache(quote(rnorm(n = 10, 16))) |> Cache(cachePath = tmpDir) # recovers cached copy
ranNumsD2 <- Cache(rnorm(n = 10, 16)) |> Cache(cachePath = tmpDir) # recovers cached copy
# pipe
ranNumsD3 <- rnorm(n = 10, 16) |> Cache(cachePath = tmpDir) # recovers cached copy

# Any minor change makes it different
ranNumsE <- rnorm(10, 6) |> Cache(cachePath = tmpDir) # different

Example 1: Basic cache use with tags

ranNumsA <- rnorm(4) |> Cache(cachePath = tmpDir, userTags = "objectName:a")
ranNumsB <- runif(4) |> Cache(cachePath = tmpDir, userTags = "objectName:b")

showCache(tmpDir, userTags = c("objectName"))
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##  1: adf21923cd1e50d0            function                     rnorm
##  2: adf21923cd1e50d0          objectName                         a
##  3: adf21923cd1e50d0            accessed 2026-11-19 15:11:21.19461
##  4: adf21923cd1e50d0             inCloud                     FALSE
##  5: adf21923cd1e50d0   elapsedTimeDigest          0.001222849 secs
##  6: adf21923cd1e50d0           preDigest     .FUN:4f604aa46882b368
##  7: adf21923cd1e50d0           preDigest     mean:c40c00762a0dac94
##  8: adf21923cd1e50d0           preDigest        n:7eef4eae85fd9229
##  9: adf21923cd1e50d0           preDigest       sd:853b1797f54b229c
## 10: adf21923cd1e50d0               class                   numeric
## 11: adf21923cd1e50d0         object.size                        80
## 12: adf21923cd1e50d0            fromDisk                     FALSE
## 13: adf21923cd1e50d0          resultHash                          
## 14: adf21923cd1e50d0 elapsedTimeFirstRun          0.003204823 secs
## 15: e23cab430872a0ea            function                     runif
## 16: e23cab430872a0ea          objectName                         b
## 17: e23cab430872a0ea            accessed 2026-11-19 15:11:21.19857
## 18: e23cab430872a0ea             inCloud                     FALSE
## 19: e23cab430872a0ea   elapsedTimeDigest          0.001057386 secs
## 20: e23cab430872a0ea           preDigest     .FUN:881ec847b7161f3c
## 21: e23cab430872a0ea           preDigest      max:853b1797f54b229c
## 22: e23cab430872a0ea           preDigest      min:c40c00762a0dac94
## 23: e23cab430872a0ea           preDigest        n:7eef4eae85fd9229
## 24: e23cab430872a0ea               class                   numeric
## 25: e23cab430872a0ea         object.size                        80
## 26: e23cab430872a0ea            fromDisk                     FALSE
## 27: e23cab430872a0ea          resultHash                          
## 28: e23cab430872a0ea elapsedTimeFirstRun         0.0005612373 secs
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##                    createdDate
##                         <char>
##  1: 2026-11-19 15:11:21.196071
##  2: 2026-11-19 15:11:21.196071
##  3: 2026-11-19 15:11:21.196071
##  4: 2026-11-19 15:11:21.196071
##  5: 2026-11-19 15:11:21.196071
##  6: 2026-11-19 15:11:21.196071
##  7: 2026-11-19 15:11:21.196071
##  8: 2026-11-19 15:11:21.196071
##  9: 2026-11-19 15:11:21.196071
## 10: 2026-11-19 15:11:21.196071
## 11: 2026-11-19 15:11:21.196071
## 12: 2026-11-19 15:11:21.196071
## 13: 2026-11-19 15:11:21.196071
## 14: 2026-11-19 15:11:21.196071
## 15: 2026-11-19 15:11:21.199744
## 16: 2026-11-19 15:11:21.199744
## 17: 2026-11-19 15:11:21.199744
## 18: 2026-11-19 15:11:21.199744
## 19: 2026-11-19 15:11:21.199744
## 20: 2026-11-19 15:11:21.199744
## 21: 2026-11-19 15:11:21.199744
## 22: 2026-11-19 15:11:21.199744
## 23: 2026-11-19 15:11:21.199744
## 24: 2026-11-19 15:11:21.199744
## 25: 2026-11-19 15:11:21.199744
## 26: 2026-11-19 15:11:21.199744
## 27: 2026-11-19 15:11:21.199744
## 28: 2026-11-19 15:11:21.199744
##                    createdDate
##                         <char>
showCache(tmpDir, userTags = c("^a$")) # regular expression ... "a" exactly
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##  1: adf21923cd1e50d0            function                     rnorm
##  2: adf21923cd1e50d0          objectName                         a
##  3: adf21923cd1e50d0            accessed 2026-11-19 15:11:21.19461
##  4: adf21923cd1e50d0             inCloud                     FALSE
##  5: adf21923cd1e50d0   elapsedTimeDigest          0.001222849 secs
##  6: adf21923cd1e50d0           preDigest     .FUN:4f604aa46882b368
##  7: adf21923cd1e50d0           preDigest     mean:c40c00762a0dac94
##  8: adf21923cd1e50d0           preDigest        n:7eef4eae85fd9229
##  9: adf21923cd1e50d0           preDigest       sd:853b1797f54b229c
## 10: adf21923cd1e50d0               class                   numeric
## 11: adf21923cd1e50d0         object.size                        80
## 12: adf21923cd1e50d0            fromDisk                     FALSE
## 13: adf21923cd1e50d0          resultHash                          
## 14: adf21923cd1e50d0 elapsedTimeFirstRun          0.003204823 secs
##                    createdDate
##                         <char>
##  1: 2026-11-19 15:11:21.196071
##  2: 2026-11-19 15:11:21.196071
##  3: 2026-11-19 15:11:21.196071
##  4: 2026-11-19 15:11:21.196071
##  5: 2026-11-19 15:11:21.196071
##  6: 2026-11-19 15:11:21.196071
##  7: 2026-11-19 15:11:21.196071
##  8: 2026-11-19 15:11:21.196071
##  9: 2026-11-19 15:11:21.196071
## 10: 2026-11-19 15:11:21.196071
## 11: 2026-11-19 15:11:21.196071
## 12: 2026-11-19 15:11:21.196071
## 13: 2026-11-19 15:11:21.196071
## 14: 2026-11-19 15:11:21.196071
showCache(tmpDir, userTags = c("runif")) # show only cached objects made during runif call
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##  1: e23cab430872a0ea            function                     runif
##  2: e23cab430872a0ea          objectName                         b
##  3: e23cab430872a0ea            accessed 2026-11-19 15:11:21.19857
##  4: e23cab430872a0ea             inCloud                     FALSE
##  5: e23cab430872a0ea   elapsedTimeDigest          0.001057386 secs
##  6: e23cab430872a0ea           preDigest     .FUN:881ec847b7161f3c
##  7: e23cab430872a0ea           preDigest      max:853b1797f54b229c
##  8: e23cab430872a0ea           preDigest      min:c40c00762a0dac94
##  9: e23cab430872a0ea           preDigest        n:7eef4eae85fd9229
## 10: e23cab430872a0ea               class                   numeric
## 11: e23cab430872a0ea         object.size                        80
## 12: e23cab430872a0ea            fromDisk                     FALSE
## 13: e23cab430872a0ea          resultHash                          
## 14: e23cab430872a0ea elapsedTimeFirstRun         0.0005612373 secs
##                    createdDate
##                         <char>
##  1: 2026-11-19 15:11:21.199744
##  2: 2026-11-19 15:11:21.199744
##  3: 2026-11-19 15:11:21.199744
##  4: 2026-11-19 15:11:21.199744
##  5: 2026-11-19 15:11:21.199744
##  6: 2026-11-19 15:11:21.199744
##  7: 2026-11-19 15:11:21.199744
##  8: 2026-11-19 15:11:21.199744
##  9: 2026-11-19 15:11:21.199744
## 10: 2026-11-19 15:11:21.199744
## 11: 2026-11-19 15:11:21.199744
## 12: 2026-11-19 15:11:21.199744
## 13: 2026-11-19 15:11:21.199744
## 14: 2026-11-19 15:11:21.199744
clearCache(tmpDir, userTags = c("runif"), ask = FALSE) # remove only cached objects made during runif call
showCache(tmpDir) # all
##              cacheId              tagKey                         tagValue
##               <char>              <char>                           <char>
##  1: 326167f55d2cf387            function                            Cache
##  2: 326167f55d2cf387            accessed        2026-11-19 15:11:21.16552
##  3: 326167f55d2cf387             inCloud                            FALSE
##  4: 326167f55d2cf387   elapsedTimeDigest                 0.001749992 secs
##  5: 326167f55d2cf387           preDigest  .cacheChaining:71681d621365dfd7
##  6: 326167f55d2cf387           preDigest     .cacheExtra:c85d88fc56f4e042
##  7: 326167f55d2cf387           preDigest            .FUN:3237d68f548b9590
##  8: 326167f55d2cf387           preDigest   .functionName:c85d88fc56f4e042
##  9: 326167f55d2cf387           preDigest            conn:118387d5d48f757d
## 10: 326167f55d2cf387           preDigest             drv:9ce9a83896bf68a1
## 11: 326167f55d2cf387           preDigest cacheSaveFormat:cf2828ea967d53e7
## 12: 326167f55d2cf387           preDigest          dryRun:e9aac936a0e8f6ae
## 13: 326167f55d2cf387           preDigest             FUN:3008d5893647c43d
## 14: 326167f55d2cf387               class                          numeric
## 15: 326167f55d2cf387         object.size                              176
## 16: 326167f55d2cf387            fromDisk                            FALSE
## 17: 326167f55d2cf387          resultHash                                 
## 18: 326167f55d2cf387 elapsedTimeFirstRun                 0.003888845 secs
## 19: aa549dd751b2f26d            function                            rnorm
## 20: aa549dd751b2f26d            accessed        2026-11-19 15:11:21.14829
## 21: aa549dd751b2f26d             inCloud                            FALSE
## 22: aa549dd751b2f26d   elapsedTimeDigest                 0.001266479 secs
## 23: aa549dd751b2f26d           preDigest            .FUN:4f604aa46882b368
## 24: aa549dd751b2f26d           preDigest            mean:15620f138033a66c
## 25: aa549dd751b2f26d           preDigest               n:c5775c3b366fb719
## 26: aa549dd751b2f26d           preDigest              sd:853b1797f54b229c
## 27: aa549dd751b2f26d               class                          numeric
## 28: aa549dd751b2f26d         object.size                              176
## 29: aa549dd751b2f26d            fromDisk                            FALSE
## 30: aa549dd751b2f26d          resultHash                                 
## 31: aa549dd751b2f26d elapsedTimeFirstRun                0.0008137226 secs
## 32: aa549dd751b2f26d            accessed        2026-11-19 15:11:21.15309
## 33: aa549dd751b2f26d            accessed        2026-11-19 15:11:21.17299
## 34: adf21923cd1e50d0            function                            rnorm
## 35: adf21923cd1e50d0          objectName                                a
## 36: adf21923cd1e50d0            accessed        2026-11-19 15:11:21.19461
## 37: adf21923cd1e50d0             inCloud                            FALSE
## 38: adf21923cd1e50d0   elapsedTimeDigest                 0.001222849 secs
## 39: adf21923cd1e50d0           preDigest            .FUN:4f604aa46882b368
## 40: adf21923cd1e50d0           preDigest            mean:c40c00762a0dac94
## 41: adf21923cd1e50d0           preDigest               n:7eef4eae85fd9229
## 42: adf21923cd1e50d0           preDigest              sd:853b1797f54b229c
## 43: adf21923cd1e50d0               class                          numeric
## 44: adf21923cd1e50d0         object.size                               80
## 45: adf21923cd1e50d0            fromDisk                            FALSE
## 46: adf21923cd1e50d0          resultHash                                 
## 47: adf21923cd1e50d0 elapsedTimeFirstRun                 0.003204823 secs
## 48: d78b46a2a76d6d80            function                            rnorm
## 49: d78b46a2a76d6d80            accessed        2026-11-19 15:11:21.17611
## 50: d78b46a2a76d6d80             inCloud                            FALSE
## 51: d78b46a2a76d6d80   elapsedTimeDigest                 0.001116037 secs
## 52: d78b46a2a76d6d80           preDigest            .FUN:4f604aa46882b368
## 53: d78b46a2a76d6d80           preDigest            mean:152602b8ff81e5bb
## 54: d78b46a2a76d6d80           preDigest               n:c5775c3b366fb719
## 55: d78b46a2a76d6d80           preDigest              sd:853b1797f54b229c
## 56: d78b46a2a76d6d80               class                          numeric
## 57: d78b46a2a76d6d80         object.size                              176
## 58: d78b46a2a76d6d80            fromDisk                            FALSE
## 59: d78b46a2a76d6d80          resultHash                                 
## 60: d78b46a2a76d6d80 elapsedTimeFirstRun                0.0005500317 secs
## 61: f2b3ace079a78c3d            function                            Cache
## 62: f2b3ace079a78c3d            accessed        2026-11-19 15:11:21.15692
## 63: f2b3ace079a78c3d             inCloud                            FALSE
## 64: f2b3ace079a78c3d   elapsedTimeDigest                 0.001952648 secs
## 65: f2b3ace079a78c3d           preDigest  .cacheChaining:71681d621365dfd7
## 66: f2b3ace079a78c3d           preDigest     .cacheExtra:c85d88fc56f4e042
## 67: f2b3ace079a78c3d           preDigest            .FUN:3237d68f548b9590
## 68: f2b3ace079a78c3d           preDigest   .functionName:c85d88fc56f4e042
## 69: f2b3ace079a78c3d           preDigest            conn:118387d5d48f757d
## 70: f2b3ace079a78c3d           preDigest             drv:9ce9a83896bf68a1
## 71: f2b3ace079a78c3d           preDigest cacheSaveFormat:cf2828ea967d53e7
## 72: f2b3ace079a78c3d           preDigest          dryRun:e9aac936a0e8f6ae
## 73: f2b3ace079a78c3d           preDigest             FUN:265d86c3bd130de5
## 74: f2b3ace079a78c3d               class                             call
## 75: f2b3ace079a78c3d         object.size                             1320
## 76: f2b3ace079a78c3d            fromDisk                            FALSE
## 77: f2b3ace079a78c3d          resultHash                                 
## 78: f2b3ace079a78c3d elapsedTimeFirstRun                 0.004739285 secs
##              cacheId              tagKey                         tagValue
##               <char>              <char>                           <char>
##                    createdDate
##                         <char>
##  1: 2026-11-19 15:11:21.170178
##  2: 2026-11-19 15:11:21.170178
##  3: 2026-11-19 15:11:21.170178
##  4: 2026-11-19 15:11:21.170178
##  5: 2026-11-19 15:11:21.170178
##  6: 2026-11-19 15:11:21.170178
##  7: 2026-11-19 15:11:21.170178
##  8: 2026-11-19 15:11:21.170178
##  9: 2026-11-19 15:11:21.170178
## 10: 2026-11-19 15:11:21.170178
## 11: 2026-11-19 15:11:21.170178
## 12: 2026-11-19 15:11:21.170178
## 13: 2026-11-19 15:11:21.170178
## 14: 2026-11-19 15:11:21.170178
## 15: 2026-11-19 15:11:21.170178
## 16: 2026-11-19 15:11:21.170178
## 17: 2026-11-19 15:11:21.170178
## 18: 2026-11-19 15:11:21.170178
## 19: 2026-11-19 15:11:21.150049
## 20: 2026-11-19 15:11:21.150049
## 21: 2026-11-19 15:11:21.150049
## 22: 2026-11-19 15:11:21.150049
## 23: 2026-11-19 15:11:21.150049
## 24: 2026-11-19 15:11:21.150049
## 25: 2026-11-19 15:11:21.150049
## 26: 2026-11-19 15:11:21.150049
## 27: 2026-11-19 15:11:21.150049
## 28: 2026-11-19 15:11:21.150049
## 29: 2026-11-19 15:11:21.150049
## 30: 2026-11-19 15:11:21.150049
## 31: 2026-11-19 15:11:21.150049
## 32: 2026-11-19 15:11:21.153155
## 33: 2026-11-19 15:11:21.173052
## 34: 2026-11-19 15:11:21.196071
## 35: 2026-11-19 15:11:21.196071
## 36: 2026-11-19 15:11:21.196071
## 37: 2026-11-19 15:11:21.196071
## 38: 2026-11-19 15:11:21.196071
## 39: 2026-11-19 15:11:21.196071
## 40: 2026-11-19 15:11:21.196071
## 41: 2026-11-19 15:11:21.196071
## 42: 2026-11-19 15:11:21.196071
## 43: 2026-11-19 15:11:21.196071
## 44: 2026-11-19 15:11:21.196071
## 45: 2026-11-19 15:11:21.196071
## 46: 2026-11-19 15:11:21.196071
## 47: 2026-11-19 15:11:21.196071
## 48: 2026-11-19 15:11:21.177359
## 49: 2026-11-19 15:11:21.177359
## 50: 2026-11-19 15:11:21.177359
## 51: 2026-11-19 15:11:21.177359
## 52: 2026-11-19 15:11:21.177359
## 53: 2026-11-19 15:11:21.177359
## 54: 2026-11-19 15:11:21.177359
## 55: 2026-11-19 15:11:21.177359
## 56: 2026-11-19 15:11:21.177359
## 57: 2026-11-19 15:11:21.177359
## 58: 2026-11-19 15:11:21.177359
## 59: 2026-11-19 15:11:21.177359
## 60: 2026-11-19 15:11:21.177359
## 61: 2026-11-19 15:11:21.162389
## 62: 2026-11-19 15:11:21.162389
## 63: 2026-11-19 15:11:21.162389
## 64: 2026-11-19 15:11:21.162389
## 65: 2026-11-19 15:11:21.162389
## 66: 2026-11-19 15:11:21.162389
## 67: 2026-11-19 15:11:21.162389
## 68: 2026-11-19 15:11:21.162389
## 69: 2026-11-19 15:11:21.162389
## 70: 2026-11-19 15:11:21.162389
## 71: 2026-11-19 15:11:21.162389
## 72: 2026-11-19 15:11:21.162389
## 73: 2026-11-19 15:11:21.162389
## 74: 2026-11-19 15:11:21.162389
## 75: 2026-11-19 15:11:21.162389
## 76: 2026-11-19 15:11:21.162389
## 77: 2026-11-19 15:11:21.162389
## 78: 2026-11-19 15:11:21.162389
##                    createdDate
##                         <char>
clearCache(tmpDir, ask = FALSE)

Example 2: using the “accessed” tag

ranNumsA <- rnorm(4) |> Cache(cachePath = tmpDir, userTags = "objectName:a")
ranNumsB <- runif(4) |> Cache(cachePath = tmpDir, userTags = "objectName:b")

# access it again, from Cache
Sys.sleep(1)
ranNumsA <- rnorm(4) |> Cache(cachePath = tmpDir, userTags = "objectName:a")
wholeCache <- showCache(tmpDir)

# keep only items accessed "recently" (i.e., only objectName:a)
onlyRecentlyAccessed <- showCache(tmpDir, userTags = max(wholeCache[tagKey == "accessed"]$tagValue))

# inverse join with 2 data.tables ... using: a[!b]
# i.e., return all of wholeCache that was not recently accessed
#   Note: the two different ways to access -- old way with "artifact" will be deprecated
toRemove <- unique(wholeCache[!onlyRecentlyAccessed, on = "cacheId"], by = "cacheId")$cacheId
clearCache(tmpDir, toRemove, ask = FALSE) # remove ones not recently accessed
showCache(tmpDir) # still has more recently accessed
## Empty data.table (0 rows and 4 cols): cacheId,tagKey,tagValue,createdDate

Example 3: using keepCache

keepCache does the same as previous example, but more simply.

ranNumsA <- rnorm(4) |> Cache(cachePath = tmpDir, userTags = "objectName:a")
ranNumsB <- Cache(runif(4)) |> Cache(cachePath = tmpDir, userTags = "objectName:b")

# keep only those cached items from the last 24 hours
oneDay <- 60 * 60 * 24
keepCache(tmpDir, after = Sys.time() - oneDay, ask = FALSE)
##              cacheId              tagKey                         tagValue
##               <char>              <char>                           <char>
##  1: 367694727f42a411            function                            Cache
##  2: 367694727f42a411          objectName                                b
##  3: 367694727f42a411            accessed        2026-11-19 15:11:22.31685
##  4: 367694727f42a411             inCloud                            FALSE
##  5: 367694727f42a411   elapsedTimeDigest                 0.001734972 secs
##  6: 367694727f42a411           preDigest  .cacheChaining:71681d621365dfd7
##  7: 367694727f42a411           preDigest     .cacheExtra:c85d88fc56f4e042
##  8: 367694727f42a411           preDigest            .FUN:3237d68f548b9590
##  9: 367694727f42a411           preDigest   .functionName:c85d88fc56f4e042
## 10: 367694727f42a411           preDigest            conn:118387d5d48f757d
## 11: 367694727f42a411           preDigest             drv:9ce9a83896bf68a1
## 12: 367694727f42a411           preDigest cacheSaveFormat:cf2828ea967d53e7
## 13: 367694727f42a411           preDigest          dryRun:e9aac936a0e8f6ae
## 14: 367694727f42a411           preDigest             FUN:1af8f89bc2115981
## 15: 367694727f42a411               class                          numeric
## 16: 367694727f42a411         object.size                             1008
## 17: 367694727f42a411            fromDisk                            FALSE
## 18: 367694727f42a411          resultHash                                 
## 19: 367694727f42a411 elapsedTimeFirstRun                   0.0044384 secs
## 20: adf21923cd1e50d0            function                            rnorm
## 21: adf21923cd1e50d0          objectName                                a
## 22: adf21923cd1e50d0            accessed        2026-11-19 15:11:22.31200
## 23: adf21923cd1e50d0             inCloud                            FALSE
## 24: adf21923cd1e50d0   elapsedTimeDigest                 0.001312494 secs
## 25: adf21923cd1e50d0           preDigest            .FUN:4f604aa46882b368
## 26: adf21923cd1e50d0           preDigest            mean:c40c00762a0dac94
## 27: adf21923cd1e50d0           preDigest               n:7eef4eae85fd9229
## 28: adf21923cd1e50d0           preDigest              sd:853b1797f54b229c
## 29: adf21923cd1e50d0               class                          numeric
## 30: adf21923cd1e50d0         object.size                               80
## 31: adf21923cd1e50d0            fromDisk                            FALSE
## 32: adf21923cd1e50d0          resultHash                                 
## 33: adf21923cd1e50d0 elapsedTimeFirstRun                0.0007474422 secs
##              cacheId              tagKey                         tagValue
##               <char>              <char>                           <char>
##                   createdDate
##                        <char>
##  1: 2026-11-19 15:11:22.32199
##  2: 2026-11-19 15:11:22.32199
##  3: 2026-11-19 15:11:22.32199
##  4: 2026-11-19 15:11:22.32199
##  5: 2026-11-19 15:11:22.32199
##  6: 2026-11-19 15:11:22.32199
##  7: 2026-11-19 15:11:22.32199
##  8: 2026-11-19 15:11:22.32199
##  9: 2026-11-19 15:11:22.32199
## 10: 2026-11-19 15:11:22.32199
## 11: 2026-11-19 15:11:22.32199
## 12: 2026-11-19 15:11:22.32199
## 13: 2026-11-19 15:11:22.32199
## 14: 2026-11-19 15:11:22.32199
## 15: 2026-11-19 15:11:22.32199
## 16: 2026-11-19 15:11:22.32199
## 17: 2026-11-19 15:11:22.32199
## 18: 2026-11-19 15:11:22.32199
## 19: 2026-11-19 15:11:22.32199
## 20: 2026-11-19 15:11:22.31355
## 21: 2026-11-19 15:11:22.31355
## 22: 2026-11-19 15:11:22.31355
## 23: 2026-11-19 15:11:22.31355
## 24: 2026-11-19 15:11:22.31355
## 25: 2026-11-19 15:11:22.31355
## 26: 2026-11-19 15:11:22.31355
## 27: 2026-11-19 15:11:22.31355
## 28: 2026-11-19 15:11:22.31355
## 29: 2026-11-19 15:11:22.31355
## 30: 2026-11-19 15:11:22.31355
## 31: 2026-11-19 15:11:22.31355
## 32: 2026-11-19 15:11:22.31355
## 33: 2026-11-19 15:11:22.31355
##                   createdDate
##                        <char>
# Keep all Cache items created with an rnorm() call
keepCache(tmpDir, userTags = "rnorm", ask = FALSE)
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##  1: adf21923cd1e50d0            function                     rnorm
##  2: adf21923cd1e50d0          objectName                         a
##  3: adf21923cd1e50d0            accessed 2026-11-19 15:11:22.31200
##  4: adf21923cd1e50d0             inCloud                     FALSE
##  5: adf21923cd1e50d0   elapsedTimeDigest          0.001312494 secs
##  6: adf21923cd1e50d0           preDigest     .FUN:4f604aa46882b368
##  7: adf21923cd1e50d0           preDigest     mean:c40c00762a0dac94
##  8: adf21923cd1e50d0           preDigest        n:7eef4eae85fd9229
##  9: adf21923cd1e50d0           preDigest       sd:853b1797f54b229c
## 10: adf21923cd1e50d0               class                   numeric
## 11: adf21923cd1e50d0         object.size                        80
## 12: adf21923cd1e50d0            fromDisk                     FALSE
## 13: adf21923cd1e50d0          resultHash                          
## 14: adf21923cd1e50d0 elapsedTimeFirstRun         0.0007474422 secs
##                   createdDate
##                        <char>
##  1: 2026-11-19 15:11:22.31355
##  2: 2026-11-19 15:11:22.31355
##  3: 2026-11-19 15:11:22.31355
##  4: 2026-11-19 15:11:22.31355
##  5: 2026-11-19 15:11:22.31355
##  6: 2026-11-19 15:11:22.31355
##  7: 2026-11-19 15:11:22.31355
##  8: 2026-11-19 15:11:22.31355
##  9: 2026-11-19 15:11:22.31355
## 10: 2026-11-19 15:11:22.31355
## 11: 2026-11-19 15:11:22.31355
## 12: 2026-11-19 15:11:22.31355
## 13: 2026-11-19 15:11:22.31355
## 14: 2026-11-19 15:11:22.31355
showCache(tmpDir)
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##  1: adf21923cd1e50d0            function                     rnorm
##  2: adf21923cd1e50d0          objectName                         a
##  3: adf21923cd1e50d0            accessed 2026-11-19 15:11:22.31200
##  4: adf21923cd1e50d0             inCloud                     FALSE
##  5: adf21923cd1e50d0   elapsedTimeDigest          0.001312494 secs
##  6: adf21923cd1e50d0           preDigest     .FUN:4f604aa46882b368
##  7: adf21923cd1e50d0           preDigest     mean:c40c00762a0dac94
##  8: adf21923cd1e50d0           preDigest        n:7eef4eae85fd9229
##  9: adf21923cd1e50d0           preDigest       sd:853b1797f54b229c
## 10: adf21923cd1e50d0               class                   numeric
## 11: adf21923cd1e50d0         object.size                        80
## 12: adf21923cd1e50d0            fromDisk                     FALSE
## 13: adf21923cd1e50d0          resultHash                          
## 14: adf21923cd1e50d0 elapsedTimeFirstRun         0.0007474422 secs
##                   createdDate
##                        <char>
##  1: 2026-11-19 15:11:22.31355
##  2: 2026-11-19 15:11:22.31355
##  3: 2026-11-19 15:11:22.31355
##  4: 2026-11-19 15:11:22.31355
##  5: 2026-11-19 15:11:22.31355
##  6: 2026-11-19 15:11:22.31355
##  7: 2026-11-19 15:11:22.31355
##  8: 2026-11-19 15:11:22.31355
##  9: 2026-11-19 15:11:22.31355
## 10: 2026-11-19 15:11:22.31355
## 11: 2026-11-19 15:11:22.31355
## 12: 2026-11-19 15:11:22.31355
## 13: 2026-11-19 15:11:22.31355
## 14: 2026-11-19 15:11:22.31355
# Remove all Cache items that happened within a rnorm() call
clearCache(tmpDir, userTags = "rnorm", ask = FALSE)
showCache(tmpDir) ## empty
## Empty data.table (0 rows and 4 cols): cacheId,tagKey,tagValue,createdDate
# Also, can set a time before caching happens and remove based on this
#  --> a useful, simple way to control Cache
ranNumsA <- rnorm(4) |> Cache(cachePath = tmpDir, userTags = "objectName:a")
startTime <- Sys.time()
Sys.sleep(1)
ranNumsB <- rnorm(5) |> Cache(cachePath = tmpDir, userTags = "objectName:b")
keepCache(tmpDir, after = startTime, ask = FALSE) # keep only those newer than startTime
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##  1: 438a3028a4570cf9            function                     rnorm
##  2: 438a3028a4570cf9          objectName                         b
##  3: 438a3028a4570cf9            accessed 2026-11-19 15:11:23.36267
##  4: 438a3028a4570cf9             inCloud                     FALSE
##  5: 438a3028a4570cf9   elapsedTimeDigest          0.001542568 secs
##  6: 438a3028a4570cf9           preDigest     .FUN:4f604aa46882b368
##  7: 438a3028a4570cf9           preDigest     mean:c40c00762a0dac94
##  8: 438a3028a4570cf9           preDigest        n:a4f076b3db622faf
##  9: 438a3028a4570cf9           preDigest       sd:853b1797f54b229c
## 10: 438a3028a4570cf9               class                   numeric
## 11: 438a3028a4570cf9         object.size                        96
## 12: 438a3028a4570cf9            fromDisk                     FALSE
## 13: 438a3028a4570cf9          resultHash                          
## 14: 438a3028a4570cf9 elapsedTimeFirstRun          0.000877142 secs
##                    createdDate
##                         <char>
##  1: 2026-11-19 15:11:23.364411
##  2: 2026-11-19 15:11:23.364411
##  3: 2026-11-19 15:11:23.364411
##  4: 2026-11-19 15:11:23.364411
##  5: 2026-11-19 15:11:23.364411
##  6: 2026-11-19 15:11:23.364411
##  7: 2026-11-19 15:11:23.364411
##  8: 2026-11-19 15:11:23.364411
##  9: 2026-11-19 15:11:23.364411
## 10: 2026-11-19 15:11:23.364411
## 11: 2026-11-19 15:11:23.364411
## 12: 2026-11-19 15:11:23.364411
## 13: 2026-11-19 15:11:23.364411
## 14: 2026-11-19 15:11:23.364411
clearCache(tmpDir, ask = FALSE)

Example 4: searching for multiple objects in the cache

# default userTags is "and" matching; for "or" matching use |
ranNumsA <- runif(4) |> Cache(cachePath = tmpDir, userTags = "objectName:a")
ranNumsB <- rnorm(4) |> Cache(cachePath = tmpDir, userTags = "objectName:b")

# show all objects (runif and rnorm in this case)
showCache(tmpDir)
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##  1: adf21923cd1e50d0            function                     rnorm
##  2: adf21923cd1e50d0          objectName                         b
##  3: adf21923cd1e50d0            accessed 2026-11-19 15:11:23.42263
##  4: adf21923cd1e50d0             inCloud                     FALSE
##  5: adf21923cd1e50d0   elapsedTimeDigest          0.001081944 secs
##  6: adf21923cd1e50d0           preDigest     .FUN:4f604aa46882b368
##  7: adf21923cd1e50d0           preDigest     mean:c40c00762a0dac94
##  8: adf21923cd1e50d0           preDigest        n:7eef4eae85fd9229
##  9: adf21923cd1e50d0           preDigest       sd:853b1797f54b229c
## 10: adf21923cd1e50d0               class                   numeric
## 11: adf21923cd1e50d0         object.size                        80
## 12: adf21923cd1e50d0            fromDisk                     FALSE
## 13: adf21923cd1e50d0          resultHash                          
## 14: adf21923cd1e50d0 elapsedTimeFirstRun         0.0005595684 secs
## 15: e23cab430872a0ea            function                     runif
## 16: e23cab430872a0ea          objectName                         a
## 17: e23cab430872a0ea            accessed 2026-11-19 15:11:23.41865
## 18: e23cab430872a0ea             inCloud                     FALSE
## 19: e23cab430872a0ea   elapsedTimeDigest          0.001309872 secs
## 20: e23cab430872a0ea           preDigest     .FUN:881ec847b7161f3c
## 21: e23cab430872a0ea           preDigest      max:853b1797f54b229c
## 22: e23cab430872a0ea           preDigest      min:c40c00762a0dac94
## 23: e23cab430872a0ea           preDigest        n:7eef4eae85fd9229
## 24: e23cab430872a0ea               class                   numeric
## 25: e23cab430872a0ea         object.size                        80
## 26: e23cab430872a0ea            fromDisk                     FALSE
## 27: e23cab430872a0ea          resultHash                          
## 28: e23cab430872a0ea elapsedTimeFirstRun         0.0007205009 secs
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##                    createdDate
##                         <char>
##  1: 2026-11-19 15:11:23.423805
##  2: 2026-11-19 15:11:23.423805
##  3: 2026-11-19 15:11:23.423805
##  4: 2026-11-19 15:11:23.423805
##  5: 2026-11-19 15:11:23.423805
##  6: 2026-11-19 15:11:23.423805
##  7: 2026-11-19 15:11:23.423805
##  8: 2026-11-19 15:11:23.423805
##  9: 2026-11-19 15:11:23.423805
## 10: 2026-11-19 15:11:23.423805
## 11: 2026-11-19 15:11:23.423805
## 12: 2026-11-19 15:11:23.423805
## 13: 2026-11-19 15:11:23.423805
## 14: 2026-11-19 15:11:23.423805
## 15: 2026-11-19 15:11:23.420122
## 16: 2026-11-19 15:11:23.420122
## 17: 2026-11-19 15:11:23.420122
## 18: 2026-11-19 15:11:23.420122
## 19: 2026-11-19 15:11:23.420122
## 20: 2026-11-19 15:11:23.420122
## 21: 2026-11-19 15:11:23.420122
## 22: 2026-11-19 15:11:23.420122
## 23: 2026-11-19 15:11:23.420122
## 24: 2026-11-19 15:11:23.420122
## 25: 2026-11-19 15:11:23.420122
## 26: 2026-11-19 15:11:23.420122
## 27: 2026-11-19 15:11:23.420122
## 28: 2026-11-19 15:11:23.420122
##                    createdDate
##                         <char>
# show objects that are both runif and rnorm
# (i.e., none in this case, because objecs are either or, not both)
showCache(tmpDir, userTags = c("runif", "rnorm")) ## empty
## Empty data.table (0 rows and 4 cols): cacheId,tagKey,tagValue,createdDate
# show objects that are either runif or rnorm ("or" search)
showCache(tmpDir, userTags = "runif|rnorm")
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##  1: adf21923cd1e50d0            function                     rnorm
##  2: adf21923cd1e50d0          objectName                         b
##  3: adf21923cd1e50d0            accessed 2026-11-19 15:11:23.42263
##  4: adf21923cd1e50d0             inCloud                     FALSE
##  5: adf21923cd1e50d0   elapsedTimeDigest          0.001081944 secs
##  6: adf21923cd1e50d0           preDigest     .FUN:4f604aa46882b368
##  7: adf21923cd1e50d0           preDigest     mean:c40c00762a0dac94
##  8: adf21923cd1e50d0           preDigest        n:7eef4eae85fd9229
##  9: adf21923cd1e50d0           preDigest       sd:853b1797f54b229c
## 10: adf21923cd1e50d0               class                   numeric
## 11: adf21923cd1e50d0         object.size                        80
## 12: adf21923cd1e50d0            fromDisk                     FALSE
## 13: adf21923cd1e50d0          resultHash                          
## 14: adf21923cd1e50d0 elapsedTimeFirstRun         0.0005595684 secs
## 15: e23cab430872a0ea            function                     runif
## 16: e23cab430872a0ea          objectName                         a
## 17: e23cab430872a0ea            accessed 2026-11-19 15:11:23.41865
## 18: e23cab430872a0ea             inCloud                     FALSE
## 19: e23cab430872a0ea   elapsedTimeDigest          0.001309872 secs
## 20: e23cab430872a0ea           preDigest     .FUN:881ec847b7161f3c
## 21: e23cab430872a0ea           preDigest      max:853b1797f54b229c
## 22: e23cab430872a0ea           preDigest      min:c40c00762a0dac94
## 23: e23cab430872a0ea           preDigest        n:7eef4eae85fd9229
## 24: e23cab430872a0ea               class                   numeric
## 25: e23cab430872a0ea         object.size                        80
## 26: e23cab430872a0ea            fromDisk                     FALSE
## 27: e23cab430872a0ea          resultHash                          
## 28: e23cab430872a0ea elapsedTimeFirstRun         0.0007205009 secs
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##                    createdDate
##                         <char>
##  1: 2026-11-19 15:11:23.423805
##  2: 2026-11-19 15:11:23.423805
##  3: 2026-11-19 15:11:23.423805
##  4: 2026-11-19 15:11:23.423805
##  5: 2026-11-19 15:11:23.423805
##  6: 2026-11-19 15:11:23.423805
##  7: 2026-11-19 15:11:23.423805
##  8: 2026-11-19 15:11:23.423805
##  9: 2026-11-19 15:11:23.423805
## 10: 2026-11-19 15:11:23.423805
## 11: 2026-11-19 15:11:23.423805
## 12: 2026-11-19 15:11:23.423805
## 13: 2026-11-19 15:11:23.423805
## 14: 2026-11-19 15:11:23.423805
## 15: 2026-11-19 15:11:23.420122
## 16: 2026-11-19 15:11:23.420122
## 17: 2026-11-19 15:11:23.420122
## 18: 2026-11-19 15:11:23.420122
## 19: 2026-11-19 15:11:23.420122
## 20: 2026-11-19 15:11:23.420122
## 21: 2026-11-19 15:11:23.420122
## 22: 2026-11-19 15:11:23.420122
## 23: 2026-11-19 15:11:23.420122
## 24: 2026-11-19 15:11:23.420122
## 25: 2026-11-19 15:11:23.420122
## 26: 2026-11-19 15:11:23.420122
## 27: 2026-11-19 15:11:23.420122
## 28: 2026-11-19 15:11:23.420122
##                    createdDate
##                         <char>
# keep only objects that are either runif or rnorm ("or" search)
keepCache(tmpDir, userTags = "runif|rnorm", ask = FALSE)
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##  1: adf21923cd1e50d0            function                     rnorm
##  2: adf21923cd1e50d0          objectName                         b
##  3: adf21923cd1e50d0            accessed 2026-11-19 15:11:23.42263
##  4: adf21923cd1e50d0             inCloud                     FALSE
##  5: adf21923cd1e50d0   elapsedTimeDigest          0.001081944 secs
##  6: adf21923cd1e50d0           preDigest     .FUN:4f604aa46882b368
##  7: adf21923cd1e50d0           preDigest     mean:c40c00762a0dac94
##  8: adf21923cd1e50d0           preDigest        n:7eef4eae85fd9229
##  9: adf21923cd1e50d0           preDigest       sd:853b1797f54b229c
## 10: adf21923cd1e50d0               class                   numeric
## 11: adf21923cd1e50d0         object.size                        80
## 12: adf21923cd1e50d0            fromDisk                     FALSE
## 13: adf21923cd1e50d0          resultHash                          
## 14: adf21923cd1e50d0 elapsedTimeFirstRun         0.0005595684 secs
## 15: e23cab430872a0ea            function                     runif
## 16: e23cab430872a0ea          objectName                         a
## 17: e23cab430872a0ea            accessed 2026-11-19 15:11:23.41865
## 18: e23cab430872a0ea             inCloud                     FALSE
## 19: e23cab430872a0ea   elapsedTimeDigest          0.001309872 secs
## 20: e23cab430872a0ea           preDigest     .FUN:881ec847b7161f3c
## 21: e23cab430872a0ea           preDigest      max:853b1797f54b229c
## 22: e23cab430872a0ea           preDigest      min:c40c00762a0dac94
## 23: e23cab430872a0ea           preDigest        n:7eef4eae85fd9229
## 24: e23cab430872a0ea               class                   numeric
## 25: e23cab430872a0ea         object.size                        80
## 26: e23cab430872a0ea            fromDisk                     FALSE
## 27: e23cab430872a0ea          resultHash                          
## 28: e23cab430872a0ea elapsedTimeFirstRun         0.0007205009 secs
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##                    createdDate
##                         <char>
##  1: 2026-11-19 15:11:23.423805
##  2: 2026-11-19 15:11:23.423805
##  3: 2026-11-19 15:11:23.423805
##  4: 2026-11-19 15:11:23.423805
##  5: 2026-11-19 15:11:23.423805
##  6: 2026-11-19 15:11:23.423805
##  7: 2026-11-19 15:11:23.423805
##  8: 2026-11-19 15:11:23.423805
##  9: 2026-11-19 15:11:23.423805
## 10: 2026-11-19 15:11:23.423805
## 11: 2026-11-19 15:11:23.423805
## 12: 2026-11-19 15:11:23.423805
## 13: 2026-11-19 15:11:23.423805
## 14: 2026-11-19 15:11:23.423805
## 15: 2026-11-19 15:11:23.420122
## 16: 2026-11-19 15:11:23.420122
## 17: 2026-11-19 15:11:23.420122
## 18: 2026-11-19 15:11:23.420122
## 19: 2026-11-19 15:11:23.420122
## 20: 2026-11-19 15:11:23.420122
## 21: 2026-11-19 15:11:23.420122
## 22: 2026-11-19 15:11:23.420122
## 23: 2026-11-19 15:11:23.420122
## 24: 2026-11-19 15:11:23.420122
## 25: 2026-11-19 15:11:23.420122
## 26: 2026-11-19 15:11:23.420122
## 27: 2026-11-19 15:11:23.420122
## 28: 2026-11-19 15:11:23.420122
##                    createdDate
##                         <char>
clearCache(tmpDir, ask = FALSE)

Example 5: using caching to speed up rerunning expensive computations

ras <- terra::rast(terra::ext(0, 5, 0, 5),
  res = 1,
  vals = sample(1:5, replace = TRUE, size = 25),
  crs = "+proj=lcc +lat_1=48 +lat_2=33 +lon_0=-100 +ellps=WGS84"
)

rasCRS <- terra::crs(ras)
# Build an explicit target raster (same CRS, coarser resolution).
# Avoids the `terra::project(x, char_crs, res = N)` shorthand which
# recurses internally and forwards an unrecognized `wopt` set on
# recent terra versions, producing
# `[write] unknown option(s): xscale,yscale`.
rasTarget <- terra::rast(terra::ext(ras), crs = rasCRS, resolution = 5)

# A slow operation, like GIS operation
notCached <- suppressWarnings(
  # project raster generates warnings when run non-interactively
  terra::project(ras, rasTarget)
)

cached <- suppressWarnings(
  # project raster generates warnings when run non-interactively
  # using quote works also
  terra::project(ras, rasTarget) |> Cache(cachePath = tmpDir)
)

# second time is much faster
reRun <- suppressWarnings(
  # project raster generates warnings when run non-interactively
  terra::project(ras, rasTarget) |> Cache(cachePath = tmpDir)
)

# recovered cached version is same as non-cached version
all.equal(notCached, reRun, check.attributes = FALSE) ## TRUE
## [1] "Attributes: < Names: 2 string mismatches >"                                                    
## [2] "Attributes: < Length mismatch: comparison on first 2 components >"                             
## [3] "Attributes: < Component 1: Modes: character, list >"                                           
## [4] "Attributes: < Component 1: names for current but not for target >"                             
## [5] "Attributes: < Component 1: Attributes: < names for target but not for current > >"             
## [6] "Attributes: < Component 1: Attributes: < Length mismatch: comparison on first 0 components > >"
## [7] "Attributes: < Component 1: target is character, current is list >"                             
## [8] "Attributes: < Component 2: 'current' is not an envRefClass >"

Nested Caching

Nested caching, which is when Caching of a function occurs inside an outer function, which is itself cached. This is a critical element to working within a reproducible work flow. It is not enough during development to cache flat code chunks, as there will be many levels of “slow” functions. Ideally, at all points in a development cycle, it should be possible to get to any line of code starting from the very initial steps, running through everything up to that point, in less than a few seconds. If the workflow can be kept very fast like this, then there is a guarantee that it will work at any point.

##########################
## Nested Caching
# Make 2 functions
inner <- function(mean) {
  d <- 1
  rnorm(n = 3, mean = mean)
}
outer <- function(n) {
  inner(0.1) |> Cache(cachePath = tmpdir2)
}

# make 2 different cache paths
tmpdir1 <- file.path(tempfile(), "first")
tmpdir2 <- file.path(tempfile(), "second")

# Run the Cache ... notOlderThan propagates to all 3 Cache calls,
#   but cachePath is tmpdir1 in top level Cache and all nested
#   Cache calls, unless individually overridden ... here inner
#   uses tmpdir2 repository
outer(n = 2) |> Cache(cachePath = tmpdir1)
## [1] -1.5685839  0.2692037 -0.8548171
## attr(,".Cache")
## attr(,".Cache")$newCache
## [1] TRUE
## 
## attr(,"tags")
## [1] "cacheId:61564dd5e84ab6d5"
## attr(,"callInCache")
## [1] ""
showCache(tmpdir1) # 2 function calls
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##  1: 61564dd5e84ab6d5            function                     outer
##  2: 61564dd5e84ab6d5            accessed 2026-11-19 15:11:23.55077
##  3: 61564dd5e84ab6d5             inCloud                     FALSE
##  4: 61564dd5e84ab6d5   elapsedTimeDigest          0.001442671 secs
##  5: 61564dd5e84ab6d5           preDigest     .FUN:fd3ff16451bebbef
##  6: 61564dd5e84ab6d5           preDigest        n:82dc709f2b91918a
##  7: 61564dd5e84ab6d5               class                   numeric
##  8: 61564dd5e84ab6d5         object.size                      1008
##  9: 61564dd5e84ab6d5            fromDisk                     FALSE
## 10: 61564dd5e84ab6d5          resultHash                          
## 11: 61564dd5e84ab6d5 elapsedTimeFirstRun          0.004245281 secs
##                   createdDate
##                        <char>
##  1: 2026-11-19 15:11:23.55571
##  2: 2026-11-19 15:11:23.55571
##  3: 2026-11-19 15:11:23.55571
##  4: 2026-11-19 15:11:23.55571
##  5: 2026-11-19 15:11:23.55571
##  6: 2026-11-19 15:11:23.55571
##  7: 2026-11-19 15:11:23.55571
##  8: 2026-11-19 15:11:23.55571
##  9: 2026-11-19 15:11:23.55571
## 10: 2026-11-19 15:11:23.55571
## 11: 2026-11-19 15:11:23.55571
showCache(tmpdir2) # 1 function call
##              cacheId              tagKey                  tagValue
##               <char>              <char>                    <char>
##  1: a352d42cb0291199            function                     inner
##  2: a352d42cb0291199       outerFunction                     outer
##  3: a352d42cb0291199            accessed 2026-11-19 15:11:23.55286
##  4: a352d42cb0291199             inCloud                     FALSE
##  5: a352d42cb0291199   elapsedTimeDigest          0.001186609 secs
##  6: a352d42cb0291199           preDigest     .FUN:c411a17f70613a02
##  7: a352d42cb0291199           preDigest     mean:22413394efd9f6a3
##  8: a352d42cb0291199               class                   numeric
##  9: a352d42cb0291199         object.size                        80
## 10: a352d42cb0291199            fromDisk                     FALSE
## 11: a352d42cb0291199          resultHash                          
## 12: a352d42cb0291199 elapsedTimeFirstRun         0.0005297661 secs
##                   createdDate
##                        <char>
##  1: 2026-11-19 15:11:23.55414
##  2: 2026-11-19 15:11:23.55414
##  3: 2026-11-19 15:11:23.55414
##  4: 2026-11-19 15:11:23.55414
##  5: 2026-11-19 15:11:23.55414
##  6: 2026-11-19 15:11:23.55414
##  7: 2026-11-19 15:11:23.55414
##  8: 2026-11-19 15:11:23.55414
##  9: 2026-11-19 15:11:23.55414
## 10: 2026-11-19 15:11:23.55414
## 11: 2026-11-19 15:11:23.55414
## 12: 2026-11-19 15:11:23.55414
# userTags get appended
# all items have the outer tag propagate, plus inner ones only have inner ones
clearCache(tmpdir1, ask = FALSE)
outerTag <- "outerTag"
innerTag <- "innerTag"
inner <- function(mean) {
  d <- 1
  rnorm(n = 3, mean = mean) |> Cache(notOlderThan = Sys.time() - 1e5, userTags = innerTag)
}
outer <- function(n) {
  inner(0.1) |> Cache()
}
aa <- Cache(outer, n = 2) |> Cache(cachePath = tmpdir1, userTags = outerTag)
showCache(tmpdir1) # rnorm function has outerTag and innerTag, inner and outer only have outerTag
##              cacheId              tagKey                         tagValue
##               <char>              <char>                           <char>
##  1: ea7c21e099aa932b            function                            Cache
##  2: ea7c21e099aa932b            userTags                         outerTag
##  3: ea7c21e099aa932b            accessed        2026-11-19 15:11:23.56427
##  4: ea7c21e099aa932b             inCloud                            FALSE
##  5: ea7c21e099aa932b   elapsedTimeDigest                 0.001713037 secs
##  6: ea7c21e099aa932b           preDigest  .cacheChaining:71681d621365dfd7
##  7: ea7c21e099aa932b           preDigest     .cacheExtra:c85d88fc56f4e042
##  8: ea7c21e099aa932b           preDigest            .FUN:3237d68f548b9590
##  9: ea7c21e099aa932b           preDigest   .functionName:c85d88fc56f4e042
## 10: ea7c21e099aa932b           preDigest            conn:118387d5d48f757d
## 11: ea7c21e099aa932b           preDigest             drv:9ce9a83896bf68a1
## 12: ea7c21e099aa932b           preDigest               n:82dc709f2b91918a
## 13: ea7c21e099aa932b           preDigest cacheSaveFormat:cf2828ea967d53e7
## 14: ea7c21e099aa932b           preDigest          dryRun:e9aac936a0e8f6ae
## 15: ea7c21e099aa932b           preDigest             FUN:f4ab56347506d214
## 16: ea7c21e099aa932b               class                          numeric
## 17: ea7c21e099aa932b         object.size                             1008
## 18: ea7c21e099aa932b            fromDisk                            FALSE
## 19: ea7c21e099aa932b          resultHash                                 
## 20: ea7c21e099aa932b elapsedTimeFirstRun                  0.01127076 secs
##              cacheId              tagKey                         tagValue
##               <char>              <char>                           <char>
##                    createdDate
##                         <char>
##  1: 2026-11-19 15:11:23.576216
##  2: 2026-11-19 15:11:23.576216
##  3: 2026-11-19 15:11:23.576216
##  4: 2026-11-19 15:11:23.576216
##  5: 2026-11-19 15:11:23.576216
##  6: 2026-11-19 15:11:23.576216
##  7: 2026-11-19 15:11:23.576216
##  8: 2026-11-19 15:11:23.576216
##  9: 2026-11-19 15:11:23.576216
## 10: 2026-11-19 15:11:23.576216
## 11: 2026-11-19 15:11:23.576216
## 12: 2026-11-19 15:11:23.576216
## 13: 2026-11-19 15:11:23.576216
## 14: 2026-11-19 15:11:23.576216
## 15: 2026-11-19 15:11:23.576216
## 16: 2026-11-19 15:11:23.576216
## 17: 2026-11-19 15:11:23.576216
## 18: 2026-11-19 15:11:23.576216
## 19: 2026-11-19 15:11:23.576216
## 20: 2026-11-19 15:11:23.576216
##                    createdDate
##                         <char>

cacheId

Sometimes, it is not absolutely desirable to maintain the work flow intact because changes that are irrelevant to the analysis, such as changing messages sent to a user, may be changed, without a desire to rerun functions. The cacheId argument is for this. Once a piece of code is run, then the cacheId can be manually extracted (it is reported at the end of a Cache call) and manually placed in the code, passed in as, say, cacheId = "ad184ce64541972b50afd8e7b75f821b".

### cacheId
set.seed(1)
rnorm(1) |> Cache(cachePath = tmpdir1)
## [1] -0.6264538
## attr(,".Cache")
## attr(,".Cache")$newCache
## [1] TRUE
## 
## attr(,"tags")
## [1] "cacheId:ca275879d5116967"
## attr(,"callInCache")
## [1] ""
# manually look at output attribute which shows cacheId: 422bae4ed2f770cc
rnorm(1) |> Cache(cachePath = tmpdir1, cacheId = "422bae4ed2f770cc") # same value
## [1] 0.1836433
## attr(,".Cache")
## attr(,".Cache")$newCache
## [1] TRUE
## 
## attr(,"tags")
## [1] "cacheId:422bae4ed2f770cc"
## attr(,"callInCache")
## [1] ""
# override even with different inputs:
rnorm(2) |> Cache(cachePath = tmpdir1, cacheId = "422bae4ed2f770cc")
## [1] 0.1836433
## attr(,".Cache")
## attr(,".Cache")$newCache
## [1] FALSE
## 
## attr(,"tags")
## [1] "cacheId:422bae4ed2f770cc"
## attr(,"callInCache")
## [1] ""

Working with the Cache manually

Since the cache is simply a DBI data table (of an SQLite database by default). In addition, there are several helpers in the reproducible package, including showCache, keepCache and clearCache that may be useful. Also, one can access cached items manually (rather than simply rerunning the same Cache function again).

# As of reproducible version 1.0, there is a new backend directly using DBI
mapHash <- unique(showCache(tmpDir, userTags = "project")$cacheId)
map <- loadFromCache(mapHash[1], cachePath = tmpDir)
terra::plot(map)

## cleanup
unlink(dirname(tmpDir), recursive = TRUE)

Alternative database backends

By default, caching relies on a sqlite database for it’s backend. While this works in many situations, there are some important limitations of using sqlite for caching, including 1) speed; 2) concurrent transactions; 3) sharing database across machines or projects. Fortunately, Cache makes use of DBI package and thus supports several database backends, including mysql and postgresql.

See https://github.com/PredictiveEcology/SpaDES/wiki/Using-alternate-database-backends-for-Cache for further information on configuring these additional backends.

Reproducible workflow

In general, we feel that a liberal use of Cache will make a re-usable and reproducible work flow. shiny apps can be made, taking advantage of Cache. Indeed, much of the difficulty in managing data sets and saving them for future use, can be accommodated by caching.