Author Image

CTO & Co-founder of Visivo

What Is BI-as-Code and Why It Matters for Modern BI Teams

How BI-as-code brings version control, review and automated deployment to business intelligence, with a Visivo project as the running example.

BI-as-Code concept visualization

Data teams know the failure modes: sprawling dashboards, metrics that disagree, deployments done by hand. According to Gartner analyst Nick Heudecker, 85% of big data projects fail, often because of exactly these problems. BI-as-code is the response. It treats dashboards and analytics as code, and brings the practices software engineers already rely on to business intelligence.

Defining BI-as-code

BI-as-code means managing every business intelligence component (dashboards, metrics, visualizations and configuration) as code in a repository rather than through a graphical interface. Instead of clicking through menus to build a report, the team defines its analytics in text files, in YAML, JSON or a domain-specific language.

In a traditional BI tool, building a sales dashboard means:

  1. Opening a BI tool
  2. Clicking through data source connections
  3. Dragging and dropping visualizations
  4. Manually configuring each chart
  5. Hoping you remember all the steps next time

With BI-as-code in Visivo, the same dashboard is one project.visivo.yml file:

# project.visivo.yml
name: Sales Performance

sources:
  - name: sales_db
    type: postgresql
    database: sales
    host: localhost
    port: 5432
    username: ${env.POSTGRES_USER}
    password: ${env.POSTGRES_PASSWORD}

models:
  - name: orders
    source: ${ref(sales_db)}
    sql: SELECT order_date, amount, status FROM orders
    metrics:
      - name: total_revenue
        expression: "SUM(CASE WHEN status = 'completed' THEN amount ELSE 0 END)"
    dimensions:
      - name: order_day
        expression: "DATE_TRUNC('day', order_date)"

  - name: customer_sessions
    source: ${ref(sales_db)}
    sql: SELECT customer_id, acquisition_channel, purchased FROM customer_sessions
    metrics:
      - name: conversion_rate
        expression: "COUNT(DISTINCT CASE WHEN purchased THEN customer_id END) * 1.0 / COUNT(DISTINCT customer_id)"

insights:
  - name: revenue-trend
    props:
      type: scatter
      mode: lines
      x: ?{ ${ref(orders).order_day} }
      y: ?{ ${ref(orders).total_revenue} }
    interactions:
      - sort: ?{ ${ref(orders).order_day} ASC }

  - name: conversion-by-channel
    props:
      type: bar
      x: ?{ ${ref(customer_sessions).acquisition_channel} }
      y: ?{ ${ref(customer_sessions).conversion_rate} }

charts:
  - name: revenue-trend-chart
    insights:
      - ${ref(revenue-trend)}
  - name: conversion-by-channel-chart
    insights:
      - ${ref(conversion-by-channel)}

dashboards:
  - name: Sales Performance Dashboard
    rows:
      - height: medium
        items:
          - chart: ${ref(revenue-trend-chart)}
          - chart: ${ref(conversion-by-channel-chart)}

Credentials stay out of the file: ${env.POSTGRES_USER} reads an environment variable, which you can keep in a local .env file.

That file is readable, reviewable and reproducible. Anyone on the team can see what the dashboard does, propose a change in a pull request, and rebuild it exactly. The same move already paid off in infrastructure: the DORA State of DevOps Report found that elite performers deploy 208x more frequently than low performers, largely through automation and Infrastructure as Code practices.

How BI-as-code works

Three parts make it work. Configuration files define the analytics. Git tracks those files, so every change is versioned and reviewed. Automation reads the files and deploys the dashboards.

Configuration files define analytics: every dashboard, metric and visualization is text. Here are two metrics, each defined on the model it belongs to:

models:
  - name: marketing_spend
    sql: SELECT month, spend, new_customers FROM marketing_monthly
    metrics:
      - name: customer_acquisition_cost
        description: "Average cost to acquire a new customer"
        expression: "SUM(spend) / NULLIF(SUM(new_customers), 0)"

  - name: subscriptions
    sql: SELECT billed_month, subscription_amount, subscription_status FROM subscriptions
    metrics:
      - name: monthly_recurring_revenue
        description: "Total recurring revenue per month from active subscriptions"
        expression: "SUM(CASE WHEN subscription_status = 'active' THEN subscription_amount ELSE 0 END)"
    dimensions:
      - name: month
        expression: "DATE_TRUNC('month', billed_month)"

Git tracks changes: every modification is a commit with a message and an author (git-scm.com covers the workflow):

git log --oneline
# 8f3d2a1 Add customer segmentation to revenue dashboard
# 7b9c4e2 Fix calculation error in churn rate metric
# 5a1e8f9 Update date filters for quarterly reporting
# 3c7d0b6 Add drill-down capability to sales charts

Automation handles deployment: a CI pipeline runs the project, runs its tests and deploys on every merge. The CI/CD analytics implementation guide goes deeper:

# .github/workflows/deploy-bi.yml
# Learn more: https://docs.github.com/en/actions
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install Visivo
        run: pip install visivo

      - name: Run queries
        run: visivo run
        env:
          POSTGRES_USER: ${{ secrets.POSTGRES_USER }}
          POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}

      - name: Run tests
        run: visivo test

      - name: Deploy to production
        run: visivo deploy -s production
        env:
          VISIVO_TOKEN: ${{ secrets.VISIVO_TOKEN }}

Why BI-as-code matters for BI teams

According to McKinsey Global Institute, data-driven organizations are 23 times more likely to acquire customers, yet most still run BI by hand. BI-as-code replaces that manual process with a workflow that scales with the team.

Automation reduces manual work: instead of rebuilding a dashboard for each department, define one dashboard and let the viewer pick the department with an input:

models:
  - name: budget
    sql: SELECT department, month, budget, actual FROM department_budget

inputs:
  - name: department
    type: single-select
    options: ["Engineering", "Sales", "Marketing", "Operations"]
    display:
      type: dropdown
      default:
        value: Engineering

insights:
  - name: budget-vs-actual
    props:
      type: bar
      x: ?{ ${ref(budget).month} }
      y: ?{ SUM(${ref(budget).actual}) - SUM(${ref(budget).budget}) }
    interactions:
      - filter: ?{ ${ref(budget).department} = '${ref(department).value}' }

charts:
  - name: budget-vs-actual-chart
    insights:
      - ${ref(budget-vs-actual)}

dashboards:
  - name: Department Performance
    rows:
      - height: compact
        items:
          - input: ${ref(department)}
      - height: medium
        items:
          - chart: ${ref(budget-vs-actual-chart)}

Adding a department is one more entry in the options list, not another dashboard to maintain.

Version control enables collaboration: several people work on the same project at the same time without conflicts. Changes are reviewed before they deploy. The history survives when a team member leaves. The GitLab DevSecOps report shows that version control adoption increases team productivity by 40%.

Consistency across dashboards: a metric is defined once on its model, and every Insight that needs it references the name:

models:
  - name: invoices
    sql: SELECT customer_id, invoice_date, invoice_amount, refunds, discounts, last_purchase_date FROM invoices
    metrics:
      - name: gross_revenue
        expression: "SUM(invoice_amount)"
      - name: net_revenue
        expression: "SUM(invoice_amount - refunds - discounts)"
      - name: total_customers
        expression: "COUNT(DISTINCT customer_id)"
      - name: active_customers
        expression: "COUNT(DISTINCT CASE WHEN last_purchase_date > CURRENT_DATE - 90 THEN customer_id END)"
    dimensions:
      - name: invoice_month
        expression: "DATE_TRUNC('month', invoice_date)"

# Every insight references the same definitions
insights:
  - name: net-revenue-by-month
    props:
      type: bar
      x: ?{ ${ref(invoices).invoice_month} }
      y: ?{ ${ref(invoices).net_revenue} }

Faster development cycles: edit a file, see the result in the browser, commit when it is right:

# Local development workflow
visivo serve  # Watches your files and reloads the browser on save
# Make changes to dashboard.yml
# See results immediately in browser
# Commit when satisfied
git add dashboard.yml
git commit -m "Add year-over-year comparison"
git push  # Triggers automatic deployment

What changes in practice

Four things get easier once the project lives in Git.

Troubleshooting: when a metric looks wrong, the history answers the first three questions:

# What changed in our revenue calculation?
git diff HEAD~1 metrics/revenue.yml

# Who modified the customer segmentation?
git blame dashboards/customer-analytics.yml

# When did we change the churn definition?
git log -p --grep="churn" metrics/

Collaboration: an analyst and an engineer review the same diff. The dashboard version control collaboration guide covers the workflow:

# Business analyst opens a pull request for a new metric.
# A data engineer reviews the diff before it merges.
models:
  - name: customer_engagement
    sql: SELECT customer_id, usage_frequency, feature_adoption, support_tickets, nps_score FROM customer_engagement
    metrics:
      - name: customer_health_score
        description: "Composite score indicating customer satisfaction and engagement"
        expression: "AVG(usage_frequency * 0.3 + feature_adoption * 0.3 + support_tickets * -0.2 + nps_score * 0.2) * 100"

DevOps integration: the dashboards ship through the same pipeline stages as the application. See automating analytics infrastructure for the details:

# Integrated deployment pipeline
pipeline:
  - stage: build
    jobs:
      - compile_application
      - build_dashboards

  - stage: test
    jobs:
      - application_tests
      - dashboard_tests

  - stage: deploy
    jobs:
      - deploy_application
      - deploy_analytics

Recovery: when a deploy breaks a dashboard, the rollback is one revert:

# Production issue detected: executive dashboard showing errors

# Immediate rollback: revert the bad commit
git revert HEAD
git push  # CI runs visivo run, visivo test and visivo deploy -s production

# Fix the issue on a branch and preview it on its own stage
git checkout -b hotfix/dashboard-error
# ... fix the issue ...
visivo run
visivo deploy -s hotfix-dashboard-error

# Merge after review; CI deploys the fix to production

Organizations adopting BI-as-code report:

  • Significant reduction in dashboard development time
  • Dramatically fewer inconsistent metrics
  • Much faster onboarding of new team members
  • Major reduction in production incidents

According to Anaconda's State of Data Science report, data scientists spend 45% of their time on data preparation and cleaning. BI-as-code automates many of those repetitive tasks.

BI-as-code is a cultural shift as much as a technical one. It turns a BI team from report builders into analytics engineers who ship through the same workflow as the rest of engineering.

For more on the practice, read developer-centric BI dashboards, BI version control best practices and visualizations as code.

If you want to see a project like the one above run end to end, the examples gallery is built this way, and /get-started takes you from install to a first dashboard in a few minutes.

Install command copied