How Celiq gets to the right answer
Six layers of accuracy, applied in order
Why use it: Understand how Celiq avoids the hallucinations that make most AI analytics tools unreliable.
Where to find it: This is an explanation of how Celiq works, not a UI feature.
Who can use it: All users benefit; Luminary can configure layers 2, 3, and 5.
How Celiq gets to the right answer
Six layers of accuracy, applied in order.
Layer 1: Semantic layer first
Before running any SQL, Orion checks your governed reveals. If a reveal exists → uses it, guaranteed canonical metric definitions. If no reveal → stops and offers to create one in Forge first.
Why: Raw SQL guesses at metric definitions. Governed reveals use the definition your team agreed on. Where to see it: Every Orion response shows a provenance footer:Source: semantic layer or Source: raw SQL.
Layer 2: Domain skills
Orion loads business rules before answering questions. These rules are stored in domain skills files — one per domain.
Example rules for ecommerce:
- Revenue = SUM(sale_price), not SUM(cost)
- Exclude cancelled orders from order counts
- AOV = revenue / COUNT(DISTINCT order_id), not AVG(sale_price)
Layer 3: Workspace memory
Orion remembers corrections across sessions. If you told Orion "AOV excludes returns" — it applies that rule every time, without you repeating it.
Five categories stored:
- Key metric definitions
- Data gotchas (always exclude X, use Y not Z)
- Past corrections
- User preferences (daily vs weekly grain)
- Active domains
Layer 4: Provenance footer
Every Orion response shows:
- Source — semantic layer (governed) or raw SQL (ad-hoc)
- Freshness — date of most recent data in the result
- Confidence — high (governed reveal) or medium (raw SQL)
Medium confidence means: verify before sharing upstream. High confidence means: uses your canonical metric definitions.
Layer 5: Adversarial reviewer
When enabled, a second AI instance reviews Orion's SQL before it runs. Catches wrong metric definitions, missing filters, incorrect joins.
Where to enable: Lumen → Orion → Advanced → Adversarial review Performance impact: Adds ~2 seconds to each response. Recommended for workspaces where accuracy is critical.Layer 6: Correction harvesting
When a user says "that's wrong" or "that number is off", Orion automatically captures it as an eval case and proposes a skill file update. Over time, the corrections build a test suite that runs automatically to catch regressions.
Where to see corrections: Lumen → Orion → CorrectionsSemantic layer routing
Why use it: Reveal-first routing guarantees that answers use your canonical metric definitions instead of SQL Orion guessed at.
Where to find it: Automatic on every Orion answer. The route taken is shown in the provenance footer.
Who can use it: All roles.
When you ask a question, Orion does not jump straight to SQL. It first matches your question against the reveals available in your workspace — their labels, metrics, dimensions, and the domains they belong to.
How reveal-first routing works
- Orion parses the intent of your question (the metric, the grain, the filters).
- It searches your active reveals for one that already defines that metric and grain.
- If a reveal matches → Orion runs the reveal. The answer uses your governed definition, and the provenance footer reads
Source: semantic layer. - If no reveal matches → Orion falls back to raw SQL generated from your CML node definitions. The footer reads
Source: raw SQLand confidence drops to medium.
Routing is metric-aware, not just keyword-aware. Asking "revenue this week" and "how much did we sell over the last 7 days" both route to the same revenue reveal, because Orion resolves them to the same governed metric.
What happens when no reveal matches
Orion never silently invents a definition. When it falls back to raw SQL, it tells you so in the footer and, for build-mode requests, stops and offers to create a reveal in Forge first. See graceful degradation in the Orion docs.
Raw SQL fallback is still grounded in your CML — Orion only references tables, columns, and joins that exist in your node files. It cannot query tables you have not modelled.
Seeing routing in the provenance footer
Every Orion response carries a provenance footer with the route it took:
Source: semantic layer · Reveal: orders_analysis · Confidence: highSource: raw SQL · Confidence: medium · No governed reveal for "campaign revenue"A semantic layer source means the number is canonical. A raw SQL source is a flag to verify the definition before sharing the number upstream.
Pairwise skills structure
Why use it: Understand where Orion's business rules come from so you can add or correct domain knowledge.
Where to find it: Lumen → Orion → Skills.
Who can use it: Luminary edits skills; all roles benefit from them.
Orion's business knowledge is not one giant prompt. It is split into small, composable files per domain so that only the rules relevant to your question are loaded. This keeps Orion's context small (fast, cheaper) and accurate (it never confuses, say, finance rules with marketing rules).
File layout
Each domain is a folder under your workspace's skills directory:
skills/
_router.md
orders/
knowledge.md
references/
revenue-definitions.md
refund-handling.md
marketing/
knowledge.md
references/
attribution.md
finance/
knowledge.md| File | Purpose |
|---|---|
_router.md | The top-level index. Maps incoming questions to the right domain(s). Loaded on every request. |
<domain>/knowledge.md | The core business rules for one domain — metric formulas, gotchas, exclusions. |
<domain>/references/*.md | Deeper reference material loaded only when the domain is active and the topic is relevant. |
How a question is routed to skills
- Orion reads
_router.mdand decides which domain(s) the question belongs to. - It loads that domain's
knowledge.md. - If the question touches a referenced topic (e.g. refunds), it pulls in the matching
references/file. - Only then does it select a reveal or write SQL.
This is the "pairwise" part: the router pairs each question with exactly the domains it needs, rather than loading everything every time.
How to add a new domain
- Go to Lumen → Orion → Skills.
- Click New domain and give it a name (e.g.
subscriptions). - Add the core rules to its
knowledge.md— metric formulas, things to always exclude, preferred grains. - Optionally add
references/files for deep topics. - Update
_router.mdso questions about the new area route to your domain.
Celiq ships with a standard skill set for ecommerce, SaaS, marketplace, and fintech. Edits you make are scoped to your workspace and never overwritten by upstream updates.
Data quality checks
Why use it: Avoid acting on a number that is stale or built from a partially loaded table.
Where to find it: Automatic. Surfaces as a ⚠️ indicator on tiles and in the provenance footer.
Who can use it: All roles.
Before Orion returns an answer — and before a mosaic tile renders a KPI — Celiq runs a lightweight check on the underlying data: is it fresh, and is it complete?
Freshness thresholds
Celiq compares the most recent date in the result against the current date and assigns one of three states:
| State | Meaning | Indicator |
|---|---|---|
| Fresh | Most recent data is within the expected load window | No indicator |
| Stale | Data is older than expected but within tolerance | ⚠️ amber, "Data may be stale" |
| Very stale | Data is well past the expected load window | ⚠️ amber, "Data is very stale — last loaded {date}" |
The expected window is derived from the table's normal load cadence (a daily-loaded table is "stale" sooner than a monthly one).
What the ⚠️ tile indicator means
When a mosaic tile or an Orion answer shows a ⚠️ icon, hover it to see the reason:
- Stale data — the source table has not loaded as recently as expected.
- Incomplete period — the latest period is still filling (e.g. today's partial data) and may understate the metric.
- Row count anomaly — the result returned far fewer rows than the previous run.
The number still renders — the indicator is a caution, not a block.
How to interpret confidence levels
The provenance footer pairs the freshness check with a confidence level:
- High — governed reveal, fresh data. Safe to share.
- Medium — raw SQL or stale data. Verify before sharing upstream.
A high-confidence reveal on stale data still shows the ⚠️ freshness indicator — the definition is trustworthy, but the underlying data is behind.
Passive monitoring
Why use it: See, at a glance, how governed your workspace is — and which questions keep falling back to raw SQL.
Where to find it: Lumen → Orion → Coverage.
Who can use it: Luminary and Weaver.
Every time Orion answers a question, Celiq records whether it routed to the semantic layer or fell back to raw SQL. Over time this builds a coverage picture of your workspace — with no extra work from you.
What the coverage % means
Coverage is the share of recent questions that were answered from a governed reveal rather than raw SQL:
Coverage = semantic-layer answers / total answers (last 30 days)A coverage of 85% means 85% of questions used canonical definitions. The remaining 15% used raw SQL fallbacks — those are the gaps in your semantic layer.
How to improve coverage (add reveals)
The Coverage panel lists the most common questions that fell back to raw SQL, grouped by the metric they were asking for. Each group shows:
- The metric or concept being asked about
- How many times it fell back in the last 30 days
- A Create reveal button that opens Forge pre-scoped to that metric
Building a reveal for a frequently-asked, ungoverned metric is the fastest way to raise coverage. The next time someone asks, Orion routes to the new reveal.
Understanding fallback reasons
Each fallback is tagged with a reason so you know why the semantic layer was bypassed:
| Reason | What it means | Fix |
|---|---|---|
no_reveal | No reveal defines this metric | Create a reveal in Forge |
grain_mismatch | A reveal exists but not at the requested grain | Add the grain (e.g. daily) to the reveal |
filter_unsupported | The reveal cannot express the requested filter | Add the dimension to the underlying node |
ambiguous | Multiple reveals could match | Disambiguate names or merge definitions |
Silent-failure KPI checks
Why use it: Pipelines fail quietly. A KPI that silently returns half its real value is worse than one that errors loudly.
Where to find it: Lumen → Orion → KPI Health.
Who can use it: Luminary and Weaver.
A "silent failure" is when a metric keeps returning a number, but the number is wrong — a join broke, a filter changed, or an upstream table only partially loaded. Nothing errors. The dashboard looks fine. Celiq runs a daily check to catch exactly this.
How blessed KPIs are selected
Celiq does not check every metric — it checks your blessed KPIs: the small set of metrics that matter most. A KPI becomes blessed when:
- It is used in a pinned mosaic or a role-based briefing, and
- It is backed by a governed reveal.
You can also bless or unbless a metric manually in Lumen → Orion → KPI Health → Manage KPIs. Keeping the blessed set small keeps the daily check fast and the alerts meaningful.
Understanding the KPI Health panel
The KPI Health panel lists every blessed KPI with:
- Its current value and the prior day's value
- The day-over-day change
- A status badge: OK, Watch, or Anomaly
- The date the value was last verified
KPIs that fail the check rise to the top of the panel and are included in the next morning briefing.
Anomaly thresholds
The daily check flags a KPI when its day-over-day change crosses a threshold:
| Change vs prior day | Status |
|---|---|
| Under 20% | OK |
| 20%–50% | Watch — surfaced in the panel |
| Over 50% | Anomaly — surfaced in the panel and the morning briefing |
A KPI that drops to zero or returns no rows is always flagged as an Anomaly, regardless of percentage, because that is the classic signature of a broken pipeline.
User corrections and the Corrections panel
Not every flagged change is a failure — sometimes a 60% jump is real (a big launch, a seasonal spike). When you mark a flagged KPI as Expected, Celiq records the correction so it does not re-flag the same legitimate movement.
These corrections live in the Corrections panel (Lumen → Orion → Corrections), alongside the corrections Orion harvests from chat. Over time the corrections tune the check to your business's real rhythms — reducing false alarms while still catching genuine silent failures.