Reveals

A Reveal is how Celiq turns a raw measure into a business metric people can trust. Instead of every analyst rebuilding "net revenue" from columns, a Weaver defines revenue once — as a Reveal — and the whole workspace (Orion, the Catalog, Mosaics) uses that single definition.

Reveals are not stored in their own table. They live inside each domain's CML, under a reveals: array, and Celiq flattens them across every domain when it builds the metrics catalog.

Overview

Each domain owns a list of Reveals. A Reveal points at a primary node (the table/node the metric is anchored to) and carries everything needed to describe and run the metric: a human label, a description, a default time grain, suggested attributes and metrics, optional filters, AI context, and sample queries.

When a user opens the metrics catalog, Celiq reads every domain's CML, pulls out each domain's reveals: array, and merges them into one flat list (catalogService.listReveals). Each flattened Reveal is enriched with three things:

• Certification — whether a Weaver has signed off on the definition (from the reveal_certifications table).
• Usage counts — how many Mosaic tiles use it and how often it has been queried (derived from mosaic_tiles and query_logs).
• Conflict status — whether another domain defines a Reveal with the same name but a different meaning.

Reveals with no description, no usage, and no certification are treated as auto-generated stubs and hidden from the catalog, so the list only shows metrics that carry real signal.

When to use it

Define a Reveal when a metric is a shared concept, not a throwaway calculation:

• The number appears in board reporting, weekly reviews, or multiple Mosaics — and everyone must compute it the same way.
• You want Orion to recognize the metric by name and answer questions about it accurately.
• You want to certify the metric so consumers can see it has been reviewed and approved.
• You want the metric to be discoverable in the Catalog and packageable into the Marketplace.

If you only need a measure for a single chart and it has no business meaning beyond that chart, a node-level measure is enough — you do not need a Reveal. See Concepts for the distinction.

Concepts

Getting started

Prerequisites:

• A domain already exists in Forge with at least one node and the measures you want to surface. See Domains.
• You have the Weaver or Luminary role to author or certify Reveals.

To open the authoring surface:

1. Open Forge and select the project and domain you want to edit.
2. Edit the domain's CML and add (or extend) the reveals: array.
3. Run the Check & Save gate to validate and save.

To review existing Reveals, open Context Studio and go to the Metric definitions section — it lists every Reveal grouped by domain, with certified / needs-review / conflict badges.

Step-by-step

Examples

A worked Reveal in a domain's CML. This defines the revenue Reveal anchored to the orders node, with a default grain, suggested attribute and metric, AI context, and sample queries:

domain: ecommerce
label: "Ecommerce"
nodes:
  - name: orders
    physical_table: DW_PROD.OMS.FCT_ORDERS
    measures:
      - name: total_revenue
        sql: "SUM(CASE WHEN status NOT IN ('cancelled','returned') THEN revenue_usd ELSE 0 END)"
        type: currency
        description: Net revenue excluding cancelled and returned orders.

reveals:
  - name: revenue
    label: "Revenue"
    description: "Total order revenue over time, excluding cancellations and returns."
    primary_node: orders
    default_grain: day
    suggested_attributes:
      - node: orders
        attribute: order_date
    suggested_metrics:
      - node: orders
        metric: total_revenue
    ai_context: >
      Always use total_revenue (not gross_revenue) as it excludes returns and cancellations.
      US drives approximately 65% of total revenue. Return rate above 15% triggers a P1 alert.
    sample_queries:
      - "What was revenue last month by region?"
      - "Show me daily revenue for Q2"

Note how the Reveal's total_revenue under suggested_metrics points at the node-level measure of the same name — the Reveal promotes that raw measure into a named, shared business metric.

Best practices

• Always write a real description. It is what distinguishes a meaningful Reveal from an auto-generated stub — undescribed, unused, uncertified Reveals are hidden from the catalog.
• Keep names consistent across domains. If two domains genuinely mean the same thing by revenue, give them matching descriptions so they are not flagged as a conflict.
• Anchor to the right primary node. resolveReveal returns the reveal together with its primary_node; the wrong node sends queries to the wrong table.
• Invest in ai_context. This is where you tell Orion the caveats (what to exclude, attribution limits, alert thresholds) so it answers accurately.
• Certify once the definition is stable. Certification is a trust signal for Tracer and Lens consumers — certify deliberately, not by default.

Tips

Common mistakes

Troubleshooting

Related pages

• Domains — the container that owns a Reveal's reveals: array.
• Metrics — node-level measures and calculated metrics that Reveals build on.
• Catalog — where certified Reveals become discoverable to consumers.
• Marketplace — packaging Reveals into installable domain packs.
• Certifications — the certification model across semantic objects.