Author Image

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.

Reliable BI insights dashboard

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.

Install command copied