Branch overlays

Try a catalog change without writing live HEAD. Package the overlay as FeatureQL, apply it on main when it is approved, then drop the branch.

Branches are a managed-registry overlay on the same names — not a second folder of features. Inspect main history first: Catalog revisions . The local engine raises UE/REVISION-MANAGED-ONLY.

There is no CREATE BRANCH. The first persist under ON BRANCH name creates the branch. A never-written read raises UE/REVISION-BRANCH-NOT-FOUND so an empty overlay does not silently become main.

ON BRANCH docs_br_never;
RETURN X := 1;

ON BRANCH main is UE/REVISION-BRANCH-INVALID.

Write the overlay

HEAD is the live main catalog (features / features_computed). An overlay is the last upsert or drop per name on that branch, applied at request time. It is not a second copy of the catalog.

An overlay write does not touch HEAD. Resolve order is in-query / TEMPORARY → branch overlay → main HEAD (or the pinned AS OF). The overlay floats on current HEAD: a later main write of the same name is hidden while you are on the branch, and applying the extract can overwrite that later main write. Pin every script with AS OF if you need a stable base. To revert a main name, AS OF the last good revision then SHOW CREATE FEATURES of that name and re-apply on main.

ON BRANCH docs_br_try;
START TRANSACTION 'try weekly grain';
CREATE OR REPLACE FEATURE FM.TUTORIALS.OVERLAYS.AMOUNT AS 99;
CREATE OR REPLACE FEATURE FM.TUTORIALS.OVERLAYS.NEW AS 7;
DROP FEATURES IF EXISTS FM.TUTORIALS.OVERLAYS.DROP_ME;
COMMIT;

The same name under ON BRANCH sees the overlay:

ON BRANCH docs_br_try;
RETURN
    fm.tutorials.overlays.amount
;

A later RETURN without ON BRANCH still sees HEAD:

RETURN
    fm.tutorials.overlays.amount
;

ON BRANCH foo; plus AS OF K7M2NPQ4; pins the main base, then applies the full overlay. The pin is not stored on the branch. Overlay drift on current HEAD is an ordinary inference error — pin every script if you need a stable base.

List overlays and their commits

SHOW BRANCHES lists overlay names (BRANCH, REVISIONS, CREATED_AT, UPDATED_AT, BASE_REVISION) and omits main. BASE_REVISION is the main HEAD (or the AS OF) at the first write. Resolve still floats on current HEAD.

SHOW BRANCHES (COLUMNS (BRANCH))
WHERE BRANCH = 'DOCS_BR_TRY'
;

SHOW REVISIONS defaults to main. Overlay commits are SHOW REVISIONS ON BRANCH name, or ON BRANCH name; then SHOW REVISIONS. Those ids are not AS OF candidates (UE/REVISION-NOT-ON-MAIN).

SHOW REVISIONS ON BRANCH docs_br_try (COLUMNS (BRANCH, KIND, MESSAGE))
LIMIT 1
;

SHOW FEATURES is not wired. It raises UE/REVISION-VIEW-NOT-WIRED rather than listing HEAD:

ON BRANCH docs_br_try;
SHOW FEATURES;

Use RETURN, SHOW CREATE, DESCRIBE, or SHOW REVISIONS against the overlay.

Package, apply, discard

ON BRANCH name; then SHOW CREATE FEATURES (no name list) returns the net overlay as a runnable script: surviving upserts, and DROP FEATURES IF EXISTS for names the overlay dropped that main actually had. A name created and dropped on the branch only is omitted.

ON BRANCH docs_br_try;
SHOW CREATE FEATURES;

Name individual features to extract a subset. Apply that script without ON BRANCH to squash onto HEAD:

START TRANSACTION;
CREATE OR REPLACE FEATURES AS PERSIST FM.TUTORIALS.OVERLAYS.AMOUNT := 99;
CREATE OR REPLACE FEATURES AS PERSIST FM.TUTORIALS.OVERLAYS.NEW := 7;
DROP FEATURES IF EXISTS FM.TUTORIALS.OVERLAYS.DROP_ME;
COMMIT;

HEAD now has the packaged change:

RETURN
    fm.tutorials.overlays.amount
;

DROP BRANCH name discards the overlay (those log rows). It does not delete HEAD. After a merge, drop the branch so ON BRANCH name is unknown again.

DROP BRANCH docs_br_try;

IN already means namespace. DROP FEATURES ON BRANCH is UE/DROP-FEATURES-ON-BRANCH — use DROP BRANCH, or a script-level ON BRANCH then DROP FEATURES to drop names in that overlay. DROP FEATURES IN FM … under a script-level ON BRANCH writes overlay drops for HEAD names — it is not “drop the branch.”

CREATE VIEW / REFRESH VIEW / DROP VIEW and /* SQL */ scans of FMV.* are not versioned. Under a pin they raise UE/REVISION-UNVERSIONED-VIEW or UE/REVISION-SQL-PASSTHROUGH. Create or refresh the view on main after you apply the overlay.

Next

Approval and lifecycle stay outside the log. Syntax: Revision context , SHOW CREATE , SHOW .