Confidence and provenance

Orion never hands you a number without telling you where it came from. Under each data answer you get a small provenance line — the source name, a freshness label, and a colored confidence badge — that you can expand into a full provenance card. This is how you tell a certified, governed answer apart from a raw-SQL one-off, without re-deriving the number yourself.

The confidence badge reflects the source tier Orion drew from, not how confidently the answer is worded. A fluent, assertive paragraph built on raw SQL is still Low confidence; a terse number pulled from a certified reveal is High. Trust the badge, not the prose.

Overview

Every Orion data answer ends with a provenance footer. When Orion has structured provenance, it renders as a compact one-line summary you can expand into the full provenance card:

• A source — either the reveal name (a dotted-underline link to the catalog) or the source tier (Semantic layer, Raw SQL, or Memory).
• A freshness label — "through <date>", where the date is the most recent date present in the data Orion actually queried.
• A confidence badge — High (green), Medium (amber), or Low (red).
• Optional chips — a warnings count, and a green "Certified" check when the reveal is certified.

Expanding the card reveals the supporting detail: who certified the reveal, the tables used, any data-quality warnings, and a "SQL reviewed and corrected" note when Orion's reviewer fixed the query. The card also gives you jump links to View in Discover, Context Studio, and the evals.

When to use it

• Before you trust a number. Glance at the badge color. High means it came from a certified reveal; Medium and Low both carry a "verify before sharing" caveat.
• Before you share an answer upstream. Expand the card and confirm the source, freshness, and certification. A Low-confidence raw-SQL answer is fine for exploring, but say so when you pass it on.
• When a number looks off. Check the freshness label first — the data may simply end earlier than you assumed. Then check the tables used and any warnings.
• When two answers disagree. Compare their source tiers. A certified reveal should win over a raw-SQL answer to the same question.

Concepts

How confidence is derived

Confidence maps directly from the source tier — it is not a judgement about how well-written the answer is:

The High/Medium/Low tier is what you see; the 0.9 / 0.6 / 0.3 value is recorded on the analytics event for measuring answer quality over time. Data-quality findings can pull a tier down — a strong warning or a failed quality check drops the answer to Low, and lesser warnings can drop a High answer to Medium.

Getting started

There is nothing to enable — provenance ships on every Orion data answer automatically.

Step-by-step

Examples

A certified-reveal answer renders a footer like this (the plain-text form Orion appends to its message):

---
Source: weekly_revenue · Freshness: data through 2026-06-20 · Confidence: high

The structured provenance behind that footer, which drives the badge and card, looks like:

{
  "source_tier": "semantic_layer",
  "reveal_name": "weekly_revenue",
  "reveal_domain": "sales",
  "freshness": "2026-06-20",
  "confidence": "high",
  "tables_used": ["orders", "order_lines"],
  "warnings": [],
  "certified_by": "amir@acme.com",
  "certified_at": "2026-05-02",
  "reviewer_fixed": false
}

A raw-SQL answer to the same question, with no reveal, carries a Low badge and a footer such as:

---
Source: raw SQL — orders · Freshness: data through 2026-06-18 ⚠️ 2 days behind · Confidence: low — data quality issues, verify before using

Honesty rules behind provenance

Two trust rules govern what Orion is allowed to say, and they are the reason provenance can be relied on:

• Observed fact vs. possible explanation. On a "why" question — "why did revenue drop?" — Orion keeps what the data proves separate from what might explain it. The contribution of each segment to a change (e.g. "Search accounted for 67% of the decline") is an observed fact. The real-world cause of that move is almost never in the data, so Orion labels it as a hypothesis with a qualifier ("a likely driver is…", "one factor may be…") and never states a cause as settled. Decomposition tells you which segment moved, never why.
• Honest date labeling. Because Orion anchors relative ranges to the dataset's latest date, it will not call a figure "yesterday", "today", "this week", or "last week" unless that exact calendar period is what the figure actually covers. Instead it labels the real date (e.g. "Jun 13" or "week of Jun 7–13") and flags when the latest data lags the real calendar.

Best practices

• Read the badge before the words. The confidence level is the source tier, not the tone of the answer.
• Promote frequently-asked questions into reveals, then certify them. Certified reveals are the only path to a High badge — see Certifications.
• When sharing a Medium or Low answer, carry the caveat with it. The footer literally says "verify before sharing upstream" for a reason.
• Always sanity-check the freshness date against the period you asked about before quoting a number.

Tips

Common mistakes

Troubleshooting

Related pages

• Accuracy and how Orion stays grounded
• AI-generated SQL
• Metric contracts
• Decision intelligence
• Certifications
• Reveals