Author Image

CEO & Co-founder of Visivo

Dashboard Lineage Management for Trusted BI Analytics

Master dashboard lineage tracking to understand data flows, identify issues quickly, and maintain trust in analytics.

Data lineage visualization diagram

When a number on a dashboard looks wrong, the first question is where it came from. Gartner puts the cost of data quality issues at "an average of $12.9 million annually," often because teams cannot trace a problem back to its source fast enough.

Lineage is the record of that path: from the source, through each transformation, to the chart. In Visivo the configuration files are the lineage. You do not maintain a separate map, because the references between objects already describe it.

Defining dashboard lineage in Visivo

Dashboard lineage is the map of sources and transformations behind each element of a dashboard. In Visivo, ${ref()} defines it. Every reference is a dependency the CLI can trace, from the source table to the final chart.

Here is a small project with its lineage spelled out:

# project.visivo.yml
name: Sales Analytics

sources:
  - name: postgres
    type: postgresql
    database: sales_db
    host: ${env.DB_HOST}
    username: ${env.DB_USER}
    password: ${env.DB_PASSWORD}

models:
  - name: orders
    source: ${ref(postgres)}
    sql: |
      SELECT
        order_id,
        customer_id,
        order_date,
        amount
      FROM orders
      WHERE status = 'completed'
        AND created_at >= '2024-01-01'
    dimensions:
      - name: month
        expression: "DATE_TRUNC('month', order_date)"
    metrics:
      - name: revenue
        expression: "SUM(amount)"
      - name: order_count
        expression: "COUNT(DISTINCT order_id)"

insights:
  - name: revenue_trend
    props:
      type: scatter
      mode: lines+markers
      name: "Monthly Revenue"
      x: ?{ ${ref(orders).month} }
      y: ?{ ${ref(orders).revenue} }
    interactions:
      - sort: ?{ ${ref(orders).month} ASC }

  - name: customer_distribution
    props:
      type: bar
      name: "Revenue by Customer"
      x: ?{ ${ref(orders).customer_id} }
      y: ?{ ${ref(orders).revenue} }

charts:
  - name: revenue_chart
    insights:
      - ${ref(revenue_trend)}
    layout:
      title:
        text: "Revenue Trends"
      xaxis:
        title:
          text: "Month"
      yaxis:
        title:
          text: "Revenue ($)"

dashboards:
  - name: executive_dashboard
    rows:
      - height: medium
        items:
          - chart: ${ref(revenue_chart)}

The Visivo lineage view traces executive_dashboard back through revenue_chart, the revenue_trend Insight and the orders model to the postgres source Lineage for +executive_dashboard in Visivo 2.3.0: postgres → orders → revenue_trend → revenue_chart → executive_dashboard.

The chain is explicit: postgres source → orders model (with its month dimension and revenue metric) → revenue_trend Insight → revenue_chart → executive_dashboard. Each ${ref()} is a dependency Visivo can trace and validate. Visivo compiles the references into a dependency graph and shows it as a lineage view.

Why lineage matters in modern analytics

Lineage builds trust because stakeholders can see how a metric is calculated. VentureBeat reports that "87% of data science projects never make it to production," and a lack of transparency and trust in the data is a common reason.

When something breaks, the team traces it to the source in minutes instead of days. When an auditor asks how a number was produced, the lineage is the documentation.

Without it, a team cannot assess the impact of a change, trace an error or prove compliance. One bad source can flow into dozens of dashboards before anyone notices the connection. That is the same problem behind reliable BI insights for stakeholders and managing staging and production environments.

The cost of poor lineage

Suppose the executive dashboard shows a 30% revenue drop overnight. Without lineage:

  • Investigation time: hours or days across different systems
  • Trust erosion: stakeholders stop trusting every metric, not just this one
  • Decision paralysis: leadership hesitates to act on any data
  • Shadow analytics: teams build their own spreadsheets as a workaround

With explicit lineage in Visivo, you know at once:

  1. Which models feed the revenue metric
  2. What SQL transformations are applied
  3. Which source tables are involved
  4. When the data was last refreshed

Implementing comprehensive lineage with Visivo

Model dependencies and references

${ref()} builds the dependency graph for you. In Visivo, each model queries its source directly, and the semantic layer carries the business logic: dimensions for row-level fields, metrics for aggregates and relations for joins. Multi-step transformations belong in dbt™ or the warehouse. Point a Visivo model at the result.

name: Analytics Project

models:
  # Model layer: one query per business entity
  - name: transactions
    sql: |
      SELECT customer_id, transaction_date, amount
      FROM payment_transactions
      WHERE transaction_date >= '2024-01-01'
        AND status = 'completed'
    # Semantic layer: business logic
    dimensions:
      - name: value_tier
        expression: |
          CASE
            WHEN amount > 1000 THEN 'high_value'
            WHEN amount > 100 THEN 'medium_value'
            ELSE 'low_value'
          END
    metrics:
      - name: total_value
        expression: "SUM(amount)"
      - name: transaction_count
        expression: "COUNT(*)"

  - name: customers
    sql: |
      SELECT customer_id, registration_date, segment
      FROM customer_profiles
      WHERE status = 'active'
    dimensions:
      - name: cohort_month
        expression: "DATE_TRUNC('month', registration_date)"

relations:
  - name: transactions_to_customers
    join_type: inner
    condition: "${ref(transactions).customer_id} = ${ref(customers).customer_id}"

# Analytics layer: the insight pulls fields from both models
insights:
  - name: cohort_analysis
    props:
      type: bar
      x: ?{ ${ref(customers).cohort_month} }
      y: ?{ ${ref(transactions).total_value} }
    interactions:
      - split: ?{ ${ref(customers).segment} }

The chain is Sources → Models → Semantic layer → Insights → Visualizations. Because transactions_to_customers is declared once, Visivo writes the join for every Insight that combines the two models. This is the structure behind BI-as-code scalable systems, and it is what makes faster feedback cycles possible when something breaks.

Cross-dashboard lineage tracking

Lineage matters most when one model feeds several dashboards:

name: KPI Project

# Shared models used across dashboards
models:
  - name: core_kpis
    sql: |
      SELECT
        'revenue' as metric,
        SUM(amount) as value,
        'daily' as frequency
      FROM payment_transactions
      WHERE transaction_date = CURRENT_DATE
      UNION ALL
      SELECT
        'new_customers' as metric,
        COUNT(*) as value,
        'daily' as frequency
      FROM customer_profiles
      WHERE registration_date = CURRENT_DATE

# Multiple insights using the same model
insights:
  - name: daily_revenue_kpi
    props:
      type: indicator
      value: ?{ ${ref(core_kpis).value} }[0]
      title:
        text: "Daily Revenue"
    interactions:
      - filter: ?{ ${ref(core_kpis).metric} = 'revenue' }

  - name: daily_customers_kpi
    props:
      type: indicator
      value: ?{ ${ref(core_kpis).value} }[0]
      title:
        text: "New Customers"
    interactions:
      - filter: ?{ ${ref(core_kpis).metric} = 'new_customers' }

charts:
  - name: revenue_kpi_chart
    insights:
      - ${ref(daily_revenue_kpi)}

  - name: customers_kpi_chart
    insights:
      - ${ref(daily_customers_kpi)}

# Used in multiple dashboards
dashboards:
  - name: executive_dashboard
    rows:
      - height: small
        items:
          - chart: ${ref(revenue_kpi_chart)}

  - name: sales_dashboard
    rows:
      - height: small
        items:
          - chart: ${ref(revenue_kpi_chart)}
          - width: 1
            chart: ${ref(customers_kpi_chart)}

Both dashboards depend on core_kpis. A change to that model reaches both, and the configuration says so before you make it.

Advanced lineage with dbt™ integration

With dbt™ enabled, Visivo reads your dbt™ project and turns each dbt™ model into a Visivo model, so lineage continues from dbt™ into Insights and dashboards. We cover the setup in dbt™ BI-as-code integration:

name: dbt Integration

# Pull dbt models and sources into Visivo
dbt:
  enabled: true

# dbt models are available by name, e.g. ${ref(customers)} and ${ref(orders)}
relations:
  - name: orders_to_customers
    join_type: left
    condition: "${ref(orders).customer_id} = ${ref(customers).customer_id}"

insights:
  - name: customer_analysis
    props:
      type: bar
      x: ?{ ${ref(customers).segment} }
      y: ?{ sum(${ref(orders).order_total}) }

Pick the dbt™ profile and target on the command line, for example visivo run --dbt-profile analytics --dbt-target prod.

dbt™ tracks lineage from your sources through its transformations. Visivo picks up at each dbt™ model and carries it on to Insights, charts and dashboards. For the local loop, see dbt™ local development.

Lineage impact analysis

Understanding dependencies

Before you change a model, follow the ${ref()} chain to see what depends on it:

name: impact_analysis
# Impact analysis example
# If you modify the orders model, what's affected?

models:
  - name: orders
    sql: SELECT order_id, customer_id, order_date, amount FROM orders
    dimensions:
      - name: month
        expression: "DATE_TRUNC('month', order_date)"
    metrics:
      - name: revenue
        expression: "SUM(amount)"

# Direct dependents (insights using the model):
insights:
  - name: revenue_trend
    props:
      type: scatter
      x: ?{ ${ref(orders).month} }
      y: ?{ ${ref(orders).revenue} }
  - name: customer_distribution
    props:
      type: bar
      x: ?{ ${ref(orders).customer_id} }
      y: ?{ ${ref(orders).revenue} }

# Final impact (charts and dashboards):
charts:
  - name: revenue_chart
    insights:
      - ${ref(revenue_trend)}

dashboards:
  - name: executive_dashboard
    rows:
      - height: medium
        items:
          - chart: ${ref(revenue_chart)}

Testing lineage integrity

Visivo validates lineage before anything deploys:

# Check for broken references: compile fails if a ${ref()} points nowhere
visivo compile

# Run the orders model and everything downstream of it
visivo run -df 'orders+'

# Assert on the computed results
visivo test

# Deploy once the checks pass
visivo deploy --stage production

More on what to check before a deploy in test before dashboard deployment.

Benefits of explicit lineage management

Quick error tracing

When a chart shows a value nobody expected, lineage gives you the order to investigate in:

  1. Identify the Insight: Which Insight feeds the problematic chart?
  2. Check the model: What SQL generates the Insight data?
  3. Verify the source: Is the underlying data correct?
  4. Test transformations: Are the calculations accurate?
# Debug a specific lineage path: run revenue_trend and everything upstream of it
visivo --verbose run -df '+revenue_trend'
visivo test

Compliance and auditing

The configuration is the audit trail. Every transformation is written down:

name: compliance_project
# Every transformation is documented
models:
  - name: gdpr_compliant_customers
    sql: |
      SELECT
        -- PII handling documented in lineage
        customer_id,
        CASE
          WHEN consent_status = 'granted' THEN email
          ELSE 'redacted@privacy.com'
        END as email,
        registration_date,
        segment
      FROM customer_profiles
      WHERE
        -- Geographic compliance filters
        country IN ('US', 'CA', 'UK', 'DE', 'FR')
        AND consent_status IS NOT NULL

Change management

Git history tells you what changed. Lineage tells you what it affects. Together they give you the review workflow in track changes with pull requests:

# See what changed in a model and its impact
git diff HEAD~1 -- models/orders.visivo.yml

# Run the changed model and its dependents, then test before deploying
visivo run -df 'orders+'
visivo test

Trust building through transparency

Stakeholders gain confidence when they can:

  1. See the source: "This revenue number comes from our orders table"
  2. Understand transformations: "We filter for completed orders and sum the amounts"
  3. Verify calculations: "The SQL is right here in the configuration"
  4. Trust the process: "Every change is code-reviewed and tested"

Advanced lineage patterns

Multi-source lineage

A project can read from more than one source:

name: multi_source_project

sources:
  - name: postgres_sales
    type: postgresql
    database: sales
    host: ${env.SALES_DB_HOST}
    username: ${env.SALES_DB_USER}
    password: ${env.SALES_DB_PASSWORD}

  - name: mysql_crm
    type: mysql
    database: crm
    host: ${env.CRM_DB_HOST}
    username: ${env.CRM_DB_USER}
    password: ${env.CRM_DB_PASSWORD}

models:
  - name: sales_data
    source: ${ref(postgres_sales)}
    sql: SELECT order_id, amount, order_date FROM orders

  - name: customer_data
    source: ${ref(mysql_crm)}
    sql: SELECT customer_id, customer_segment FROM customers

insights:
  - name: daily_sales
    props:
      type: bar
      x: ?{ ${ref(sales_data).order_date} }
      y: ?{ sum(${ref(sales_data).amount}) }

  - name: customers_by_segment
    props:
      type: bar
      x: ?{ ${ref(customer_data).customer_segment} }
      y: ?{ count(${ref(customer_data).customer_id}) }

Each Insight reads models from one source, and the lineage view shows which source feeds each Insight. To join data across the two databases, land it in one warehouse first, for example with dbt™, and point a single model at the joined table.

Computed lineage

Dimensions and metrics keep calculated columns inside the lineage. They are defined on the model, so every Insight that uses them traces back to that model and its source:

name: computed_project

models:
  - name: sales_data
    sql: SELECT order_date, amount, order_id FROM orders
    dimensions:
      - name: month
        expression: "DATE_TRUNC('month', order_date)"
    metrics:
      - name: revenue
        expression: "SUM(amount)"
      - name: order_count
        expression: "COUNT(DISTINCT order_id)"

insights:
  - name: calculated_metrics
    props:
      type: scatter
      x: ?{ ${ref(sales_data).month} }
      y: ?{ ${ref(sales_data).revenue} }

Why lineage matters

MIT research finds that "Companies using data-driven strategies have 5-6% higher productivity," and that advantage depends on people trusting the numbers.

Getting started with lineage management

Step 1: Structure your models

Keep staging and mart transformations in dbt™ or the warehouse. In Visivo, give each business entity one model and put its business logic in the semantic layer:

name: layered_project

models:
  # Model layer: query the cleaned table directly
  - name: orders
    sql: SELECT order_id, customer_id, order_date, amount FROM analytics.orders
    # Semantic layer: business logic
    dimensions:
      - name: order_month
        expression: "DATE_TRUNC('month', order_date)"
    metrics:
      - name: revenue
        expression: "SUM(amount)"

Step 2: Use explicit references

Always use ${ref()} to connect objects, so every dependency is in the graph:

name: reference_example

models:
  - name: upstream_model
    sql: SELECT order_month, revenue FROM source_table

insights:
  - name: downstream_insight
    props:
      type: bar
      # Good - explicit reference
      x: ?{ ${ref(upstream_model).order_month} }
      y: ?{ sum(${ref(upstream_model).revenue}) }

Step 3: Document complex logic

Comment the SQL that encodes a business rule:

name: documentation_example

models:
  - name: complex_calculation
    sql: |
      -- Customer lifetime value calculation
      -- Based on standard CLTV formula: avg_purchase_value * purchase_frequency * customer_lifespan
      SELECT
        customer_id,
        (total_revenue / order_count) * -- avg purchase value
        (order_count / customer_tenure_months) * -- purchase frequency
        36 as projected_ltv -- 36 month average lifespan
      FROM customers

Step 4: Test dependencies

Make these part of every change:

# Run the full dependency chain: everything upstream and downstream
visivo run -df '+important_model+'

# Assert on the results
visivo test

# Validate references before deployment
visivo compile

Lineage stops being optional once more than a few people depend on a dashboard. It is how you keep trust, pass an audit and fix problems quickly. With ${ref()}, Visivo makes lineage a by-product of writing the configuration rather than a separate job.

Related reading: BI version control best practices, dashboard version control collaboration, and visualizations as code.

Lineage documentation written this way cannot go stale, because it is the configuration. To see the graph for your own project, /get-started walks you from install to a running project.

Install command copied