Cache and downloads

How caching works

When you call datasus_download() with use_cache = TRUE (the default), files are stored in a structured subdirectory tree under the cache folder. On subsequent calls for the same files, the cached versions are reused without any network access.

library(datasusr)

downloads <- datasus_fetch(
  source    = "SIHSUS",
  file_type = c("RD", "SP"),
  year      = 2024,
  month     = 1,
  uf        = c("PE", "PB")
)

Configuring the cache directory

By default, downloads are placed in a session-scoped subdirectory of tempdir() (which R cleans up automatically when the session ends), so the package never writes outside the user-controlled tempdir unless you opt in.

The cache location is resolved in the following order:

1. The cache_dir function argument
2. The DATASUSR_CACHE_DIR environment variable
3. The datasusr.cache_dir R option
4. The session default (file.path(tempdir(), "datasusr-cache"))

To enable a persistent cache that survives across sessions, point one of the above to a directory of your choice — for example tools::R_user_dir("datasusr", "cache") — and the cache becomes truly persistent.

To set it globally, add a line to your .Renviron:

DATASUSR_CACHE_DIR=/path/to/my/cache

Or in R:

options(datasusr.cache_dir = "/path/to/my/cache")

Inspecting the cache

# Quick summary
datasus_cache_info(verbose = TRUE)

# Detailed listing of all cached files
datasus_cache_list()

Forcing a re-download

Pass refresh = TRUE to datasus_download() (or datasus_fetch()) to re-download files even when they exist in the cache:

datasus_download(files, refresh = TRUE)

Pruning and clearing the cache

Over time the cache can grow large. Two functions help manage its size:

# Remove files older than 90 days
datasus_cache_prune(older_than_days = 90)

# Keep the total cache under 5 GB
datasus_cache_prune(max_size_bytes = 5 * 1024^3)

# Remove everything
datasus_cache_clear()

When pruning by size, the least-recently-accessed files are removed first.