Skip to contents

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, or NULL for 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.

Value

A plasticdb_client object (a list) to pass as client =.

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: option plasticdb.release, PLASTICDB_RELEASE; default none (the live database).

  • base_url: option plasticdb.base_url, PLASTICDB_BASE_URL; default https://v2.plasticdb.org/api/v1.

  • cache: option plasticdb.cache, PLASTICDB_CACHE_DIR; default TRUE.

  • timeout, max_retries, max_retry_wait: options plasticdb.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.

Examples

client <- plasticdb_client(release = "2026.50", cache = FALSE)
client

## Or pin every call in a script:
old <- options(plasticdb.release = "2026.50")
plasticdb_client()$release
options(old)