
CEO & Co-founder of Visivo
How to Provide Reliable BI Insights for Stakeholders
Stakeholders trust numbers they have never seen be wrong. How to get there with tests on Insights, one definition per metric, and checks that run before every deploy.

A dashboard is only useful while stakeholders believe it. The first time a number is wrong in front of someone who cares, every other number on the page becomes suspect. Gartner research puts it in dollars: "Data quality issues cost organizations an average of $12.9 million annually," primarily due to decisions made on unreliable data.
Reliability comes from three habits: validate the data, define each metric once, and check the output before anyone sees it. Visivo's code-first approach builds all three into the development process instead of adding them afterward: tests on the values your Insights compute, explicit model definitions, and validation you run in CI before every deployment.
Why trust decides whether BI works
Decisions are only as good as the data behind them. Executives allocate millions from dashboard metrics, managers restructure teams from performance indicators, and strategies pivot on trend analysis. When the numbers are off, so is every one of those decisions.
MIT research finds that "Companies using data-driven strategies have 5-6% higher productivity." That edge only exists when people trust the analytics enough to act on them.
The failures look like this:
- Strategic missteps: A 15% revenue growth target based on incorrect historical data
- Resource waste: Marketing budget reallocated based on faulty attribution metrics
- Missed opportunities: Product launches delayed due to inaccurate demand forecasts
- Cultural damage: Teams lose faith in data-driven decision making
Without trust, stakeholders build their own spreadsheets, question every number, and fall back on gut calls. The BI investment is still on the books, but nobody is using it.
Forrester research shows between 60% and 73% of enterprise data goes unused for analytics, often because stakeholders lack confidence in data quality.
Testing with Visivo
Visivo's tests run against the values your Insights compute, so a wrong number fails before it ships. This is testing before dashboard deployment, applied at the level stakeholders actually see.
Rules in the model
A model's SQL is the first place to enforce a rule. Filter out rows that cannot be valid, and compute the columns that your tests will check:
sources:
- name: warehouse
type: postgresql
host: ${env.DB_HOST}
database: analytics
username: ${env.DB_USER}
password: ${env.DB_PASSWORD}
models:
- name: revenue_analysis
source: ${ref(warehouse)}
sql: |
SELECT
DATE_TRUNC('month', order_date) as month,
SUM(
CASE
WHEN status = 'completed' AND refund_date IS NULL
THEN order_amount
ELSE 0
END
) as net_revenue,
COUNT(DISTINCT customer_id) as unique_customers,
COUNT(*) as total_orders
FROM orders
WHERE order_date >= '2023-01-01'
AND order_date < DATE_TRUNC('month', CURRENT_DATE) -- complete months only
AND customer_id IS NOT NULL
GROUP BY DATE_TRUNC('month', order_date)
Tests on Insights
A test asserts on the values an Insight computes, which are the exact values its chart shows. Tests live at the top level of the project. visivo run computes every Insight on your dashboards (the dashboard for these two is in the next section), and visivo test checks the assertions against that output. A failing test makes the command exit non-zero:
insights:
- name: monthly-revenue-trend
props:
type: scatter
mode: lines+markers
x: ?{ ${ref(revenue_analysis).month} }
y: ?{ ${ref(revenue_analysis).net_revenue} }
name: "Monthly Revenue"
hovertemplate: |
Month: %{x}<br>
Revenue: $%{y:,.0f}<br>
Customers: %{text}<br>
text: ?{ ${ref(revenue_analysis).unique_customers} }
interactions:
- sort: ?{ ${ref(revenue_analysis).month} ASC }
- name: monthly-orders
props:
type: bar
x: ?{ ${ref(revenue_analysis).month} }
y: ?{ ${ref(revenue_analysis).total_orders} }
interactions:
- sort: ?{ ${ref(revenue_analysis).month} ASC }
tests:
- name: at-least-twelve-months
assertions:
- ">{ len( ${ref(monthly-revenue-trend).props.x} ) >= 12 }"
- name: revenue-is-never-negative
assertions:
- ">{ numpy.min( ${ref(monthly-revenue-trend).props.y} ) >= 0 }"
- name: customers-never-exceed-orders
assertions:
- ">{ numpy.max( ${ref(monthly-revenue-trend).props.text} - ${ref(monthly-orders).props.y} ) <= 0 }"
- name: month-over-month-change-under-50-percent
assertions:
- ">{ numpy.max( ${ref(monthly-revenue-trend).props.y[1:]} / ${ref(monthly-revenue-trend).props.y[:-1]} ) < 1.5 }"
- ">{ numpy.min( ${ref(monthly-revenue-trend).props.y[1:]} / ${ref(monthly-revenue-trend).props.y[:-1]} ) > 0.5 }"
Checks across a dashboard
A dashboard arranges charts, and each chart is built from Insights. A test on an Insight therefore covers every dashboard that shows it. To check that a KPI agrees with the detail below it, write one more test that compares the two Insights:
insights:
- name: total-revenue-kpi
props:
type: indicator
value: ?{ sum(${ref(revenue_analysis).net_revenue}) }[0]
number:
prefix: "$"
tests:
- name: kpi-matches-monthly-detail
assertions:
- ">{ -0.01 < ${ref(total-revenue-kpi).props.value} - numpy.sum( ${ref(monthly-revenue-trend).props.y} ) < 0.01 }"
dashboards:
- name: Executive Revenue Dashboard
description: "Monthly revenue performance and key metrics"
rows:
- height: small
items:
- width: 1
chart:
name: total-revenue
insights:
- ${ref(total-revenue-kpi)}
layout:
title:
text: "Total Revenue"
- height: large
items:
- width: 3
chart:
name: revenue-performance
insights:
- ${ref(monthly-revenue-trend)}
layout:
title:
text: "Monthly Revenue"
showlegend: true
- height: medium
items:
- width: 3
chart:
name: monthly-order-volume
insights:
- ${ref(monthly-orders)}
layout:
title:
text: "Monthly Orders"
This is real output from Visivo 2.3.0 on sample data in which one month loaded only part of its orders. visivo test prints a dot for each passing assertion and an F for each failing one. Both assertions of the month-over-month test fail, and each failure line shows the actual ratio:
$ visivo test
Starting Visivo...
Compile completed in 0.04s imports: 0.0s, parse: 0.04s
...FF.
Testing complete. 6 tests run in 0 seconds.
Failures:
> project.tests[3]: >{ numpy.max( ${ref(monthly-revenue-trend).props.y[1:]} / ${ref(monthly-revenue-trend).props.y[:-1]} ) < 1.5 } (actual: 4.6361188139931695 < 1.5)
> project.tests[3]: >{ numpy.min( ${ref(monthly-revenue-trend).props.y[1:]} / ${ref(monthly-revenue-trend).props.y[:-1]} ) > 0.5 } (actual: 0.21975428627580118 > 0.5)
Validation at every layer
Three layers in one project
One project can carry rules at each layer: the model SQL rejects rows that cannot be valid, Insights define what the charts show, and tests check the computed values, including a reconciliation against a second source. Because all three live in the same files, dashboard lineage stays traceable from chart to source:
sources:
- name: finance
type: postgresql
host: ${env.FINANCE_DB_HOST}
database: finance
username: ${env.FINANCE_DB_USER}
password: ${env.FINANCE_DB_PASSWORD}
models:
# Layer 1: Source data rules, embedded in the model SQL
- name: business_metrics
source: ${ref(warehouse)}
sql: |
WITH valid_orders AS (
SELECT *
FROM raw_orders
WHERE
order_date IS NOT NULL
AND order_amount > 0
AND customer_id IS NOT NULL
AND status IN ('pending', 'completed', 'cancelled', 'refunded')
)
SELECT
DATE_TRUNC('day', order_date) as date,
SUM(CASE WHEN status = 'completed' THEN order_amount ELSE 0 END) as revenue,
COUNT(CASE WHEN status = 'completed' THEN 1 END) as completed_orders,
COUNT(DISTINCT customer_id) as unique_customers
FROM valid_orders
GROUP BY DATE_TRUNC('day', order_date)
- name: finance_daily_revenue
source: ${ref(finance)}
sql: SELECT date, revenue FROM daily_revenue
# Layer 2: What the charts show
insights:
- name: daily-revenue-chart
props:
type: scatter
mode: lines+markers
x: ?{ ${ref(business_metrics).date} }
y: ?{ ${ref(business_metrics).revenue} }
interactions:
- sort: ?{ ${ref(business_metrics).date} ASC }
- name: finance-daily-revenue
props:
type: scatter
x: ?{ ${ref(finance_daily_revenue).date} }
y: ?{ ${ref(finance_daily_revenue).revenue} }
# Layer 3: Business rules on the computed values
tests:
- name: daily-revenue-in-expected-range
assertions:
- ">{ numpy.min( ${ref(daily-revenue-chart).props.y} ) >= 0 }"
- ">{ numpy.max( ${ref(daily-revenue-chart).props.y} ) <= 1000000 }"
- name: revenue-reconciles-with-finance
assertions:
- ">{ numpy.sum( ${ref(daily-revenue-chart).props.y} ) >= 0.95 * numpy.sum( ${ref(finance-daily-revenue).props.y} ) }"
- ">{ numpy.sum( ${ref(daily-revenue-chart).props.y} ) <= 1.05 * numpy.sum( ${ref(finance-daily-revenue).props.y} ) }"
dashboards:
- name: Revenue Reconciliation
rows:
- height: medium
items:
- chart:
name: revenue-vs-finance
insights:
- ${ref(daily-revenue-chart)}
- ${ref(finance-daily-revenue)}
The deploy script
Run the commands in order and let set -e stop the deploy at the first failure. This is the core of CI/CD for analytics:
#!/bin/bash
# deploy_with_validation.sh
set -e # stop at the first command that fails
echo "Running Visivo validation pipeline..."
# Step 1: Validate configuration and references
echo "Compiling the project..."
visivo compile
# Step 2: Run the models and compute every Insight
echo "Running the project..."
visivo run
# Step 3: Run every test (exits non-zero on any failure)
echo "Running data quality tests..."
visivo test
# Step 4: Deploy to staging for review in Visivo Cloud
echo "Deploying to staging..."
visivo deploy -s staging
# Step 5: Deploy to production
echo "Deploying to production..."
visivo deploy -s production
echo "Deployment completed successfully!"
One definition per metric
Metrics in the semantic layer
Two dashboards disagree when each carries its own copy of the formula. In Visivo the semantic layer holds the only copy: each metric and dimension is defined once on its model, every Insight that references it uses the same SQL, and the definition is versioned in Git with the rest of the project:
models:
- name: orders
source: ${ref(warehouse)}
sql: SELECT * FROM orders
dimensions:
- name: order_day
expression: "DATE_TRUNC('day', order_date)"
metrics:
- name: revenue
expression: "SUM(CASE WHEN status = 'completed' THEN order_amount ELSE 0 END)"
description: "Total revenue from completed orders. Owner: finance"
- name: unique_customers
expression: "COUNT(DISTINCT CASE WHEN status = 'completed' THEN customer_id END)"
description: "Count of distinct customers with completed orders. Owner: analytics"
# Derived metrics reference the base metrics instead of repeating their SQL
metrics:
- name: revenue_per_customer
expression: "${ref(orders).revenue} / ${ref(orders).unique_customers}"
description: "Revenue per customer with a completed order"
# Reusable insights for consistent visualization
insights:
- name: revenue-kpi-base
props:
type: indicator
value: ?{ ${ref(orders).revenue} }[0]
number:
prefix: "$"
font:
size: 24
valueformat: ",.0f"
- name: daily-revenue-trend
props:
type: scatter
mode: lines
x: ?{ ${ref(orders).order_day} }
y: ?{ ${ref(orders).revenue} }
interactions:
- sort: ?{ ${ref(orders).order_day} ASC }
# Used consistently across dashboards
dashboards:
- name: Executive Dashboard
rows:
- height: small
items:
- chart:
name: executive-daily-revenue
insights:
- ${ref(revenue-kpi-base)}
layout:
title:
text: "Daily Revenue"
- name: Finance Dashboard
rows:
- height: small
items:
- chart:
name: finance-revenue-performance
insights:
- ${ref(revenue-kpi-base)}
layout:
title:
text: "Revenue Performance"
- height: medium
items:
- chart:
name: finance-daily-revenue-trend
insights:
- ${ref(daily-revenue-trend)}
Checking that Insights agree
Both dashboards render the same Insight, built on the same metric, so they cannot disagree. The risk that remains is two Insights that should agree but are built differently, such as a KPI total and a daily trend. A test catches that drift:
tests:
- name: revenue-kpi-matches-daily-trend
assertions:
- ">{ -0.01 < ${ref(revenue-kpi-base).props.value} - numpy.sum( ${ref(daily-revenue-trend).props.y} ) < 0.01 }"
Automated quality monitoring
Anomaly and freshness checks
Catch problems before stakeholders do. Write each anomaly rule as a test, then run visivo run and visivo test on a schedule, from a CI job or cron. visivo test exits non-zero when any test fails, so the job's own failure notification (Slack, email, or a pager) reaches the data team first:
models:
- name: daily_revenue_stats
source: ${ref(warehouse)}
sql: |
WITH daily AS (
SELECT
DATE_TRUNC('day', order_date) as date,
SUM(CASE WHEN status = 'completed' THEN order_amount ELSE 0 END) as revenue
FROM orders
WHERE order_date >= CURRENT_DATE - 8
GROUP BY DATE_TRUNC('day', order_date)
),
daily_stats AS (
SELECT
date,
revenue,
AVG(revenue) OVER (ORDER BY date ROWS BETWEEN 6 PRECEDING AND 1 PRECEDING) as avg_7_day
FROM daily
)
SELECT *
FROM daily_stats
WHERE date = CURRENT_DATE - 1
- name: order_freshness
source: ${ref(warehouse)}
sql: |
SELECT
EXTRACT(EPOCH FROM (CURRENT_TIMESTAMP - MAX(created_at))) / 3600 as hours_since_last_order
FROM orders
insights:
- name: yesterday-vs-average
props:
type: bar
x: ?{ ${ref(daily_revenue_stats).date} }
y: ?{ ${ref(daily_revenue_stats).revenue} }
customdata: ?{ ${ref(daily_revenue_stats).avg_7_day} }
- name: hours-since-last-order
props:
type: indicator
value: ?{ ${ref(order_freshness).hours_since_last_order} }[0]
tests:
- name: revenue-within-normal-range
assertions:
# No more than 30% below the 7-day average
- ">{ ${ref(yesterday-vs-average).props.y[0]} >= 0.7 * ${ref(yesterday-vs-average).props.customdata[0]} }"
# No more than 50% above the 7-day average
- ">{ ${ref(yesterday-vs-average).props.y[0]} <= 1.5 * ${ref(yesterday-vs-average).props.customdata[0]} }"
- name: orders-updated-in-last-6-hours
assertions:
- ">{ ${ref(hours-since-last-order).props.value} < 6 }"
dashboards:
- name: Data Health
rows:
- height: small
items:
- chart:
name: yesterday-revenue
insights:
- ${ref(yesterday-vs-average)}
- chart:
name: order-freshness
insights:
- ${ref(hours-since-last-order)}
Transparency
Self-documenting dashboards
Put the sources, the refresh cadence, and the metric definitions on the dashboard itself, so the reader never has to ask:
dashboards:
- name: Sales Performance Dashboard
description: |
**Sales Performance Dashboard**
This dashboard provides real-time insights into sales performance,
helping teams understand revenue trends, customer behavior, and product performance.
**Data Sources:**
- Orders: Updated every 15 minutes from Shopify
- Customers: Updated daily from CRM
- Products: Updated when catalog changes
**Key Metrics:**
- Revenue: Sum of completed order amounts (excludes refunds)
- Customers: Count of unique customers with completed orders
- AOV: Average order value for completed orders
rows:
- height: compact
items:
- markdown:
name: sales-dashboard-notes
content: |
### ๐ Sales Performance Dashboard
**Testing:** every number on this page passes `visivo test` before it is deployed.
**Definitions:** each metric is defined once in the semantic layer.
[Contact Data Team](mailto:data@company.com)
- height: small
items:
- width: 1
chart:
name: revenue-last-30-days
insights:
- ${ref(revenue-kpi-base)}
layout:
title:
text: "Revenue"
annotations:
- text: "โ
Validated"
x: 1
y: 1
xref: "paper"
yref: "paper"
showarrow: false
font:
size: 10
color: "green"
Showing the quality score
Show the reader how much to trust each point. Here the daily_kpis model computes a data_quality_score column (0 to 100) in SQL, from the same rules your tests check, and the marker color carries it onto the chart:
name: example_project
insights:
- name: revenue_with_confidence
props:
type: scatter
mode: lines+markers
x: ?{ ${ref(daily_kpis).date} }
y: ?{ ${ref(daily_kpis).revenue} }
name: "Daily Revenue"
marker:
# Color by the quality score the model computes
color: ?{ ${ref(daily_kpis).data_quality_score} }
colorscale:
- [0, "red"] # Low score
- [0.8, "yellow"] # Some rules failed
- [1, "green"] # All rules passed
colorbar:
title:
text: "Data Quality Score"
hovertemplate: |
Date: %{x}<br>
Revenue: $%{y:,.0f}<br>
Quality Score: %{marker.color}/100<br>
<extra></extra>
What changes when the numbers hold
When stakeholders trust the data, the conversation changes:
Faster decisions
- Before: "We need to validate these numbers before making a decision"
- After: "The data shows X, let's act on it immediately"
More self-service
- Before: Every question requires data team involvement for validation
- After: Stakeholders confidently explore data independently
Data as the starting point
- Before: Gut decisions with data as backup justification
- After: Data-first decision making with confidence
What teams aim for
Teams that build this kind of reliability into their BI aim for:
- High stakeholder confidence in dashboard accuracy
- Significant reduction in "is this number correct?" questions
- Faster decision-making cycles
- Increased self-service analytics adoption
- Fewer critical decisions reversed due to data quality issues
- Reduced manual data validation effort
VentureBeat reports that "87% of data science projects never make it to production." The ones that do usually have a quality framework like this behind them.
None of this needs a separate quality tool. In Visivo the tests, the metric definitions, and the dashboard notes are text in the same project, reviewed in the same pull requests, and run by visivo run and visivo test before every deploy.
For related topics, explore our guides on managing staging and production environments, faster feedback cycles, and developer-first BI workflows.
The examples gallery has full projects to read, and /get-started takes you from install to a running project in a few minutes.