Catalog revisions

On the managed registry, every persist appends FeatureQL to a changelog beside live HEAD. Inspect that log, then read main at a past commit with AS OF.

Catalog revisions are a managed-registry capability, like lifecycle and permissions . The local engine raises UE/REVISION-MANAGED-ONLY.

A name still has one current definition. CREATE OR REPLACE updates HEAD and appends a log entry. It does not keep two current versions under that name. Registry consistency still validates the graph you are about to persist.

Write a revision

Attach a message with START TRANSACTION '…'. Bare START TRANSACTION still wraps the request; the revision MESSAGE is then null.

START TRANSACTION 'docs rev weekly';
CREATE OR REPLACE FEATURE FM.TUTORIALS.REVISIONS.AMOUNT AS 1;
COMMIT;

TEMPORARY creates and EXPLAIN persists do not write revisions. Kind is CREATE, DROP, ALTER, or TRANSACTION when one request mixed those sources.

Inspect one name

DESCRIBE (FIELDS (HISTORY)) lists per-name ops (upsert / drop), newest first. Each item has revision, branch, op, created_at, created_by, message, and a formula preview from that entry — not the original query_text.

DESCRIBE (FIELDS (NAME, HISTORY)) FM.TUTORIALS.REVISIONS.AMOUNT;

After a later replace, the newest row is the current formula; the older row still has the message from the first persist.

List main commits

SHOW REVISIONS lists main — the ids AS OF can name. Default columns are REVISION, BRANCH, KIND, MESSAGE, CREATED_AT, CREATED_BY. Newest order_key first; created_at is display only.

SHOW REVISIONS (COLUMNS (BRANCH, KIND, MESSAGE))
WHERE MESSAGE = 'docs rev weekly'
LIMIT 1
;

Public ids are eight uppercase identifier characters ([A-Z] then [A-Z0-9]). FeatureQL uppercases identifiers, so AS OF k7m2npq4 and AS OF K7M2NPQ4 are the same lookup.

Overlay commits are not in this list. Use SHOW REVISIONS ON BRANCH name or SHOW BRANCHES — Branch overlays .

Read main at a past commit

AS OF pins the rest of the script to a main revision. Place USE, then at most one ON BRANCH, then at most one AS OF, then the rest. After a RETURN / persist / SHOW / DESCRIBE is too late (UE/REVISION-CONTEXT-MUST-LEAD).

AS OF K7M2NPQ4;
RETURN FM.SALES.WEEKLY_REVENUE;
SHOW CREATE FEATURES FM.SALES.WEEKLY_REVENUE;
DESCRIBE FM.SALES.WEEKLY_REVENUE;

Pick the id from SHOW REVISIONS or from DESCRIBE history. An unknown id raises UE/REVISION-NOT-FOUND:

AS OF ZZZZNOT1;
RETURN X := 1;

AS OF without ON BRANCH is read-only. A persist on main raises UE/REVISION-READ-ONLY. A branch commit id raises UE/REVISION-NOT-ON-MAIN.

Reconstruction is definitions-as-of today's compiler and today's source schemas. Unchanged names reuse HEAD; a changed name (or a dirty dependency) is replayed from the last FeatureQL entry and re-inferred. Views are unversioned: a closure that reaches a view raises UE/REVISION-UNVERSIONED-VIEW. Permissions and lifecycle are current-time.

SHOW FEATURES and JDBC catalog paths are not wired. They raise UE/REVISION-VIEW-NOT-WIRED rather than silently reading HEAD. Use RETURN, SHOW CREATE, DESCRIBE, or SHOW REVISIONS.

What the log does not do

• Approval. Status and review stay lifecycle and your release process.
• Serving pins. Prepared statements and real-time sources still read current HEAD.
• Secret redaction. The log is append-only. Do not persist secrets in FeatureQL you would not leave in the catalog.
• Full-catalog dump at a past commit. Nameless SHOW CREATE FEATURES under AS OF is not a catalog export.

To revert one name on main, pin AS OF the last good revision, SHOW CREATE FEATURES that name, then re-apply the FeatureQL without AS OF.

To try a change without writing HEAD, continue with Branch overlays . Syntax: Revision context , SHOW , DESCRIBE , Transactions .