Semantic Rails guardrails

Strongly supported

graph-first package authoring
guided discovery through discover, inspect, plan, and build-options
safe fact-to-dimension traversal and ambiguous-path rejection
supported mixed-grain rewrites
historical attribute slicing with temporal-validity joins
event-count conversion metrics for the supported execution model
explainable validation, planning, and SQL lowering

Scope boundary

Semantic Rails is a semantic layer, not an ELT tool. The shipped surface is model relations, semantic joins, segments, metrics, supported predicates, compile/explain output, and package checks. A generalized pipeline for arbitrary derived relations, chained SQL, materialization orchestration, or unrestricted nested predicates is not part of the runtime contract.

Supported with explicit guardrails

Area	What works	How it fails when unsafe
Mixed grain	Planner-owned leaf rewrites for supported shapes	`MIXED_GRAIN_INVALID` or `REWRITE_NOT_SUPPORTED`
Temporal roles	Multiple clocks when bindings stay compatible	`INVALID_TEMPORAL_ROLE` or `INCOMPATIBLE_TEMPORAL_ROLE`
Metric predicates	Supported contextual and entity-only cases	`PREDICATE_SCOPE_UNSAFE` and related predicate errors
Conversions	Supported event-count model	`CONVERSION_NOT_SUPPORTED` for richer unsupported shapes

Limits

DuckDB is the zero-setup local execution backend; Snowflake execution is supported through Snow CLI or the optional native connector when a connection is configured. The other supported warehouses connect through their native connectors the same way.
metric_predicate is scoped to supported contextual and entity-only predicate shapes.
Path ranking is deterministic; it is not a fully costed planner.
Managed cloud execution-on-behalf is not part of the local runtime contract.
The API-key and request-context layer is a runtime shim, not JWT/JWKS, tenant administration, or billing.
The open-source engine has no managed acceleration, result caching, materialization or relation-pipeline runtime: execution is the warehouse's job.
The repo does not ship a broader action orchestration system.

When hard failures are expected

common blocked cases

- alias token matches multiple semantic objects
- multiple non-equivalent paths remain valid
- selected aggregation is not legal for the measure
- requested time role is invalid for the selected metric or measure
- grouped or filtered context would smear a predicate
- conversion shape falls outside the supported event-count model
- request requires arbitrary chained SQL or an unmodeled materialization boundary (out of scope per the experimental boundary above)
- no valid-values source exists for the requested dimension

A blocked query is often the correct product behavior. The site is deliberately explicit about this rather than promising silent fallback magic.

What guardrails do not cover yet

Declared value domain vs warehouse coverage. valid-values returns the authored value_domain / valid_values set for a dimension, and a dimension can advertise five categories while the warehouse only contains two. On engine 0.3.2, execute warns FILTER_VALUE_NOT_FOUND when a text is filter value matches no row the caller can read (under the default observation_scope: "dataset"). Treat the declared domain as the authoring contract, not a guarantee of warehouse coverage.
Unknown keys in package.yml. Unknown keys inside models and metrics are rejected with a "did you mean" hint (for example dimentions: or descripton:). The loader still ignores a misspelled top-level key in package.yml, such as defualts:, so the setting it names doesn't apply; on engine 0.3.2, semantic-rails project validate reports it with a "did you mean" hint. Validate the package and cross-check the catalog after parsing.

Continue to API Reference for the public routes and representative request shapes that sit on top of these guardrails.

Guardrails