Metric Studio

Metric Studio is the authoring surface for turning metric intent into governed metric context. It is where a business owner, analyst, or analytics engineer can describe a metric, import existing SQL, or start from a template, then use AI clarification to crystallize the work into a structured definition that can move through validation, governance, release, registry discovery, and API consumption.

Use this page for the public operating model. The product page explains the value proposition at a higher level: Metric Studio feature page.

Metric Studio is not a free-form prompt box that quietly creates production logic. It is a structured authoring workflow. The important output is a metric artifact with explicit business meaning, owner context, source assumptions, grain, filters, lifecycle state, template lineage when present, validation readiness, and reasoning that future reviewers can inspect.

Authoring entry points

Metric Studio supports three common starts because teams rarely begin with a perfect blank page.

Describe a metric

Use Describe a metric when the owner knows the business question but not the final implementation. The first input should name what is being measured and why it matters. Good starting details include the business event being counted, the entity or grain, the time window, common exclusions, and the consumer who will rely on the answer.

For example, a useful draft prompt is not just "monthly active customers." It should say whether a customer is active because they logged in, created a record, generated revenue, or crossed another threshold. It should also state whether test accounts, internal workspaces, trials, cancelled customers, or free-tier customers are included.

The AI guide then asks targeted clarifying questions. Those questions are meant to move implicit business knowledge into durable context before SQL or release review hardens the definition.

Import SQL

Use Import SQL when the team already has a warehouse query, dashboard calculation, notebook snippet, or semantic-layer measure that people trust enough to preserve. SQL import treats the SQL as source context, not as proof that the metric is governed.

Imported SQL can help ClariLayer extract the candidate calculation, source tables, filters, joins, time semantics, and aggregation pattern. The author still needs to explain the business intent in plain language, identify the owner, resolve exclusions, and decide whether the imported logic should become a new metric, replace an old metric, or become a managed variant of an existing one.

SQL import is especially useful for migration work. It brings existing logic into the Metric Lifecycle Management path without asking teams to rewrite every metric from scratch. Once imported, the definition can be clarified, checked for overlap, validated against warehouse reality, reviewed under the appropriate governance rule, and released like any other metric.

Start from a template

Use Start from a template when the metric follows a known business pattern. Built-in templates provide reusable starting structure for common metrics such as MRR, churn, ARR, NRR, pipeline, and other recurring operating patterns. A template can pre-seed guided questions, default fields, expected grain, common exclusions, governance constraints, and optional SQL-generation context.

Templates should accelerate authoring without hiding decisions. A template answer still needs the team to confirm the owner, source assumptions, fiscal calendar, dimensions, filters, consumer context, lifecycle target, and any exceptions that make the definition different from the default pattern.

How templates should be used

A template is a reusable starting point for metric definition. It can encode domain expertise, required fields, guided questions, default values, governance constraints, and a SQL template link. The selected template becomes part of the authoring context, so reviewers can see which template influenced the metric.

There are two public template categories to understand.

Built-in templates are system-provided starting points. They are intended to cover common metric patterns and are treated as published templates. They give teams a consistent baseline for frequently repeated definitions.

Org-created templates are organization-specific starting points. They are useful when a company has a recurring internal definition pattern, a domain convention, or a governance requirement that built-in templates cannot capture. Org templates can be created or forked from published templates, then managed through a governance path before they are used broadly.

The high-level lifecycle for org templates is draft, pending approval, published, and deprecated. Rejected templates return to draft for revision. Only draft templates should be edited or deleted. Publishing a template means the organization has approved it as a reusable authoring pattern; it does not automatically approve every metric created from it.

Template versioning should be treated carefully in public docs. A template can influence authoring, but the metric's own definition version, lifecycle state, validation evidence, and release history remain the trust contract for downstream consumers.

Clarification and crystallization

After an author chooses an entry point, the AI guide helps close gaps in the definition. Useful clarification areas include:

• Metric purpose and primary consumer.
• Business owner or owning team.
• Included and excluded populations.
• Grain, time bucket, and fiscal calendar assumptions.
• Source table or catalog assumptions.
• Filters, dimensions, and grouping behavior.
• Whether the metric is base or derived.
• Governance tier and release expectations.
• Related metrics, conflicts, replacements, or variants.

The author should answer enough questions for a reviewer to understand the definition without reconstructing the conversation from memory. If a decision is uncertain, it is better to mark the caveat explicitly than to bury it in SQL.

Crystallization turns the conversation into a structured metric definition. That structured definition is the artifact that can be validated, reviewed, released, discovered in the registry, and read through the public API. The conversation is not discarded. The reasoning trail remains attached so later readers can see how the definition reached its current shape.

Structured definition concepts

A useful Metric Studio output should make these concepts visible:

name

Human-readable metric name. Prefer a name that is specific enough to distinguish variants, such as "Finance Net Revenue" rather than a vague "Revenue."

description

Plain-language meaning. This should explain what the number means before it explains how the SQL works.

owner

Person or team accountable for the business meaning and future review.

policy_tier

Governance tier or policy class. This helps determine how much evidence and approval is needed before release.

metric_type

Base metrics are computed directly from warehouse logic. Derived metrics are computed from other metrics through a composition expression.

grain and time_semantics

The entity, time bucket, fiscal calendar, and time-window rules that make the metric interpretable.

filters and exclusions

The inclusion and exclusion rules that prevent hidden differences between dashboards, teams, and agents.

source_refs

Warehouse tables, catalog references, or imported SQL context used to shape the definition.

template_id

Optional template reference when the author started from a built-in or org-created template.

relationships

Links to other metrics, such as a variant, replacement, conflict, related metric, or derived input.

Overlap checks during authoring

Metric Studio should not encourage teams to create a new churn, ARR, pipeline, or activation metric without checking what already exists. The authoring flow can surface candidate duplicates and related definitions from the registry so the author can reuse an existing metric, create a managed variant, or mark a relationship deliberately.

Early overlap detection is cheaper than cleanup later. It helps teams decide whether they are making a new metric, replacing an older one, creating a domain-specific variant, or composing a derived metric from approved inputs.

Reasoning trail

The reasoning trail preserves the human explanation behind the structured definition. It can include questions, objections, clarifications, approval rationale, and caveats that should survive the handoff from business owner to reviewer to downstream consumer.

Not every note should become agent-readable context. Use pinned notes for facts that should travel with the metric into AI-agent or API consumption, such as "Finance approved UTC month boundaries for board reporting" or "Free-tier customers are excluded until the retention policy is revised."

Read the Reasoning Trail concept

What happens next

Metric Studio creates the authoring artifact. The rest of the lifecycle makes it trustworthy.

1. Use the Metric Registry docs to check existing definitions, variants, relationships, and trust signals.
2. Use warehouse validation to prove the definition against connected data where available.
3. Use governance review to approve the appropriate release candidate.
4. Use the API v1 docs and metrics contract endpoint when downstream tools or AI agents need to read the released context.

The goal is not to make authoring magical. The goal is to make metric meaning explicit, reviewable, versioned, and reusable.