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,
urls = NULL,
force_identical_write = FALSE
)Arguments
- board
A pin board, created by
board_folder(),board_connect(),board_url()or anotherboard_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_hashinpin_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
xto 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
userkey, to avoid potential clashes with the metadata that pins itself uses.- versioned
Should the pin be versioned? The default,
NULL, will use the default forboardA character vector of tags for the pin; most important for discoverability on shared boards.
- urls
A character vector of URLs for more info on the pin, such as a link to a wiki or other documentation.
- 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.
Value
pin_read() returns an R object read from the pin;
pin_write() returns the fully qualified name of the new pin, invisibly.
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")
#> Guessing `type = 'rds'`
#> Creating new version '20241007T174657Z-76a69'
#> Writing to pin 'x'
b
#> Pin board <pins_board_folder>
#> Path: '/tmp/RtmphSQBxo/pins-170c5f67eef'
#> Cache size: 0
b %>% pin_meta("x")
#> List of 13
#> $ file : chr "x.rds"
#> $ file_size : 'fs_bytes' int 61
#> $ pin_hash : chr "76a6946bd82fc9ec"
#> $ type : chr "rds"
#> $ title : chr "x: a pinned integer vector"
#> $ description: chr "10 numbers"
#> $ tags : NULL
#> $ urls : NULL
#> $ created : POSIXct[1:1], format: "2024-10-07 17:46:57"
#> $ api_version: int 1
#> $ user : list()
#> $ name : chr "x"
#> $ local :List of 3
#> ..$ dir : 'fs_path' chr "/tmp/RtmphSQBxo/pins-170c5f67eef/x/20241007T174657Z-76a69"
#> ..$ url : NULL
#> ..$ version: chr "20241007T174657Z-76a69"
b %>% pin_read("x")
#> [1] 1 2 3 4 5 6 7 8 9 10
# Add a new version
b %>% pin_write(2:11, "x")
#> Guessing `type = 'rds'`
#> Creating new version '20241007T174657Z-972c2'
#> Writing to pin 'x'
b %>% pin_read("x")
#> [1] 2 3 4 5 6 7 8 9 10 11
# Retrieve an older version
b %>% pin_versions("x")
#> # A tibble: 2 × 3
#> version created hash
#> <chr> <dttm> <chr>
#> 1 20241007T174657Z-76a69 2024-10-07 17:46:57 76a69
#> 2 20241007T174657Z-972c2 2024-10-07 17:46:57 972c2
b %>% pin_read("x", version = .Last.value$version[[1]])
#> [1] 2 3 4 5 6 7 8 9 10 11
# (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)