sddb.Catalog

class sddb.Catalog(url: str | None = None, *, cache_dir: str | Path | None = None, version: str | None = None, refresh: bool = False)

The dataset catalog: fetched, cached and validated on construction.

__init__(url: str | None = None, *, cache_dir: str | Path | None = None, version: str | None = None, refresh: bool = False) → None

Fetch + cache + validate the catalog.

Parameters:

• url – Catalog parquet URL or path; falls back to the SDDB_CATALOG_URL env var, then DEFAULT_CATALOG_URL.

• cache_dir – Cache directory override.

• version – Dated snapshot (e.g. "2026-10-16"); selects the catalog-<version> release in place of catalog-latest. Ignored if an explicit url is given or the resolved URL is not the default rolling-release URL.

• refresh – Bypass the cache and re-download.

Methods

__init__([url, cache_dir, version, refresh])	Fetch + cache + validate the catalog.
cohort(*[, uids, study_ids])	Build a cohort from an explicit set of uids or study_ids (exactly one).
from_file(path, *[, cache_dir])	Load a catalog from a local catalog.parquet (absolute or relative path, or file:// URL).
query(*[, validation, license_set, ...])	Filter the catalog.
search(text)	Deterministic text search over facet values.
to_df()	Return the full catalog as a DataFrame copy.

Attributes

generated_at	Generation timestamp from the parquet metadata, if present.
genes	Cross-dataset gene index bound to this catalog (loaded lazily).