Catalog

The Catalog is version control for everything in a Project. Each time your application appends rows to frames or creates a Table, the Catalog records a commit: an exact record of which version of every Table, Location, and other Resource the Project held at that moment. Pin a commit and a training run reads the same data next year as it did today. Branches and tags are names for commits, so creating one copies no data.

Catalog is optional for a Project. Initialize it with POST /api/catalog/projects/{project_id}/initialize before using it. This creates the initial commit and main branch. Repeating initialization returns the current main branch without changing its history. Reading the Catalog does not initialize it.

Commits and branches explains the model. This page covers what the Catalog service does with it.

An exampleCopy Anchor Link

A labeling job appends 2,000 frames to frames and, in the same commit, publishes a new version of the is_blurry Enrichment. Then you tag that commit for a training run:

main          P184 ── P185 ── P188
                        │
training-v7  ───────────┘   (tag: never moves)

Readers of main see both changes at P185 or neither. The training run reads frames at the commit that training-v7 names, so the appends at P188 do not change its input.

CommitsCopy Anchor Link

A commit is immutable. It records changes to Resource names and to the Resource version that each name selects, and its parent identifies the previous Project state. One commit can publish several related changes, and a reader sees all of the commit or none of it.

A commit ID is a UUID, such as 0198c5d5-76f2-7b18-9eb0-7f93356af196. To find how two commits are related, follow the parent links or ask the Catalog for the merge base; the IDs and timestamps do not tell you.

The Catalog stores names and version pointers only. A rename changes a Resource's path and keeps its Resource ID, so anything that refers to the ID keeps working. Table rows never pass through the Catalog.

BranchesCopy Anchor Link

A branch is a name that moves to each new commit published on it. A new Project has the branch main. Create a branch to make changes that readers of main do not see yet; it copies no Resources.

main        P184 → P185 → P188
                     ↘
experiment             P186 → P187

Each branch has a stable branch ID, which a rename keeps. A publication names the branch ID and the commit that it started from. If the branch has since changed the same Resources or names, the Catalog reports a conflict and publishes nothing. A publication can also name the head that it expects, as the Rust SDK always does; then any move of the branch rejects it.

TagsCopy Anchor Link

A tag is a name for one commit that never moves. Use one for a validated dataset, a training input, a release, or an audit point, such as training-v7. The Catalog does not move, rename, or delete tags, so a tag is a durable record of what a job read.

Merge and revertCopy Anchor Link

A merge compares the source branch and the target branch with their common base, and creates a merge commit once the changed Resources are reconciled. A revert creates a new commit that undoes an earlier one; it never moves a branch backward. A later change to the same Resource can make a revert conflict.

Assess a merge or a revert before you apply it. The assessment reports the conflicts and changes nothing.

Recover an interrupted publicationCopy Anchor Link

A network failure can hide whether a publication happened. Keep the transaction ID until you know. Recovery checks whether you published that transaction ID, and returns the original commit or reports that nothing was published; it never publishes a second commit. The Rust SDK keeps the request in a FrozenCommit for this. See Write rows and Retries.

Browse history in StudioCopy Anchor Link

Studio groups work by branch. Select the branch in the top bar; the sidebar shows the Resources of that branch, and Studio keeps a separate tab layout for each branch.

Open History and Changes from the branch sidebar. History starts at the branch head. Changes compares the branch with main by Resource name and kind, without reading Resource data. Expand Technical details to see the Resource ID and both version IDs. Open a commit from History to view that exact Project state.

Where nextCopy Anchor Link

• Select an exact state: pin a branch, resolve a tag, and read Tables at the commit.
• Create branches and tags.
• How the Catalog works: snapshots, commits, and conflict rules.

The Catalog HTTP reference documents every branch, tag, compare, merge, revert, and recovery operation. The Catalog runs in Spiral's control plane; see Architecture.