EXPLAIN
EXPLAIN compiles a statement and returns planning metadata as JSON without executing the generated query or applying a mutation.
This page is the long form. The short version sits with the other statement tools: Statement tools .
Basic usage
Prefix any query with EXPLAIN:
EXPLAIN (FIELDS (STAGE, OUTPUT_SCHEMA, FEATURES)) RETURN feature1 := 1, feature2 := feature1 + 1;| JMESPATH VARCHAR | EXPECTED_VALUE VARCHAR |
|---|---|
| stage | "base" |
| output_schema[*].{name: name, type: type} | [{"name": "FEATURE1", "type": "BIGINT"}, {"name": "FEATURE2", "type": "BIGINT"}] |
| features[?name == 'FEATURE1'].function | ["VALUE"] |
| features[?name == 'FEATURE2'].function | ["ADD"] |
The result is one OUTPUT VARCHAR cell containing JSON. Use EXPLAIN (FIELDS (…)) to keep only the top-level keys you need — for example STAGE, OUTPUT_SCHEMA, FEATURES, FINAL_NODES. Unknown field names raise a stable user error.
Syntax and multi-statement forms: EXPLAIN .
Reading the plan
Typical top-level keys:
| Key | What it is |
|---|---|
STAGE | Compiler stage (base, and later rewrite stages when present) |
OUTPUT_SCHEMA | Output feature names and FeatureQL types |
FEATURES | Per-feature function, grain, dependencies, metric contracts |
FINAL_NODES | Features that appear in the result |
MUTATION_DRY_RUN | Preview of a persist mutation without saving |
Project a subset when you only need one of those. Semantic pages use EXPLAIN (FIELDS (FEATURES)) and EXPLAIN (FIELDS (MUTATION_DRY_RUN)) — Units and measures , Metric summarizability .
Request-local overlay
CREATE TEMPORARY builds a request overlay: later RETURN, SHOW, DESCRIBE, and EXPLAIN in the same request see those names, and the registry is unchanged.
EXPLAIN START TRANSACTION; …; COMMIT; and FORMAT START TRANSACTION; …; COMMIT; are request prefixes: they explain or format the trailing result against the overlay. They do not write the registry.
A lone CREATE TEMPORARY plus RETURN can stay unwrapped. Several overlay mutations need START TRANSACTION / COMMIT, and the last inner statement must be the result you want.
Do not mix persistent CREATE / ALTER / DROP with TEMPORARY in the same script (UE/TRANSACTION-INVALID-SHAPE). Publish with a persist-only transaction instead — Create features . Script shapes: Transactions . Overlay also appears after SHOW CREATE on Statement tools .
See also
- Statement tools
- Feature metadata — mutation dry-run use cases
- Python library tools —
validate()anddiagnose()useEXPLAIN