Evidence

Evidence is a library designed for creating reports using a combination of Markdown and SQL. It integrates several powerful underlying libraries to provide its core functionality:

• Charts: Powered by ECharts.
• Maps: Powered by Leaflet.
• UI Components: Powered by Shadcn.

Components are categorized into functional groups such as Data (for displaying metrics and tables) and Charts (for visual data representation).

The DimensionGrid component displays an interactive grid of one-dimensional tables, one for each string column in the source data. It is primarily used to allow users to filter data by multiple dimensions simultaneously. It can also function as an input component that generates SQL conditions for use in other queries.

<DimensionGrid data={my_query} />

The Redshift adapter allows Evidence to connect to Amazon Redshift data sources. It functions as a wrapper around the Postgres adapter, meaning connection configurations compatible with Postgres will generally work for Redshift.

For detailed connection information and configuration requirements, refer to the official Evidence documentation on Redshift data sources: https://docs.evidence.dev/core-concepts/data-sources/#redshift

You can define formats directly in your SQL by appending a format tag to the column name with an underscore. This ensures the column is formatted consistently across all components and tables.

Syntax: column_name_tag (e.g., growth_pct for a column named growth).

Rules:

• Format tags are case-insensitive.
• When creating tables, Evidence uses the tag to format the column title (e.g., customer_id becomes Customer ID, while growth_pct becomes Growth).
• Formatting configuration is managed in the Value Formatting Section of Evidence Settings.

-- Example of applying a percentage tag in SQL
SELECT
    growth_pct
FROM sales_data

In Evidence, you can name a SQL code block by appending a name to the language identifier in the code fence: ```sql name. This allows you to treat the result of that SQL block as a variable that can be interpolated into other SQL blocks using the ${name} syntax.

select *
from my_table

select count(*) as n_months from ${orders_by_category}

A templated page is defined by using square brackets around a filename or a folder name. The string inside the brackets becomes a parameter that can be referenced within the page. The value in the URL replaces the parameter name.

Equivalent declarations:

• pages/customers/[customer].md
• pages/customers/[customer]/index.md

You can programmatically control the visibility of content in your reports using {#if}, {:else if}, {:else}, and {/if} blocks. This is useful for managing information density or showing specific call-to-action messages only when certain data thresholds are met.

Syntax structure:

• {#if condition}: Starts the conditional block.
• {:else if condition}: (Optional) Provides an alternative condition.
• {:else}: (Optional) Provides a fallback if no previous conditions are met.
• {/if}: Closes the conditional block.

{#if condition}

Display some content.

{:else if another condition}

Another thing instead.

{:else }

Something completely different.

{/if}

The <CalendarHeatmap /> component supports three legend modes via the legend and filter props:

1. Default Legend: The standard legend display (set filter=false).
2. No Legend: Completely hides the legend by setting legend={false}.
3. Filter Legend: Enables interactive filtering by setting filter={true}.

// No Legend
<CalendarHeatmap
    data={oneyear}
    date=date
    value=orders
    legend={false}
    filter={false}
/>

// Filter Legend
<CalendarHeatmap
    data={oneyear}
    date=date
    value=orders
    filter={true}
/>

Evidence defines three distinct user roles based on how you interact with the tool:

• Developers: Users who write JavaScript to create plugins, custom components, or customize application shells.
• Authors: Users who create and maintain Evidence Projects (writing Markdown and SQL) without directly interacting with the SDK.
• Viewers: End-users who consume the completed, built Evidence App.

Evidence provides several components specifically for displaying data values and structured datasets:

• Value: Used for displaying single data points or metrics.
• Big Value: A specialized component for emphasizing large or critical metrics.
• Data Table: Used for displaying structured, tabular data sets.