Revision context
ON BRANCH and AS OF are script-level pins, like USE . They set how the rest of the request resolves persisted features. They are not HTTP fields.
Catalog revisions are a managed-registry capability. The local engine raises UE/REVISION-MANAGED-ONLY. Workflow: Catalog revisions , Branch overlays .
Syntax
ON BRANCH identifier AS OF identifier DROP BRANCH [IF EXISTS] identifier
AS OF takes an 8-character revision id ([A-Z][A-Z0-9]{7}). FeatureQL uppercases identifiers. There is no CREATE BRANCH: the first persist under ON BRANCH name creates the branch.
DROP BRANCH name deletes that branch's revision-log rows (the overlay). Live HEAD in features is untouched. Afterward ON BRANCH name on a read is UE/REVISION-BRANCH-NOT-FOUND until the next persist creates it again. DROP BRANCH main is UE/REVISION-BRANCH-INVALID. Unknown name is UE/REVISION-BRANCH-NOT-FOUND; IF EXISTS skips.
Placement
USE, then at most one ON BRANCH, then at most one AS OF, then the rest. Either pin after a RETURN / persist / SHOW / DESCRIBE is UE/REVISION-CONTEXT-MUST-LEAD. More than one of each is UE/REVISION-CONTEXT-DUPLICATE.
ON BRANCH experiment;
AS OF K7M2NPQ4;
RETURN FM.SALES.WEEKLY_REVENUE;
Resolve
| Script | Main base | Overlay |
|---|---|---|
| neither | live HEAD | none |
AS OF id; | main at that commit | none (read-only) |
ON BRANCH name; | live HEAD | full overlay |
| both | main at that commit | full overlay |
In-query / TEMPORARY names win first. AS OF names a main revision only. Unknown id → UE/REVISION-NOT-FOUND. Branch commit → UE/REVISION-NOT-ON-MAIN.
AS OF without ON BRANCH on a persist → UE/REVISION-READ-ONLY. ON BRANCH main → UE/REVISION-BRANCH-INVALID. A never-written branch on a read → UE/REVISION-BRANCH-NOT-FOUND. Write creates the branch.
SHOW FEATURES and JDBC catalog paths raise UE/REVISION-VIEW-NOT-WIRED. CREATE / REFRESH / DROP VIEW under a pin raise UE/REVISION-UNVERSIONED-VIEW. A pin plus /* SQL */ raises UE/REVISION-SQL-PASSTHROUGH. A pin with no following statement raises UE/REVISION-CONTEXT-EMPTY.
SHOW REVISIONS lists main (the ids AS OF can name). SHOW REVISIONS ON BRANCH name lists that overlay stream. SHOW BRANCHES lists overlay names and omits main.
See SHOW for SHOW REVISIONS / SHOW BRANCHES, SHOW CREATE for overlay extract, and Transactions for START TRANSACTION 'message'. How-to: Catalog revisions , Branch overlays .