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)

# A tibble: 1 × 4
  compression metadata_folder_name backend_path                                                                                          backend_group
  <chr>       <lgl>                <chr>                                                                                                 <chr>        
1 zstd        NA                   /private/var/folders/_x/bq8vb1b156sgl363l71by61h0000gn/T/RtmpERAu23/dvs_init_726310197a76/basic-store staff        

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 = "/private/var/folders/_x/bq8vb1b156sgl363l71by61h0000gn/T/RtmpERAu23/dvs_init_726310197a76/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")

# A tibble: 1 × 4
  compression metadata_folder_name backend_path                                        backend_group
  <chr>       <lgl>                <chr>                                               <chr>
1 zstd        NA                   /tmp/Rtmp0oQgN3/dvs_init_d13e1444c8b2/grouped-store rstudio

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")

# A tibble: 1 × 4
  compression metadata_folder_name backend_path                                                                                         backend_group
  <chr>       <chr>                <chr>                                                                                                <chr>        
1 zstd        .meta                /private/var/folders/_x/bq8vb1b156sgl363l71by61h0000gn/T/RtmpERAu23/dvs_init_726310197a76/meta-store staff        

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")

# 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")

# 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 one-row tibble describing the resulting configuration: the compression mode, the metadata folder name (NA when the default .dvs is used), and the backend path and group. The call's purpose is the side effect of creating the project; the return value describes what was written.

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

tibble [1 × 4] (S3: tbl_df/tbl/data.frame)
 $ compression         : chr "zstd"
 $ metadata_folder_name: logi NA
 $ backend_path        : chr "/private/var/folders/_x/bq8vb1b156sgl363l71by61h0000gn/T/RtmpERAu23/dvs_init_726310197a76/ret-store"
 $ backend_group       : chr "staff"

🔗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