The DB stack#
The client reads a published catalog (one row per dataset) and then streams the SpatialData stores it points to. This page explains what you can rely on.
Release catalogs#
Catalogs are published as dated releases named catalog-YYYY-MM-DD.
sddb.Catalog() reads the latest; pin an older one with the version= argument:
import sddb
cat = sddb.Catalog() # latest release
cat = sddb.Catalog(version="2026-10-18") # catalog-2026-10-18
Validation status and tiers#
Every row has a validation_status; queries keep only "pass" rows by default
(validation=None disables the filter). Rows also carry a tier: gold, silver or bronze,
from most to least curated. Some rows have no tier assigned yet. Not every tier is populated in every release, and gold is not guaranteed to be present. This release holds 4391 datasets (bronze), 4061 datasets (silver), 19 datasets (unassigned).
In the current catalog every dataset passes validation, so the validation filter changes nothing yet. Filter on tier (silver, bronze) for quality.
silver = cat.query(tier="silver")
Licenses#
Datasets keep their original license, in the license column. Two boolean columns make
filtering easy: license_noncommercial (use is restricted to non-commercial work) and
license_redistributable (the license allows redistribution; false when the license is unknown). Check them before reusing data
in a product or republishing it. query(noncommercial=False) keeps only datasets with a known
license that allows commercial use; see 4. Citations and licenses.
Where the bytes live#
Each row's zarr_url points to a SpatialData Zarr store on S3, readable anonymously
(no credentials). Stores are registered in the Lamin instance
scverse/spatialdata-db. Remote stores are copied to the local cache once, then reused:
hits = cat.query(technology="Visium", tissue="lung")
smallest = min(hits, key=lambda ds: ds.size_bytes)
sdata = smallest.to_sdata() # about 7 MB
Versioning and drift#
A dataset uid pins a specific version, but the DB does not yet retain old store bytes: when a dataset
is republished its store is replaced. freeze() records exactly which versions you used;
verify() raises CohortDriftError when a pinned version no longer resolves, and check_updates()
lists members a newer version supersedes. download(..., pin_versions=True) keeps your own copy.
freeze() also records the sha256 of the catalog file, and verify() raises CatalogChangedError when a
dated release was modified after the freeze (for catalog-latest it only warns).
cohort = cat.query(technology="Visium")
manifest = cohort.freeze() # exact members + deterministic hash
cohort.verify() # raises CohortDriftError if a pinned store no longer resolves
cohort.check_updates(cat) # {pinned_uid: current_uid} for members a newer version supersedes