Resolve a release's column names for the cross-version queries

The v8 rewrite renamed three things every taxon/model query depends on, and the app-side copy of one such query was never migrated — which is why the v8 "Table of Species" tab came up empty with "Can't select columns that don't exist":

Usage

sdm_cols(con, mc_tbl = "model_cell")

Arguments

con

open connection to a release database, or to a set of views over one

mc_tbl

name of the model-cell table to inspect, or NULL to skip it. Skipping matters on the server: inspecting model_cell there makes DuckDB LIST the S3 prefix just to read a schema, which fails outright.

Value

a list with valid, marine, tkey, mkey, val

Details

concept	v1-v7	v8
taxon validity	is_ok	is_valid_usa
model id	mdl_seq	ms_merge_key (taxon) / mdl_key (model_cell)
cell value	value	val (value is reserved in DuckDB)

Resolved per connection by introspection, so one implementation serves every release and no caller needs to know which generation it is talking to. Exported because the versioned documentation asks the same question of the same published tables — a second copy of the rule in the docs is exactly how a v3 page ends up printing a v8 column name.

Note the semantics the names hide: v7's is_ok already baked in the marine/category cull, while v8's is_valid_usa only means "has >= 1 merged cell in US waters", so scoring eligibility on v8 additionally needs is_marine (returned as marine, NA when the release has no such column).

Examples

if (FALSE) { # \dontrun{
con <- attach_atlas(version = "v7")
sdm_cols(con, mc_tbl = NULL)$valid   # "is_ok"
} # }