
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.

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)}
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:
- Which models feed the revenue metric
- What SQL transformations are applied
- Which source tables are involved
- 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:
- Identify the Insight: Which Insight feeds the problematic chart?
- Check the model: What SQL generates the Insight data?
- Verify the source: Is the underlying data correct?
- 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:
- See the source: "This revenue number comes from our orders table"
- Understand transformations: "We filter for completed orders and sum the amounts"
- Verify calculations: "The SQL is right here in the configuration"
- 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.