Evidence

https://docs.evidence.dev
Admin
Evidence is an open-source framework for building data products like reports and dashboards using...
Tokens:116,850
Snippets:1,789
Trust Score:9.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Evidence CLI

Source: https://docs.evidence.dev/cli

Installation commands for macOS/Linux and Windows environments.

```bash
curl -fsSL https://evidence.studio/install.sh | sh
```

```powershell
irm https://evidence.studio/install.ps1 | iex
```

--------------------------------

### Start Development Server

Source: https://docs.evidence.dev/cli

Launch the local development server from within a project directory.

```bash
evidence dev
```

--------------------------------

### Line Options Configuration

Source: https://docs.evidence.dev/components/line

Example configuration for line styling options.

```text
options={
    color = "string"
    width = 0
    type = "solid"
    opacity = 0
    markers = {
      shape = "circle"
      size = 0
    }
    step = "start"
    smooth = true
  }
```

--------------------------------

### Verify CLI Installation

Source: https://docs.evidence.dev/cli

Check the currently installed version of the Evidence CLI.

```bash
evidence version
```

--------------------------------

### Serve Self-Hosted Project

Source: https://docs.evidence.dev/cli/commands

Starts the production server for self-hosting. Requires a configured direct connector in connection.yaml.

```bash
evidence serve
evidence serve --port 8080
evidence serve --host 0.0.0.0
```

--------------------------------

### Start the development server

Source: https://docs.evidence.dev/cli/commands

Launch the local development server. The default port is 3000, but it can be overridden with the --port flag.

```bash
evidence dev
evidence dev --port 8080
```

--------------------------------

### Configure Axis Options

Source: https://docs.evidence.dev/components/bubble_chart

Examples for configuring primary, secondary, and x-axis settings using options groups.

```text
y_axis_options={
  title = "string"
  title_position = "top"
  ticks = true
  baseline = true
  labels = true
  gridlines = true
  min = 0
  max = 0
  fit_to_data = true
  interval = 0
}
```

```text
y2_axis_options={
  title = "string"
  title_position = "top"
  ticks = true
  baseline = true
  labels = true
  gridlines = true
  min = 0
  max = 0
  fit_to_data = true
  interval = 0
}
```

```text
x_axis_options={
  title = "string"
  show_title = true
  label_wrap = true
  ticks = true
  baseline = true
  labels = true
  gridlines = true
  min = 0
  max = 0
  fit_to_data = true
  min_interval = "year"
  max_interval = "year"
  interval = 0
  label_rotate = 0
  title_arrow = true
  max_label_length = 0
}
```

--------------------------------

### Configure Snowflake connection via CLI

Source: https://docs.evidence.dev/direct-connectors/snowflake

Example configuration for a connection.yaml file when using the CLI.

```yaml
type: snowflake
account: xy12345.us-east-1
user: evidence_user
private_key_path: ./snowflake-key.pem
warehouse: COMPUTE_WH
database: ANALYTICS
# role: EVIDENCE_READER
# schema: { production: ANALYTICS, devSchemas: [DEV_ALICE] }
# session_variables:
#   - snowflakeVariable: APP_USER_EMAIL
#     evidenceVariable: user.email
```

--------------------------------

### Compare vs Fixed Goal

Source: https://docs.evidence.dev/components/target_comparison

Example of comparing against a static numeric goal.

```liquid
{% target_comparison 
    name="vs 100K Goal" 
    target="100000"
/%}
```

--------------------------------

### Define partial path structure

Source: https://docs.evidence.dev/core-concepts/partials

Example of project-relative path resolution for partial files.

```text
partials/
    ├── new-partial        # Referenced as file="/partials/new-partial"
    └── components/
        └── footer         # Referenced as file="/partials/components/footer"
```

--------------------------------

### evidence dev

Source: https://docs.evidence.dev/cli/commands

Starts the local development server for the Evidence project.

```APIDOC
## evidence dev

### Description
Start the local development server.

### Parameters
#### Options
- **--port**, **-p** (integer) - Optional - Port to run on (default: 3000).
```

--------------------------------

### Chart Options Configuration Example

Source: https://docs.evidence.dev/components/chord_chart

Shows how to define color palettes and series-specific colors within the chart_options attribute.

```text
chart_options={
  color_palette = ["value1", "value2"]
  series_colors = {
    "key1" = "value1"
    "key2" = "value2"
  }
}
```

--------------------------------

### Configure BigQuery connection in connection.yaml

Source: https://docs.evidence.dev/direct-connectors/bigquery

Example configuration for a BigQuery data source using a local keyfile path.

```yaml
type: bigquery
project: my-gcp-project
keyfile: ./evidence-bq-primary.json
# dataset: analytics
datasets:
  - analytics
  - reporting
# roles:
#   - name: customer_a
#     serviceAccountEmail: customer-a@my-gcp-project.iam.gserviceaccount.com
```

--------------------------------

### Define Skill Configuration

Source: https://docs.evidence.dev/features/evidence-agent

Example of a SKILL.md file using YAML frontmatter to define the skill's name and usage description.

```markdown
---
name: cohort-analysis
description: What this skill does and WHEN to use it — this line is how the agent decides to load it, so be specific.
---

# Cohort analysis

Step-by-step instructions for running a cohort analysis in this workspace.
```

--------------------------------

### Postgres connection.yaml configuration

Source: https://docs.evidence.dev/direct-connectors/postgres

Example configuration for a Postgres data source defined in the CLI connection.yaml file.

```yaml
type: postgres
host: mydb.abc123.us-east-1.rds.amazonaws.com
# port: 5432
user: evidence
password: <your-password>
database: analytics
# sslmode: verify-full
# ssl_ca_path: ./certs/rds-global-bundle.pem # PEM CA bundle for verify-ca / verify-full
# ssl_cert_path: ./certs/client.crt # mutual TLS client certificate
# ssl_key_path: ./certs/client.key # mutual TLS client key
# schema: public
# schemas: [public, analytics]
```

--------------------------------

### Configure BigQuery connection

Source: https://docs.evidence.dev/cli/connections

Example configuration for connecting to a BigQuery warehouse using a service account key file.

```yaml
type: bigquery
project: my-gcp-project
keyfile: ./evidence-bq-primary.json
datasets:
  - analytics
  - reporting
# dataset: analytics
# location: US
```

--------------------------------

### Area Options Configuration

Source: https://docs.evidence.dev/components/area

Example configuration for area-specific options like stepping, smoothing, and gradients.

```text
options={
  step = "start"
  smooth = true
  gradient = true
}
```

--------------------------------

### Define Workspace Context

Source: https://docs.evidence.dev/features/evidence-agent

Example of a context file providing organizational knowledge and metric definitions.

```markdown
# Workspace context

Our fiscal year starts in February. "Revenue" always means net revenue
(gross minus refunds). When a reader asks about "active users", use the
28-day rolling definition from the `active_users` model.
```

--------------------------------

### Configure Snowflake connection

Source: https://docs.evidence.dev/cli/connections

Example configuration for connecting to a Snowflake warehouse using a private key path.

```yaml
type: snowflake
account: xy12345.us-east-1
user: evidence_user
private_key_path: ./snowflake-key.pem
warehouse: COMPUTE_WH
database: ANALYTICS
# role: EVIDENCE_READER
# schema: { production: ANALYTICS, devSchemas: [DEV_ALICE] }
```

--------------------------------

### Configure project access grants

Source: https://docs.evidence.dev/features/page-level-access-control

Examples of defining project-level access for different audiences.

```yaml
project:
  grants:
    viewers: []
```

```yaml
project:
  grants:
    viewers:
      - $org
```

```yaml
project:
  grants:
    viewers:
      - finance
```

```yaml
project:
  grants:
    viewers:
      - finance
      - leadership
      - alex@example.com
      - jordan@example.com
```

--------------------------------

### Configure Secondary Y-Axis Options

Source: https://docs.evidence.dev/components/bar_chart

Example configuration object for customizing the secondary y-axis.

```text
y2_axis_options={
  title = "string"
  title_position = "top"
  ticks = true
  baseline = true
  labels = true
  gridlines = true
  min = 0
  max = 0
  fit_to_data = true
  interval = 0
}
```

--------------------------------

### Configure chart_options attribute

Source: https://docs.evidence.dev/components/calendar_heatmap

Example of defining color scales, palettes, and maps for heatmap styling.

```text
chart_options={
  color_scale = ["value1", "value2"]
  color_palette = ["value1", "value2"]
  conditional_colors = "string"
  color_map = {
    "key1" = "value1"
    "key2" = "value2"
  }
}
```

--------------------------------

### Configure ClickHouse connection in connection.yaml

Source: https://docs.evidence.dev/direct-connectors/clickhouse

Example configuration for a ClickHouse connection using the CLI, specifying the host and optional parameters.

```yaml
type: clickhouse
host: abc123.us-east-1.aws.clickhouse.cloud
# port: 8443
# secure: true
# username: default
# database: default
# databases: [analytics, reporting]
```

--------------------------------

### Configure page-level access overrides

Source: https://docs.evidence.dev/features/page-level-access-control

Examples of restricting or expanding access for specific pages within a project.

```yaml
project:
  grants:
    viewers:
      - $org

pages:
  reports/board-meeting:
    inherit: false
    grants:
      viewers:
        - executives
```

```yaml
project:
  grants:
    viewers:
      - finance

pages:
  reports/quarterly-summary:
    grants:
      viewers:
        - leadership
  reports/headcount:
    grants:
      viewers:
        - hr
        - leadership
```

--------------------------------

### Link to Evidence Pages

Source: https://docs.evidence.dev/components/link

Use absolute paths starting with the project slug to link to internal pages at various folder depths.

```liquid
<!-- Root page, not in a folder -->
[My Other Page](/project-slug/page-slug)

<!-- Page within a folder -->
[My Other Page](/project-slug/folder-slug/page-slug)

<!-- Page nested depply within folders -->
[My Other Page](/project-slug/folder1-slug/folder2-slug/page-slug)
```

--------------------------------

### Scaffold connection.yaml with evidence init

Source: https://docs.evidence.dev/cli/connections

Use the CLI to initialize a project with a pre-filled connection.yaml file for specific warehouse types.

```bash
evidence init my-project --warehouse snowflake
# or
evidence init my-project --warehouse bigquery
```

--------------------------------

### Account Signup

Source: https://docs.evidence.dev/cli/commands

Initiates the account and workspace creation process in the browser.

```bash
evidence signup
```

--------------------------------

### Filter SQL by Start Date

Source: https://docs.evidence.dev/components/range_calendar

Use the .start property to filter data starting from a specific date.

```liquid
{% range_calendar id="date_filter" /%}

```sql filtered_data
select * from events
where event_date >= {{date_filter.start}}
```
```

--------------------------------

### whoami

Source: https://docs.evidence.dev/mcp/studio

Get the authenticated Evidence user and their active organization.

```APIDOC
## whoami

### Description
Get the authenticated Evidence user and their active organization.
```

--------------------------------

### Launch and deploy a project

Source: https://docs.evidence.dev/cli/commands

Connect the project to Evidence Studio and GitHub. Use --upload-credentials to securely provide warehouse access for non-interactive deployments.

```bash
evidence launch
evidence launch --name "My Project" --upload-credentials
```

--------------------------------

### Initialize a new Evidence project

Source: https://docs.evidence.dev/cli/commands

Scaffold a new project directory. Use the --warehouse flag to configure a direct connection to Snowflake or BigQuery.

```bash
evidence init my-project
evidence init my-project --warehouse snowflake
```

--------------------------------

### get_page_summary

Source: https://docs.evidence.dev/mcp/studio

Get a structured summary of a published page (title, queries, components).

```APIDOC
## get_page_summary

### Description
Get a structured summary of a published page (title, queries, components) so you can describe what it shows.
```

--------------------------------

### Compare vs Aggregated Target

Source: https://docs.evidence.dev/components/target_comparison

Example of comparing against an aggregated column value.

```liquid
{% target_comparison 
    name="vs Target" 
    target="sum(target_sales)"
/%}
```

--------------------------------

### Show Project Schema

Source: https://docs.evidence.dev/cli/commands

List all tables and their associated columns.

```bash
evidence schema
```

--------------------------------

### Display Help Information

Source: https://docs.evidence.dev/cli/commands

Lists all available commands and usage information for the CLI.

```bash
evidence help
```

--------------------------------

### Run Evidence Migration Commands

Source: https://docs.evidence.dev/migration-guide

Commands to preview, execute, and validate the migration process.

```bash
evidence migrate --dry-run
```

```bash
evidence migrate
```

```bash
evidence validate
```

```bash
evidence dev
```

--------------------------------

### ECharts Options Override

Source: https://docs.evidence.dev/components/area

Example of passing raw ECharts options to the area series.

```text
echarts_options={
    endLabel={ show=true }
    markPoint={ data=[{ type="max" }, { type="min" }] }
}
```

--------------------------------

### Data Labels Configuration

Source: https://docs.evidence.dev/components/area

Example configuration for customizing data labels on the area series.

```text
data_labels={
  position = "above"
  fmt = "date"
  size = 0
  distance = 0
  rotate = 0
  color = "string"
  border_color = "string"
  show_overlap = true
}
```

--------------------------------

### Link a repository to an existing Studio project

Source: https://docs.evidence.dev/cli/commands

Attach the current repository to an existing project in Evidence Studio. Future pushes will overwrite the project content with the repository state.

```bash
evidence link my-project
evidence link --project my-project
```

--------------------------------

### evidence init

Source: https://docs.evidence.dev/cli/commands

Scaffolds a new Evidence project. Optionally configures a direct warehouse connection.

```APIDOC
## evidence init

### Description
Scaffold a new Evidence project.

### Parameters
#### Positional Arguments
- **project_name** (string) - Required - The name of the project to scaffold.

#### Options
- **--warehouse** (string) - Optional - Scaffold a connection.yaml for a direct warehouse connection: 'snowflake' or 'bigquery'.
```

--------------------------------

### Date Range Configuration

Source: https://docs.evidence.dev/components/sparkline

Example of the date_range object structure for filtering data by time period.

```liquid
date_range={
    range = "today"
    date = "string"
  }
```

--------------------------------

### Initialize Fly.io Deployment

Source: https://docs.evidence.dev/self-host/fly

Generate the initial fly.toml configuration file without triggering a deployment.

```bash
fly launch --no-deploy
```

--------------------------------

### Deploy to Fly.io

Source: https://docs.evidence.dev/self-host/fly

Execute the deployment process to the Fly.io platform.

```bash
fly deploy
```

--------------------------------

### evidence.ready()

Source: https://docs.evidence.dev/components/html

Signals that the first render is complete.

```APIDOC
## evidence.ready()

### Description
Signals that the first render is done. Should be called after async draws so PDF/PNG export captures a finished frame.
```

--------------------------------

### Compare Component Syntax

Source: https://docs.evidence.dev/migration-guide

Legacy Evidence uses Svelte-based component syntax, while Evidence Studio utilizes Markdoc tags.

```svelte
<LineChart data={orders} x=date y=sales />
```

```markdoc
{% line_chart data="orders" x="date" y="sum(sales)" /%}
```

--------------------------------

### Configure data labels for bubble series

Source: https://docs.evidence.dev/components/bubble

Example configuration for the data_labels attribute to customize point labeling.

```text
data_labels={
    position = "above"
    fmt = "date"
    size = 0
    distance = 0
    rotate = 0
    color = "string"
    border_color = "string"
    show_overlap = true
  }
```

--------------------------------

### Create Dockerfile for Evidence

Source: https://docs.evidence.dev/self-host/fly

Use this Dockerfile to package the Evidence project for deployment.

```docker
FROM evidencedev/serve:latest
COPY --chown=evidence:evidence . /project
```

--------------------------------

### Access Component Documentation

Source: https://docs.evidence.dev/cli/commands

Provides tools to browse, search, and view details for specific components.

```bash
evidence docs                         # Overview
evidence docs search "chart"          # Search docs
evidence docs component bar_chart     # Component details
```

--------------------------------

### Redefining all time range

Source: https://docs.evidence.dev/components/range_calendar

Sets a custom starting point for the all time range option using the all_time_range property.

```liquid
{% range_calendar id="date_filter" value_column="date" all_time_range="from 2022-12-01" /%}

{% big_value
    data="demo.daily_orders"
    value="sum(total_sales)"
    filters=["date_filter"]
/%}
```

--------------------------------

### GET /v1/embedded/{nonce}

Source: https://docs.evidence.dev/features/embedded

Loads the embedded report when accessed via iframe using a validated single-use nonce.

```APIDOC
## GET /v1/embedded/{nonce}

### Description
Loads the embedded report when accessed via iframe. The nonce in the URL path is validated and can only be used once.

### Method
GET

### Endpoint
/v1/embedded/{nonce}

### Parameters
#### Path Parameters
- **nonce** (string) - Required - The single-use nonce generated by the POST /v1/embedded endpoint.
```

--------------------------------

### Render a basic partial

Source: https://docs.evidence.dev/components/partial

Include a reusable partial file by specifying its path.

```liquid
{% partial file="my_partial" /%}
```

--------------------------------

### Compare Logic Syntax

Source: https://docs.evidence.dev/migration-guide

Legacy Evidence relies on Svelte/JS logic blocks, while Evidence Studio uses specific Markdoc tags for control flow.

```svelte
{#each}, {#if}, {@const}
```

```markdoc
{% repeat %}, {% if %}
```

--------------------------------

### Deploy via Vercel CLI

Source: https://docs.evidence.dev/self-host/vercel

Commands to link, configure environment variables, and deploy the project using the Vercel CLI.

```bash
vercel link
```

```bash
vercel env add SNOWFLAKE_USER production
vercel env add SNOWFLAKE_PRIVATE_KEY production
vercel env add EVIDENCE_BASIC_USER production
vercel env add EVIDENCE_BASIC_PASSWORD production
```

```bash
vercel deploy --prod
```

```bash
vercel git connect
```

--------------------------------

### Configure symbols for reference lines

Source: https://docs.evidence.dev/components/reference_line

Defines the shapes and sizes of symbols displayed at the start and end points of a reference line.

```text
symbols={
  start = {
    shape = "circle"
    size = 0
  }
  end = {
    shape = "circle"
    size = 0
  }
}
```

--------------------------------

### get_context

Source: https://docs.evidence.dev/mcp/studio

Get the workspace context (the projects’ agent/context instructions and available skills) that Evidence maintains for AI assistants.

```APIDOC
## get_context

### Description
Get the workspace context (the projects’ agent/context instructions and available skills) that Evidence maintains for AI assistants. Call with no arguments to get context for every project you can access, or pass a projectSlug to scope it to one project.
```

--------------------------------

### Import a map plugin

Source: https://docs.evidence.dev/components/custom_map

Shows how to dynamically load external stylesheets and ESM modules for map plugins like Mapbox Draw.

```liquid
{% custom_map height=500 %}
// The draw control's buttons are CSS sprites — load its stylesheet or they render blank.
const link = document.createElement('link');
link.rel = 'stylesheet';
link.href = 'https://cdn.jsdelivr.net/npm/@mapbox/mapbox-gl-draw@1/dist/mapbox-gl-draw.css';
document.head.appendChild(link);

const { default: MapboxDraw } = await import('https://cdn.jsdelivr.net/npm/@mapbox/mapbox-gl-draw@1/+esm');
const map = new mapgl.Map({ container, center: [-98, 39], zoom: 3 });
map.on('load', () => {
  map.addControl(new MapboxDraw({ displayControlsDefault: false, controls: { polygon: true, trash: true } }));
});
{% /custom_map %}
```

--------------------------------

### Create a service account for Evidence

Source: https://docs.evidence.dev/direct-connectors/bigquery

Creates a new service account in the specified GCP project.

```bash
gcloud iam service-accounts create evidence-bq-primary \
  --project=<project> \
  --display-name="Evidence BigQuery primary"
```

--------------------------------

### Override ECharts options for bubble series

Source: https://docs.evidence.dev/components/bubble

Example of using echarts_options to apply raw ECharts configuration to the bubble series.

```text
echarts_options={
      endLabel={ show=true }
      markPoint={ data=[{ type="max" }, { type="min" }] }
  }
```

--------------------------------

### evidence launch

Source: https://docs.evidence.dev/cli/commands

Connects the project to Evidence Studio and GitHub to enable deployment.

```APIDOC
## evidence launch

### Description
Connect this project to Evidence Studio and GitHub, then deploy by pushing to your repo.

### Parameters
#### Options
- **--name** (string) - Optional - Name for the Studio project to create.
- **--branch** (string) - Optional - Branch to publish from (default: auto-detected).
- **--root-directory** (string) - Optional - Project root within the repo (default: auto-detected).
- **--upload-credentials** (flag) - Optional - Upload warehouse credentials from connection.yaml to your org.
```

--------------------------------

### Unlink a repository from a Studio project

Source: https://docs.evidence.dev/cli/commands

Disconnect the repository from its associated Studio project. The project and GitHub App installation remain unaffected.

```bash
evidence unlink
evidence unlink --project my-project
```

--------------------------------

### Create a basic reactive bar chart with HTML

Source: https://docs.evidence.dev/components/html

Uses a SQL query to fetch data and renders a simple bar chart using standard DOM manipulation. The render function is registered with evidence.subscribe to ensure reactivity.

```sql
select 'Mon' as day, 120 as orders union all
select 'Tue', 180 union all
select 'Wed', 90
```

```html
{% html %}
<div id="bars" style="display:flex; gap:8px; align-items:flex-end; height:120px;"></div>
<script>
	// Wrap the draw in a function and register it with evidence.subscribe so
	// it re-runs whenever a filter, theme, or variable changes. evidence.query
	// always returns the latest interpolated rows, so the same function works
	// for the first render AND every subsequent reactive re-render.
	async function render() {
		const rows = await evidence.query("daily_orders");
		const max = Math.max(...rows.map((r) => r.orders));
		document.getElementById("bars").innerHTML = rows
			.map((r) => `<div style="flex:1; background:${evidence.theme.palette[0]}; height:${(r.orders / max) * 100}%"></div>`)
			.join("");
	}
	evidence.subscribe(render);
	await render();
	evidence.ready();
</script>
{% /html %}
```

--------------------------------

### Define User Attributes for RLS

Source: https://docs.evidence.dev/features/embedded

Example JSON structure for passing user attributes to the embed request to enable row-level security filtering.

```json
{
	"attributes": [
		{
			"key": "employee_id",
			"value": 1102
		},
		{
			"key": "region",
			"value": "Canada"
		},
		{
			"key": "departments",
			"value": ["Sales", "Marketing"]
		},
		{
			"key": "zone_ids",
			"value": [193, 992, 19183]
		},
		{
			"key": "isAdmin",
			"value": false
		}
	]
}
```

--------------------------------

### Configure Evidence Docs MCP in Cursor

Source: https://docs.evidence.dev/mcp/docs

Add the server configuration to the .cursor/mcp.json file to enable the tool in Cursor.

```json
{
  "mcpServers": {
    "evidence-studio": {
      "url": "https://evidence.studio/mcp"
    }
  }
}
```

--------------------------------

### Define JSON User Variable Values

Source: https://docs.evidence.dev/features/access-rules

Examples of JSON formats for different data types used in user variables. Ensure the value type matches the corresponding database column type.

```json
"123"
```

```json
123
```

```json
[1, 23, 30]
```

```json
["abc", "true", "22"]
```

```json
true
```

--------------------------------

### Basic Download Usage

Source: https://docs.evidence.dev/components/download

The simplest implementation of the download component, requiring only the data source.

```liquid
{% download data="demo.daily_orders" /%}
```

--------------------------------

### Manage Models

Source: https://docs.evidence.dev/cli/commands

List all models and their current refresh status.

```bash
evidence models
evidence models --json
```

--------------------------------

### Configure evidence.config.yaml

Source: https://docs.evidence.dev/features/project-settings

Defines project-wide settings including name, page directory, date handling, and layout defaults.

```yaml
# Evidence Project Configuration
# Docs: https://docs.evidence.studio/features/project-settings

project:
  name: 'My Project'
  evidence: '0.4.4'

pages: ./pages

date:
  first_day_of_week: monday
  default_date_range_end:
    type: relative
    days_ago: 1

layout:
  page_width: full
  cards: true
  table_of_contents: true
  auto_refresh: 300000

directories:
  pages/reports:
    title: 'Quarterly Reports'
```

--------------------------------

### Authenticate with Evidence

Source: https://docs.evidence.dev/cli

Log in to your Evidence account via the command line.

```bash
evidence login
```

--------------------------------

### Run SQL Queries

Source: https://docs.evidence.dev/cli/commands

Execute SQL queries directly from the command line, from a file, or via standard input.

```bash
evidence query "SELECT * FROM orders LIMIT 10"
evidence query --file query.sql
cat query.sql | evidence query -
```

--------------------------------

### Initialize a Minimal Map

Source: https://docs.evidence.dev/components/custom_map

Use the mapgl global to instantiate a map within the provided container and signal readiness to Evidence.

```js
const map = new mapgl.Map({ container, center: [-71.06, 42.36], zoom: 9 });
map.on('idle', () => evidence.ready());
```

--------------------------------

### List Data Tables

Source: https://docs.evidence.dev/cli/commands

Display all available data tables in the project.

```bash
evidence tables
```

--------------------------------

### Configure IP Whitelisting for Evidence Studio

Source: https://docs.evidence.dev/core-concepts/data-sources

List of IP addresses and hostnames required for database firewall configuration when connecting to Evidence.

```text
104.197.50.84
34.56.211.45
35.234.176.144
35.234.176.145
35.234.176.146
35.234.176.147
35.234.176.148
35.234.176.149
35.234.176.150
35.234.176.151
35.192.240.48
35.192.240.49
35.192.240.50
35.192.240.51
35.192.240.52
35.192.240.53
35.192.240.54
35.192.240.55
*.us-east4.gcp.proxy.prod.fivetran.com
*.us-central1.gcp.proxy.prod.fivetran.com
```

--------------------------------

### Create a role service account

Source: https://docs.evidence.dev/direct-connectors/bigquery

Create a dedicated service account for each RLS role.

```bash
gcloud iam service-accounts create customer-a \
  --project=<project> \
  --display-name="Evidence RLS role: customer_a"
```

--------------------------------

### Manage Connectors

Source: https://docs.evidence.dev/cli/commands

List all data connectors and their current health status.

```bash
evidence connectors
evidence connectors --json
```

--------------------------------

### Define a SQL Query File

Source: https://docs.evidence.dev/features/sql-files

Create a standalone SQL file with the .sql extension to define reusable queries.

```sql
SELECT
    date,
    sum(amount) as total_amount,
    count(*) as order_count
FROM orders
WHERE status = 'completed'
GROUP BY date
ORDER BY date DESC
```

--------------------------------

### Initialize a basic map

Source: https://docs.evidence.dev/components/custom_map

Use this to render a standard map instance. The 'idle' event listener is required to ensure exports capture the fully rendered map.

```liquid
{% custom_map height=400 %}
// mapgl is Mapbox GL when a token is available, else MapLibre GL.
// container and the access token are provided for you.
const map = new mapgl.Map({
  container,
  center: [-71.06, 42.36],
  zoom: 9
});
// Tiles load asynchronously — signal readiness once painted so PDF/PNG
// export captures a finished map rather than a blank frame.
map.on('idle', () => evidence.ready());
{% /custom_map %}
```

--------------------------------

### Basic Link Usage

Source: https://docs.evidence.dev/components/link

The standard syntax for creating a link with display text and a destination.

```liquid
[Link Text](href)
```

--------------------------------

### Use components with content

Source: https://docs.evidence.dev/core-concepts/components

Components that require content are wrapped between opening and closing tags.

```jinja
{% callout %}
This is a note
{% /callout %}
```

--------------------------------

### Add Evidence Studio to Claude Code

Source: https://docs.evidence.dev/mcp/studio

Use the CLI command to register the Evidence Studio MCP server with Claude Code.

```bash
claude mcp add evidence-studio --transport http https://evidence.studio/api/mcp
```

--------------------------------

### Basic Image Usage

Source: https://docs.evidence.dev/components/image

Display a static image by providing a URL and a description for alt text.

```liquid
{% image
    url="https://raw.githubusercontent.com/evidence-dev/media-kit/refs/heads/main/png/wordmark-gray-800.png"
    description="Sample placeholder image"
/%}
```

--------------------------------

### Configure fly.toml for Port and Memory

Source: https://docs.evidence.dev/self-host/fly

Set the internal port to 3000 and ensure memory is at least 512MB to prevent OOM errors.

```toml
[http_service]
  internal_port = 3000   # the port the image listens on

[[vm]]
  memory = '512mb'       # or more - default 256mb OOM-kills the server
```

--------------------------------

### Plot Evidence data as points

Source: https://docs.evidence.dev/components/custom_map

Demonstrates how to fetch data from an Evidence query and add it as a GeoJSON source to the map.

```liquid
```sql locations
select 'New York'    as name, -74.01  as lng, 40.71 as lat
union all select 'Los Angeles', -118.24, 34.05
union all select 'Chicago',      -87.63, 41.88
union all select 'Houston',      -95.37, 29.76
union all select 'Denver',      -104.99, 39.74
union all select 'Seattle',     -122.33, 47.61
union all select 'Miami',        -80.19, 25.76
```

{% custom_map height=500 %}
const map = new mapgl.Map({ container, center: [-98, 39], zoom: 3 });
map.on('load', async () => {
  const rows = await evidence.query('locations');
  map.addSource('pts', {
    type: 'geojson',
    data: {
      type: 'FeatureCollection',
      features: rows.map((r) => ({
        type: 'Feature',
        geometry: { type: 'Point', coordinates: [r.lng, r.lat] },
        properties: r
      }))
    }
  });
  map.addLayer({ id: 'pts', type: 'circle', source: 'pts', paint: { 'circle-radius': 5 } });
});
{% /custom_map %}
```

--------------------------------

### Compare SQL Variable Interpolation

Source: https://docs.evidence.dev/migration-guide

Legacy Evidence supports Svelte-style interpolation, whereas Evidence Studio requires moving input-driven logic into page-level SQL blocks.

```sql
${inputs.x.value}
```

```sql
{{ }}
```
Tokens:
Raw