Cache Assets — asset management within a cache

DataCaches.CacheAssets.cp([src_cache::DataCache,] src, dest_cache::DataCache; kwargs...)
DataCaches.CacheAssets.cp([src_cache::DataCache,] srcs::AbstractVector, dest_cache::DataCache; kwargs...)

Copy one or more assets to dest_cache. Each copy receives a new UUID, sequence number, and datecached timestamp in the destination. Copying within the same cache is allowed and produces a distinct new entry.

src / each element of srcs can be a CacheEntry, label String, UUID-prefix String, or sequence index Integer.

Single-source form:

• label="" — override the destination label (default: preserve original label)
• force=false — when true, silently replace an existing entry with the same label

Multi-source form (srcs::AbstractVector):

• Each entry preserves its original label; returns a Vector{CacheEntry} of new entries
• force=false — apply to all entries

If src_cache is omitted, active_autocache() is used as the source.

DataCaches.CacheAssets.ls!([cache::DataCache]; kwargs...) → nothing

Print a formatted listing of assets in cache to io (default stdout). If cache is omitted, the active default cache is used (see active_autocache()).

Accepts all the same filtering and sorting keyword arguments as ls, plus:

Additional keyword arguments

Display:

• detail::Symbol = :normal — richness of the output:
  • :minimal — sequence index and label only
  • :normal (default) — index, write timestamp, UUID prefix, label, and file path
  • :full — all of :normal plus last-access time, file size, and data format
• io::IO = stdout

DataCaches.CacheAssets.ls([cache::DataCache]; kwargs...) → Vector{CacheEntry}

Return a filtered and sorted vector of cache entries from cache. If cache is omitted, the active default cache is used (see active_autocache()).

Keyword arguments

Filtering:

• pattern — Regex or String (converted to Regex); matched against label, description, then UUID. Pass nothing (default) to disable.
• filepath_pattern — Regex or String; matched against the full absolute file path of each entry's backing data file.
• filename_pattern — Regex or String; matched against only the filename (i.e. basename(path)) of each entry's backing data file.
• before::DateTime — include only entries written before this time
• after::DateTime — include only entries written after this time
• accessed_before_date::DateTime — include only entries last accessed before this time
• accessed_after_date::DateTime — include only entries last accessed after this time
• labeled::Union{Nothing,Bool} = nothing — true for labeled entries only, false for unlabeled only, nothing for all
• missing_file::Bool = false — when true, include entries whose backing file is absent
• format::Union{Nothing,String,Regex} = nothing — String for exact format tag match (e.g. "csv", "jls"), Regex for pattern match (e.g. r"csv|json")

Sorting:

• sortby::Symbol = :seq — sort criterion: :seq, :label, :date, :date_desc, :dateaccessed, :dateaccessed_desc, :size, :size_desc
• rev::Bool = false — reverse the sort order

See also ls! for a display-oriented variant that prints to an IO stream.

DataCaches.CacheAssets.mv([src_cache::DataCache,] src, dest; kwargs...)

Move or relabel a cache asset. src can be a CacheEntry, label String, UUID-prefix String, or sequence index Integer.

Relabel within the same cache (when dest is a String):

mv(cache, src, new_label::String; force=false)

Rename src to new_label in place. If new_label is already taken by a different entry, an error is raised unless force=true, in which case the conflicting entry is removed first.

Move to another cache (when dest is a DataCache):

mv(src_cache, src, dest_cache::DataCache; label="", force=false)

Read the asset from src_cache, write it to dest_cache (with a new UUID, sequence number, and datecached timestamp), then remove it from src_cache. The label kwarg overrides the destination label (default: preserve the original). Pass force=true to overwrite an existing entry with the same label in dest_cache.

If src_cache is omitted, active_autocache() is used as the source.

DataCaches.CacheAssets.purge!([cache::DataCache]; kwargs...) → DataCache

Bulk-delete cache entries matching the given criteria. All standard ls filtering keyword arguments are accepted to scope which entries are candidates for purging. When cache is omitted, the active default cache is used (see active_autocache()).

All removals are batched into a single index rewrite.

Standard filter kwargs (same as ls)

• pattern, filepath_pattern, filename_pattern — label/path/filename pattern
• format::Union{Nothing,String,Regex} — format tag filter (e.g. "jls", r"csv|json")
• before, after — filter by datecached
• accessed_before_date, accessed_after_date — filter by dateaccessed
• labeled::Union{Nothing,Bool} — true = labeled only; false = unlabeled only

Purge criteria (applied after filtering)

• stale::Bool = false — delete entries past their TTL (requires TTL to be configured)
• max_age::Union{Nothing,Period} — delete entries whose age (by datecached) exceeds this
• max_idle::Union{Nothing,Period} — delete entries that have not been accessed within this period (entries never accessed are treated as least-recently-used and are eligible)
• keep_count::Union{Nothing,Int} — keep only the N most-recently-accessed entries among the candidates; delete the rest
• max_size_bytes::Union{Nothing,Int} — purge LRU entries until the total size of the remaining candidates is at or below this limit

Options

• keep_labeled::Bool = false — when true, labeled entries are never deleted, even if they match all other criteria
• dry_run::Bool = false — print what would be deleted to io without deleting
• io::IO = stdout — output stream for dry_run messages

Examples

dc = DataCache(:myproject)

# Remove all stale entries (requires TTL on entries or cache)
CacheAssets.purge!(dc; stale = true)

# Remove entries older than 30 days
CacheAssets.purge!(dc; max_age = Dates.Day(30))

# Keep only the 10 most recently accessed entries
CacheAssets.purge!(dc; keep_count = 10)

# Purge LRU entries until cache is under 100 MiB, keep labeled entries
CacheAssets.purge!(dc; max_size_bytes = 100 * 1024 * 1024, keep_labeled = true)

# Preview without deleting
CacheAssets.purge!(dc; max_age = Dates.Day(7), dry_run = true)

# Purge using default cache
CacheAssets.purge!(; keep_count = 50)

See also ls, rm, DataCaches.invalidate!, DataCaches.set_autopurge!.

DataCaches.CacheAssets.rm([cache::DataCache,] assets...; force=false)
DataCaches.CacheAssets.rm([cache::DataCache,] specs::AbstractVector; force=false)

Remove one or more assets from cache (default: active default cache). Each asset can be specified as a CacheEntry, label String, UUID-prefix String, or sequence index Integer. The backing data file is also deleted from disk.

All removals are batched into a single index rewrite for efficiency.

The AbstractVector form accepts a vector of any mix of the above specifier types, which is convenient for operating on the result of ls.

Pass force=true to suppress errors for unresolvable specifiers (they are silently skipped).