Registry consistency

Every create, replace, or drop must leave the registry dependency graph consistent. FeatureQL validates the proposed final state before applying the mutation; permissions can control who may change the registry, but they do not bypass these checks.

Think in terms of the final graph

A mutation can affect more than the feature named in the statement. Replacing a feature can change the types seen by every downstream dependent, while dropping one can remove a node that other definitions still reference.

FeatureQL therefore validates the graph that would exist after the complete statement or transaction. Features created together may reference one another in any order as long as every reference resolves in that final graph.

Checks applied to every mutation

Definitions must type-check

Each formula must call functions and operators with compatible argument types. For example, a numeric addition cannot combine a BIGINT with arbitrary text.

Every dependency must resolve

All referenced persisted features must exist in the proposed final state. A transaction may create a dependency and its dependent together; it may not commit a dangling reference.

Dependencies must remain acyclic

The graph must remain a directed acyclic graph. If feature A depends on B, B cannot depend on A directly or through any longer chain.

Replacements must preserve downstream compatibility

When CREATE OR REPLACE changes a definition, FeatureQL checks the affected dependents. If FEATURE3 adds 1 to a BIGINT FEATURE2, replacing FEATURE2 with a VARCHAR definition is rejected because the downstream formula would no longer type-check.

Drops must include all affected dependents

A feature can be removed only when no feature outside the mutation still depends on it. Include the dependents in the same DROP statement or coordinate the changes in a transaction.

Lifecycle management adds another rule: a dependent feature cannot have a higher lifecycle status than its dependencies. See Feature lifecycle .

Mutations are atomic

A rejected statement leaves the registry unchanged. Persist transactions extend that guarantee across coordinated creates, replacements, and drops: FeatureQL validates the final graph and applies the net change together. They never include TEMPORARY mutations — that overlay is a different request shape, documented under Statement tools .

A safe change workflow

1. Use IS_DOWNSTREAM_OF() to find the features a change could affect.
2. Inspect their formulas and types with SHOW FEATURES.
3. Use CREATE OR REPLACE for a compatible update, or a transaction for a coordinated graph change.
4. Evaluate representative features on the target backend after the mutation. Registry consistency protects definitions and dependencies; it cannot guarantee that external data sources are available or that runtime data satisfies every operational expectation.

Next

Use Explore features for impact analysis, or Drop features when a change requires removing definitions. The transaction syntax reference covers coordinated mutations. To try a change without writing HEAD, see Branch overlays .