# Database releases

A **release** is one built knowledge-graph store (see
[Knowledge graph](../guide/knowledge-graph.md)). 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`.

```bash
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 {ref}`kg-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:

```{toctree}
:maxdepth: 1

compatibility
```

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](../guide/downloads.md).