dvs_init()

dvs_init() creates a dvs.toml project file and a metadata folder (.dvs by default), recording where file contents are stored and how they are compressed.

dvs_init(
  storage_path,
  root_dir = NULL,
  group = NULL,
  metadata_folder_name = NULL,
  compression = c("zstd", "none")
)

🔗Parameters

🔗Setup

Each example initializes its own project directory, because dvs_init() errors if a dvs.toml already exists in the target root.

options(width = 1000)
library(dvs)
base <- tempfile("dvs_init_")
dir.create(base)

🔗storage_path and root_dir

storage_path is the only required argument. root_dir controls where the project file lands; it defaults to the current working directory.

proj  <- file.path(base, "basic")
store <- file.path(base, "basic-store")
dir.create(proj)
dir.create(store)
dvs_init(store, root_dir = proj)

DVS Initialized

dvs.toml is written in root_dir and records the storage path:

cat(readLines(file.path(proj, "dvs.toml")), sep = "\n")

compression = "zstd"

[backend]
path = "/var/folders/_x/bq8vb1b156sgl363l71by61h0000gn/T//RtmpP5AuC2/dvs_init_1a0b333ff86a/basic-store"
group = "staff"

🔗group

group sets a Unix group on the storage directory and stored files for shared access. The group must exist and you must be a member. This example is not executed; it depends on a specific group on the host.

proj  <- file.path(base, "grouped")
store <- file.path(base, "grouped-store")
dir.create(proj)
dir.create(store)
dvs_init(store, root_dir = proj, group = "rstudio")

$status
[1] "initialized"

The chosen group is written to dvs.toml under [backend].

🔗metadata_folder_name

Use a metadata folder name other than .dvs. The name is recorded in dvs.toml.

proj  <- file.path(base, "meta")
store <- file.path(base, "meta-store")
dir.create(proj)
dir.create(store)
dvs_init(store, root_dir = proj, metadata_folder_name = ".meta")

DVS Initialized

list.files(proj, all.files = TRUE, no.. = TRUE)

[1] ".meta"    "dvs.toml"

🔗compression

compression is an enum: "zstd" (default) or "none". With "none" the stored blob is the same size as the input. Here the same file is added under both settings and the stored_size column differs.

mk <- function(name, comp) {
  proj  <- file.path(base, name)
  store <- file.path(base, paste0(name, "-store"))
  dir.create(proj)
  dir.create(store)
  dvs_init(store, root_dir = proj, compression = comp)
  write.csv(mtcars, file.path(proj, "cars.csv"))
  old <- setwd(proj)
  on.exit(setwd(old))
  dvs_add("cars.csv")
}
mk("zstd-proj", "zstd")

DVS Initialized

# A tibble: 1 × 5
  path     outcome hash                                                                size stored_size
  <chr>    <chr>   <chr>                                                            <bytes>     <bytes>
1 cars.csv copied  5920946da5cfd6b4b32cf7b2fb866d926637dadb1b38d3d943bf8db3b9ebdb63  1.7 KB       905 B

mk("none-proj", "none")

DVS Initialized

# A tibble: 1 × 5
  path     outcome hash                                                                size stored_size
  <chr>    <chr>   <chr>                                                            <bytes>     <bytes>
1 cars.csv copied  5920946da5cfd6b4b32cf7b2fb866d926637dadb1b38d3d943bf8db3b9ebdb63  1.7 KB      1.7 KB

There is no no_compression argument. The CLI flag --no-compression maps to compression = "none". See dvs init.

🔗Return value

dvs_init() returns a list with a single status element and prints a confirmation line. It is called for its side effect of creating the project.

proj  <- file.path(base, "ret")
store <- file.path(base, "ret-store")
dir.create(proj)
dir.create(store)
res <- dvs_init(store, root_dir = proj)

DVS Initialized

str(res)

List of 1
 $ status: chr "initialized"

🔗Differences from the CLI

The CLI command is dvs init. It uses a --no-compression boolean instead of the compression enum, and adds --threads and --json, which the R surface does not have. Threads are set process-wide with set_dvs_threads().

🔗See also

• dvs_add(), dvs_status(), dvs_get()
• The dvs.toml project file
• Storage and meta files