/dune

Visualization Management

Prerequisite: Read the main skill for authentication, global flags, and key concepts.

Create and manage visualizations on saved Dune queries.

dune visualization <subcommand> [flags]
dune viz <subcommand> [flags]         # alias

viz create

Create a new visualization attached to an existing saved query.

dune viz create --query-id <ID> --name <NAME> --type <TYPE> --options '<JSON>' [flags]

Flags

Visualization Types

Note: Types marked "undocumented" are accepted by the API but their --options format is not yet documented. Stick to chart, table, and counter for reliable results.

[!CAUTION] This is a write command -- it creates a resource in the user's Dune account.

viz get

Retrieve detailed information about a visualization by its ID.

dune viz get <visualization_id> [flags]

Arguments

Flags

Examples

# View a visualization's details
dune viz get 12345 -o json

# Inspect current options before updating
dune viz get 12345 -o json | jq '.options'

viz list

List all visualizations attached to a query.

dune viz list --query-id <ID> [flags]

Flags

Examples

# List all visualizations for a query
dune viz list --query-id 12345 -o json

# Paginate through results
dune viz list --query-id 12345 --limit 10 --offset 0 -o json
dune viz list --query-id 12345 --limit 10 --offset 10 -o json

viz update

Update an existing visualization. Fetches the current state first, applies only the provided changes, and preserves unchanged fields.

dune viz update <visualization_id> [flags]

Arguments

Flags

At least one flag must be provided. Only the provided flags are updated; omitted fields remain unchanged.

Important: The --options flag replaces the entire options object, not individual fields within it. To change a single option field, first fetch the current options with dune viz get <id> -o json, modify the JSON, then pass the full updated object to --options.

Examples

# Rename a visualization
dune viz update 12345 --name "New Chart Name" -o json

# Change chart type and options
dune viz update 12345 --type counter \
  --options '{"counterColName":"count","rowNumber":1,"stringDecimal":0}' -o json

# Update description only
dune viz update 12345 --description "Updated weekly report chart" -o json

[!CAUTION] This is a write command -- it modifies an existing resource in the user's Dune account.

viz delete

Permanently delete a visualization. This action cannot be undone.

dune viz delete <visualization_id> [flags]

Arguments

Flags

Examples

# Delete a visualization
dune viz delete 12345 -o json

# List first, then delete
dune viz list --query-id 12345 -o json
dune viz delete <id-from-list> -o json

[!CAUTION] This is a destructive command -- it permanently deletes the visualization. There is no undelete. Use dune viz get <id> to inspect the visualization before deleting.

Required Workflow (for creating visualizations)

You MUST follow this workflow every time. Skipping step 1 is the #1 cause of broken visualizations.

Visualizations require saved (non-temporary) queries. When creating a query that will have visualizations, do NOT use --temp. Temporary queries are auto-deleted and cannot have visualizations attached.

Step 1: Run the query first (required for both column discovery AND rendering)

dune query run <query-id> -o json

This step is required for two reasons:

1. Column discovery: Look at result.metadata.column_names in the response — these are the exact column names you must use in --options. Column names are case-sensitive and may be auto-generated (e.g. SELECT 1 produces _col0, not 1).
2. Rendering: A visualization will show "No results available" until the query has been executed at least once. The embed page displays results from the latest execution — without one, there's nothing to render.

Step 2: Build options using the discovered column names

Use the column names from step 1 to construct the --options JSON for your visualization type (see format below).

Step 3: Create the visualization

dune viz create --query-id <id> --name "..." --type <type> --options '<json>' -o json

Step 4: Verify the visualization renders

Open the returned URL to confirm it renders correctly.

Options Format

Applies to: viz create --options and viz update --options.

Critical: The --options JSON must match the visualization type. Column names in options must match the actual query result column names exactly. Omitting required fields or using wrong column names produces broken visualizations.

Minimum Required Templates

Copy the appropriate template, replace <placeholders> with actual column names from result.metadata.column_names:

Counter (minimum):

{"counterColName":"<column>","rowNumber":1,"stringDecimal":0}

Table (minimum — one entry per column you want to show):

{"columns":[{"name":"<column>","title":"<Display Name>","type":"normal","alignContent":"left","isHidden":false}]}

Line/Column/Area/Scatter chart (minimum):

{"globalSeriesType":"line","sortX":true,"columnMapping":{"<x_column>":"x","<y_column>":"y"},"seriesOptions":{"<y_column>":{"type":"line","yAxis":0,"zIndex":0}},"xAxis":{"title":{"text":"<X Label>"}},"yAxis":[{"title":{"text":"<Y Label>"}}],"legend":{"enabled":true},"series":{"stacking":null}}

Change "line" to "column", "area", or "scatter" in both globalSeriesType and seriesOptions[].type.

Pie chart (minimum):

{"globalSeriesType":"pie","sortX":true,"columnMapping":{"<category_column>":"x","<value_column>":"y"},"seriesOptions":{"<value_column>":{"type":"pie","yAxis":0,"zIndex":0}}}

Counter Options

The simplest type — displays a single number from one row of the query results.

dune viz create --query-id 12345 --name "Total Transfers" --type counter \
  --options '{"counterColName":"count","rowNumber":1,"stringDecimal":0,"counterLabel":"Total Transfers"}' -o json

Table Options

Displays query results as a formatted table.

Each column object:

dune viz create --query-id 12345 --name "Top Wallets" --type table \
  --options '{"itemsPerPage":25,"columns":[{"name":"address","title":"Wallet","type":"normal","alignContent":"left","isHidden":false},{"name":"balance","title":"Balance (ETH)","type":"normal","alignContent":"right","isHidden":false,"numberFormat":"0,0.0000"}]}' -o json

Chart Options (line, column, area, scatter)

2D charts require mapping query columns to axes.

columnMapping maps each query column to an axis role:

• Exactly one column mapped to "x" (the x-axis)
• One or more columns mapped to "y" (data series)

seriesOptions has one entry per y-column:

{"<column_name>": {"type": "line", "yAxis": 0, "zIndex": 0, "name": "Display Name"}}

# Line chart with single series
dune viz create --query-id 12345 --name "Daily Volume" --type chart \
  --options '{"globalSeriesType":"line","sortX":true,"columnMapping":{"day":"x","volume":"y"},"seriesOptions":{"volume":{"type":"line","yAxis":0,"zIndex":0,"name":"Volume"}},"xAxis":{"title":{"text":"Day"}},"yAxis":[{"title":{"text":"Volume (USD)"}}],"legend":{"enabled":true},"series":{"stacking":null}}' -o json

# Stacked column chart with multiple series
dune viz create --query-id 12345 --name "Volume by Chain" --type chart \
  --options '{"globalSeriesType":"column","sortX":true,"columnMapping":{"day":"x","eth_vol":"y","arb_vol":"y"},"seriesOptions":{"eth_vol":{"type":"column","yAxis":0,"zIndex":0,"name":"Ethereum"},"arb_vol":{"type":"column","yAxis":0,"zIndex":0,"name":"Arbitrum"}},"xAxis":{"title":{"text":"Day"}},"yAxis":[{"title":{"text":"Volume"}}],"legend":{"enabled":true},"series":{"stacking":"stack"}}' -o json

Chart Options (pie)

dune viz create --query-id 12345 --name "Volume by Chain" --type chart \
  --options '{"globalSeriesType":"pie","sortX":true,"showDataLabels":true,"columnMapping":{"chain":"x","volume":"y"},"seriesOptions":{"volume":{"type":"pie","yAxis":0,"zIndex":0,"name":"Volume"}}}' -o json

Numeral.js Format Reference

Use these in numberFormat, stringPrefix/stringSuffix fields:

Common Mistakes

1. Using a temporary query: Visualizations only work on saved (non-temp) queries. If you created the query with --temp, recreate it without --temp before adding a visualization.
2. Not running the query first: You MUST run dune query run <id> -o json first to discover actual column names from result.metadata.column_names. Never guess column names — SELECT 1 produces _col0, SELECT count(*) FROM x produces _col0, etc. Only SELECT x AS my_name gives predictable names.
3. Empty options: --options '{}' always produces a broken visualization that shows errors when opened
4. Wrong column names: Column names in options must match query result columns exactly (case-sensitive)
5. Missing columnMapping: Charts require columnMapping with at least one "x" and one "y" entry
6. Counter row number: rowNumber is 1-based, not 0-based
7. Chart type vs globalSeriesType: Use --type chart for all chart subtypes, then set globalSeriesType in options to "line", "column", "area", "scatter", or "pie"
8. Deleting without checking first: Always use dune viz get <id> or dune viz list --query-id <id> to verify the visualization before deleting. There is no undo.
9. Updating options without fetching first: When changing --options, use dune viz get <id> -o json to see the current options format, then provide a complete replacement. The --options flag replaces the entire options object, not individual fields within it.

See Also

• query-management.md -- create and manage the queries that visualizations are attached to
• query-execution.md -- execute queries to generate data for visualizations