Skip to contents

Connect to CalCOFI Database

Source: R/database.R
cc_get_db.Rd

Connects to a frozen CalCOFI DuckLake release. Downloads and caches the database locally for fast subsequent access.

Usage

cc_get_db(
  version = "latest",
  local_cache = TRUE,
  cache_dir = NULL,
  refresh = FALSE,
  local_data = FALSE,
  tables = NULL,
  supplemental = FALSE
)

Arguments

version

Version string (e.g., "v2026.02") or "latest" (default)

local_cache

Use local cache if available (default: TRUE)

cache_dir

Directory for local cache. Default uses rappdirs::user_cache_dir("calcofi4r") if rappdirs is installed, otherwise a temp directory.

refresh

Force re-download even if cached (default: FALSE)

local_data

Download parquet files locally and create tables instead of remote views (default: FALSE). Useful for apps that need fast local queries without network overhead.

tables

Character vector of table names to include. NULL (default) includes all (non-supplemental) tables. Use to exclude large tables, or to explicitly include a supplemental table by name. Naming a catalog view (obs since the v2026.09 releases — the UNION ALL over obs_bio + obs_env, see cc_catalog_views()) pulls in the tables it reads.

supplemental

Logical; include supplemental tables (e.g. obs_ctd_full, the 216M full-resolution CTD scans) that are hosted + cataloged but hidden by default. Default FALSE. Ignored when tables names them explicitly.

Value

DuckDB connection object with every requested table present. A table that cannot be loaded is an error naming it (never a warning and a database missing tables); the views are created in one transaction, so a failed call leaves no partial local cache behind.

Details

The frozen releases contain clean, stable data without provenance columns, suitable for analysis and visualization. Use cc_list_versions() to see available releases.

When local_data = FALSE (default), the connection points to Parquet files from the frozen release registered as views in DuckDB. This allows querying without downloading the entire database.

When local_data = TRUE, parquet files are downloaded to cache_dir/parquet/{version}/ and loaded as local tables for faster queries. Files are only downloaded if missing or if refresh = TRUE.

Data is stored at gs://calcofi-db/ducklake/releases/{version}/; since the v2026.09 releases each table's bytes are content-addressed objects under ducklake/tables/ that the release catalog points at — see cc_release_sources, which is how every table here is resolved.

A catalog may also carry views (cc_catalog_views): obs is one since the v2026.09 releases, the UNION ALL over the observation tables obs_bio + obs_env that reconstructs its 18 columns under their original names. Every view whose source tables load is created after them, so FROM obs keeps working; the deprecated obs table's own objects are read only when those sources are not loaded (tables = "obs" pulls them in).

Examples

if (FALSE) { # \dontrun{
# connect to latest release (remote views)
con <- cc_get_db()
DBI::dbListTables(con)

# connect with local data (downloads parquets)
con <- cc_get_db(local_data = TRUE, cache_dir = "data")

# exclude CTD tables
con <- cc_get_db(
  local_data = TRUE,
  tables     = setdiff(cc_db_info()$tables$name,
    c("ctd_cast", "ctd_measurement", "ctd_summary")))
} # }