Warehouse Validation

Warehouse validation is the check step between authoring a metric and trusting it as reusable context. Validation checks whether the authored metric still matches warehouse reality before a definition becomes trusted context.

This page covers the public operating model. The product page explains the value proposition at a higher level: Warehouse Validation feature page.

Validation is not a generic claim that a metric is correct forever. It is evidence that a specific candidate was checked against available warehouse context at a specific point in the lifecycle. A metric can still need owner review, approval, release handoff, or later revalidation when source data changes.

What validation proves

Validation is meant to answer practical questions before a metric reaches a dashboard, semantic layer, AI agent, or release bundle.

• Does the metric reference sources that exist in the connected warehouse catalog?
• Does the generated or imported SQL compile for the selected warehouse dialect?
• Do bounded probes find obvious source, type, null, uniqueness, or join-shape issues?
• Is the result evidence fresh enough for the policy tier and release target?
• Should reviewers trust the metric, ask for changes, or block promotion until evidence is refreshed?

This is different from reading a wiki page or trusting an old dashboard query. Warehouse validation connects the stated business definition to the current warehouse surface. It does not make an unreviewed metric canonical by itself.

Catalog context

Metric authoring often starts with business language: "active customer," "net revenue," "pipeline created," or "retained account." Validation needs that language to meet real schemas, tables, columns, and warehouse dialect behavior.

ClariLayer uses catalog context from connected Databricks, Snowflake, and BigQuery warehouses to ground validation. Catalog browse and refresh surfaces help the workflow understand available schemas, tables, and columns before SQL is compiled or probed. That context helps the authoring and review flow avoid obvious misses, such as referencing a column that no longer exists or assuming a table name from a previous warehouse model.

Catalog context is still context, not final proof. A table can exist while the metric logic is still wrong for the business question. The validation report should therefore sit beside the business definition, owner, policy tier, reasoning trail, relationships, and release history.

SQL compilation and probes

Validation uses targeted checks rather than open-ended warehouse execution. The public model is:

1. Resolve the metric definition and warehouse connection context.
2. Compile or render the SQL for the selected adapter and dialect.
3. Run bounded, write-nothing probes where a live connection is available.
4. Record validation evidence on the metric version.
5. Let the policy tier and release gate decide what can move forward.

The checks focus on failures that are expensive to discover late: missing sources, broken SQL compilation, type mismatches, unexpected null behavior, uniqueness assumptions, and other basic integrity issues. The goal is enough evidence for governance, not an unbounded data-quality platform or a blank check against the warehouse.

Imported SQL follows the same principle. Importing a trusted query is useful authoring context, but it is not the same thing as validation evidence. The imported logic still needs to compile in the selected warehouse context and pass the checks required for the metric's policy tier.

Validation evidence

Validation evidence belongs with the candidate being reviewed and the release bundle that carries it forward. It should not live only in a temporary console log, chat message, or one-off ticket. A later reviewer should be able to inspect which warehouse surface was used, when the check ran, whether it passed, and what caveats remain.

That candidate attachment matters because metric meaning can change. If the finance definition of revenue changes exclusions, time-window semantics, or source assumptions, the next candidate should carry refreshed evidence. Reusing old proof for a meaning-changing edit would make downstream users and agents trust the wrong contract.

Evidence is also a trust signal for the registry and API. A consumer can treat a released metric with current validation evidence differently from a draft, unverified metric, stale metric, or metric blocked from release. AI agents should preserve that distinction instead of treating every matching metric name as authoritative.

See how the metrics contract exposes validation evidence

Policy tiers

Validation requirements scale with risk.

Tier 0 Experimental metrics can move quickly. They are useful for internal exploration, early analysis, and lower-risk experimentation. They still need standard checks before release, but the governance posture is lighter than higher-stakes metrics.

Tier 1 Operational metrics are used for day-to-day decisions. They should have warehouse validation before release, and policy can require owner approval or additional review depending on the workflow.

Tier 2 Financial metrics carry the highest scrutiny. They are used for board-level, finance, or externally sensitive decisions. They should not be promoted without the required validation evidence and review path.

Policy tiers do not change the basic truth of validation: evidence should travel with the reviewed candidate, and release review should treat missing, stale, or mismatched evidence as a blocker rather than proof.

Shared warehouse path

The shared warehouse product path covers catalog browse, validation probes, direct deployment, and rollback across Databricks, Snowflake, and BigQuery. For catalog and validation capability, treat those three warehouses together.

There is one important monitoring boundary: Observe and query-history ingest are narrower today. Live Observe/query-history ingest is Databricks-only. Snowflake and BigQuery share catalog, validation, deployment, rollback, registry, and API context paths, but they do not yet share the live query-history loop that powers Observe evidence.

That distinction keeps the public claim accurate. A Snowflake or BigQuery metric can be authored, grounded in catalog context, validated, released, deployed through the allowed direct-deploy boundary when eligible, rolled back, and exposed through the API. It should not be described as having Databricks-style live Observe/query-history ingestion until that parity exists.

How validation fits the lifecycle

Validation is one step in Metric Lifecycle Management:

1. Author or import the metric in Metric Studio.
2. Check the registry for existing definitions, variants, and dependencies with Metric Registry.
3. Validate the candidate against connected warehouse context where available.
4. Review validation evidence and approval expectations in Governance and Release.
5. Release the approved version or revise the candidate before downstream use.

This keeps the system honest. Validation does not replace governance. Governance does not replace validation. Together they turn a metric from an authored definition into a versioned, evidence-backed piece of context that downstream humans and AI systems can evaluate.