plasticdb_client() describes how to reach the API: which server, which
dataset release to pin every read to, the API key, and where pinned answers
are cached. Every function in the package takes client = plasticdb_client() as its last argument, so in most scripts you never call
it yourself: set the options or environment variables once and every call
follows them.
Usage
plasticdb_client(
api_key = NULL,
release = NULL,
base_url = NULL,
cache = NULL,
timeout = NULL,
max_retries = NULL,
max_retry_wait = NULL
)Arguments
- api_key
An API key, needed only for jobs. Never stored in an option.
- release
A dataset release version (e.g.
"2026.50") to pin every read to, orNULLfor the live database.- base_url
The API root.
- cache
TRUE,FALSE, or a cache directory.- timeout
Request timeout in seconds.
- max_retries
How many times a request is retried.
- max_retry_wait
The longest wait (seconds) honoured before a retry.
Details
Each setting is resolved, first match wins, from the argument, then the R option, then the environment variable, then the default:
api_key:PLASTICDB_API_KEY; default none (reads are anonymous).release: optionplasticdb.release,PLASTICDB_RELEASE; default none (the live database).base_url: optionplasticdb.base_url,PLASTICDB_BASE_URL; defaulthttps://v2.plasticdb.org/api/v1.cache: optionplasticdb.cache,PLASTICDB_CACHE_DIR; defaultTRUE.timeout,max_retries,max_retry_wait: optionsplasticdb.timeout,plasticdb.max_retries,plasticdb.max_retry_wait; defaults 30 seconds, 3 and 60 seconds.
A pinned client sends ?release= on every read; the server answers from
that release's snapshot. Answers from a past release are immutable, so they
are kept in a BiocFileCache::BiocFileCache() and reused without a request.
Live answers (including the current release, which the live database
serves) are never cached. cache = TRUE uses
tools::R_user_dir("plasticdb", "cache"), a string names another
directory, and FALSE turns caching off.
Rate-limited requests (429) are retried after the server's Retry-After
when that is within max_retry_wait; requests are also retried with
backoff on 5xx answers and connection errors.