Evidence — Business Intelligence as Code

Introduction

Evidence is a code-based BI tool that lets analysts write SQL queries in Markdown files and automatically generates polished data reports with interactive charts, tables, and KPI cards. Reports are version-controlled, reviewable in pull requests, and deployable as static sites.

What Evidence Does

• Combines SQL queries and Markdown narrative into data-driven pages
• Renders interactive charts, tables, and summary components automatically
• Connects to databases like PostgreSQL, BigQuery, Snowflake, DuckDB, and more
• Builds to a static site deployable on any hosting platform
• Supports parameterized queries and dynamic filtering without custom code

Architecture Overview

Evidence uses a build pipeline that runs SQL queries against configured data sources at build time, caching results as Parquet files. A Svelte-based frontend renders Markdown pages with embedded query results into interactive components. The final output is a static site with client-side interactivity.

Self-Hosting & Configuration

• Bootstrap a project with the Evidence template and connect your data sources in sources/
• Configure database connections via connection.yaml or environment variables
• Write pages as Markdown files with embedded SQL code blocks
• Deploy as a static site to Netlify, Vercel, GitHub Pages, or your own server
• Schedule data refreshes in CI/CD pipelines with npm run sources

Key Features

• SQL-first: write queries directly in Markdown, no drag-and-drop builder needed
• Version-controlled: pages, queries, and configs live in Git
• 20+ built-in chart and component types (line, bar, scatter, map, funnel, etc.)
• Templating and loops for generating pages from data dynamically
• DuckDB integration for analyzing local CSV, Parquet, and JSON files

Comparison with Similar Tools

• Metabase — GUI-based BI tool; easier for non-technical users but not code-native
• Apache Superset — Feature-rich dashboarding; heavier to deploy and maintain
• Lightdash — dbt-native BI; requires dbt models as the semantic layer
• Redash — SQL-first dashboards; server-based, not static-site deployable
• Observable — Reactive notebooks for data; JavaScript-focused, different authoring model

FAQ

Q: Do I need to know a programming language? A: No. Evidence pages are Markdown with SQL. No JavaScript or Python is required for standard reports.

Q: How does Evidence handle large datasets? A: Queries run at build time and results are cached as Parquet files. The browser loads only the data needed for each page.

Q: Can I embed Evidence reports in other applications? A: Yes. Since Evidence outputs static HTML, you can embed pages in iframes or integrate them into internal portals.

Q: Does Evidence support real-time data? A: Data is refreshed at build time. For near-real-time dashboards, schedule frequent rebuilds in your CI/CD pipeline.

Sources

• https://github.com/evidence-dev/evidence
• https://docs.evidence.dev