Database releases

A release is one built knowledge-graph store (see Knowledge graph). Releases are defined in torchcell/knowledge_graphs/releases.py.

Release ids and versions

  • Release id: <YYYY.MM.DD>-<commit[:8]>, the build date and the first eight characters of the torchcell commit that produced it, for example 2026.09.21-ab6d8c5d. The id is immutable: a dump, a backup and a served database of the same build all carry it. After an incremental admission, the commit in the id is the commit that ran the admission.

  • Version: <major>.<minor>. A full rebuild bumps the major and resets the minor (1.2 to 2.0); an incremental admission bumps the minor (1.2 to 1.3). The first release is 1.0.

What a release records

Each served database holds one KgRelease node, written before the store is served, and the build manifest beside the store carries the same release id, version and per-dataset content hashes. The node is the KgRelease pydantic model:

Field

Meaning

release

the release id

version

major.minor

torchcell_commit

the commit of the full build the store descends from

built_at

build time

biocypher_out

name of the BioCypher CSV output the store was imported from

neo4j_version

Neo4j version of the build

n_nodes

node count

datasets

per dataset: class name, n_experiments, and content_sha256, the sha256 of its sorted experiment ids

closures

per dataset: the contract fingerprint of every schema symbol its records were serialized under

A dump loaded anywhere answers what it is with MATCH (r:KgRelease) RETURN r. Equal content_sha256 values in two releases mean the dataset’s serialized experiment records are byte-identical; closures is what python -m torchcell.knowledge_graphs.releases compat compares against a local checkout.

Pinning a release

A client names the release it wants and never a database name. Set TORCHCELL_KG_VERSION for a whole run, or pass version= to Neo4jQueryRaw, with one of:

  • latest, the default, an alias that follows each newly published release;

  • pinned, an alias held on a release that published work depends on;

  • a release id, such as 2026.09.21-ab6d8c5d;

  • a version, such as 1.2.

export TORCHCELL_KG_VERSION=2026.09.21-ab6d8c5d

A name that matches no alias, database, release id or version raises LookupError. Resolution is described in Choosing a release.

Compatibility with torchcell versions

Records are serialized under the schema of the commit that built them, so a release is tied to a range of torchcell source. The matrix of package tags against knowledge-graph releases is generated by scripts/kg_compat_page.py from the snapshots committed under database/releases/ and lives on its own page:

A release and a package version are used as a pair: the page’s first table names the package each release is paired with, and the client refuses at connect to read a release the installed package does not fully reproduce (releases.require_paired), so there is no partially working combination. In the matrix a cell reads compatible when every served dataset’s schema closure fingerprints match the tag’s schema surface, incompatible when any dataset drifted or went unverified, and unknown when the tag predates the surface modules.

Downloads

Built datasets and the raw mirror are served by the tc-data endpoint (Swagger at its /docs route); the client, the environment variables and the library download path are described in Downloads.