pins (version 1.2.1)

pin_read: Read and write objects to and from a board

Description

Use pin_write() to pin an object to board, and pin_read() to retrieve it.

Usage

pin_read(board, name, version = NULL, hash = NULL, ...)
pin_write(
  board,
  x,
  name = NULL,
  type = NULL,
  title = NULL,
  description = NULL,
  metadata = NULL,
  versioned = NULL,
  tags = NULL,
  ...,
  force_identical_write = FALSE
)

Value

pin_read() returns an R object read from the pin; pin_write() returns the fully qualified name of the new pin, invisibly.

Arguments

board

A pin board, created by board_folder(), board_connect(), board_url() or another board_ function.

name

Pin name.

version

Retrieve a specific version of a pin. Use pin_versions() to find out which versions are available and when they were created.

hash

Specify a hash to verify that you get exactly the dataset that you expect. You can find the hash of an existing pin by looking for pin_hash in pin_meta().

...

Additional arguments passed on to methods for a specific board.

x

An object (typically a data frame) to pin.

type

File type used to save x to disk. Must be one of "csv", "json", "rds", "parquet", "arrow", or "qs". If not supplied, will use JSON for bare lists and RDS for everything else. Be aware that CSV and JSON are plain text formats, while RDS, Parquet, Arrow, and qs are binary formats.

title

A title for the pin; most important for shared boards so that others can understand what the pin contains. If omitted, a brief description of the contents will be automatically generated.

description

A detailed description of the pin contents.

metadata

A list containing additional metadata to store with the pin. When retrieving the pin, this will be stored in the user key, to avoid potential clashes with the metadata that pins itself uses.

versioned

Should the pin be versioned? The default, NULL, will use the default for board

tags

A character vector of tags for the pin; most important for discoverability on shared boards.

force_identical_write

Store the pin even if the pin contents are identical to the last version (compared using the hash). Only the pin contents are compared, not the pin metadata. Defaults to FALSE.

Details

pin_write() takes care of the details of serialising an R object to disk, controlled by the type argument. See pin_download()/pin_upload() if you want to perform the serialisation yourself and work just with files.

Examples

b <- board_temp(versioned = TRUE)

b %>% pin_write(1:10, "x", description = "10 numbers")
b

b %>% pin_meta("x")
b %>% pin_read("x")

# Add a new version
b %>% pin_write(2:11, "x")
b %>% pin_read("x")

# Retrieve an older version
b %>% pin_versions("x")
b %>% pin_read("x", version = .Last.value$version[[1]])
# (Normally you'd specify the version with a string, but since the
# version includes the date-time I can't do that in an example)