> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prodexlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Results
> Analyze simulation output with KPIs, charts, and direct SQL queries over run-level event data.
## Overview
Every simulation run produces a persistent results dataset: event-level tables plus the **KPIs** and **charts** authored on the model, computed automatically when the run finishes. Results are stored permanently and opened from the run's Results page.
The Results page is **scoped to a single run**. Cross-configuration comparison lives in [Experiments](/product/experiments); repeated-seed variability analysis lives in [Monte Carlo](/product/monte-carlo). Durable dashboards that don't depend on any single simulation live in [Insights](/product/insights).
Every chart and KPI belongs to one view — a run's Results, Experiments, or Monte Carlo — and renders only there. Experiments and Monte Carlo aren't just aggregations of run-level charts: each view carries its own authored charts and KPIs.
## KPIs
A KPI is a **SQL query that returns one row with a single `value` column**, plus a required **format type** that tells the UI how to render it. There is no separate "text KPI" type — a status-style label is just a `category`-formatted KPI.
| Family | Format types |
| ----------- | ---------------------------------------------------------------------------------------------- |
| Numeric | `integer`, `decimal`, `compact` (1.2K / 3.4M), `percentage`, `currency` |
| Duration | `duration`, `duration_min_sec`, `duration_hour_min`, `duration_day_hour`, `duration_month_day` |
| Time & date | `clock_hour_min`, `datetime`, `date` |
| Text | `category` (status labels like "On target", "At risk") |
The palette has ten colors (`blue`, `orange`, `green`, `red`, `purple`, `yellow`, `cyan`, `brown`, `gray`, `lime`), but four of them carry a documented **semantic** meaning: `red` for higher-is-worse (defects, downtime), `green` for higher-is-better (yield, throughput), `gray` for context or baseline, `blue` for neutral. The rest are neutral palette options. An optional **unit** suffix renders alongside the value.
### Authoring and inspecting KPIs
KPI results appear as cards at the top of the Results page. Hovering a card reveals a kebab `⋮` menu with two items:
* **View source code** — opens a modal showing the formula header in a tinted box, a plain-English description, and the underlying SQL with syntax highlighting.
* **Delete** — removes the KPI from the model.
The **+ Create KPI** dashed tile opens a Dexter dialog (*"Describe the metric you want to track and the AI will build it."*) with a single textarea and Cancel/Create buttons. Describe the metric in natural language and [Dexter](/product/dexter/chat-and-tasks) writes the SQL against the [results dataset](#querying-simulation-data) and saves the KPI to the model. KPIs are authored through Dexter, not by writing SQL directly in the UI.
## Charts
The Add Chart picker exposes thirteen chart types: **Line**, **Area**, **Stacked Area**, **Bar**, **Stacked Bar**, **Pie**, **Scatter**, **Histogram**, **Heatmap**, **Gantt**, **Table**, **Box Plot**, and **Mixed**.
**Charts on a run are static snapshots, not live queries.** Each chart's data is computed once and committed when the run finishes. The chart's query is durable — what refreshes is the *evaluation*: any new run of the model automatically evaluates every existing chart query against it, and an existing run can be recomputed on demand (ask Dexter to recompute the run).
Each chart carries:
* A SQL **query** and an `x_key` naming the x-axis column.
* One or more **series**, each with a key, optional label, a color from the palette, and a per-series format. On **Mixed** charts each series also carries its own type (`line`, `area`, `bar`, or `scatter`), so one chart can combine bars with a trend line.
* Optional **axis formats and labels** (`x_format` / `y_format`, `x_label` / `y_label`). The axis format vocabulary is the same as KPIs, so any numeric axis can render as a duration, currency, percentage, clock time, or date.
* The **view** it belongs to — a run's Results, Experiments, or Monte Carlo — which decides where it renders.
The **+ Create chart** tile opens a Dexter dialog with a **Chart type** dropdown that defaults to *Any (optional)* — leave it and Dexter picks the type, or pin a specific one. Like KPIs, charts are authored through Dexter rather than a manual editor.
### Per-chart actions
Hovering a chart reveals an **expand icon** and a **kebab `⋮` menu** in the top-right corner. The kebab menu has three items: **View source code**, **Download chart** (image export), and **Delete** (immediate, no confirmation).
**View source code** replaces the rendered chart in place with a three-part panel: the formula header in a tinted box, a plain-English description, and the SQL that produced the chart. Every number on the page is traceable back to its query without leaving the view.
**The expand icon** opens a fullscreen modal with the chart on the left and the source panel (formula + description + SQL) on the right.
## Charts vs Insights
Charts and [Insights](/product/insights) share one rendering contract — the same chart types, axis formats, colors, and series vocabulary. They differ in where the data comes from:
| | Chart | Insight |
| ----------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Data source | SQL `query` run against a run, experiment, or Monte Carlo dataset | Inline `data` committed once, independent of any simulation |
| Extras | Per-run recomputation | Composite builders (`distribution`, `breakdown`, `breakdown_over_time`, `trend`, `pareto`, `schedule`) and transforms (`stack`, `overlay`, `to_pie`), with derivation recorded via pipelines |
## Querying Simulation Data
KPIs and charts aren't preconfigured dashboards: they're **SQL queries** against the event tables the simulation engine writes for every run. Any question the event data supports is a query away — and [Dexter](/product/dexter/chat-and-tasks) writes those queries when you describe the metric you want.
Every event table carries a `timestamp` (float, simulation seconds) and a global `event_seq` (strictly increasing across all event tables).
Use `ORDER BY timestamp, event_seq` for deterministic event ordering — `timestamp` alone can tie when multiple events fire at the same simulation instant.
### Event tables
One row per event; all carry `timestamp` and `event_seq`.
| Table | What it records |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `entity_lifecycle` | Entity created / terminated events — the main source for throughput, cycle time, and flow metrics |
| `entity_movements` | Inter-component handoffs, for flow analysis and path reconstruction |
| `process_activity` | Process started / completed events — the source for utilization and bottleneck analysis |
| `resource_activity` | Capacity-slot state transitions (`free` / `waiting` / `working` / `retired`) |
| `buffer_activity` | Buffer enter / exit and pause / resume — the source for WIP and queue-length metrics |
| `station_activity` | Entity station enter / exit |
| `station_occupancy` | Per-slot-type occupancy changes at stations |
| `state_variable_activity` | [State variable](/reference/events#state-variables) assignments (hook, listener, scheduled, initial) |
| `topic_activity` | Emit actions (`schedule` / `hook` / `listener` / `bridge`) |
### Context tables
No `timestamp` / `event_seq` — static context you join against.
| Table | What it holds |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `component_lookup` | Every component, entity type, state variable, and topic — resolves IDs to names |
| `component_input_entity_type` / `component_output_entity_type` | Per-component entity type wiring |
| `entity_attribute` | Attribute sets keyed by `attributes_hash`; join through `entity_lifecycle.attributes_hash` to slice metrics by attribute |
| `entity_lineage_edge` | Parent → child entity edges from transformations |
| `event_lookup` | [Event hook](/reference/events#event-hooks) and listener action rules |
| `schedule_definition` | Scheduled material releases, assigns, and emits |
| `advisories` | Post-run advisory codes, aggregated by code and component |
| `metadata` | Single-row run context: `run_id`, `model_id`, `duration_seconds`, `total_entities_created`, `total_events_processed`, `dataset_generation_time_seconds`, plus `schedule_id` / `schedule_start_time` on scheduled runs |
**Every run materializes the full table set.** Tables a run didn't exercise come back as zero-row views, not missing tables, so a query against them is always valid. Only legacy runs from before this behavior may lack unexercised tables.
## The Run Page
Opening a run lays the page out as:
* **Top bar** (left to right): back arrow, model name, run name (inline-editable — click to edit, Enter saves, Escape cancels), run date, and a trash icon that deletes the run.
* **Top-bar actions** (right side): **Simulation Event Log**, **Export PDF**, **Monte Carlo**.
* **KPI cards**, then **charts**, each with the hover actions described above.
* A vertical **AI Assistant** rail tab on the right edge that reopens the Dexter chat panel.
### Simulation Event Log
The **Simulation Event Log** opens as a right-side slide-in drawer with an **Export** button and close (X) in the header and a search input that filters rows in place. Each row shows the time, the queue or area, and the event, covering both flow events (entity created, process started, entity routed) and every [event hook](/reference/events#event-hooks) firing. Use it to debug event-driven behavior, validate routing decisions, or confirm scheduled actions fired when expected.
## Monte Carlo
Monte Carlo has its own **Monte Carlo** item in the sidebar, and is also reachable from the **Monte Carlo** button in a run's top bar. From the empty state, **Run Monte Carlo** opens a modal with an **N Runs** input (default **100**, range **1–1,024**) and a **Run Simulation** button.
The first thing you see on the Monte Carlo view is a set of **per-KPI summary cards** that render automatically for every multi-seed run. Each card reports five values across the seeds — **mean**, **standard deviation**, **min**, **max**, and **median** — for that KPI. These summary cards are structurally privileged: the view keeps them regardless of what else you author, so don't try to delete or rename them. Any additional charts and KPIs you author for the Monte Carlo view render alongside them against the aggregated dataset across seeds.
The seeded summary reports mean/standard-deviation/min/max/median only — not quartiles or tail percentiles. To read a specific percentile like p95 or p99, author a chart or KPI that computes it (for example with `QUANTILE_CONT`) against the seed-level data.
100 seeds is the right starting point for most models; push to 200+ when you care about tail metrics. See [Monte Carlo](/product/monte-carlo) for reading distributions, percentiles, and confidence.
## Exporting Results
* **Export PDF** — the top-bar button produces a branded report with KPI summaries, charts, and narrative. The same artifact can be requested conversationally from Dexter when you want to tailor what's included.
* **Event log export** — the Simulation Event Log drawer's own Export button produces the raw event data.
* **Per-chart image** — every chart's kebab menu has a **Download chart** action.
* **Excel / CSV** — there is no top-bar spreadsheet export; ask Dexter (*"Export the results to Excel"*) and it generates one from the underlying tables.